diff options
Diffstat (limited to 'Documentation/media/uapi/cec/cec-ioc-dqevent.rst')
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 257 |
1 files changed, 0 insertions, 257 deletions
diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst deleted file mode 100644 index d16b226b1bef..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ /dev/null @@ -1,257 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_DQEVENT: - -***************** -ioctl CEC_DQEVENT -***************** - -Name -==== - -CEC_DQEVENT - Dequeue a CEC event - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp ) - :name: CEC_DQEVENT - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. - -``argp`` - - -Description -=========== - -CEC devices can send asynchronous events. These can be retrieved by -calling :c:func:`CEC_DQEVENT`. If the file descriptor is in -non-blocking mode and no event is pending, then it will return -1 and -set errno to the ``EAGAIN`` error code. - -The internal event queues are per-filehandle and per-event type. If -there is no more room in a queue then the last event is overwritten with -the new one. This means that intermediate results can be thrown away but -that the latest event is always available. This also means that is it -possible to read two successive events that have the same value (e.g. -two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with -the same state). In that case the intermediate state changes were lost but -it is guaranteed that the state did change in between the two events. - -.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| - -.. c:type:: cec_event_state_change - -.. flat-table:: struct cec_event_state_change - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 8 - - * - __u16 - - ``phys_addr`` - - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no - valid physical address is set. - * - __u16 - - ``log_addr_mask`` - - The current set of claimed logical addresses. This is 0 if no logical - addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``. - If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device - has the unregistered logical address. In that case all other bits are 0. - * - __u16 - - ``have_conn_info`` - - If non-zero, then HDMI connector information is available. - This field is only valid if ``CEC_CAP_CONNECTOR_INFO`` is set. If that - capability is set and ``have_conn_info`` is zero, then that indicates - that the HDMI connector device is not instantiated, either because - the HDMI driver is still configuring the device or because the HDMI - device was unbound. - - -.. c:type:: cec_event_lost_msgs - -.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| - -.. flat-table:: struct cec_event_lost_msgs - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - __u32 - - ``lost_msgs`` - - Set to the number of lost messages since the filehandle was opened - or since the last time this event was dequeued for this - filehandle. The messages lost are the oldest messages. So when a - new message arrives and there is no more room, then the oldest - message is discarded to make room for the new one. The internal - size of the message queue guarantees that all messages received in - the last two seconds will be stored. Since messages should be - replied to within a second according to the CEC specification, - this is more than enough. - - -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| - -.. c:type:: cec_event - -.. flat-table:: struct cec_event - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 8 - - * - __u64 - - ``ts`` - - Timestamp of the event in ns. - - The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. - - To access the same clock from userspace use :c:func:`clock_gettime`. - * - __u32 - - ``event`` - - The CEC event type, see :ref:`cec-events`. - * - __u32 - - ``flags`` - - Event flags, see :ref:`cec-event-flags`. - * - union { - - (anonymous) - * - struct cec_event_state_change - - ``state_change`` - - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` - event. - * - struct cec_event_lost_msgs - - ``lost_msgs`` - - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>` - event. - * - } - - - - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _cec-events: - -.. flat-table:: CEC Events Types - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 16 - - * .. _`CEC-EVENT-STATE-CHANGE`: - - - ``CEC_EVENT_STATE_CHANGE`` - - 1 - - Generated when the CEC Adapter's state changes. When open() is - called an initial event will be generated for that filehandle with - the CEC Adapter's state at that time. - * .. _`CEC-EVENT-LOST-MSGS`: - - - ``CEC_EVENT_LOST_MSGS`` - - 2 - - Generated if one or more CEC messages were lost because the - application didn't dequeue CEC messages fast enough. - * .. _`CEC-EVENT-PIN-CEC-LOW`: - - - ``CEC_EVENT_PIN_CEC_LOW`` - - 3 - - Generated if the CEC pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. - * .. _`CEC-EVENT-PIN-CEC-HIGH`: - - - ``CEC_EVENT_PIN_CEC_HIGH`` - - 4 - - Generated if the CEC pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. - * .. _`CEC-EVENT-PIN-HPD-LOW`: - - - ``CEC_EVENT_PIN_HPD_LOW`` - - 5 - - Generated if the HPD pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the HPD pin can be read and - if the HPD is low, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-HPD-HIGH`: - - - ``CEC_EVENT_PIN_HPD_HIGH`` - - 6 - - Generated if the HPD pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the HPD pin can be read and - if the HPD is high, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-5V-LOW`: - - - ``CEC_EVENT_PIN_5V_LOW`` - - 6 - - Generated if the 5V pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the 5V pin can be read and - if the 5V is low, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-5V-HIGH`: - - - ``CEC_EVENT_PIN_5V_HIGH`` - - 7 - - Generated if the 5V pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the 5V pin can be read and - if the 5V is high, then an initial event will be generated for that - filehandle. - - -.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| - -.. _cec-event-flags: - -.. flat-table:: CEC Event Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 8 - - * .. _`CEC-EVENT-FL-INITIAL-STATE`: - - - ``CEC_EVENT_FL_INITIAL_STATE`` - - 1 - - Set for the initial events that are generated when the device is - opened. See the table above for which events do this. This allows - applications to learn the initial state of the CEC adapter at - open() time. - * .. _`CEC-EVENT-FL-DROPPED-EVENTS`: - - - ``CEC_EVENT_FL_DROPPED_EVENTS`` - - 2 - - Set if one or more events of the given event type have been dropped. - This is an indication that the application cannot keep up. - - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. - -The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following -error codes: - -EAGAIN - This is returned when the filehandle is in non-blocking mode and there - are no pending events. - -ERESTARTSYS - An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for - events to arrive. |