diff options
Diffstat (limited to 'Documentation/media/uapi/cec')
| -rw-r--r-- | Documentation/media/uapi/cec/cec-api.rst | 5 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-close.rst | 2 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-ioctl.rst | 2 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-open.rst | 4 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-poll.rst | 8 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-funcs.rst | 1 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst | 9 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst | 13 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 31 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-g-mode.rst | 82 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-receive.rst | 2 |
11 files changed, 113 insertions, 46 deletions
diff --git a/Documentation/media/uapi/cec/cec-api.rst b/Documentation/media/uapi/cec/cec-api.rst index bb018709970c..b68ca9c1d2e0 100644 --- a/Documentation/media/uapi/cec/cec-api.rst +++ b/Documentation/media/uapi/cec/cec-api.rst @@ -10,7 +10,10 @@ Part V - Consumer Electronics Control API This part describes the CEC: Consumer Electronics Control -.. class:: toc-title + +.. only:: html + + .. class:: toc-title Table of Contents diff --git a/Documentation/media/uapi/cec/cec-func-close.rst b/Documentation/media/uapi/cec/cec-func-close.rst index 895d9c2d1c04..334358dfa72e 100644 --- a/Documentation/media/uapi/cec/cec-func-close.rst +++ b/Documentation/media/uapi/cec/cec-func-close.rst @@ -40,7 +40,7 @@ freed. The device configuration remain unchanged. Return Value ============ -:c:func:`close()` returns 0 on success. On error, -1 is returned, and +:c:func:`close() <cec-close>` returns 0 on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: ``EBADF`` diff --git a/Documentation/media/uapi/cec/cec-func-ioctl.rst b/Documentation/media/uapi/cec/cec-func-ioctl.rst index 22fb6304a2df..e2b6260b0086 100644 --- a/Documentation/media/uapi/cec/cec-func-ioctl.rst +++ b/Documentation/media/uapi/cec/cec-func-ioctl.rst @@ -39,7 +39,7 @@ Arguments Description =========== -The :c:func:`ioctl()` function manipulates cec device parameters. The +The :c:func:`ioctl() <cec-ioctl>` function manipulates cec device parameters. The argument ``fd`` must be an open file descriptor. The ioctl ``request`` code specifies the cec function to be called. It diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst index 18dfb62f2efe..5d6663a649bd 100644 --- a/Documentation/media/uapi/cec/cec-func-open.rst +++ b/Documentation/media/uapi/cec/cec-func-open.rst @@ -46,7 +46,7 @@ Arguments Description =========== -To open a cec device applications call :c:func:`open()` with the +To open a cec device applications call :c:func:`open() <cec-open>` with the desired device name. The function has no side effects; the device configuration remain unchanged. @@ -58,7 +58,7 @@ EBADF. Return Value ============ -:c:func:`open()` returns the new file descriptor on success. On error, +:c:func:`open() <cec-open>` returns the new file descriptor on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes include: diff --git a/Documentation/media/uapi/cec/cec-func-poll.rst b/Documentation/media/uapi/cec/cec-func-poll.rst index fa0abd8fb160..d49f1ee0742d 100644 --- a/Documentation/media/uapi/cec/cec-func-poll.rst +++ b/Documentation/media/uapi/cec/cec-func-poll.rst @@ -39,10 +39,10 @@ Arguments Description =========== -With the :c:func:`poll()` function applications can wait for CEC +With the :c:func:`poll() <cec-poll>` function applications can wait for CEC events. -On success :c:func:`poll()` returns the number of file descriptors +On success :c:func:`poll() <cec-poll>` returns the number of file descriptors that have been selected (that is, file descriptors for which the ``revents`` field of the respective struct :c:type:`pollfd` is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in @@ -53,13 +53,13 @@ then the ``POLLPRI`` flag is set. When the function times out it returns a value of zero, on failure it returns -1 and the ``errno`` variable is set appropriately. -For more details see the :c:func:`poll()` manual page. +For more details see the :c:func:`poll() <cec-poll>` manual page. Return Value ============ -On success, :c:func:`poll()` returns the number structures which have +On success, :c:func:`poll() <cec-poll>` returns the number structures which have non-zero ``revents`` fields, or zero if the call timed out. On error -1 is returned, and the ``errno`` variable is set appropriately: diff --git a/Documentation/media/uapi/cec/cec-funcs.rst b/Documentation/media/uapi/cec/cec-funcs.rst index 5b7630f2e076..6d696cead5cb 100644 --- a/Documentation/media/uapi/cec/cec-funcs.rst +++ b/Documentation/media/uapi/cec/cec-funcs.rst @@ -7,7 +7,6 @@ Function Reference .. toctree:: :maxdepth: 1 - :numbered: cec-func-open cec-func-close diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst index 6d7bf7bef3eb..6c1f6efb822e 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst @@ -21,7 +21,7 @@ Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <cec-func-open>`. + File descriptor returned by :c:func:`open() <cec-open>`. ``argp`` @@ -121,6 +121,13 @@ returns the information to the application. The ioctl never fails. high. This makes it impossible to use CEC to wake up displays that set the HPD pin low when in standby mode, but keep the CEC bus alive. + * .. _`CEC-CAP-MONITOR-PIN`: + + - ``CEC_CAP_MONITOR_PIN`` + - 0x00000080 + - The CEC hardware can monitor CEC pin changes from low to high voltage + and vice versa. When in pin monitoring mode the application will + receive ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst index fcf863ab6f43..84f431a022ad 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst @@ -48,7 +48,9 @@ can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE` the ``EBUSY`` error code will be returned. To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields -will be ignored in that case. The adapter will go to the unconfigured state. +will be ignored in that case. The adapter will go to the unconfigured state and the +``cec_version``, ``vendor_id`` and ``osd_name`` fields are all reset to their default +values (CEC version 2.0, no vendor ID and an empty OSD name). If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`), then this ioctl will block until all requested logical @@ -63,7 +65,7 @@ logical address types are already defined will return with error ``EBUSY``. .. c:type:: cec_log_addrs -.. tabularcolumns:: |p{1.0cm}|p{7.5cm}|p{8.0cm}| +.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{7.5cm}| .. cssclass:: longtable @@ -146,6 +148,9 @@ logical address types are already defined will return with error ``EBUSY``. give the CEC framework more information about the device type, even though the framework won't use it directly in the CEC message. + +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| + .. _cec-log-addrs-flags: .. flat-table:: Flags for struct cec_log_addrs @@ -173,7 +178,7 @@ logical address types are already defined will return with error ``EBUSY``. to avoid trivial snooping of the keystrokes. * .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`: - - `CEC_LOG_ADDRS_FL_CDC_ONLY` + - ``CEC_LOG_ADDRS_FL_CDC_ONLY`` - 4 - If this flag is set, then the device is CDC-Only. CDC-Only CEC devices are CEC devices that can only handle CDC messages. @@ -181,7 +186,7 @@ logical address types are already defined will return with error ``EBUSY``. All other messages are ignored. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| .. _cec-versions: diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst index 4d3570c2e0b3..a5c821809cc6 100644 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst @@ -22,7 +22,7 @@ Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <cec-func-open>`. + File descriptor returned by :c:func:`open() <cec-open>`. ``argp`` @@ -87,7 +87,7 @@ it is guaranteed that the state did change in between the two events. this is more than enough. -.. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{2.5cm}|p{8.8cm}| +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| .. c:type:: cec_event @@ -98,10 +98,11 @@ it is guaranteed that the state did change in between the two events. * - __u64 - ``ts`` - - :cspan:`1` Timestamp of the event in ns. + - :cspan:`1`\ 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`. + The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. + + To access the same clock from userspace use :c:func:`clock_gettime`. * - __u32 - ``event`` - :cspan:`1` The CEC event type, see :ref:`cec-events`. @@ -146,6 +147,20 @@ it is guaranteed that the state did change in between the two events. - 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. .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| @@ -165,6 +180,12 @@ it is guaranteed that the state did change in between the two events. 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. diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst index 664f0d47bbcd..508e2e325683 100644 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst @@ -108,6 +108,8 @@ Available follower modes are: .. _cec-mode-follower_e: +.. cssclass:: longtable + .. flat-table:: Follower Modes :header-rows: 0 :stub-columns: 0 @@ -149,13 +151,28 @@ Available follower modes are: code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified, the ``EINVAL`` error code is returned in that case. + * .. _`CEC-MODE-MONITOR-PIN`: + + - ``CEC_MODE_MONITOR_PIN`` + - 0xd0 + - Put the file descriptor into pin monitoring mode. Can only be used in + combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, + otherwise the ``EINVAL`` error code will be returned. + This mode requires that the :ref:`CEC_CAP_MONITOR_PIN <CEC-CAP-MONITOR-PIN>` + capability is set, otherwise the ``EINVAL`` error code is returned. + While in pin monitoring mode this file descriptor can receive the + ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the + low-level CEC pin transitions. This is very useful for debugging. + This mode is only allowed if the process has the ``CAP_NET_ADMIN`` + capability. If that is not set, then the ``EPERM`` error code is returned. * .. _`CEC-MODE-MONITOR`: - ``CEC_MODE_MONITOR`` - 0xe0 - Put the file descriptor into monitor mode. Can only be used in - combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise EINVAL error - code will be returned. In monitor mode all messages this CEC + combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,i + otherwise the ``EINVAL`` error code will be returned. + In monitor mode all messages this CEC device transmits and all messages it receives (both broadcast messages and directed messages for one its logical addresses) will be reported. This is very useful for debugging. This is only @@ -191,55 +208,68 @@ Core message processing details: * .. _`CEC-MSG-GET-CEC-VERSION`: - ``CEC_MSG_GET_CEC_VERSION`` - - When in passthrough mode this message has to be handled by - userspace, otherwise the core will return the CEC version that was - set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`. + - The core will return the CEC version that was set with + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`, + except when in passthrough mode. In passthrough mode the core + does nothing and this message has to be handled by a follower + instead. * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`: - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID`` - - When in passthrough mode this message has to be handled by - userspace, otherwise the core will return the vendor ID that was - set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`. + - The core will return the vendor ID that was set with + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`, + except when in passthrough mode. In passthrough mode the core + does nothing and this message has to be handled by a follower + instead. * .. _`CEC-MSG-ABORT`: - ``CEC_MSG_ABORT`` - - When in passthrough mode this message has to be handled by - userspace, otherwise the core will return a feature refused - message as per the specification. + - The core will return a Feature Abort message with reason + 'Feature Refused' as per the specification, except when in + passthrough mode. In passthrough mode the core does nothing + and this message has to be handled by a follower instead. * .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`: - ``CEC_MSG_GIVE_PHYSICAL_ADDR`` - - When in passthrough mode this message has to be handled by - userspace, otherwise the core will report the current physical - address. + - The core will report the current physical address, except when + in passthrough mode. In passthrough mode the core does nothing + and this message has to be handled by a follower instead. * .. _`CEC-MSG-GIVE-OSD-NAME`: - ``CEC_MSG_GIVE_OSD_NAME`` - - When in passthrough mode this message has to be handled by - userspace, otherwise the core will report the current OSD name as - was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`. + - The core will report the current OSD name that was set with + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`, + except when in passthrough mode. In passthrough mode the core + does nothing and this message has to be handled by a follower + instead. * .. _`CEC-MSG-GIVE-FEATURES`: - ``CEC_MSG_GIVE_FEATURES`` - - When in passthrough mode this message has to be handled by - userspace, otherwise the core will report the current features as - was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` - or the message is ignored if the CEC version was older than 2.0. + - The core will do nothing if the CEC version is older than 2.0, + otherwise it will report the current features that were set with + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`, + except when in passthrough mode. In passthrough mode the core + does nothing (for any CEC version) and this message has to be handled + by a follower instead. * .. _`CEC-MSG-USER-CONTROL-PRESSED`: - ``CEC_MSG_USER_CONTROL_PRESSED`` - - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key - press. This message is always passed on to userspace. + - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if + :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>` + is set, then generate a remote control key + press. This message is always passed on to the follower(s). * .. _`CEC-MSG-USER-CONTROL-RELEASED`: - ``CEC_MSG_USER_CONTROL_RELEASED`` - - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key - release. This message is always passed on to userspace. + - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if + :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>` + is set, then generate a remote control key + release. This message is always passed on to the follower(s). * .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`: - ``CEC_MSG_REPORT_PHYSICAL_ADDR`` - The CEC framework will make note of the reported physical address - and then just pass the message on to userspace. + and then just pass the message on to the follower(s). diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst index 267044f7ac30..0f397c535a4c 100644 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst @@ -195,6 +195,8 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. +.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}| + .. _cec-msg-flags: .. flat-table:: Flags for struct cec_msg |