[media] doc-rst: linux_tv CEC part, DocBook to reST migration

This is the reST migration of media's CEC part.  The migration is based
on media_tree's cec branch:

 https://git.linuxtv.org/media_tree.git

 c7169ad * cec media_tree/cec [media] DocBook/media: add CEC documentation

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

1 files changed, 237 insertions, 0 deletions

diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst
new file mode 100644
index 000000000000..832627bb0a90
--- /dev/null
+++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst
@@ -0,0 +1,237 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _cec-ioc-g-event:
+
+*****************
+ioctl CEC_DQEVENT
+*****************
+
+*man CEC_DQEVENT(2)*
+
+Dequeue a CEC event
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct cec_event *argp )
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by :ref:`open() <cec-func-open>`.
+
+``request``
+    CEC_DQEVENT
+
+``argp``
+
+
+Description
+===========
+
+Note: this documents the proposed CEC API. This API is not yet finalized
+and is currently only available as a staging kernel module.
+
+CEC devices can send asynchronous events. These can be retrieved by
+calling the ``CEC_DQEVENT`` ioctl. 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 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.
+
+
+.. _cec-event-state-change:
+
+.. flat-table:: struct cec_event_state_change
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2
+
+
+    -  .. row 1
+
+       -  __u16
+
+       -  ``phys_addr``
+
+       -  The current physical address.
+
+    -  .. row 2
+
+       -  __u16
+
+       -  ``log_addr_mask``
+
+       -  The current set of claimed logical addresses.
+
+
+
+.. _cec-event-lost-msgs:
+
+.. flat-table:: struct cec_event_lost_msgs
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2
+
+
+    -  .. row 1
+
+       -  __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.
+
+
+
+.. _cec-event:
+
+.. flat-table:: struct cec_event
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2 1
+
+
+    -  .. row 1
+
+       -  __u64
+
+       -  ``ts``
+
+       -  Timestamp of the event in ns.
+
+       -
+
+    -  .. row 2
+
+       -  __u32
+
+       -  ``event``
+
+       -  The CEC event type, see :ref:`cec-events`.
+
+       -
+
+    -  .. row 3
+
+       -  __u32
+
+       -  ``flags``
+
+       -  Event flags, see :ref:`cec-event-flags`.
+
+       -
+
+    -  .. row 4
+
+       -  union
+
+       -  (anonymous)
+
+       -
+       -
+
+    -  .. row 5
+
+       -
+       -  struct cec_event_state_change
+
+       -  ``state_change``
+
+       -  The new adapter state as sent by the ``CEC_EVENT_STATE_CHANGE``
+          event.
+
+    -  .. row 6
+
+       -
+       -  struct cec_event_lost_msgs
+
+       -  ``lost_msgs``
+
+       -  The number of lost messages as sent by the ``CEC_EVENT_LOST_MSGS``
+          event.
+
+
+
+.. _cec-events:
+
+.. flat-table:: CEC Events Types
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       3 1 4
+
+
+    -  .. row 1
+
+       -  ``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.
+
+    -  .. row 2
+
+       -  ``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-flags:
+
+.. flat-table:: CEC Event Flags
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       3 1 4
+
+
+    -  .. row 1
+
+       -  ``CEC_EVENT_FL_INITIAL_VALUE``
+
+       -  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.
+
+
+
+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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------