1.. -*- coding: utf-8; mode: rst -*- 2 3.. _CEC_DQEVENT: 4 5***************** 6ioctl CEC_DQEVENT 7***************** 8 9Name 10==== 11 12CEC_DQEVENT - Dequeue a CEC event 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp ) 19 :name: CEC_DQEVENT 20 21Arguments 22========= 23 24``fd`` 25 File descriptor returned by :c:func:`open() <cec-open>`. 26 27``argp`` 28 29 30Description 31=========== 32 33CEC devices can send asynchronous events. These can be retrieved by 34calling :c:func:`CEC_DQEVENT`. If the file descriptor is in 35non-blocking mode and no event is pending, then it will return -1 and 36set errno to the ``EAGAIN`` error code. 37 38The internal event queues are per-filehandle and per-event type. If 39there is no more room in a queue then the last event is overwritten with 40the new one. This means that intermediate results can be thrown away but 41that the latest event is always available. This also means that is it 42possible to read two successive events that have the same value (e.g. 43two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with 44the same state). In that case the intermediate state changes were lost but 45it is guaranteed that the state did change in between the two events. 46 47.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| 48 49.. c:type:: cec_event_state_change 50 51.. flat-table:: struct cec_event_state_change 52 :header-rows: 0 53 :stub-columns: 0 54 :widths: 1 1 8 55 56 * - __u16 57 - ``phys_addr`` 58 - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no 59 valid physical address is set. 60 * - __u16 61 - ``log_addr_mask`` 62 - The current set of claimed logical addresses. This is 0 if no logical 63 addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``. 64 If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device 65 has the unregistered logical address. In that case all other bits are 0. 66 67 68.. c:type:: cec_event_lost_msgs 69 70.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| 71 72.. flat-table:: struct cec_event_lost_msgs 73 :header-rows: 0 74 :stub-columns: 0 75 :widths: 1 1 16 76 77 * - __u32 78 - ``lost_msgs`` 79 - Set to the number of lost messages since the filehandle was opened 80 or since the last time this event was dequeued for this 81 filehandle. The messages lost are the oldest messages. So when a 82 new message arrives and there is no more room, then the oldest 83 message is discarded to make room for the new one. The internal 84 size of the message queue guarantees that all messages received in 85 the last two seconds will be stored. Since messages should be 86 replied to within a second according to the CEC specification, 87 this is more than enough. 88 89 90.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| 91 92.. c:type:: cec_event 93 94.. flat-table:: struct cec_event 95 :header-rows: 0 96 :stub-columns: 0 97 :widths: 1 1 1 8 98 99 * - __u64 100 - ``ts`` 101 - :cspan:`1`\ Timestamp of the event in ns. 102 103 The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. 104 105 To access the same clock from userspace use :c:func:`clock_gettime`. 106 * - __u32 107 - ``event`` 108 - :cspan:`1` The CEC event type, see :ref:`cec-events`. 109 * - __u32 110 - ``flags`` 111 - :cspan:`1` Event flags, see :ref:`cec-event-flags`. 112 * - union 113 - (anonymous) 114 - 115 - 116 * - 117 - struct cec_event_state_change 118 - ``state_change`` 119 - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` 120 event. 121 * - 122 - struct cec_event_lost_msgs 123 - ``lost_msgs`` 124 - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>` 125 event. 126 127 128.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| 129 130.. _cec-events: 131 132.. flat-table:: CEC Events Types 133 :header-rows: 0 134 :stub-columns: 0 135 :widths: 3 1 16 136 137 * .. _`CEC-EVENT-STATE-CHANGE`: 138 139 - ``CEC_EVENT_STATE_CHANGE`` 140 - 1 141 - Generated when the CEC Adapter's state changes. When open() is 142 called an initial event will be generated for that filehandle with 143 the CEC Adapter's state at that time. 144 * .. _`CEC-EVENT-LOST-MSGS`: 145 146 - ``CEC_EVENT_LOST_MSGS`` 147 - 2 148 - Generated if one or more CEC messages were lost because the 149 application didn't dequeue CEC messages fast enough. 150 * .. _`CEC-EVENT-PIN-CEC-LOW`: 151 152 - ``CEC_EVENT_PIN_CEC_LOW`` 153 - 3 154 - Generated if the CEC pin goes from a high voltage to a low voltage. 155 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` 156 capability set. 157 * .. _`CEC-EVENT-PIN-CEC-HIGH`: 158 159 - ``CEC_EVENT_PIN_CEC_HIGH`` 160 - 4 161 - Generated if the CEC pin goes from a low voltage to a high voltage. 162 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` 163 capability set. 164 165 166.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| 167 168.. _cec-event-flags: 169 170.. flat-table:: CEC Event Flags 171 :header-rows: 0 172 :stub-columns: 0 173 :widths: 3 1 8 174 175 * .. _`CEC-EVENT-FL-INITIAL-VALUE`: 176 177 - ``CEC_EVENT_FL_INITIAL_VALUE`` 178 - 1 179 - Set for the initial events that are generated when the device is 180 opened. See the table above for which events do this. This allows 181 applications to learn the initial state of the CEC adapter at 182 open() time. 183 * .. _`CEC-EVENT-FL-DROPPED-EVENTS`: 184 185 - ``CEC_EVENT_FL_DROPPED_EVENTS`` 186 - 2 187 - Set if one or more events of the given event type have been dropped. 188 This is an indication that the application cannot keep up. 189 190 191 192Return Value 193============ 194 195On success 0 is returned, on error -1 and the ``errno`` variable is set 196appropriately. The generic error codes are described at the 197:ref:`Generic Error Codes <gen-errors>` chapter. 198 199The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following 200error codes: 201 202EAGAIN 203 This is returned when the filehandle is in non-blocking mode and there 204 are no pending events. 205 206ERESTARTSYS 207 An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for 208 events to arrive. 209