diff options
Diffstat (limited to 'Documentation/media/uapi/cec')
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-close.rst | 4 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-ioctl.rst | 4 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-open.rst | 4 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-poll.rst | 4 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-intro.rst | 4 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst | 38 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst | 80 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst | 4 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 36 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-g-mode.rst | 122 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-receive.rst | 114 |
11 files changed, 207 insertions, 207 deletions
diff --git a/Documentation/media/uapi/cec/cec-func-close.rst b/Documentation/media/uapi/cec/cec-func-close.rst index ae55e55ab84a..bb94e4358910 100644 --- a/Documentation/media/uapi/cec/cec-func-close.rst +++ b/Documentation/media/uapi/cec/cec-func-close.rst @@ -32,8 +32,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. Closes the cec device. Resources associated with the file descriptor are freed. The device configuration remain unchanged. diff --git a/Documentation/media/uapi/cec/cec-func-ioctl.rst b/Documentation/media/uapi/cec/cec-func-ioctl.rst index 69510ac5088a..a07cc7cf8afb 100644 --- a/Documentation/media/uapi/cec/cec-func-ioctl.rst +++ b/Documentation/media/uapi/cec/cec-func-ioctl.rst @@ -38,8 +38,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. The :c:func:`ioctl()` function manipulates cec device parameters. The argument ``fd`` must be an open file descriptor. diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst index 95db9d1dc6b5..245d6793dd35 100644 --- a/Documentation/media/uapi/cec/cec-func-open.rst +++ b/Documentation/media/uapi/cec/cec-func-open.rst @@ -45,8 +45,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. To open a cec device applications call :c:func:`open()` with the desired device name. The function has no side effects; the device diff --git a/Documentation/media/uapi/cec/cec-func-poll.rst b/Documentation/media/uapi/cec/cec-func-poll.rst index eacc164558a5..fcab65f6d6b8 100644 --- a/Documentation/media/uapi/cec/cec-func-poll.rst +++ b/Documentation/media/uapi/cec/cec-func-poll.rst @@ -29,8 +29,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. With the :c:func:`poll()` function applications can wait for CEC events. diff --git a/Documentation/media/uapi/cec/cec-intro.rst b/Documentation/media/uapi/cec/cec-intro.rst index d6a878866b3f..afa76f26fdde 100644 --- a/Documentation/media/uapi/cec/cec-intro.rst +++ b/Documentation/media/uapi/cec/cec-intro.rst @@ -3,8 +3,8 @@ Introduction ============ -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. HDMI connectors provide a single pin for use by the Consumer Electronics Control protocol. This protocol allows different devices connected by an 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 6cf959ee6929..2ca9199c3305 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst @@ -31,8 +31,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. All cec devices must support the :ref:`CEC_ADAP_G_CAPS` ioctl. To query device information, applications call the ioctl with a pointer to a @@ -63,7 +63,7 @@ returns the information to the application. The ioctl never fails. - ``name[32]`` - The name of this CEC adapter. The combination ``driver`` and - ``name`` must be unique. + ``name`` must be unique. - .. row 3 @@ -72,7 +72,7 @@ returns the information to the application. The ioctl never fails. - ``capabilities`` - The capabilities of the CEC adapter, see - :ref:`cec-capabilities`. + :ref:`cec-capabilities`. - .. row 4 @@ -81,7 +81,7 @@ returns the information to the application. The ioctl never fails. - ``version`` - CEC Framework API version, formatted with the ``KERNEL_VERSION()`` - macro. + macro. @@ -100,10 +100,10 @@ returns the information to the application. The ioctl never fails. - 0x00000001 - Userspace has to configure the physical address by calling - :ref:`CEC_ADAP_S_PHYS_ADDR`. If - this capability isn't set, then setting the physical address is - handled by the kernel whenever the EDID is set (for an HDMI - receiver) or read (for an HDMI transmitter). + :ref:`CEC_ADAP_S_PHYS_ADDR`. If + this capability isn't set, then setting the physical address is + handled by the kernel whenever the EDID is set (for an HDMI + receiver) or read (for an HDMI transmitter). - .. _`CEC-CAP-LOG-ADDRS`: @@ -112,9 +112,9 @@ returns the information to the application. The ioctl never fails. - 0x00000002 - Userspace has to configure the logical addresses by calling - :ref:`CEC_ADAP_S_LOG_ADDRS`. If - this capability isn't set, then the kernel will have configured - this. + :ref:`CEC_ADAP_S_LOG_ADDRS`. If + this capability isn't set, then the kernel will have configured + this. - .. _`CEC-CAP-TRANSMIT`: @@ -123,11 +123,11 @@ returns the information to the application. The ioctl never fails. - 0x00000004 - Userspace can transmit CEC messages by calling - :ref:`CEC_TRANSMIT`. This implies that - userspace can be a follower as well, since being able to transmit - messages is a prerequisite of becoming a follower. If this - capability isn't set, then the kernel will handle all CEC - transmits and process all CEC messages it receives. + :ref:`CEC_TRANSMIT`. This implies that + userspace can be a follower as well, since being able to transmit + messages is a prerequisite of becoming a follower. If this + capability isn't set, then the kernel will handle all CEC + transmits and process all CEC messages it receives. - .. _`CEC-CAP-PASSTHROUGH`: @@ -136,7 +136,7 @@ returns the information to the application. The ioctl never fails. - 0x00000008 - Userspace can use the passthrough mode by calling - :ref:`CEC_S_MODE`. + :ref:`CEC_S_MODE`. - .. _`CEC-CAP-RC`: @@ -153,7 +153,7 @@ returns the information to the application. The ioctl never fails. - 0x00000020 - The CEC hardware can monitor all messages, not just directed and - broadcast messages. + broadcast messages. 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 322df752465f..7d7a3b43aedc 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 @@ -35,8 +35,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. To query the current CEC logical addresses, applications call the :ref:`CEC_ADAP_G_LOG_ADDRS` ioctl with a pointer to a @@ -68,10 +68,10 @@ by a file handle in initiator mode (see - ``log_addr`` [CEC_MAX_LOG_ADDRS] - The actual logical addresses that were claimed. This is set by the - driver. If no logical address could be claimed, then it is set to - ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then - ``log_addr[0]`` is set to 0xf and all others to - ``CEC_LOG_ADDR_INVALID``. + driver. If no logical address could be claimed, then it is set to + ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then + ``log_addr[0]`` is set to 0xf and all others to + ``CEC_LOG_ADDR_INVALID``. - .. row 2 @@ -80,9 +80,9 @@ by a file handle in initiator mode (see - ``log_addr_mask`` - The bitmask of all logical addresses this adapter has claimed. If - this adapter is Unregistered then ``log_addr_mask`` sets bit 15 - and clears all other bits. If this adapter is not configured at - all, then ``log_addr_mask`` is set to 0. Set by the driver. + this adapter is Unregistered then ``log_addr_mask`` sets bit 15 + and clears all other bits. If this adapter is not configured at + all, then ``log_addr_mask`` is set to 0. Set by the driver. - .. row 3 @@ -91,10 +91,10 @@ by a file handle in initiator mode (see - ``cec_version`` - The CEC version that this adapter shall use. See - :ref:`cec-versions`. Used to implement the - ``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages. - Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC - framework. + :ref:`cec-versions`. Used to implement the + ``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages. + Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC + framework. - .. row 4 @@ -103,17 +103,17 @@ by a file handle in initiator mode (see - ``num_log_addrs`` - Number of logical addresses to set up. Must be ≤ - ``available_log_addrs`` as returned by - :ref:`CEC_ADAP_G_CAPS`. All arrays in - this structure are only filled up to index - ``available_log_addrs``-1. The remaining array elements will be - ignored. Note that the CEC 2.0 standard allows for a maximum of 2 - logical addresses, although some hardware has support for more. - ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual - number of logical addresses it could claim, which may be less than - what was requested. If this field is set to 0, then the CEC - adapter shall clear all claimed logical addresses and all other - fields will be ignored. + ``available_log_addrs`` as returned by + :ref:`CEC_ADAP_G_CAPS`. All arrays in + this structure are only filled up to index + ``available_log_addrs``-1. The remaining array elements will be + ignored. Note that the CEC 2.0 standard allows for a maximum of 2 + logical addresses, although some hardware has support for more. + ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual + number of logical addresses it could claim, which may be less than + what was requested. If this field is set to 0, then the CEC + adapter shall clear all claimed logical addresses and all other + fields will be ignored. - .. row 5 @@ -122,9 +122,9 @@ by a file handle in initiator mode (see - ``vendor_id`` - The vendor ID is a 24-bit number that identifies the specific - vendor or entity. Based on this ID vendor specific commands may be - defined. If you do not want a vendor ID then set it to - ``CEC_VENDOR_ID_NONE``. + vendor or entity. Based on this ID vendor specific commands may be + defined. If you do not want a vendor ID then set it to + ``CEC_VENDOR_ID_NONE``. - .. row 6 @@ -141,7 +141,7 @@ by a file handle in initiator mode (see - ``osd_name``\ [15] - The On-Screen Display name as is returned by the - ``CEC_MSG_SET_OSD_NAME`` message. + ``CEC_MSG_SET_OSD_NAME`` message. - .. row 8 @@ -150,7 +150,7 @@ by a file handle in initiator mode (see - ``primary_device_type`` [CEC_MAX_LOG_ADDRS] - Primary device type for each logical address. See - :ref:`cec-prim-dev-types` for possible types. + :ref:`cec-prim-dev-types` for possible types. - .. row 9 @@ -159,9 +159,9 @@ by a file handle in initiator mode (see - ``log_addr_type`` [CEC_MAX_LOG_ADDRS] - Logical address types. See :ref:`cec-log-addr-types` for - possible types. The driver will update this with the actual - logical address type that it claimed (e.g. it may have to fallback - to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`). + possible types. The driver will update this with the actual + logical address type that it claimed (e.g. it may have to fallback + to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`). - .. row 10 @@ -170,9 +170,9 @@ by a file handle in initiator mode (see - ``all_device_types`` [CEC_MAX_LOG_ADDRS] - CEC 2.0 specific: all device types. See - :ref:`cec-all-dev-types-flags`. Used to implement the - ``CEC_MSG_REPORT_FEATURES`` message. This field is ignored if - ``cec_version`` < :ref:`CEC_OP_CEC_VERSION_2_0 <CEC-OP-CEC-VERSION-2-0>`. + :ref:`cec-all-dev-types-flags`. Used to implement the + ``CEC_MSG_REPORT_FEATURES`` message. This field is ignored if + ``cec_version`` < :ref:`CEC_OP_CEC_VERSION_2_0 <CEC-OP-CEC-VERSION-2-0>`. - .. row 11 @@ -181,9 +181,9 @@ by a file handle in initiator mode (see - ``features`` [CEC_MAX_LOG_ADDRS][12] - Features for each logical address. Used to implement the - ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the - RC Profile and the Device Features. This field is ignored if - ``cec_version`` < :ref:`CEC_OP_CEC_VERSION_2_0 <CEC-OP-CEC-VERSION-2-0>`. + ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the + RC Profile and the Device Features. This field is ignored if + ``cec_version`` < :ref:`CEC_OP_CEC_VERSION_2_0 <CEC-OP-CEC-VERSION-2-0>`. @@ -350,8 +350,8 @@ by a file handle in initiator mode (see - 6 - Use this if you just want to remain unregistered. Used for pure - CEC switches or CDC-only devices (CDC: Capability Discovery and - Control). + CEC switches or CDC-only devices (CDC: Capability Discovery and + Control). diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst index 40e0baaa1630..58aaba6e21f8 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst @@ -34,8 +34,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. To query the current physical address applications call the :ref:`CEC_ADAP_G_PHYS_ADDR` ioctl with a pointer to an __u16 where the diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst index 204bc18d69a9..681201fc92d7 100644 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst @@ -32,8 +32,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. 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 :ref:`CEC_DQEVENT` ioctl. If the file descriptor is in @@ -91,14 +91,14 @@ state did change in between the two events. - ``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. + 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. @@ -157,7 +157,7 @@ state did change in between the two events. - ``state_change`` - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` - event. + event. - .. row 6 @@ -167,7 +167,7 @@ state did change in between the two events. - ``lost_msgs`` - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>` - event. + event. @@ -186,8 +186,8 @@ state did change in between the two events. - 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. + called an initial event will be generated for that filehandle with + the CEC Adapter's state at that time. - .. _`CEC-EVENT-LOST-MSGS`: @@ -196,7 +196,7 @@ 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. + application didn't dequeue CEC messages fast enough. @@ -215,9 +215,9 @@ state did change in between the two events. - 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. + 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. diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst index c11de2f4ddf0..c5a0fc41469e 100644 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst @@ -30,8 +30,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. By default any filehandle can use :ref:`CEC_TRANSMIT` and @@ -89,7 +89,7 @@ Available initiator modes are: - 0x0 - This is not an initiator, i.e. it cannot transmit CEC messages or - make any other changes to the CEC adapter. + make any other changes to the CEC adapter. - .. _`CEC-MODE-INITIATOR`: @@ -98,8 +98,8 @@ Available initiator modes are: - 0x1 - This is an initiator (the default when the device is opened) and - it can transmit CEC messages and make changes to the CEC adapter, - unless there is an exclusive initiator. + it can transmit CEC messages and make changes to the CEC adapter, + unless there is an exclusive initiator. - .. _`CEC-MODE-EXCL-INITIATOR`: @@ -108,10 +108,10 @@ Available initiator modes are: - 0x2 - This is an exclusive initiator and this file descriptor is the - only one that can transmit CEC messages and make changes to the - CEC adapter. If someone else is already the exclusive initiator - then an attempt to become one will return the EBUSY error code - error. + only one that can transmit CEC messages and make changes to the + CEC adapter. If someone else is already the exclusive initiator + then an attempt to become one will return the EBUSY error code + error. Available follower modes are: @@ -140,9 +140,9 @@ Available follower modes are: - 0x10 - This is a follower and it will receive CEC messages unless there - is an exclusive follower. 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, EINVAL error code is returned in that case. + is an exclusive follower. 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, EINVAL error code is returned in that case. - .. _`CEC-MODE-EXCL-FOLLOWER`: @@ -151,11 +151,11 @@ Available follower modes are: - 0x20 - This is an exclusive follower and only this file descriptor will - receive CEC messages for processing. If someone else is already - the exclusive follower then an attempt to become one will return - the EBUSY error code error. 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, EINVAL error code is returned in that case. + receive CEC messages for processing. If someone else is already + the exclusive follower then an attempt to become one will return + the EBUSY error code error. 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, EINVAL error code is returned in that case. - .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`: @@ -164,14 +164,14 @@ Available follower modes are: - 0x30 - This is an exclusive follower and only this file descriptor will - receive CEC messages for processing. In addition it will put the - CEC device into passthrough mode, allowing the exclusive follower - to handle most core messages instead of relying on the CEC - framework for that. If someone else is already the exclusive - follower then an attempt to become one will return the EBUSY error - code error. 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, EINVAL - error code is returned in that case. + receive CEC messages for processing. In addition it will put the + CEC device into passthrough mode, allowing the exclusive follower + to handle most core messages instead of relying on the CEC + framework for that. If someone else is already the exclusive + follower then an attempt to become one will return the EBUSY error + code error. 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, EINVAL + error code is returned in that case. - .. _`CEC-MODE-MONITOR`: @@ -180,13 +180,13 @@ Available follower modes are: - 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 - 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 - allowed if the process has the ``CAP_NET_ADMIN`` capability. If - that is not set, then EPERM error code is returned. + 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 + 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 + allowed if the process has the ``CAP_NET_ADMIN`` capability. If + that is not set, then EPERM error code is returned. - .. _`CEC-MODE-MONITOR-ALL`: @@ -195,15 +195,15 @@ Available follower modes are: - 0xf0 - Put the file descriptor into 'monitor all' 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 all' mode all messages - this CEC device transmits and all messages it receives, including - directed messages for other CEC devices will be reported. This is - very useful for debugging, but not all devices support this. This - mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set, - otherwise EINVAL error code is returned. This is only allowed if - the process has the ``CAP_NET_ADMIN`` capability. If that is not - set, then EPERM error code is returned. + in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise EINVAL + error code will be returned. In 'monitor all' mode all messages + this CEC device transmits and all messages it receives, including + directed messages for other CEC devices will be reported. This is + very useful for debugging, but not all devices support this. This + mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set, + otherwise EINVAL error code is returned. This is only allowed if + the process has the ``CAP_NET_ADMIN`` capability. If that is not + set, then EPERM error code is returned. Core message processing details: @@ -222,74 +222,74 @@ Core message processing details: - ``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:`CEC_ADAP_S_LOG_ADDRS`. + userspace, otherwise the core will return the CEC version that was + set with + :ref:`CEC_ADAP_S_LOG_ADDRS`. - .. _`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:`CEC_ADAP_S_LOG_ADDRS`. + userspace, otherwise the core will return the vendor ID that was + set with + :ref:`CEC_ADAP_S_LOG_ADDRS`. - .. _`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. + userspace, otherwise the core will return a feature refused + message as per the specification. - .. _`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. + userspace, otherwise the core will report the current physical + address. - .. _`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:`CEC_ADAP_S_LOG_ADDRS`. + userspace, otherwise the core will report the current OSD name as + was set with + :ref:`CEC_ADAP_S_LOG_ADDRS`. - .. _`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:`CEC_ADAP_S_LOG_ADDRS` or - the message is ignore if the CEC version was older than 2.0. + userspace, otherwise the core will report the current features as + was set with + :ref:`CEC_ADAP_S_LOG_ADDRS` or + the message is ignore if the CEC version was older than 2.0. - .. _`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. + press. This message is always passed on to userspace. - .. _`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. + release. This message is always passed on to userspace. - .. _`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 userspace. diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst index 2bc2d6091f53..47aadcd553ee 100644 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst @@ -33,8 +33,8 @@ Arguments Description =========== -Note: this documents the proposed CEC API. This API is not yet finalized -and is currently only available as a staging kernel module. +.. note:: This documents the proposed CEC API. This API is not yet finalized + and is currently only available as a staging kernel module. To receive a CEC message the application has to fill in the :c:type:`struct cec_msg` structure and pass it to the :ref:`CEC_RECEIVE` @@ -67,8 +67,8 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``ts`` - Timestamp of when the message was transmitted in ns in the case of - :ref:`CEC_TRANSMIT` with ``reply`` set to 0, or the timestamp of the - received message in all other cases. + :ref:`CEC_TRANSMIT` with ``reply`` set to 0, or the timestamp of the + received message in all other cases. - .. row 2 @@ -77,9 +77,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``len`` - The length of the message. For :ref:`CEC_TRANSMIT` this is filled in - by the application. The driver will fill this in for - :ref:`CEC_RECEIVE` and for :ref:`CEC_TRANSMIT` it will be filled in with - the length of the reply message if ``reply`` was set. + by the application. The driver will fill this in for + :ref:`CEC_RECEIVE` and for :ref:`CEC_TRANSMIT` it will be filled in with + the length of the reply message if ``reply`` was set. - .. row 3 @@ -88,11 +88,11 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``timeout`` - The timeout in milliseconds. This is the time the device will wait - for a message to be received before timing out. If it is set to 0, - then it will wait indefinitely when it is called by - :ref:`CEC_RECEIVE`. If it is 0 and it is called by :ref:`CEC_TRANSMIT`, - then it will be replaced by 1000 if the ``reply`` is non-zero or - ignored if ``reply`` is 0. + for a message to be received before timing out. If it is set to 0, + then it will wait indefinitely when it is called by + :ref:`CEC_RECEIVE`. If it is 0 and it is called by :ref:`CEC_TRANSMIT`, + then it will be replaced by 1000 if the ``reply`` is non-zero or + ignored if ``reply`` is 0. - .. row 4 @@ -101,9 +101,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``sequence`` - The sequence number is automatically assigned by the CEC framework - for all transmitted messages. It can be later used by the - framework to generate an event if a reply for a message was - requested and the message was transmitted in a non-blocking mode. + for all transmitted messages. It can be later used by the + framework to generate an event if a reply for a message was + requested and the message was transmitted in a non-blocking mode. - .. row 5 @@ -120,10 +120,10 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``rx_status`` - The status bits of the received message. See - :ref:`cec-rx-status` for the possible status values. It is 0 if - this message was transmitted, not received, unless this is the - reply to a transmitted message. In that case both ``rx_status`` - and ``tx_status`` are set. + :ref:`cec-rx-status` for the possible status values. It is 0 if + this message was transmitted, not received, unless this is the + reply to a transmitted message. In that case both ``rx_status`` + and ``tx_status`` are set. - .. row 7 @@ -132,8 +132,8 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``tx_status`` - The status bits of the transmitted message. See - :ref:`cec-tx-status` for the possible status values. It is 0 if - this messages was received, not transmitted. + :ref:`cec-tx-status` for the possible status values. It is 0 if + this messages was received, not transmitted. - .. row 8 @@ -142,9 +142,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``msg``\ [16] - The message payload. For :ref:`CEC_TRANSMIT` this is filled in by the - application. The driver will fill this in for :ref:`CEC_RECEIVE` and - for :ref:`CEC_TRANSMIT` it will be filled in with the payload of the - reply message if ``reply`` was set. + application. The driver will fill this in for :ref:`CEC_RECEIVE` and + for :ref:`CEC_TRANSMIT` it will be filled in with the payload of the + reply message if ``reply`` was set. - .. row 9 @@ -153,15 +153,15 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``reply`` - Wait until this message is replied. If ``reply`` is 0 and the - ``timeout`` is 0, then don't wait for a reply but return after - transmitting the message. If there was an error as indicated by a - non-zero ``tx_status`` field, then ``reply`` and ``timeout`` are - both set to 0 by the driver. Ignored by :ref:`CEC_RECEIVE`. The case - where ``reply`` is 0 (this is the opcode for the Feature Abort - message) and ``timeout`` is non-zero is specifically allowed to - send a message and wait up to ``timeout`` milliseconds for a - Feature Abort reply. In this case ``rx_status`` will either be set - to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or :ref:`CEC_RX_STATUS-FEATURE-ABORT <CEC-RX-STATUS-FEATURE-ABORT>`. + ``timeout`` is 0, then don't wait for a reply but return after + transmitting the message. If there was an error as indicated by a + non-zero ``tx_status`` field, then ``reply`` and ``timeout`` are + both set to 0 by the driver. Ignored by :ref:`CEC_RECEIVE`. The case + where ``reply`` is 0 (this is the opcode for the Feature Abort + message) and ``timeout`` is non-zero is specifically allowed to + send a message and wait up to ``timeout`` milliseconds for a + Feature Abort reply. In this case ``rx_status`` will either be set + to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or :ref:`CEC_RX_STATUS-FEATURE-ABORT <CEC-RX-STATUS-FEATURE-ABORT>`. - .. row 10 @@ -170,9 +170,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``tx_arb_lost_cnt`` - A counter of the number of transmit attempts that resulted in the - Arbitration Lost error. This is only set if the hardware supports - this, otherwise it is always 0. This counter is only valid if the - :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set. + Arbitration Lost error. This is only set if the hardware supports + this, otherwise it is always 0. This counter is only valid if the + :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set. - .. row 11 @@ -181,9 +181,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``tx_nack_cnt`` - A counter of the number of transmit attempts that resulted in the - Not Acknowledged error. This is only set if the hardware supports - this, otherwise it is always 0. This counter is only valid if the - :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set. + Not Acknowledged error. This is only set if the hardware supports + this, otherwise it is always 0. This counter is only valid if the + :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set. - .. row 12 @@ -192,9 +192,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``tx_low_drive_cnt`` - A counter of the number of transmit attempts that resulted in the - Arbitration Lost error. This is only set if the hardware supports - this, otherwise it is always 0. This counter is only valid if the - :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set. + Arbitration Lost error. This is only set if the hardware supports + this, otherwise it is always 0. This counter is only valid if the + :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set. - .. row 13 @@ -203,9 +203,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - ``tx_error_cnt`` - A counter of the number of transmit errors other than Arbitration - Lost or Not Acknowledged. This is only set if the hardware - supports this, otherwise it is always 0. This counter is only - valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. + Lost or Not Acknowledged. This is only set if the hardware + supports this, otherwise it is always 0. This counter is only + valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. @@ -224,9 +224,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - 0x01 - The message was transmitted successfully. This is mutually - exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still - be set if earlier attempts met with failure before the transmit - was eventually successful. + exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still + be set if earlier attempts met with failure before the transmit + was eventually successful. - .. _`CEC-TX-STATUS-ARB-LOST`: @@ -251,8 +251,8 @@ queue, then it will return -1 and set errno to the EBUSY error code. - 0x08 - Low drive was detected on the CEC bus. This indicates that a - follower detected an error on the bus and requests a - retransmission. + follower detected an error on the bus and requests a + retransmission. - .. _`CEC-TX-STATUS-ERROR`: @@ -261,9 +261,9 @@ queue, then it will return -1 and set errno to the EBUSY error code. - 0x10 - Some error occurred. This is used for any errors that do not fit - the previous two, either because the hardware could not tell which - error occurred, or because the hardware tested for other - conditions besides those two. + the previous two, either because the hardware could not tell which + error occurred, or because the hardware tested for other + conditions besides those two. - .. _`CEC-TX-STATUS-MAX-RETRIES`: @@ -272,8 +272,8 @@ queue, then it will return -1 and set errno to the EBUSY error code. - 0x20 - The transmit failed after one or more retries. This status bit is - mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still - be set to explain which failures were seen. + mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still + be set to explain which failures were seen. @@ -308,8 +308,8 @@ queue, then it will return -1 and set errno to the EBUSY error code. - 0x04 - The message was received successfully but the reply was - ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message - was the reply to an earlier transmitted message. + ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message + was the reply to an earlier transmitted message. |