Initial commit: Linux kernel 4.19 for Unplugged OS

This commit is contained in:
ziv committed 2025-10-06 13:52:42 +00:00
commit d30235b04c
80519 files changed
+35800681

No files matched your search

+47
View File
@@ -0,0 +1,47 @@
.. -*- coding: utf-8; mode: rst -*-
.. include:: <isonum.txt>
.. _cec:
#########################################
Part V - Consumer Electronics Control API
#########################################
This part describes the CEC: Consumer Electronics Control
.. only:: html
.. class:: toc-title
Table of Contents
.. toctree::
:maxdepth: 5
:numbered:
cec-intro
cec-funcs
cec-pin-error-inj
cec-header
**********************
Revision and Copyright
**********************
Authors:
- Verkuil, Hans <hans.verkuil@cisco.com>
- Initial version.
**Copyright** |copy| 2016 : Hans Verkuil
****************
Revision History
****************
:revision: 1.0.0 / 2016-03-17 (*hv*)
Initial revision
@@ -0,0 +1,47 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec-func-close:
***********
cec close()
***********
Name
====
cec-close - Close a cec device
Synopsis
========
.. code-block:: c
#include <unistd.h>
.. c:function:: int close( int fd )
:name: cec-close
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
Description
===========
Closes the cec device. Resources associated with the file descriptor are
freed. The device configuration remain unchanged.
Return Value
============
:c:func:`close() <cec-close>` returns 0 on success. On error, -1 is returned, and
``errno`` is set appropriately. Possible error codes are:
``EBADF``
``fd`` is not a valid open file descriptor.
@@ -0,0 +1,66 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec-func-ioctl:
***********
cec ioctl()
***********
Name
====
cec-ioctl - Control a cec device
Synopsis
========
.. code-block:: c
#include <sys/ioctl.h>
.. c:function:: int ioctl( int fd, int request, void *argp )
:name: cec-ioctl
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``request``
CEC ioctl request code as defined in the cec.h header file, for
example :ref:`CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`.
``argp``
Pointer to a request-specific structure.
Description
===========
The :c:func:`ioctl() <cec-ioctl>` function manipulates cec device parameters. The
argument ``fd`` must be an open file descriptor.
The ioctl ``request`` code specifies the cec function to be called. It
has encoded in it whether the argument is an input, output or read/write
parameter, and the size of the argument ``argp`` in bytes.
Macros and structures definitions specifying cec ioctl requests and
their parameters are located in the cec.h header file. All cec ioctl
requests, their respective function and parameters are specified in
:ref:`cec-user-func`.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
Request-specific error codes are listed in the individual requests
descriptions.
When an ioctl that takes an output or read/write parameter fails, the
parameter remains unmodified.
@@ -0,0 +1,78 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec-func-open:
**********
cec open()
**********
Name
====
cec-open - Open a cec device
Synopsis
========
.. code-block:: c
#include <fcntl.h>
.. c:function:: int open( const char *device_name, int flags )
:name: cec-open
Arguments
=========
``device_name``
Device to be opened.
``flags``
Open flags. Access mode must be ``O_RDWR``.
When the ``O_NONBLOCK`` flag is given, the
:ref:`CEC_RECEIVE <CEC_RECEIVE>` and :ref:`CEC_DQEVENT <CEC_DQEVENT>` ioctls
will return the ``EAGAIN`` error code when no message or event is available, and
ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`,
:ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and
:ref:`CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
all return 0.
Other flags have no effect.
Description
===========
To open a cec device applications call :c:func:`open() <cec-open>` with the
desired device name. The function has no side effects; the device
configuration remain unchanged.
When the device is opened in read-only mode, attempts to modify its
configuration will result in an error, and ``errno`` will be set to
EBADF.
Return Value
============
:c:func:`open() <cec-open>` returns the new file descriptor on success. On error,
-1 is returned, and ``errno`` is set appropriately. Possible error codes
include:
``EACCES``
The requested access to the file is not allowed.
``EMFILE``
The process already has the maximum number of files open.
``ENFILE``
The system limit on the total number of open files has been reached.
``ENOMEM``
Insufficient kernel memory was available.
``ENXIO``
No device corresponding to this device special file exists.
@@ -0,0 +1,77 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec-func-poll:
**********
cec poll()
**********
Name
====
cec-poll - Wait for some event on a file descriptor
Synopsis
========
.. code-block:: c
#include <sys/poll.h>
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
:name: cec-poll
Arguments
=========
``ufds``
List of FD events to be watched
``nfds``
Number of FD events at the \*ufds array
``timeout``
Timeout to wait for events
Description
===========
With the :c:func:`poll() <cec-poll>` function applications can wait for CEC
events.
On success :c:func:`poll() <cec-poll>` returns the number of file descriptors
that have been selected (that is, file descriptors for which the
``revents`` field of the respective struct :c:type:`pollfd`
is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
the ``revents`` field if there are messages in the receive queue. If the
transmit queue has room for new messages, the ``POLLOUT`` and
``POLLWRNORM`` flags are set. If there are events in the event queue,
then the ``POLLPRI`` flag is set. When the function times out it returns
a value of zero, on failure it returns -1 and the ``errno`` variable is
set appropriately.
For more details see the :c:func:`poll() <cec-poll>` manual page.
Return Value
============
On success, :c:func:`poll() <cec-poll>` returns the number structures which have
non-zero ``revents`` fields, or zero if the call timed out. On error -1
is returned, and the ``errno`` variable is set appropriately:
``EBADF``
One or more of the ``ufds`` members specify an invalid file
descriptor.
``EFAULT``
``ufds`` references an inaccessible memory area.
``EINTR``
The call was interrupted by a signal.
``EINVAL``
The ``nfds`` argument is greater than ``OPEN_MAX``.
@@ -0,0 +1,20 @@
.. _cec-user-func:
******************
Function Reference
******************
.. toctree::
:maxdepth: 1
cec-func-open
cec-func-close
cec-func-ioctl
cec-func-poll
cec-ioc-adap-g-caps
cec-ioc-adap-g-log-addrs
cec-ioc-adap-g-phys-addr
cec-ioc-dqevent
cec-ioc-g-mode
cec-ioc-receive
@@ -0,0 +1,10 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec_header:
***************
CEC Header File
***************
.. kernel-include:: $BUILDDIR/cec.h.rst
@@ -0,0 +1,40 @@
.. _cec-intro:
Introduction
============
HDMI connectors provide a single pin for use by the Consumer Electronics
Control protocol. This protocol allows different devices connected by an
HDMI cable to communicate. The protocol for CEC version 1.4 is defined
in supplements 1 (CEC) and 2 (HEAC or HDMI Ethernet and Audio Return
Channel) of the HDMI 1.4a (:ref:`hdmi`) specification and the
extensions added to CEC version 2.0 are defined in chapter 11 of the
HDMI 2.0 (:ref:`hdmi2`) specification.
The bitrate is very slow (effectively no more than 36 bytes per second)
and is based on the ancient AV.link protocol used in old SCART
connectors. The protocol closely resembles a crazy Rube Goldberg
contraption and is an unholy mix of low and high level messages. Some
messages, especially those part of the HEAC protocol layered on top of
CEC, need to be handled by the kernel, others can be handled either by
the kernel or by userspace.
In addition, CEC can be implemented in HDMI receivers, transmitters and
in USB devices that have an HDMI input and an HDMI output and that
control just the CEC pin.
Drivers that support CEC will create a CEC device node (/dev/cecX) to
give userspace access to the CEC adapter. The
:ref:`CEC_ADAP_G_CAPS` ioctl will tell userspace what it is allowed to do.
In order to check the support and test it, it is suggested to download
the `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ package. It
provides three tools to handle CEC:
- cec-ctl: the Swiss army knife of CEC. Allows you to configure, transmit
and monitor CEC messages.
- cec-compliance: does a CEC compliance test of a remote CEC device to
determine how compliant the CEC implementation is.
- cec-follower: emulates a CEC follower.
@@ -0,0 +1,139 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_ADAP_G_CAPS:
*********************
ioctl CEC_ADAP_G_CAPS
*********************
Name
====
CEC_ADAP_G_CAPS - Query device capabilities
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp )
:name: CEC_ADAP_G_CAPS
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Description
===========
All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`. To query
device information, applications call the ioctl with a pointer to a
struct :c:type:`cec_caps`. The driver fills the structure and
returns the information to the application. The ioctl never fails.
.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.8cm}|
.. c:type:: cec_caps
.. flat-table:: struct cec_caps
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
* - char
- ``driver[32]``
- The name of the cec adapter driver.
* - char
- ``name[32]``
- The name of this CEC adapter. The combination ``driver`` and
``name`` must be unique.
* - __u32
- ``capabilities``
- The capabilities of the CEC adapter, see
:ref:`cec-capabilities`.
* - __u32
- ``version``
- CEC Framework API version, formatted with the ``KERNEL_VERSION()``
macro.
.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
.. _cec-capabilities:
.. flat-table:: CEC Capabilities Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 8
* .. _`CEC-CAP-PHYS-ADDR`:
- ``CEC_CAP_PHYS_ADDR``
- 0x00000001
- Userspace has to configure the physical address by calling
:ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`. If
this capability isn't set, then setting the physical address is
handled by the kernel whenever the EDID is set (for an HDMI
receiver) or read (for an HDMI transmitter).
* .. _`CEC-CAP-LOG-ADDRS`:
- ``CEC_CAP_LOG_ADDRS``
- 0x00000002
- Userspace has to configure the logical addresses by calling
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`. If
this capability isn't set, then the kernel will have configured
this.
* .. _`CEC-CAP-TRANSMIT`:
- ``CEC_CAP_TRANSMIT``
- 0x00000004
- Userspace can transmit CEC messages by calling
:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. This implies that
userspace can be a follower as well, since being able to transmit
messages is a prerequisite of becoming a follower. If this
capability isn't set, then the kernel will handle all CEC
transmits and process all CEC messages it receives.
* .. _`CEC-CAP-PASSTHROUGH`:
- ``CEC_CAP_PASSTHROUGH``
- 0x00000008
- Userspace can use the passthrough mode by calling
:ref:`ioctl CEC_S_MODE <CEC_S_MODE>`.
* .. _`CEC-CAP-RC`:
- ``CEC_CAP_RC``
- 0x00000010
- This adapter supports the remote control protocol.
* .. _`CEC-CAP-MONITOR-ALL`:
- ``CEC_CAP_MONITOR_ALL``
- 0x00000020
- The CEC hardware can monitor all messages, not just directed and
broadcast messages.
* .. _`CEC-CAP-NEEDS-HPD`:
- ``CEC_CAP_NEEDS_HPD``
- 0x00000040
- The CEC hardware is only active if the HDMI Hotplug Detect pin is
high. This makes it impossible to use CEC to wake up displays that
set the HPD pin low when in standby mode, but keep the CEC bus
alive.
* .. _`CEC-CAP-MONITOR-PIN`:
- ``CEC_CAP_MONITOR_PIN``
- 0x00000080
- The CEC hardware can monitor CEC pin changes from low to high voltage
and vice versa. When in pin monitoring mode the application will
receive ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
@@ -0,0 +1,371 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_ADAP_LOG_ADDRS:
.. _CEC_ADAP_G_LOG_ADDRS:
.. _CEC_ADAP_S_LOG_ADDRS:
****************************************************
ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS
****************************************************
Name
====
CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp )
:name: CEC_ADAP_G_LOG_ADDRS
.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp )
:name: CEC_ADAP_S_LOG_ADDRS
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Pointer to struct :c:type:`cec_log_addrs`.
Description
===========
To query the current CEC logical addresses, applications call
:ref:`ioctl CEC_ADAP_G_LOG_ADDRS <CEC_ADAP_G_LOG_ADDRS>` with a pointer to a
struct :c:type:`cec_log_addrs` where the driver stores the logical addresses.
To set new logical addresses, applications fill in
struct :c:type:`cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is
returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
the ``EBUSY`` error code will be returned.
To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields
will be ignored in that case. The adapter will go to the unconfigured state and the
``cec_version``, ``vendor_id`` and ``osd_name`` fields are all reset to their default
values (CEC version 2.0, no vendor ID and an empty OSD name).
If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`),
then this ioctl will block until all requested logical
addresses have been claimed. If the file descriptor is in non-blocking mode then it will
not wait for the logical addresses to be claimed, instead it just returns 0.
A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the
logical addresses are claimed or cleared.
Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when
logical address types are already defined will return with error ``EBUSY``.
.. c:type:: cec_log_addrs
.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{7.5cm}|
.. cssclass:: longtable
.. flat-table:: struct cec_log_addrs
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
* - __u8
- ``log_addr[CEC_MAX_LOG_ADDRS]``
- The actual logical addresses that were claimed. This is set by the
driver. If no logical address could be claimed, then it is set to
``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then
``log_addr[0]`` is set to 0xf and all others to
``CEC_LOG_ADDR_INVALID``.
* - __u16
- ``log_addr_mask``
- The bitmask of all logical addresses this adapter has claimed. If
this adapter is Unregistered then ``log_addr_mask`` sets bit 15
and clears all other bits. If this adapter is not configured at
all, then ``log_addr_mask`` is set to 0. Set by the driver.
* - __u8
- ``cec_version``
- The CEC version that this adapter shall use. See
:ref:`cec-versions`. Used to implement the
``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages.
Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC
framework.
* - __u8
- ``num_log_addrs``
- Number of logical addresses to set up. Must be ≤
``available_log_addrs`` as returned by
:ref:`CEC_ADAP_G_CAPS`. All arrays in
this structure are only filled up to index
``available_log_addrs``-1. The remaining array elements will be
ignored. Note that the CEC 2.0 standard allows for a maximum of 2
logical addresses, although some hardware has support for more.
``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual
number of logical addresses it could claim, which may be less than
what was requested. If this field is set to 0, then the CEC
adapter shall clear all claimed logical addresses and all other
fields will be ignored.
* - __u32
- ``vendor_id``
- The vendor ID is a 24-bit number that identifies the specific
vendor or entity. Based on this ID vendor specific commands may be
defined. If you do not want a vendor ID then set it to
``CEC_VENDOR_ID_NONE``.
* - __u32
- ``flags``
- Flags. See :ref:`cec-log-addrs-flags` for a list of available flags.
* - char
- ``osd_name[15]``
- The On-Screen Display name as is returned by the
``CEC_MSG_SET_OSD_NAME`` message.
* - __u8
- ``primary_device_type[CEC_MAX_LOG_ADDRS]``
- Primary device type for each logical address. See
:ref:`cec-prim-dev-types` for possible types.
* - __u8
- ``log_addr_type[CEC_MAX_LOG_ADDRS]``
- Logical address types. See :ref:`cec-log-addr-types` for
possible types. The driver will update this with the actual
logical address type that it claimed (e.g. it may have to fallback
to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`).
* - __u8
- ``all_device_types[CEC_MAX_LOG_ADDRS]``
- CEC 2.0 specific: the bit mask of all device types. See
:ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0
``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave
this field to 0, or fill it in according to the CEC 2.0 guidelines to
give the CEC framework more information about the device type, even
though the framework won't use it directly in the CEC message.
* - __u8
- ``features[CEC_MAX_LOG_ADDRS][12]``
- Features for each logical address. It is used in the CEC 2.0
``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the
RC Profile and the Device Features. For CEC 1.4 you can either leave
this field to all 0, or fill it in according to the CEC 2.0 guidelines to
give the CEC framework more information about the device type, even
though the framework won't use it directly in the CEC message.
.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
.. _cec-log-addrs-flags:
.. flat-table:: Flags for struct cec_log_addrs
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`:
- ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK``
- 1
- By default if no logical address of the requested type can be claimed, then
it will go back to the unconfigured state. If this flag is set, then it will
fallback to the Unregistered logical address. Note that if the Unregistered
logical address was explicitly requested, then this flag has no effect.
* .. _`CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU`:
- ``CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU``
- 2
- By default the ``CEC_MSG_USER_CONTROL_PRESSED`` and ``CEC_MSG_USER_CONTROL_RELEASED``
messages are only passed on to the follower(s), if any. If this flag is set,
then these messages are also passed on to the remote control input subsystem
and will appear as keystrokes. This features needs to be enabled explicitly.
If CEC is used to enter e.g. passwords, then you may not want to enable this
to avoid trivial snooping of the keystrokes.
* .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`:
- ``CEC_LOG_ADDRS_FL_CDC_ONLY``
- 4
- If this flag is set, then the device is CDC-Only. CDC-Only CEC devices
are CEC devices that can only handle CDC messages.
All other messages are ignored.
.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
.. _cec-versions:
.. flat-table:: CEC Versions
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-OP-CEC-VERSION-1-3A`:
- ``CEC_OP_CEC_VERSION_1_3A``
- 4
- CEC version according to the HDMI 1.3a standard.
* .. _`CEC-OP-CEC-VERSION-1-4B`:
- ``CEC_OP_CEC_VERSION_1_4B``
- 5
- CEC version according to the HDMI 1.4b standard.
* .. _`CEC-OP-CEC-VERSION-2-0`:
- ``CEC_OP_CEC_VERSION_2_0``
- 6
- CEC version according to the HDMI 2.0 standard.
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-prim-dev-types:
.. flat-table:: CEC Primary Device Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-OP-PRIM-DEVTYPE-TV`:
- ``CEC_OP_PRIM_DEVTYPE_TV``
- 0
- Use for a TV.
* .. _`CEC-OP-PRIM-DEVTYPE-RECORD`:
- ``CEC_OP_PRIM_DEVTYPE_RECORD``
- 1
- Use for a recording device.
* .. _`CEC-OP-PRIM-DEVTYPE-TUNER`:
- ``CEC_OP_PRIM_DEVTYPE_TUNER``
- 3
- Use for a device with a tuner.
* .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`:
- ``CEC_OP_PRIM_DEVTYPE_PLAYBACK``
- 4
- Use for a playback device.
* .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`:
- ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM``
- 5
- Use for an audio system (e.g. an audio/video receiver).
* .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`:
- ``CEC_OP_PRIM_DEVTYPE_SWITCH``
- 6
- Use for a CEC switch.
* .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`:
- ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC``
- 7
- Use for a video processor device.
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-log-addr-types:
.. flat-table:: CEC Logical Address Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-LOG-ADDR-TYPE-TV`:
- ``CEC_LOG_ADDR_TYPE_TV``
- 0
- Use for a TV.
* .. _`CEC-LOG-ADDR-TYPE-RECORD`:
- ``CEC_LOG_ADDR_TYPE_RECORD``
- 1
- Use for a recording device.
* .. _`CEC-LOG-ADDR-TYPE-TUNER`:
- ``CEC_LOG_ADDR_TYPE_TUNER``
- 2
- Use for a tuner device.
* .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`:
- ``CEC_LOG_ADDR_TYPE_PLAYBACK``
- 3
- Use for a playback device.
* .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`:
- ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM``
- 4
- Use for an audio system device.
* .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`:
- ``CEC_LOG_ADDR_TYPE_SPECIFIC``
- 5
- Use for a second TV or for a video processor device.
* .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`:
- ``CEC_LOG_ADDR_TYPE_UNREGISTERED``
- 6
- Use this if you just want to remain unregistered. Used for pure
CEC switches or CDC-only devices (CDC: Capability Discovery and
Control).
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-all-dev-types-flags:
.. flat-table:: CEC All Device Types Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-OP-ALL-DEVTYPE-TV`:
- ``CEC_OP_ALL_DEVTYPE_TV``
- 0x80
- This supports the TV type.
* .. _`CEC-OP-ALL-DEVTYPE-RECORD`:
- ``CEC_OP_ALL_DEVTYPE_RECORD``
- 0x40
- This supports the Recording type.
* .. _`CEC-OP-ALL-DEVTYPE-TUNER`:
- ``CEC_OP_ALL_DEVTYPE_TUNER``
- 0x20
- This supports the Tuner type.
* .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`:
- ``CEC_OP_ALL_DEVTYPE_PLAYBACK``
- 0x10
- This supports the Playback type.
* .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`:
- ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM``
- 0x08
- This supports the Audio System type.
* .. _`CEC-OP-ALL-DEVTYPE-SWITCH`:
- ``CEC_OP_ALL_DEVTYPE_SWITCH``
- 0x04
- This supports the CEC Switch or Video Processing type.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` can return the following
error codes:
ENOTTY
The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported.
EBUSY
The CEC adapter is currently configuring itself, or it is already configured and
``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or
initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``.
EINVAL
The contents of struct :c:type:`cec_log_addrs` is invalid.
@@ -0,0 +1,93 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_ADAP_PHYS_ADDR:
.. _CEC_ADAP_G_PHYS_ADDR:
.. _CEC_ADAP_S_PHYS_ADDR:
****************************************************
ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR
****************************************************
Name
====
CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp )
:name: CEC_ADAP_G_PHYS_ADDR
.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp )
:name: CEC_ADAP_S_PHYS_ADDR
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Pointer to the CEC address.
Description
===========
To query the current physical address applications call
:ref:`ioctl CEC_ADAP_G_PHYS_ADDR <CEC_ADAP_G_PHYS_ADDR>` with a pointer to a __u16 where the
driver stores the physical address.
To set a new physical address applications store the physical address in
a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` with a pointer to
this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` is only available if
``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned
otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can only be called
by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
the ``EBUSY`` error code will be returned.
To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``.
The adapter will go to the unconfigured state.
If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`),
then this ioctl will block until all
requested logical addresses have been claimed. If the file descriptor is in non-blocking mode
then it will not wait for the logical addresses to be claimed, instead it just returns 0.
A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the physical address
changes.
The physical address is a 16-bit number where each group of 4 bits
represent a digit of the physical address a.b.c.d where the most
significant 4 bits represent 'a'. The CEC root device (usually the TV)
has address 0.0.0.0. Every device that is hooked up to an input of the
TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in
turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep
is supported. The physical address a device shall use is stored in the
EDID of the sink.
For example, the EDID for each HDMI input of the TV will have a
different physical address of the form a.0.0.0 that the sources will
read out and use as their physical address.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can return the following
error codes:
ENOTTY
The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported.
EBUSY
Another filehandle is in exclusive follower or initiator mode, or the filehandle
is in mode ``CEC_MODE_NO_INITIATOR``.
EINVAL
The physical address is malformed.
@@ -0,0 +1,244 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_DQEVENT:
*****************
ioctl CEC_DQEVENT
*****************
Name
====
CEC_DQEVENT - Dequeue a CEC event
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp )
:name: CEC_DQEVENT
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Description
===========
CEC devices can send asynchronous events. These can be retrieved by
calling :c:func:`CEC_DQEVENT`. If the file descriptor is in
non-blocking mode and no event is pending, then it will return -1 and
set errno to the ``EAGAIN`` error code.
The internal event queues are per-filehandle and per-event type. If
there is no more room in a queue then the last event is overwritten with
the new one. This means that intermediate results can be thrown away but
that the latest event is always available. This also means that is it
possible to read two successive events that have the same value (e.g.
two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with
the same state). In that case the intermediate state changes were lost but
it is guaranteed that the state did change in between the two events.
.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|
.. c:type:: cec_event_state_change
.. flat-table:: struct cec_event_state_change
:header-rows: 0
:stub-columns: 0
:widths: 1 1 8
* - __u16
- ``phys_addr``
- The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no
valid physical address is set.
* - __u16
- ``log_addr_mask``
- The current set of claimed logical addresses. This is 0 if no logical
addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``.
If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device
has the unregistered logical address. In that case all other bits are 0.
.. c:type:: cec_event_lost_msgs
.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}|
.. flat-table:: struct cec_event_lost_msgs
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
* - __u32
- ``lost_msgs``
- Set to the number of lost messages since the filehandle was opened
or since the last time this event was dequeued for this
filehandle. The messages lost are the oldest messages. So when a
new message arrives and there is no more room, then the oldest
message is discarded to make room for the new one. The internal
size of the message queue guarantees that all messages received in
the last two seconds will be stored. Since messages should be
replied to within a second according to the CEC specification,
this is more than enough.
.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}|
.. c:type:: cec_event
.. flat-table:: struct cec_event
:header-rows: 0
:stub-columns: 0
:widths: 1 1 1 8
* - __u64
- ``ts``
- :cspan:`1`\ Timestamp of the event in ns.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock.
To access the same clock from userspace use :c:func:`clock_gettime`.
* - __u32
- ``event``
- :cspan:`1` The CEC event type, see :ref:`cec-events`.
* - __u32
- ``flags``
- :cspan:`1` Event flags, see :ref:`cec-event-flags`.
* - union
- (anonymous)
-
-
* -
- struct cec_event_state_change
- ``state_change``
- The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>`
event.
* -
- struct cec_event_lost_msgs
- ``lost_msgs``
- The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>`
event.
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-events:
.. flat-table:: CEC Events Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-EVENT-STATE-CHANGE`:
- ``CEC_EVENT_STATE_CHANGE``
- 1
- Generated when the CEC Adapter's state changes. When open() is
called an initial event will be generated for that filehandle with
the CEC Adapter's state at that time.
* .. _`CEC-EVENT-LOST-MSGS`:
- ``CEC_EVENT_LOST_MSGS``
- 2
- Generated if one or more CEC messages were lost because the
application didn't dequeue CEC messages fast enough.
* .. _`CEC-EVENT-PIN-CEC-LOW`:
- ``CEC_EVENT_PIN_CEC_LOW``
- 3
- Generated if the CEC pin goes from a high voltage to a low voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set.
* .. _`CEC-EVENT-PIN-CEC-HIGH`:
- ``CEC_EVENT_PIN_CEC_HIGH``
- 4
- Generated if the CEC pin goes from a low voltage to a high voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set.
* .. _`CEC-EVENT-PIN-HPD-LOW`:
- ``CEC_EVENT_PIN_HPD_LOW``
- 5
- Generated if the HPD pin goes from a high voltage to a low voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set. When open() is called, the HPD pin can be read and
if the HPD is low, then an initial event will be generated for that
filehandle.
* .. _`CEC-EVENT-PIN-HPD-HIGH`:
- ``CEC_EVENT_PIN_HPD_HIGH``
- 6
- Generated if the HPD pin goes from a low voltage to a high voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set. When open() is called, the HPD pin can be read and
if the HPD is high, then an initial event will be generated for that
filehandle.
* .. _`CEC-EVENT-PIN-5V-LOW`:
- ``CEC_EVENT_PIN_5V_LOW``
- 6
- Generated if the 5V pin goes from a high voltage to a low voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set. When open() is called, the 5V pin can be read and
if the 5V is low, then an initial event will be generated for that
filehandle.
* .. _`CEC-EVENT-PIN-5V-HIGH`:
- ``CEC_EVENT_PIN_5V_HIGH``
- 7
- Generated if the 5V pin goes from a low voltage to a high voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set. When open() is called, the 5V pin can be read and
if the 5V is high, then an initial event will be generated for that
filehandle.
.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}|
.. _cec-event-flags:
.. flat-table:: CEC Event Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 8
* .. _`CEC-EVENT-FL-INITIAL-STATE`:
- ``CEC_EVENT_FL_INITIAL_STATE``
- 1
- Set for the initial events that are generated when the device is
opened. See the table above for which events do this. This allows
applications to learn the initial state of the CEC adapter at
open() time.
* .. _`CEC-EVENT-FL-DROPPED-EVENTS`:
- ``CEC_EVENT_FL_DROPPED_EVENTS``
- 2
- Set if one or more events of the given event type have been dropped.
This is an indication that the application cannot keep up.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following
error codes:
EAGAIN
This is returned when the filehandle is in non-blocking mode and there
are no pending events.
ERESTARTSYS
An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for
events to arrive.
@@ -0,0 +1,293 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_MODE:
.. _CEC_G_MODE:
.. _CEC_S_MODE:
********************************
ioctls CEC_G_MODE and CEC_S_MODE
********************************
CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp )
:name: CEC_G_MODE
.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp )
:name: CEC_S_MODE
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Pointer to CEC mode.
Description
===========
By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
applications from stepping on each others toes it must be possible to
obtain exclusive access to the CEC adapter. This ioctl sets the
filehandle to initiator and/or follower mode which can be exclusive
depending on the chosen mode. The initiator is the filehandle that is
used to initiate messages, i.e. it commands other CEC devices. The
follower is the filehandle that receives messages sent to the CEC
adapter and processes them. The same filehandle can be both initiator
and follower, or this role can be taken by two different filehandles.
When a CEC message is received, then the CEC framework will decide how
it will be processed. If the message is a reply to an earlier
transmitted message, then the reply is sent back to the filehandle that
is waiting for it. In addition the CEC framework will process it.
If the message is not a reply, then the CEC framework will process it
first. If there is no follower, then the message is just discarded and a
feature abort is sent back to the initiator if the framework couldn't
process it. If there is a follower, then the message is passed on to the
follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
the new message. The framework expects the follower to make the right
decisions.
The CEC framework will process core messages unless requested otherwise
by the follower. The follower can enable the passthrough mode. In that
case, the CEC framework will pass on most core messages without
processing them and the follower will have to implement those messages.
There are some messages that the core will always process, regardless of
the passthrough mode. See :ref:`cec-core-processing` for details.
If there is no initiator, then any CEC filehandle can use
:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
initiator then only that initiator can call
:ref:`CEC_TRANSMIT`. The follower can of course
always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
Available initiator modes are:
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-mode-initiator_e:
.. flat-table:: Initiator Modes
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-MODE-NO-INITIATOR`:
- ``CEC_MODE_NO_INITIATOR``
- 0x0
- This is not an initiator, i.e. it cannot transmit CEC messages or
make any other changes to the CEC adapter.
* .. _`CEC-MODE-INITIATOR`:
- ``CEC_MODE_INITIATOR``
- 0x1
- This is an initiator (the default when the device is opened) and
it can transmit CEC messages and make changes to the CEC adapter,
unless there is an exclusive initiator.
* .. _`CEC-MODE-EXCL-INITIATOR`:
- ``CEC_MODE_EXCL_INITIATOR``
- 0x2
- This is an exclusive initiator and this file descriptor is the
only one that can transmit CEC messages and make changes to the
CEC adapter. If someone else is already the exclusive initiator
then an attempt to become one will return the ``EBUSY`` error code
error.
Available follower modes are:
.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}|
.. _cec-mode-follower_e:
.. cssclass:: longtable
.. flat-table:: Follower Modes
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-MODE-NO-FOLLOWER`:
- ``CEC_MODE_NO_FOLLOWER``
- 0x00
- This is not a follower (the default when the device is opened).
* .. _`CEC-MODE-FOLLOWER`:
- ``CEC_MODE_FOLLOWER``
- 0x10
- This is a follower and it will receive CEC messages unless there
is an exclusive follower. You cannot become a follower if
:ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
was specified, the ``EINVAL`` error code is returned in that case.
* .. _`CEC-MODE-EXCL-FOLLOWER`:
- ``CEC_MODE_EXCL_FOLLOWER``
- 0x20
- This is an exclusive follower and only this file descriptor will
receive CEC messages for processing. If someone else is already
the exclusive follower then an attempt to become one will return
the ``EBUSY`` error code. You cannot become a follower if
:ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
was specified, the ``EINVAL`` error code is returned in that case.
* .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
- ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
- 0x30
- This is an exclusive follower and only this file descriptor will
receive CEC messages for processing. In addition it will put the
CEC device into passthrough mode, allowing the exclusive follower
to handle most core messages instead of relying on the CEC
framework for that. If someone else is already the exclusive
follower then an attempt to become one will return the ``EBUSY`` error
code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
the ``EINVAL`` error code is returned in that case.
* .. _`CEC-MODE-MONITOR-PIN`:
- ``CEC_MODE_MONITOR_PIN``
- 0xd0
- Put the file descriptor into pin monitoring mode. Can only be used in
combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
otherwise the ``EINVAL`` error code will be returned.
This mode requires that the :ref:`CEC_CAP_MONITOR_PIN <CEC-CAP-MONITOR-PIN>`
capability is set, otherwise the ``EINVAL`` error code is returned.
While in pin monitoring mode this file descriptor can receive the
``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the
low-level CEC pin transitions. This is very useful for debugging.
This mode is only allowed if the process has the ``CAP_NET_ADMIN``
capability. If that is not set, then the ``EPERM`` error code is returned.
* .. _`CEC-MODE-MONITOR`:
- ``CEC_MODE_MONITOR``
- 0xe0
- Put the file descriptor into monitor mode. Can only be used in
combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,i
otherwise the ``EINVAL`` error code will be returned.
In monitor mode all messages this CEC
device transmits and all messages it receives (both broadcast
messages and directed messages for one its logical addresses) will
be reported. This is very useful for debugging. This is only
allowed if the process has the ``CAP_NET_ADMIN`` capability. If
that is not set, then the ``EPERM`` error code is returned.
* .. _`CEC-MODE-MONITOR-ALL`:
- ``CEC_MODE_MONITOR_ALL``
- 0xf0
- Put the file descriptor into 'monitor all' mode. Can only be used
in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
this CEC device transmits and all messages it receives, including
directed messages for other CEC devices will be reported. This is
very useful for debugging, but not all devices support this. This
mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
otherwise the ``EINVAL`` error code is returned. This is only allowed if
the process has the ``CAP_NET_ADMIN`` capability. If that is not
set, then the ``EPERM`` error code is returned.
Core message processing details:
.. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
.. _cec-core-processing:
.. flat-table:: Core Message Processing
:header-rows: 0
:stub-columns: 0
:widths: 1 8
* .. _`CEC-MSG-GET-CEC-VERSION`:
- ``CEC_MSG_GET_CEC_VERSION``
- The core will return the CEC version that was set with
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
except when in passthrough mode. In passthrough mode the core
does nothing and this message has to be handled by a follower
instead.
* .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
- ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
- The core will return the vendor ID that was set with
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
except when in passthrough mode. In passthrough mode the core
does nothing and this message has to be handled by a follower
instead.
* .. _`CEC-MSG-ABORT`:
- ``CEC_MSG_ABORT``
- The core will return a Feature Abort message with reason
'Feature Refused' as per the specification, except when in
passthrough mode. In passthrough mode the core does nothing
and this message has to be handled by a follower instead.
* .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
- ``CEC_MSG_GIVE_PHYSICAL_ADDR``
- The core will report the current physical address, except when
in passthrough mode. In passthrough mode the core does nothing
and this message has to be handled by a follower instead.
* .. _`CEC-MSG-GIVE-OSD-NAME`:
- ``CEC_MSG_GIVE_OSD_NAME``
- The core will report the current OSD name that was set with
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
except when in passthrough mode. In passthrough mode the core
does nothing and this message has to be handled by a follower
instead.
* .. _`CEC-MSG-GIVE-FEATURES`:
- ``CEC_MSG_GIVE_FEATURES``
- The core will do nothing if the CEC version is older than 2.0,
otherwise it will report the current features that were set with
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
except when in passthrough mode. In passthrough mode the core
does nothing (for any CEC version) and this message has to be handled
by a follower instead.
* .. _`CEC-MSG-USER-CONTROL-PRESSED`:
- ``CEC_MSG_USER_CONTROL_PRESSED``
- If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
:ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
is set, then generate a remote control key
press. This message is always passed on to the follower(s).
* .. _`CEC-MSG-USER-CONTROL-RELEASED`:
- ``CEC_MSG_USER_CONTROL_RELEASED``
- If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
:ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
is set, then generate a remote control key
release. This message is always passed on to the follower(s).
* .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
- ``CEC_MSG_REPORT_PHYSICAL_ADDR``
- The CEC framework will make note of the reported physical address
and then just pass the message on to the follower(s).
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following
error codes:
EINVAL
The requested mode is invalid.
EPERM
Monitor mode is requested without having root permissions
EBUSY
Someone else is already an exclusive follower or initiator.
@@ -0,0 +1,371 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_TRANSMIT:
.. _CEC_RECEIVE:
***********************************
ioctls CEC_RECEIVE and CEC_TRANSMIT
***********************************
Name
====
CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp )
:name: CEC_RECEIVE
.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp )
:name: CEC_TRANSMIT
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Pointer to struct cec_msg.
Description
===========
To receive a CEC message the application has to fill in the
``timeout`` field of struct :c:type:`cec_msg` and pass it to
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
If the file descriptor is in non-blocking mode and there are no received
messages pending, then it will return -1 and set errno to the ``EAGAIN``
error code. If the file descriptor is in blocking mode and ``timeout``
is non-zero and no message arrived within ``timeout`` milliseconds, then
it will return -1 and set errno to the ``ETIMEDOUT`` error code.
A received message can be:
1. a message received from another CEC device (the ``sequence`` field will
be 0).
2. the result of an earlier non-blocking transmit (the ``sequence`` field will
be non-zero).
To send a CEC message the application has to fill in the struct
:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if
``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
queue, then it will return -1 and set errno to the ``EBUSY`` error code.
The transmit queue has enough room for 18 messages (about 1 second worth
of 2-byte messages). Note that the CEC kernel framework will also reply
to core messages (see :ref:`cec-core-processing`), so it is not a good
idea to fully fill up the transmit queue.
If the file descriptor is in non-blocking mode then the transmit will
return 0 and the result of the transmit will be available via
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished
(including waiting for a reply, if requested).
The ``sequence`` field is filled in for every transmit and this can be
checked against the received messages to find the corresponding transmit
result.
Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical
address is invalid (due to e.g. a disconnect) will return ``ENONET``.
However, the CEC specification allows sending messages from 'Unregistered' to
'TV' when the physical address is invalid since some TVs pull the hotplug detect
pin of the HDMI connector low when they go into standby, or when switching to
another input.
When the hotplug detect pin goes low the EDID disappears, and thus the
physical address, but the cable is still connected and CEC still works.
In order to detect/wake up the device it is allowed to send poll and 'Image/Text
View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}|
.. c:type:: cec_msg
.. cssclass:: longtable
.. flat-table:: struct cec_msg
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
* - __u64
- ``tx_ts``
- Timestamp in ns of when the last byte of the message was transmitted.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
the same clock from userspace use :c:func:`clock_gettime`.
* - __u64
- ``rx_ts``
- Timestamp in ns of when the last byte of the message was received.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
the same clock from userspace use :c:func:`clock_gettime`.
* - __u32
- ``len``
- The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
by the application. The driver will fill this in for
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be
filled in by the driver with the length of the reply message if ``reply`` was set.
* - __u32
- ``timeout``
- The timeout in milliseconds. This is the time the device will wait
for a message to be received before timing out. If it is set to 0,
then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
then it will be replaced by 1000 if the ``reply`` is non-zero or
ignored if ``reply`` is 0.
* - __u32
- ``sequence``
- A non-zero sequence number is automatically assigned by the CEC framework
for all transmitted messages. It is used by the CEC framework when it queues
the transmit result (when transmit was called in non-blocking mode). This
allows the application to associate the received message with the original
transmit.
* - __u32
- ``flags``
- Flags. See :ref:`cec-msg-flags` for a list of available flags.
* - __u8
- ``tx_status``
- The status bits of the transmitted message. See
:ref:`cec-tx-status` for the possible status values. It is 0 if
this message was received, not transmitted.
* - __u8
- ``msg[16]``
- The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
the payload of the reply message if ``timeout`` was set.
* - __u8
- ``reply``
- Wait until this message is replied. If ``reply`` is 0 and the
``timeout`` is 0, then don't wait for a reply but return after
transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
The case where ``reply`` is 0 (this is the opcode for the Feature Abort
message) and ``timeout`` is non-zero is specifically allowed to make it
possible to send a message and wait up to ``timeout`` milliseconds for a
Feature Abort reply. In this case ``rx_status`` will either be set
to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
:ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply``
values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED``
are processed differently: either value will match both possible replies.
The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC
message that has two possible replies other than Feature Abort. The
``reply`` field will be updated with the actual reply so that it is
synchronized with the contents of the received message.
* - __u8
- ``rx_status``
- The status bits of the received message. See
:ref:`cec-rx-status` for the possible status values. It is 0 if
this message was transmitted, not received, unless this is the
reply to a transmitted message. In that case both ``rx_status``
and ``tx_status`` are set.
* - __u8
- ``tx_status``
- The status bits of the transmitted message. See
:ref:`cec-tx-status` for the possible status values. It is 0 if
this message was received, not transmitted.
* - __u8
- ``tx_arb_lost_cnt``
- A counter of the number of transmit attempts that resulted in the
Arbitration Lost error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
* - __u8
- ``tx_nack_cnt``
- A counter of the number of transmit attempts that resulted in the
Not Acknowledged error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
* - __u8
- ``tx_low_drive_cnt``
- A counter of the number of transmit attempts that resulted in the
Arbitration Lost error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
* - __u8
- ``tx_error_cnt``
- A counter of the number of transmit errors other than Arbitration
Lost or Not Acknowledged. This is only set if the hardware
supports this, otherwise it is always 0. This counter is only
valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}|
.. _cec-msg-flags:
.. flat-table:: Flags for struct cec_msg
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
- ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``
- 1
- If a CEC transmit expects a reply, then by default that reply is only sent to
the filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If this
flag is set, then the reply is also sent to all followers, if any. If the
filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is also a
follower, then that filehandle will receive the reply twice: once as the
result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-tx-status:
.. flat-table:: CEC Transmit Status
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-TX-STATUS-OK`:
- ``CEC_TX_STATUS_OK``
- 0x01
- The message was transmitted successfully. This is mutually
exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`.
Other bits can still be set if earlier attempts met with failure before
the transmit was eventually successful.
* .. _`CEC-TX-STATUS-ARB-LOST`:
- ``CEC_TX_STATUS_ARB_LOST``
- 0x02
- CEC line arbitration was lost, i.e. another transmit started at the
same time with a higher priority. Optional status, not all hardware
can detect this error condition.
* .. _`CEC-TX-STATUS-NACK`:
- ``CEC_TX_STATUS_NACK``
- 0x04
- Message was not acknowledged. Note that some hardware cannot tell apart
a 'Not Acknowledged' status from other error conditions, i.e. the result
of a transmit is just OK or FAIL. In that case this status will be
returned when the transmit failed.
* .. _`CEC-TX-STATUS-LOW-DRIVE`:
- ``CEC_TX_STATUS_LOW_DRIVE``
- 0x08
- Low drive was detected on the CEC bus. This indicates that a
follower detected an error on the bus and requests a
retransmission. Optional status, not all hardware can detect this
error condition.
* .. _`CEC-TX-STATUS-ERROR`:
- ``CEC_TX_STATUS_ERROR``
- 0x10
- Some error occurred. This is used for any errors that do not fit
``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because
the hardware could not tell which error occurred, or because the hardware
tested for other conditions besides those two. Optional status.
* .. _`CEC-TX-STATUS-MAX-RETRIES`:
- ``CEC_TX_STATUS_MAX_RETRIES``
- 0x20
- The transmit failed after one or more retries. This status bit is
mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`.
Other bits can still be set to explain which failures were seen.
* .. _`CEC-TX-STATUS-ABORTED`:
- ``CEC_TX_STATUS_ABORTED``
- 0x40
- The transmit was aborted due to an HDMI disconnect, or the adapter
was unconfigured, or a transmit was interrupted, or the driver
returned an error when attempting to start a transmit.
* .. _`CEC-TX-STATUS-TIMEOUT`:
- ``CEC_TX_STATUS_TIMEOUT``
- 0x80
- The transmit timed out. This should not normally happen and this
indicates a driver problem.
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-rx-status:
.. flat-table:: CEC Receive Status
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-RX-STATUS-OK`:
- ``CEC_RX_STATUS_OK``
- 0x01
- The message was received successfully.
* .. _`CEC-RX-STATUS-TIMEOUT`:
- ``CEC_RX_STATUS_TIMEOUT``
- 0x02
- The reply to an earlier transmitted message timed out.
* .. _`CEC-RX-STATUS-FEATURE-ABORT`:
- ``CEC_RX_STATUS_FEATURE_ABORT``
- 0x04
- The message was received successfully but the reply was
``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
was the reply to an earlier transmitted message.
* .. _`CEC-RX-STATUS-ABORTED`:
- ``CEC_RX_STATUS_ABORTED``
- 0x08
- The wait for a reply to an earlier transmitted message was aborted
because the HDMI cable was disconnected, the adapter was unconfigured
or the :ref:`CEC_TRANSMIT <CEC_RECEIVE>` that waited for a
reply was interrupted.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can return the following
error codes:
EAGAIN
No messages are in the receive queue, and the filehandle is in non-blocking mode.
ETIMEDOUT
The ``timeout`` was reached while waiting for a message.
ERESTARTSYS
The wait for a message was interrupted (e.g. by Ctrl-C).
The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` can return the following
error codes:
ENOTTY
The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported.
EPERM
The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
has never been called.
ENONET
The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
was called, but the physical address is invalid so no logical address was claimed.
An exception is made in this case for transmits from initiator 0xf ('Unregistered')
to destination 0 ('TV'). In that case the transmit will proceed as usual.
EBUSY
Another filehandle is in exclusive follower or initiator mode, or the filehandle
is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit
queue is full.
EINVAL
The contents of struct :c:type:`cec_msg` is invalid.
ERESTARTSYS
The wait for a successful transmit was interrupted (e.g. by Ctrl-C).
@@ -0,0 +1,325 @@
CEC Pin Framework Error Injection
=================================
The CEC Pin Framework is a core CEC framework for CEC hardware that only
has low-level support for the CEC bus. Most hardware today will have
high-level CEC support where the hardware deals with driving the CEC bus,
but some older devices aren't that fancy. However, this framework also
allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and
you have now made a CEC adapter.
What makes doing this so interesting is that since we have full control
over the bus it is easy to support error injection. This is ideal to
test how well CEC adapters can handle error conditions.
Currently only the cec-gpio driver (when the CEC line is directly
connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver
support this framework.
If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available
through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is
now an ``error-inj`` file.
.. note::
The error injection commands are not a stable ABI and may change in the
future.
With ``cat error-inj`` you can see both the possible commands and the current
error injection status::
$ cat /sys/kernel/debug/cec/cec0/error-inj
# Clear error injections:
# clear clear all rx and tx error injections
# rx-clear clear all rx error injections
# tx-clear clear all tx error injections
# <op> clear clear all rx and tx error injections for <op>
# <op> rx-clear clear all rx error injections for <op>
# <op> tx-clear clear all tx error injections for <op>
#
# RX error injection:
# <op>[,<mode>] rx-nack NACK the message instead of sending an ACK
# <op>[,<mode>] rx-low-drive <bit> force a low-drive condition at this bit position
# <op>[,<mode>] rx-add-byte add a spurious byte to the received CEC message
# <op>[,<mode>] rx-remove-byte remove the last byte from the received CEC message
# <op>[,<mode>] rx-arb-lost <poll> generate a POLL message to trigger an arbitration lost
#
# TX error injection settings:
# tx-ignore-nack-until-eom ignore early NACKs until EOM
# tx-custom-low-usecs <usecs> define the 'low' time for the custom pulse
# tx-custom-high-usecs <usecs> define the 'high' time for the custom pulse
# tx-custom-pulse transmit the custom pulse once the bus is idle
#
# TX error injection:
# <op>[,<mode>] tx-no-eom don't set the EOM bit
# <op>[,<mode>] tx-early-eom set the EOM bit one byte too soon
# <op>[,<mode>] tx-add-bytes <num> append <num> (1-255) spurious bytes to the message
# <op>[,<mode>] tx-remove-byte drop the last byte from the message
# <op>[,<mode>] tx-short-bit <bit> make this bit shorter than allowed
# <op>[,<mode>] tx-long-bit <bit> make this bit longer than allowed
# <op>[,<mode>] tx-custom-bit <bit> send the custom pulse instead of this bit
# <op>[,<mode>] tx-short-start send a start pulse that's too short
# <op>[,<mode>] tx-long-start send a start pulse that's too long
# <op>[,<mode>] tx-custom-start send the custom pulse instead of the start pulse
# <op>[,<mode>] tx-last-bit <bit> stop sending after this bit
# <op>[,<mode>] tx-low-drive <bit> force a low-drive condition at this bit position
#
# <op> CEC message opcode (0-255) or 'any'
# <mode> 'once' (default), 'always', 'toggle' or 'off'
# <bit> CEC message bit (0-159)
# 10 bits per 'byte': bits 0-7: data, bit 8: EOM, bit 9: ACK
# <poll> CEC poll message used to test arbitration lost (0x00-0xff, default 0x0f)
# <usecs> microseconds (0-10000000, default 1000)
clear
You can write error injection commands to ``error-inj`` using
``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj``
output contains the current error commands. You can save the output to a file
and use it as an input to ``error-inj`` later.
Basic Syntax
------------
Leading spaces/tabs are ignored. If the next character is a ``#`` or the end
of the line was reached, then the whole line is ignored. Otherwise a command
is expected.
The error injection commands fall in two main groups: those relating to
receiving CEC messages and those relating to transmitting CEC messages. In
addition, there are commands to clear existing error injection commands and
to create custom pulses on the CEC bus.
Most error injection commands can be executed for specific CEC opcodes or for
all opcodes (``any``). Each command also has a 'mode' which can be ``off``
(can be used to turn off an existing error injection command), ``once``
(the default) which will trigger the error injection only once for the next
received or transmitted message, ``always`` to always trigger the error
injection and ``toggle`` to toggle the error injection on or off for every
transmit or receive.
So '``any rx-nack``' will NACK the next received CEC message,
'``any,always rx-nack``' will NACK all received CEC messages and
'``0x82,toggle rx-nack``' will only NACK if an Active Source message was
received and do that only for every other received message.
After an error was injected with mode ``once`` the error injection command
is cleared automatically, so ``once`` is a one-time deal.
All combinations of ``<op>`` and error injection commands can co-exist. So
this is fine::
0x9e tx-add-bytes 1
0x9e tx-early-eom
0x9f tx-add-bytes 2
any rx-nack
All four error injection commands will be active simultaneously.
However, if the same ``<op>`` and command combination is specified,
but with different arguments::
0x9e tx-add-bytes 1
0x9e tx-add-bytes 2
Then the second will overwrite the first.
Clear Error Injections
----------------------
``clear``
Clear all error injections.
``rx-clear``
Clear all receive error injections
``tx-clear``
Clear all transmit error injections
``<op> clear``
Clear all error injections for the given opcode.
``<op> rx-clear``
Clear all receive error injections for the given opcode.
``<op> tx-clear``
Clear all transmit error injections for the given opcode.
Receive Messages
----------------
``<op>[,<mode>] rx-nack``
NACK broadcast messages and messages directed to this CEC adapter.
Every byte of the message will be NACKed in case the transmitter
keeps transmitting after the first byte was NACKed.
``<op>[,<mode>] rx-low-drive <bit>``
Force a Low Drive condition at this bit position. If <op> specifies
a specific CEC opcode then the bit position must be at least 18,
otherwise the opcode hasn't been received yet. This tests if the
transmitter can handle the Low Drive condition correctly and reports
the error correctly. Note that a Low Drive in the first 4 bits can also
be interpreted as an Arbitration Lost condition by the transmitter.
This is implementation dependent.
``<op>[,<mode>] rx-add-byte``
Add a spurious 0x55 byte to the received CEC message, provided
the message was 15 bytes long or less. This is useful to test
the high-level protocol since spurious bytes should be ignored.
``<op>[,<mode>] rx-remove-byte``
Remove the last byte from the received CEC message, provided it
was at least 2 bytes long. This is useful to test the high-level
protocol since messages that are too short should be ignored.
``<op>[,<mode>] rx-arb-lost <poll>``
Generate a POLL message to trigger an Arbitration Lost condition.
This command is only allowed for ``<op>`` values of ``next`` or ``all``.
As soon as a start bit has been received the CEC adapter will switch
to transmit mode and it will transmit a POLL message. By default this is
0x0f, but it can also be specified explicitly via the ``<poll>`` argument.
This command can be used to test the Arbitration Lost condition in
the remote CEC transmitter. Arbitration happens when two CEC adapters
start sending a message at the same time. In that case the initiator
with the most leading zeroes wins and the other transmitter has to
stop transmitting ('Arbitration Lost'). This is very hard to test,
except by using this error injection command.
This does not work if the remote CEC transmitter has logical address
0 ('TV') since that will always win.
Transmit Messages
-----------------
``tx-ignore-nack-until-eom``
This setting changes the behavior of transmitting CEC messages. Normally
as soon as the receiver NACKs a byte the transmit will stop, but the
specification also allows that the full message is transmitted and only
at the end will the transmitter look at the ACK bit. This is not
recommended behavior since there is no point in keeping the CEC bus busy
for longer than is strictly needed. Especially given how slow the bus is.
This setting can be used to test how well a receiver deals with
transmitters that ignore NACKs until the very end of the message.
``<op>[,<mode>] tx-no-eom``
Don't set the EOM bit. Normally the last byte of the message has the EOM
(End-Of-Message) bit set. With this command the transmit will just stop
without ever sending an EOM. This can be used to test how a receiver
handles this case. Normally receivers have a time-out after which
they will go back to the Idle state.
``<op>[,<mode>] tx-early-eom``
Set the EOM bit one byte too soon. This obviously only works for messages
of two bytes or more. The EOM bit will be set for the second-to-last byte
and not for the final byte. The receiver should ignore the last byte in
this case. Since the resulting message is likely to be too short for this
same reason the whole message is typically ignored. The receiver should be
in Idle state after the last byte was transmitted.
``<op>[,<mode>] tx-add-bytes <num>``
Append ``<num>`` (1-255) spurious bytes to the message. The extra bytes
have the value of the byte position in the message. So if you transmit a
two byte message (e.g. a Get CEC Version message) and add 2 bytes, then
the full message received by the remote CEC adapter is
``0x40 0x9f 0x02 0x03``.
This command can be used to test buffer overflows in the receiver. E.g.
what does it do when it receives more than the maximum message size of 16
bytes.
``<op>[,<mode>] tx-remove-byte``
Drop the last byte from the message, provided the message is at least
two bytes long. The receiver should ignore messages that are too short.
``<op>[,<mode>] tx-short-bit <bit>``
Make this bit period shorter than allowed. The bit position cannot be
an Ack bit. If <op> specifies a specific CEC opcode then the bit position
must be at least 18, otherwise the opcode hasn't been received yet.
Normally the period of a data bit is between 2.05 and 2.75 milliseconds.
With this command the period of this bit is 1.8 milliseconds, this is
done by reducing the time the CEC bus is high. This bit period is less
than is allowed and the receiver should respond with a Low Drive
condition.
This command is ignored for 0 bits in bit positions 0 to 3. This is
because the receiver also looks for an Arbitration Lost condition in
those first four bits and it is undefined what will happen if it
sees a too-short 0 bit.
``<op>[,<mode>] tx-long-bit <bit>``
Make this bit period longer than is valid. The bit position cannot be
an Ack bit. If <op> specifies a specific CEC opcode then the bit position
must be at least 18, otherwise the opcode hasn't been received yet.
Normally the period of a data bit is between 2.05 and 2.75 milliseconds.
With this command the period of this bit is 2.9 milliseconds, this is
done by increasing the time the CEC bus is high.
Even though this bit period is longer than is valid it is undefined what
a receiver will do. It might just accept it, or it might time out and
return to Idle state. Unfortunately the CEC specification is silent about
this.
This command is ignored for 0 bits in bit positions 0 to 3. This is
because the receiver also looks for an Arbitration Lost condition in
those first four bits and it is undefined what will happen if it
sees a too-long 0 bit.
``<op>[,<mode>] tx-short-start``
Make this start bit period shorter than allowed. Normally the period of
a start bit is between 4.3 and 4.7 milliseconds. With this command the
period of the start bit is 4.1 milliseconds, this is done by reducing
the time the CEC bus is high. This start bit period is less than is
allowed and the receiver should return to Idle state when this is detected.
``<op>[,<mode>] tx-long-start``
Make this start bit period longer than is valid. Normally the period of
a start bit is between 4.3 and 4.7 milliseconds. With this command the
period of the start bit is 5 milliseconds, this is done by increasing
the time the CEC bus is high. This start bit period is more than is
valid and the receiver should return to Idle state when this is detected.
Even though this start bit period is longer than is valid it is undefined
what a receiver will do. It might just accept it, or it might time out and
return to Idle state. Unfortunately the CEC specification is silent about
this.
``<op>[,<mode>] tx-last-bit <bit>``
Just stop transmitting after this bit. If <op> specifies a specific CEC
opcode then the bit position must be at least 18, otherwise the opcode
hasn't been received yet. This command can be used to test how the receiver
reacts when a message just suddenly stops. It should time out and go back
to Idle state.
``<op>[,<mode>] tx-low-drive <bit>``
Force a Low Drive condition at this bit position. If <op> specifies a
specific CEC opcode then the bit position must be at least 18, otherwise
the opcode hasn't been received yet. This can be used to test how the
receiver handles Low Drive conditions. Note that if this happens at bit
positions 0-3 the receiver can interpret this as an Arbitration Lost
condition. This is implementation dependent.
Custom Pulses
-------------
``tx-custom-low-usecs <usecs>``
This defines the duration in microseconds that the custom pulse pulls
the CEC line low. The default is 1000 microseconds.
``tx-custom-high-usecs <usecs>``
This defines the duration in microseconds that the custom pulse keeps the
CEC line high (unless another CEC adapter pulls it low in that time).
The default is 1000 microseconds. The total period of the custom pulse is
``tx-custom-low-usecs + tx-custom-high-usecs``.
``<op>[,<mode>] tx-custom-bit <bit>``
Send the custom bit instead of a regular data bit. The bit position cannot
be an Ack bit. If <op> specifies a specific CEC opcode then the bit
position must be at least 18, otherwise the opcode hasn't been received yet.
``<op>[,<mode>] tx-custom-start``
Send the custom bit instead of a regular start bit.
``tx-custom-pulse``
Transmit a single custom pulse as soon as the CEC bus is idle.