diff options
Diffstat (limited to 'Documentation/media/uapi/cec/cec-ioc-receive.rst')
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-receive.rst | 423 |
1 files changed, 172 insertions, 251 deletions
diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst index d585b1bba6ac..dc2adb391c0a 100644 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst @@ -34,11 +34,6 @@ Arguments Description =========== -.. note:: - - This documents the proposed CEC API. This API is not yet finalized - and is currently only available as a staging kernel module. - 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>`. @@ -86,173 +81,126 @@ result. :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 messages 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 messages 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. + + +.. _cec-msg-flags: + +.. flat-table:: Flags for struct cec_msg + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 - - .. row 1 - - - __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`. - - - .. row 2 - - - __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`. - - - .. row 3 - - - __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. - - - .. row 4 - - - __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. - - - .. row 5 - - - __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. - - - .. row 6 - - - __u32 - - - ``flags`` - - - Flags. No flags are defined yet, so set this to 0. - - - .. row 7 - - - __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 messages was received, not transmitted. - - - .. row 8 - - - __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. - - - .. row 8 - - - __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>`. - - - .. row 9 - - - __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. - - - .. row 10 - - - __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 messages was received, not transmitted. - - - .. row 11 - - - __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. - - - .. row 12 - - - __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. - - - .. row 13 - - - __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. - - - .. row 14 - - - __u8 - - - ``tx_error_cnt`` + * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`: - - 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. + - ``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}| @@ -264,64 +212,46 @@ result. :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. - - - .. _`CEC-TX-STATUS-NACK`: - - - ``CEC_TX_STATUS_NACK`` - - - 0x04 - - - Message was not acknowledged. - - - .. _`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. - - - .. _`CEC-TX-STATUS-ERROR`: - - - ``CEC_TX_STATUS_ERROR`` - - - 0x10 - - - Some error occurred. This is used for any errors that do not fit - the previous two, either because the hardware could not tell which - error occurred, or because the hardware tested for other - conditions besides those two. - - - .. _`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-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. + * .. _`CEC-TX-STATUS-NACK`: + + - ``CEC_TX_STATUS_NACK`` + - 0x04 + - Message was not acknowledged. + * .. _`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. + * .. _`CEC-TX-STATUS-ERROR`: + + - ``CEC_TX_STATUS_ERROR`` + - 0x10 + - Some error occurred. This is used for any errors that do not fit + the previous two, either because the hardware could not tell which + error occurred, or because the hardware tested for other + conditions besides those two. + * .. _`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. .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| @@ -333,32 +263,23 @@ result. :stub-columns: 0 :widths: 3 1 16 + * .. _`CEC-RX-STATUS-OK`: - - .. _`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`` + - ``CEC_RX_STATUS_OK`` + - 0x01 + - The message was received successfully. + * .. _`CEC-RX-STATUS-TIMEOUT`: - - 0x04 + - ``CEC_RX_STATUS_TIMEOUT`` + - 0x02 + - The reply to an earlier transmitted message timed out. + * .. _`CEC-RX-STATUS-FEATURE-ABORT`: - - 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_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. |