summaryrefslogtreecommitdiff
path: root/Documentation/userspace-api
diff options
context:
space:
mode:
authorHans Verkuil <hverkuil-cisco@xs4all.nl>2021-11-02 12:24:27 +0000
committerMauro Carvalho Chehab <mchehab+huawei@kernel.org>2021-11-15 08:12:03 +0000
commit0a1c80c6570005ddc516cf649e0ced76c3d680e5 (patch)
treee8046604bb2c1387f3ebc323b45324a84955d474 /Documentation/userspace-api
parentd7894721f73bf5f135233625985a17043fa836a2 (diff)
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>
Diffstat (limited to 'Documentation/userspace-api')
-rw-r--r--Documentation/userspace-api/media/cec/cec-ioc-receive.rst49
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