0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: CEC
0003
0004 .. _CEC_DQEVENT:
0005
0006 *****************
0007 ioctl CEC_DQEVENT
0008 *****************
0009
0010 Name
0011 ====
0012
0013 CEC_DQEVENT - Dequeue a CEC event
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: CEC_DQEVENT
0019
0020 ``int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029
0030 Description
0031 ===========
0032
0033 CEC devices can send asynchronous events. These can be retrieved by
0034 calling :c:func:`CEC_DQEVENT`. If the file descriptor is in
0035 non-blocking mode and no event is pending, then it will return -1 and
0036 set errno to the ``EAGAIN`` error code.
0037
0038 The internal event queues are per-filehandle and per-event type. If
0039 there is no more room in a queue then the last event is overwritten with
0040 the new one. This means that intermediate results can be thrown away but
0041 that the latest event is always available. This also means that is it
0042 possible to read two successive events that have the same value (e.g.
0043 two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with
0044 the same state). In that case the intermediate state changes were lost but
0045 it is guaranteed that the state did change in between the two events.
0046
0047 .. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.2cm}|
0048
0049 .. c:type:: cec_event_state_change
0050
0051 .. flat-table:: struct cec_event_state_change
0052 :header-rows: 0
0053 :stub-columns: 0
0054 :widths: 1 1 8
0055
0056 * - __u16
0057 - ``phys_addr``
0058 - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no
0059 valid physical address is set.
0060 * - __u16
0061 - ``log_addr_mask``
0062 - The current set of claimed logical addresses. This is 0 if no logical
0063 addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``.
0064 If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device
0065 has the unregistered logical address. In that case all other bits are 0.
0066 * - __u16
0067 - ``have_conn_info``
0068 - If non-zero, then HDMI connector information is available.
0069 This field is only valid if ``CEC_CAP_CONNECTOR_INFO`` is set. If that
0070 capability is set and ``have_conn_info`` is zero, then that indicates
0071 that the HDMI connector device is not instantiated, either because
0072 the HDMI driver is still configuring the device or because the HDMI
0073 device was unbound.
0074
0075 .. c:type:: cec_event_lost_msgs
0076
0077 .. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}|
0078
0079 .. flat-table:: struct cec_event_lost_msgs
0080 :header-rows: 0
0081 :stub-columns: 0
0082 :widths: 1 1 16
0083
0084 * - __u32
0085 - ``lost_msgs``
0086 - Set to the number of lost messages since the filehandle was opened
0087 or since the last time this event was dequeued for this
0088 filehandle. The messages lost are the oldest messages. So when a
0089 new message arrives and there is no more room, then the oldest
0090 message is discarded to make room for the new one. The internal
0091 size of the message queue guarantees that all messages received in
0092 the last two seconds will be stored. Since messages should be
0093 replied to within a second according to the CEC specification,
0094 this is more than enough.
0095
0096 .. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}|
0097
0098 .. c:type:: cec_event
0099
0100 .. flat-table:: struct cec_event
0101 :header-rows: 0
0102 :stub-columns: 0
0103 :widths: 1 1 8
0104
0105 * - __u64
0106 - ``ts``
0107 - Timestamp of the event in ns.
0108
0109 The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock.
0110
0111 To access the same clock from userspace use :c:func:`clock_gettime`.
0112 * - __u32
0113 - ``event``
0114 - The CEC event type, see :ref:`cec-events`.
0115 * - __u32
0116 - ``flags``
0117 - Event flags, see :ref:`cec-event-flags`.
0118 * - union {
0119 - (anonymous)
0120 * - struct cec_event_state_change
0121 - ``state_change``
0122 - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>`
0123 event.
0124 * - struct cec_event_lost_msgs
0125 - ``lost_msgs``
0126 - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>`
0127 event.
0128 * - }
0129 -
0130
0131 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}|
0132
0133 .. _cec-events:
0134
0135 .. flat-table:: CEC Events Types
0136 :header-rows: 0
0137 :stub-columns: 0
0138 :widths: 3 1 16
0139
0140 * .. _`CEC-EVENT-STATE-CHANGE`:
0141
0142 - ``CEC_EVENT_STATE_CHANGE``
0143 - 1
0144 - Generated when the CEC Adapter's state changes. When open() is
0145 called an initial event will be generated for that filehandle with
0146 the CEC Adapter's state at that time.
0147 * .. _`CEC-EVENT-LOST-MSGS`:
0148
0149 - ``CEC_EVENT_LOST_MSGS``
0150 - 2
0151 - Generated if one or more CEC messages were lost because the
0152 application didn't dequeue CEC messages fast enough.
0153 * .. _`CEC-EVENT-PIN-CEC-LOW`:
0154
0155 - ``CEC_EVENT_PIN_CEC_LOW``
0156 - 3
0157 - Generated if the CEC pin goes from a high voltage to a low voltage.
0158 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
0159 capability set.
0160 * .. _`CEC-EVENT-PIN-CEC-HIGH`:
0161
0162 - ``CEC_EVENT_PIN_CEC_HIGH``
0163 - 4
0164 - Generated if the CEC pin goes from a low voltage to a high voltage.
0165 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
0166 capability set.
0167 * .. _`CEC-EVENT-PIN-HPD-LOW`:
0168
0169 - ``CEC_EVENT_PIN_HPD_LOW``
0170 - 5
0171 - Generated if the HPD pin goes from a high voltage to a low voltage.
0172 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
0173 capability set. When open() is called, the HPD pin can be read and
0174 if the HPD is low, then an initial event will be generated for that
0175 filehandle.
0176 * .. _`CEC-EVENT-PIN-HPD-HIGH`:
0177
0178 - ``CEC_EVENT_PIN_HPD_HIGH``
0179 - 6
0180 - Generated if the HPD pin goes from a low voltage to a high voltage.
0181 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
0182 capability set. When open() is called, the HPD pin can be read and
0183 if the HPD is high, then an initial event will be generated for that
0184 filehandle.
0185 * .. _`CEC-EVENT-PIN-5V-LOW`:
0186
0187 - ``CEC_EVENT_PIN_5V_LOW``
0188 - 6
0189 - Generated if the 5V pin goes from a high voltage to a low voltage.
0190 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
0191 capability set. When open() is called, the 5V pin can be read and
0192 if the 5V is low, then an initial event will be generated for that
0193 filehandle.
0194 * .. _`CEC-EVENT-PIN-5V-HIGH`:
0195
0196 - ``CEC_EVENT_PIN_5V_HIGH``
0197 - 7
0198 - Generated if the 5V pin goes from a low voltage to a high voltage.
0199 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
0200 capability set. When open() is called, the 5V pin can be read and
0201 if the 5V is high, then an initial event will be generated for that
0202 filehandle.
0203
0204 .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.7cm}|
0205
0206 .. _cec-event-flags:
0207
0208 .. flat-table:: CEC Event Flags
0209 :header-rows: 0
0210 :stub-columns: 0
0211 :widths: 3 1 8
0212
0213 * .. _`CEC-EVENT-FL-INITIAL-STATE`:
0214
0215 - ``CEC_EVENT_FL_INITIAL_STATE``
0216 - 1
0217 - Set for the initial events that are generated when the device is
0218 opened. See the table above for which events do this. This allows
0219 applications to learn the initial state of the CEC adapter at
0220 open() time.
0221 * .. _`CEC-EVENT-FL-DROPPED-EVENTS`:
0222
0223 - ``CEC_EVENT_FL_DROPPED_EVENTS``
0224 - 2
0225 - Set if one or more events of the given event type have been dropped.
0226 This is an indication that the application cannot keep up.
0227
0228
0229 Return Value
0230 ============
0231
0232 On success 0 is returned, on error -1 and the ``errno`` variable is set
0233 appropriately. The generic error codes are described at the
0234 :ref:`Generic Error Codes <gen-errors>` chapter.
0235
0236 The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following
0237 error codes:
0238
0239 EAGAIN
0240 This is returned when the filehandle is in non-blocking mode and there
0241 are no pending events.
0242
0243 ERESTARTSYS
0244 An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for
0245 events to arrive.
