diff options
Diffstat (limited to 'Documentation/userspace-api/media/cec/cec-ioc-receive.rst')
| -rw-r--r-- | Documentation/userspace-api/media/cec/cec-ioc-receive.rst | 49 |
1 files changed, 26 insertions, 23 deletions
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst index bd7f7e7235cb..364938ad34df 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst @@ -48,9 +48,12 @@ 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). + be 0, ``tx_status`` will be 0 and ``rx_status`` will be non-zero). +2. the transmit result of an earlier non-blocking transmit (the ``sequence`` + field will be non-zero, ``tx_status`` will be non-zero and ``rx_status`` + will be 0). +3. the reply to an earlier non-blocking transmit (the ``sequence`` field will + be non-zero, ``tx_status`` will be 0 and ``rx_status`` 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>`. @@ -64,12 +67,11 @@ 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. +:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished. +If a non-blocking transmit also specified waiting for a reply, then +the reply will arrive in a later message. The ``sequence`` field can +be used to associate both transmit results and replies with the original +transmit. Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical address is invalid (due to e.g. a disconnect) will return ``ENONET``. @@ -123,18 +125,17 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - ``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. + the transmit result for a non-blocking transmit. This allows the application + to associate the received message with the original transmit. + + In addition, if a non-blocking transmit will wait for a reply (ii.e. ``timeout`` + was not 0), then the ``sequence`` field of the reply will be set to the sequence + value of the original transmit. 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>`. @@ -162,15 +163,17 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). * - __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. + :ref:`cec-rx-status` for the possible status values. * - __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. + :ref:`cec-tx-status` for the possible status values. + When calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` in non-blocking mode, + this field will be 0 if the transmit started, or non-0 if the transmit + result is known immediately. The latter would be the case when attempting + to transmit a Poll message to yourself. That results in a + :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` without ever actually + transmitting the Poll message. * - __u8 - ``tx_arb_lost_cnt`` - A counter of the number of transmit attempts that resulted in the |