media: cec-ioc-receive.rst: clarify sequence and status fields

Improve the documentation for CEC_RECEIVE/TRANSMIT w.r.t. the
sequence and tx/rx_status fields.

Also remove a duplicate tx_status description.

Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
index bd7f7e7235cbfd494883e83f60b379823b1dd261..364938ad34df91dde335b628e163934f44022086 100644 (file)
--- 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,17 +125,16 @@ 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
@@ -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