^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. c:namespace:: CEC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _CEC_TRANSMIT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) .. _CEC_RECEIVE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ***********************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ioctls CEC_RECEIVE and CEC_TRANSMIT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) ***********************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) .. c:macro:: CEC_RECEIVE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) ``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) .. c:macro:: CEC_TRANSMIT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) ``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) ``argp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Pointer to struct cec_msg.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) To receive a CEC message the application has to fill in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) ``timeout`` field of struct :c:type:`cec_msg` and pass it to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) If the file descriptor is in non-blocking mode and there are no received
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) messages pending, then it will return -1 and set errno to the ``EAGAIN``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) error code. If the file descriptor is in blocking mode and ``timeout``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) is non-zero and no message arrived within ``timeout`` milliseconds, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) it will return -1 and set errno to the ``ETIMEDOUT`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) A received message can be:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 1. a message received from another CEC device (the ``sequence`` field will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) be 0).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) 2. the result of an earlier non-blocking transmit (the ``sequence`` field will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) be non-zero).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) To send a CEC message the application has to fill in the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) :c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) ``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) queue, then it will return -1 and set errno to the ``EBUSY`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) The transmit queue has enough room for 18 messages (about 1 second worth
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) of 2-byte messages). Note that the CEC kernel framework will also reply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) to core messages (see :ref:`cec-core-processing`), so it is not a good
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) idea to fully fill up the transmit queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) If the file descriptor is in non-blocking mode then the transmit will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) return 0 and the result of the transmit will be available via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) (including waiting for a reply, if requested).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) The ``sequence`` field is filled in for every transmit and this can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) checked against the received messages to find the corresponding transmit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) result.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) address is invalid (due to e.g. a disconnect) will return ``ENONET``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) However, the CEC specification allows sending messages from 'Unregistered' to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) 'TV' when the physical address is invalid since some TVs pull the hotplug detect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) pin of the HDMI connector low when they go into standby, or when switching to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) another input.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) When the hotplug detect pin goes low the EDID disappears, and thus the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) physical address, but the cable is still connected and CEC still works.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) In order to detect/wake up the device it is allowed to send poll and 'Image/Text
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) .. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) .. c:type:: cec_msg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) .. cssclass:: longtable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) .. flat-table:: struct cec_msg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) :widths: 1 1 16
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) * - __u64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) - ``tx_ts``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) - Timestamp in ns of when the last byte of the message was transmitted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) the same clock from userspace use :c:func:`clock_gettime`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) * - __u64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) - ``rx_ts``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) - Timestamp in ns of when the last byte of the message was received.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) the same clock from userspace use :c:func:`clock_gettime`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) - ``len``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) - The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) by the application. The driver will fill this in for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) filled in by the driver with the length of the reply message if ``reply`` was set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) - ``timeout``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) - The timeout in milliseconds. This is the time the device will wait
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) for a message to be received before timing out. If it is set to 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) then it will be replaced by 1000 if the ``reply`` is non-zero or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) ignored if ``reply`` is 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) - ``sequence``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) - A non-zero sequence number is automatically assigned by the CEC framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) for all transmitted messages. It is used by the CEC framework when it queues
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) the transmit result (when transmit was called in non-blocking mode). This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) allows the application to associate the received message with the original
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) transmit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) - Flags. See :ref:`cec-msg-flags` for a list of available flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) - ``tx_status``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) - The status bits of the transmitted message. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) :ref:`cec-tx-status` for the possible status values. It is 0 if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) this message was received, not transmitted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) - ``msg[16]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) the payload of the reply message if ``timeout`` was set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) - ``reply``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) - Wait until this message is replied. If ``reply`` is 0 and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) ``timeout`` is 0, then don't wait for a reply but return after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) The case where ``reply`` is 0 (this is the opcode for the Feature Abort
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) message) and ``timeout`` is non-zero is specifically allowed to make it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) possible to send a message and wait up to ``timeout`` milliseconds for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) Feature Abort reply. In this case ``rx_status`` will either be set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) are processed differently: either value will match both possible replies.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) message that has two possible replies other than Feature Abort. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) ``reply`` field will be updated with the actual reply so that it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) synchronized with the contents of the received message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) - ``rx_status``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) - The status bits of the received message. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) :ref:`cec-rx-status` for the possible status values. It is 0 if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) this message was transmitted, not received, unless this is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) reply to a transmitted message. In that case both ``rx_status``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) and ``tx_status`` are set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) - ``tx_status``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) - The status bits of the transmitted message. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) :ref:`cec-tx-status` for the possible status values. It is 0 if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) this message was received, not transmitted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) - ``tx_arb_lost_cnt``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) - A counter of the number of transmit attempts that resulted in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) Arbitration Lost error. This is only set if the hardware supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) this, otherwise it is always 0. This counter is only valid if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) - ``tx_nack_cnt``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) - A counter of the number of transmit attempts that resulted in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) Not Acknowledged error. This is only set if the hardware supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) this, otherwise it is always 0. This counter is only valid if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) - ``tx_low_drive_cnt``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) - A counter of the number of transmit attempts that resulted in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Arbitration Lost error. This is only set if the hardware supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) this, otherwise it is always 0. This counter is only valid if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) - ``tx_error_cnt``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) - A counter of the number of transmit errors other than Arbitration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) Lost or Not Acknowledged. This is only set if the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) supports this, otherwise it is always 0. This counter is only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) .. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) .. _cec-msg-flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) .. flat-table:: Flags for struct cec_msg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) :widths: 3 1 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) - 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) - If a CEC transmit expects a reply, then by default that reply is only sent to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) the filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) flag is set, then the reply is also sent to all followers, if any. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is also a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) follower, then that filehandle will receive the reply twice: once as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) * .. _`CEC-MSG-FL-RAW`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) - ``CEC_MSG_FL_RAW``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) - 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) - Normally CEC messages are validated before transmitting them. If this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) flag is set when :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is called,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) then no validation takes place and the message is transmitted as-is.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) This is useful when debugging CEC issues.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) This flag is only allowed if the process has the ``CAP_SYS_RAWIO``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) capability. If that is not set, then the ``EPERM`` error code is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) .. _cec-tx-status:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) .. flat-table:: CEC Transmit Status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) :widths: 3 1 16
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) * .. _`CEC-TX-STATUS-OK`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) - ``CEC_TX_STATUS_OK``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) - 0x01
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) - The message was transmitted successfully. This is mutually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) Other bits can still be set if earlier attempts met with failure before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) the transmit was eventually successful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) * .. _`CEC-TX-STATUS-ARB-LOST`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) - ``CEC_TX_STATUS_ARB_LOST``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) - 0x02
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) - CEC line arbitration was lost, i.e. another transmit started at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) same time with a higher priority. Optional status, not all hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) can detect this error condition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) * .. _`CEC-TX-STATUS-NACK`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) - ``CEC_TX_STATUS_NACK``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) - 0x04
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) - Message was not acknowledged. Note that some hardware cannot tell apart
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) a 'Not Acknowledged' status from other error conditions, i.e. the result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) of a transmit is just OK or FAIL. In that case this status will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) returned when the transmit failed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) * .. _`CEC-TX-STATUS-LOW-DRIVE`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) - ``CEC_TX_STATUS_LOW_DRIVE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) - 0x08
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) - Low drive was detected on the CEC bus. This indicates that a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) follower detected an error on the bus and requests a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) retransmission. Optional status, not all hardware can detect this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) error condition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) * .. _`CEC-TX-STATUS-ERROR`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) - ``CEC_TX_STATUS_ERROR``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) - 0x10
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) - Some error occurred. This is used for any errors that do not fit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) the hardware could not tell which error occurred, or because the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) tested for other conditions besides those two. Optional status.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) * .. _`CEC-TX-STATUS-MAX-RETRIES`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) - ``CEC_TX_STATUS_MAX_RETRIES``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) - 0x20
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) - The transmit failed after one or more retries. This status bit is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) Other bits can still be set to explain which failures were seen.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) * .. _`CEC-TX-STATUS-ABORTED`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) - ``CEC_TX_STATUS_ABORTED``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) - 0x40
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) - The transmit was aborted due to an HDMI disconnect, or the adapter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) was unconfigured, or a transmit was interrupted, or the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) returned an error when attempting to start a transmit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) * .. _`CEC-TX-STATUS-TIMEOUT`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) - ``CEC_TX_STATUS_TIMEOUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) - 0x80
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) - The transmit timed out. This should not normally happen and this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) indicates a driver problem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) .. _cec-rx-status:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) .. flat-table:: CEC Receive Status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) :widths: 3 1 16
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) * .. _`CEC-RX-STATUS-OK`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) - ``CEC_RX_STATUS_OK``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) - 0x01
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) - The message was received successfully.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) * .. _`CEC-RX-STATUS-TIMEOUT`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) - ``CEC_RX_STATUS_TIMEOUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) - 0x02
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) - The reply to an earlier transmitted message timed out.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) - ``CEC_RX_STATUS_FEATURE_ABORT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) - 0x04
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) - The message was received successfully but the reply was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) was the reply to an earlier transmitted message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) * .. _`CEC-RX-STATUS-ABORTED`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) - ``CEC_RX_STATUS_ABORTED``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) - 0x08
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) - The wait for a reply to an earlier transmitted message was aborted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) because the HDMI cable was disconnected, the adapter was unconfigured
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) or the :ref:`CEC_TRANSMIT <CEC_RECEIVE>` that waited for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) reply was interrupted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) On success 0 is returned, on error -1 and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) appropriately. The generic error codes are described at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) :ref:`Generic Error Codes <gen-errors>` chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can return the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) error codes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) EAGAIN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) No messages are in the receive queue, and the filehandle is in non-blocking mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) ETIMEDOUT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) The ``timeout`` was reached while waiting for a message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) ERESTARTSYS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) The wait for a message was interrupted (e.g. by Ctrl-C).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` can return the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) error codes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) ENOTTY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) EPERM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) has never been called, or ``CEC_MSG_FL_RAW`` was used from a process that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) did not have the ``CAP_SYS_RAWIO`` capability.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) ENONET
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) was called, but the physical address is invalid so no logical address was claimed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) An exception is made in this case for transmits from initiator 0xf ('Unregistered')
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) to destination 0 ('TV'). In that case the transmit will proceed as usual.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) EBUSY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) Another filehandle is in exclusive follower or initiator mode, or the filehandle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) queue is full.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) The contents of struct :c:type:`cec_msg` is invalid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) ERESTARTSYS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) The wait for a successful transmit was interrupted (e.g. by Ctrl-C).
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags