diff --git a/Documentation/media/uapi/cec/cec-func-close.rst b/Documentation/media/uapi/cec/cec-func-close.rst index ae55e55ab84af06fa0e552cf567bf515e5e83db0..bb94e435891072f329e68d180a48bd8422839e27 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 69510ac5088a2d43a897b1459db0f27d83d132d2..a07cc7cf8afb33b77278c0c6244aeb8a73b40b1e 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 95db9d1dc6b58a5391052bf0022a466cebb5f4ea..245d6793dd354df7ab4e650d990fbd70ac4db6cd 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 eacc164558a5e1ce4152bb1104039611a01c7363..fcab65f6d6b8889f02eedc81ebc43a8727159475 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 d6a878866b3fd9094611a09495f549e150c80b8b..afa76f26fdde285f052a9e79c054ff594799c03d 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 6cf959ee692977ef20947eba95db4e533365e67c..2ca9199c330582e0cbc77e7a91f46bdd62e16c1c 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 322df752465f1a41aae591a50f8234392ef32372..7d7a3b43aedcc7ca11580b9c8eb1e7edc3066a22 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 ` 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 ` 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 `). + 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 `). - .. 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 `. + :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 `. - .. 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_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 `. @@ -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 40e0baaa163054d268221c57323131833fcba50c..58aaba6e21f8c52ee2bcd04a8f5fa0a9fbd89050 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 204bc18d69a9690ccc2abc1414ee68dc6930e630..681201fc92d77c7ac6c03850855f00a77e16d5c3 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 ` - 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 ` - 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 c11de2f4ddf094bab8ab4b065000439ac5466fc7..c5a0fc41469e969d6cab939769ef294dfcfe2787 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 ` is not set or if :ref:`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 ` is not set or if :ref:`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 ` is not set or if :ref:`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 ` is not set or if :ref:`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 ` - is not set or if :ref:`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 ` + is not set or if :ref:`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 `, 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 `, 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 `, 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 ` 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 `, 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 ` 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 ` 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 ` 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 2bc2d6091f534dac0d29bf8b2b4d7a18e2d0f98e..47aadcd553ee8bc7987181e6b862bcaca0bf446f 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 ` or :ref:`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 ` or :ref:`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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 `. 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 `. 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 `. Other bits can still - be set to explain which failures were seen. + mutually exclusive with :ref:`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. diff --git a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst b/Documentation/media/uapi/dvb/dvb-fe-read-status.rst index 1c708c5e6bc0476bc1e6394ea03e412b0387250d..fcffaa7e1463695e0703dcc64c0ca1261a1522ac 100644 --- a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst +++ b/Documentation/media/uapi/dvb/dvb-fe-read-status.rst @@ -15,8 +15,9 @@ The information about the frontend tuner locking status can be queried using :ref:`FE_READ_STATUS`. Signal statistics are provided via -:ref:`FE_GET_PROPERTY`. Please note that several -statistics require the demodulator to be fully locked (e. g. with -FE_HAS_LOCK bit set). See -:ref:`Frontend statistics indicators ` for -more details. +:ref:`FE_GET_PROPERTY`. + +.. note:: Most statistics require the demodulator to be fully locked + (e. g. with FE_HAS_LOCK bit set). See + :ref:`Frontend statistics indicators ` for + more details. diff --git a/Documentation/media/uapi/dvb/dvbapi.rst b/Documentation/media/uapi/dvb/dvbapi.rst index 60fb3d46b1d64d0a2f594b199a28ffd61da507ce..6c06147f167c20a686cc88ee800e939d0682d13c 100644 --- a/Documentation/media/uapi/dvb/dvbapi.rst +++ b/Documentation/media/uapi/dvb/dvbapi.rst @@ -8,8 +8,8 @@ Digital TV API ############## -**NOTE:** This API is also known as **DVB API**, although it is generic -enough to support all digital TV standards. +.. note:: This API is also known as **DVB API**, although it is generic + enough to support all digital TV standards. **Version 5.10** diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst index 3c348e585729e7e204c58dd0e9df671a3753b465..cd0511b06c2c4842d762700afefeea2905469689 100644 --- a/Documentation/media/uapi/dvb/dvbproperty.rst +++ b/Documentation/media/uapi/dvb/dvbproperty.rst @@ -20,13 +20,13 @@ Also, the union didn't have any space left to be expanded without breaking userspace. So, the decision was to deprecate the legacy union/struct based approach, in favor of a properties set approach. -NOTE: on Linux DVB API version 3, setting a frontend were done via -:ref:`struct dvb_frontend_parameters `. -This got replaced on version 5 (also called "S2API", as this API were -added originally_enabled to provide support for DVB-S2), because the -old API has a very limited support to new standards and new hardware. -This section describes the new and recommended way to set the frontend, -with suppports all digital TV delivery systems. +.. note:: On Linux DVB API version 3, setting a frontend were done via + :ref:`struct dvb_frontend_parameters `. + This got replaced on version 5 (also called "S2API", as this API were + added originally_enabled to provide support for DVB-S2), because the + old API has a very limited support to new standards and new hardware. + This section describes the new and recommended way to set the frontend, + with suppports all digital TV delivery systems. Example: with the properties based approach, in order to set the tuner to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and @@ -93,12 +93,12 @@ Example: Setting digital TV frontend properties return 0; } -NOTE: While it is possible to directly call the Kernel code like the -above example, it is strongly recommended to use -`libdvbv5 `__, as it -provides abstraction to work with the supported digital TV standards and -provides methods for usual operations like program scanning and to -read/write channel descriptor files. +.. attention:: While it is possible to directly call the Kernel code like the + above example, it is strongly recommended to use + `libdvbv5 `__, as it + provides abstraction to work with the supported digital TV standards and + provides methods for usual operations like program scanning and to + read/write channel descriptor files. .. toctree:: diff --git a/Documentation/media/uapi/dvb/examples.rst b/Documentation/media/uapi/dvb/examples.rst index ead3ddf764c0ad5aea9d04d2f759894093eb655b..bf0a8617de9244a4794f4e37c2d217c14ebb8a38 100644 --- a/Documentation/media/uapi/dvb/examples.rst +++ b/Documentation/media/uapi/dvb/examples.rst @@ -9,10 +9,10 @@ Examples In this section we would like to present some examples for using the DVB API. -NOTE: This section is out of date, and the code below won't even -compile. Please refer to the -`libdvbv5 `__ for -updated/recommended examples. +..note:: This section is out of date, and the code below won't even + compile. Please refer to the + `libdvbv5 `__ for + updated/recommended examples. .. _tuning: diff --git a/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst index 9f71b39de0c288ecc93303883c2a4af925898895..d47e9dbf558a2aa5d8377573e97a25204ede768b 100644 --- a/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst +++ b/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst @@ -36,8 +36,9 @@ Arguments Description =========== -WARNING: This is a very obscure legacy command, used only at stv0299 -driver. Should not be used on newer drivers. +.. warning:: + This is a very obscure legacy command, used only at stv0299 + driver. Should not be used on newer drivers. It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches. diff --git a/Documentation/media/uapi/dvb/fe-get-info.rst b/Documentation/media/uapi/dvb/fe-get-info.rst index 9a9ddbcdb1ec346cff6963f8aeb21513df5c3c9d..bb6c32e47ce8052a524acd4fb036534687ebcb21 100644 --- a/Documentation/media/uapi/dvb/fe-get-info.rst +++ b/Documentation/media/uapi/dvb/fe-get-info.rst @@ -144,8 +144,8 @@ struct dvb_frontend_info - Capabilities supported by the frontend -NOTE: The frequencies are specified in Hz for Terrestrial and Cable -systems. They're specified in kHz for Satellite systems +.. note:: The frequencies are specified in Hz for Terrestrial and Cable + systems. They're specified in kHz for Satellite systems .. _fe-caps-t: diff --git a/Documentation/media/uapi/dvb/fe-read-status.rst b/Documentation/media/uapi/dvb/fe-read-status.rst index 339955fbe133502b6884697a413dbb6b4b7357e2..624ed9d06488e2e64caa6caaad800f9674537f93 100644 --- a/Documentation/media/uapi/dvb/fe-read-status.rst +++ b/Documentation/media/uapi/dvb/fe-read-status.rst @@ -40,9 +40,9 @@ used to check about the locking status of the frontend after being tuned. The ioctl takes a pointer to an integer where the status will be written. -NOTE: the size of status is actually sizeof(enum fe_status), with -varies according with the architecture. This needs to be fixed in the -future. +.. note:: The size of status is actually sizeof(enum fe_status), with + varies according with the architecture. This needs to be fixed in the + future. .. _fe-status-t: diff --git a/Documentation/media/uapi/dvb/fe-set-tone.rst b/Documentation/media/uapi/dvb/fe-set-tone.rst index 763b61d91004d814795949872507062f35307407..545e2afba2c018130f564110c578ae1b22eb9746 100644 --- a/Documentation/media/uapi/dvb/fe-set-tone.rst +++ b/Documentation/media/uapi/dvb/fe-set-tone.rst @@ -42,10 +42,10 @@ to send a 22kHz tone in order to select between high/low band on some dual-band LNBf. It is also used to send signals to DiSEqC equipment, but this is done using the DiSEqC ioctls. -NOTE: if more than one device is connected to the same antenna, setting -a tone may interfere on other devices, as they may lose the capability -of selecting the band. So, it is recommended that applications would -change to SEC_TONE_OFF when the device is not used. +.. attention:: If more than one device is connected to the same antenna, + setting a tone may interfere on other devices, as they may lose the + capability of selecting the band. So, it is recommended that applications + would change to SEC_TONE_OFF when the device is not used. .. _fe-sec-tone-mode-t: diff --git a/Documentation/media/uapi/dvb/fe-set-voltage.rst b/Documentation/media/uapi/dvb/fe-set-voltage.rst index 517f79bdbb4bf98dfc145aa5c291e129aaf4af13..2b19086b660a09bb5713cf1bdc19dc3e06453f34 100644 --- a/Documentation/media/uapi/dvb/fe-set-voltage.rst +++ b/Documentation/media/uapi/dvb/fe-set-voltage.rst @@ -48,11 +48,11 @@ the ones that implement DISEqC and multipoint LNBf's don't need to control the voltage level, provided that either 13V or 18V is sent to power up the LNBf. -NOTE: if more than one device is connected to the same antenna, setting -a voltage level may interfere on other devices, as they may lose the -capability of setting polarization or IF. So, on those cases, setting -the voltage to SEC_VOLTAGE_OFF while the device is not is used is -recommended. +.. attention:: if more than one device is connected to the same antenna, + setting a voltage level may interfere on other devices, as they may lose + the capability of setting polarization or IF. So, on those cases, setting + the voltage to SEC_VOLTAGE_OFF while the device is not is used is + recommended. Return Value diff --git a/Documentation/media/uapi/dvb/frontend.rst b/Documentation/media/uapi/dvb/frontend.rst index 8c7e502bff1f1bbaeca4f965d3055f293d7dad63..48c5cd487ce7601b37ea31183b9fe3b8900cfa1a 100644 --- a/Documentation/media/uapi/dvb/frontend.rst +++ b/Documentation/media/uapi/dvb/frontend.rst @@ -29,8 +29,8 @@ The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``. Data types and ioctl definitions can be accessed by including ``linux/dvb/frontend.h`` in your application. -NOTE: Transmission via the internet (DVB-IP) is not yet handled by this -API but a future extension is possible. +.. note:: Transmission via the internet (DVB-IP) is not yet handled by this + API but a future extension is possible. On Satellite systems, the API support for the Satellite Equipment Control (SEC) allows to power control and to send/receive signals to diff --git a/Documentation/media/uapi/gen-errors.rst b/Documentation/media/uapi/gen-errors.rst index 6cd5d26f32abd6118651e7d0165ce21ceef697eb..d6b0cfd00a3fff25de59fc65cfa2d84ed63231ce 100644 --- a/Documentation/media/uapi/gen-errors.rst +++ b/Documentation/media/uapi/gen-errors.rst @@ -92,10 +92,12 @@ Generic Error Codes - Permission denied. Can be returned if the device needs write permission, or some special capabilities is needed (e. g. root) +.. note:: -Note 1: ioctls may return other error codes. Since errors may have side -effects such as a driver reset, applications should abort on unexpected -errors. + #. This list is not exaustive; ioctls may return other error codes. + Since errors may have side effects such as a driver reset, + applications should abort on unexpected errors, or otherwise + assume that the device is in a bad state. -Note 2: Request-specific error codes are listed in the individual -requests descriptions. + #. Request-specific error codes are listed in the individual + requests descriptions. diff --git a/Documentation/media/uapi/rc/lirc_ioctl.rst b/Documentation/media/uapi/rc/lirc_ioctl.rst index c1c7163ba2f78e79ece3068f480c1993948cd312..77f39d11e2268b2ff1778806bcd47c03edebc2ad 100644 --- a/Documentation/media/uapi/rc/lirc_ioctl.rst +++ b/Documentation/media/uapi/rc/lirc_ioctl.rst @@ -251,11 +251,13 @@ I/O control requests be useful of receivers that have otherwise narrow band receiver that prevents them to be used with some remotes. Wide band receiver might also be more precise On the other hand its disadvantage it usually - reduced range of reception. Note: wide band receiver might be - implictly enabled if you enable carrier reports. In that case it - will be disabled as soon as you disable carrier reports. Trying to - disable wide band receiver while carrier reports are active will do - nothing. + reduced range of reception. + + .. note:: Wide band receiver might be + implictly enabled if you enable carrier reports. In that case it + will be disabled as soon as you disable carrier reports. Trying to + disable wide band receiver while carrier reports are active will do + nothing. .. _lirc_dev_errors: diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst index 47f8334f071e907991f94b76ff8b08c25a09f95e..cd3057326de7a32bac4f5e365d58d3c84175a69c 100644 --- a/Documentation/media/uapi/v4l/audio.rst +++ b/Documentation/media/uapi/v4l/audio.rst @@ -35,11 +35,12 @@ The struct :ref:`v4l2_audio ` returned by the The :ref:`VIDIOC_G_AUDIO ` and :ref:`VIDIOC_G_AUDOUT ` ioctls report the current -audio input and output, respectively. Note that, unlike -:ref:`VIDIOC_G_INPUT ` and -:ref:`VIDIOC_G_OUTPUT ` these ioctls return a -structure as :ref:`VIDIOC_ENUMAUDIO` and -:ref:`VIDIOC_ENUMAUDOUT ` do, not just an index. +audio input and output, respectively. + +.. note:: Note that, unlike :ref:`VIDIOC_G_INPUT ` and + :ref:`VIDIOC_G_OUTPUT ` these ioctls return a + structure as :ref:`VIDIOC_ENUMAUDIO` and + :ref:`VIDIOC_ENUMAUDOUT ` do, not just an index. To select an audio input and change its properties applications call the :ref:`VIDIOC_S_AUDIO ` ioctl. To select an audio diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst index b195eb5b63a139ea224988b1d17ea5715ad30d76..16cdd8e2c4d7df600d2a5f24e70b99d616c8fc96 100644 --- a/Documentation/media/uapi/v4l/buffer.rst +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -166,11 +166,11 @@ struct v4l2_buffer output device because the application did not pass new data in time. - Note this may count the frames received e.g. over USB, without - taking into account the frames dropped by the remote hardware due - to limited compression throughput or bus bandwidth. These devices - identify by not enumerating any video standards, see - :ref:`standard`. + .. note:: This may count the frames received e.g. over USB, without + taking into account the frames dropped by the remote hardware due + to limited compression throughput or bus bandwidth. These devices + identify by not enumerating any video standards, see + :ref:`standard`. - .. row 10 @@ -297,8 +297,10 @@ struct v4l2_plane stream, applications when it refers to an output stream. If the application sets this to 0 for an output stream, then ``bytesused`` will be set to the size of the plane (see the - ``length`` field of this struct) by the driver. Note that the - actual image data starts at ``data_offset`` which may not be 0. + ``length`` field of this struct) by the driver. + + .. note:: Note that the actual image data starts at ``data_offset`` + which may not be 0. - .. row 2 @@ -367,10 +369,11 @@ struct v4l2_plane - - Offset in bytes to video data in the plane. Drivers must set this field when ``type`` refers to a capture stream, applications when - it refers to an output stream. Note that data_offset is included - in ``bytesused``. So the size of the image in the plane is - ``bytesused``-``data_offset`` at offset ``data_offset`` from the - start of the plane. + it refers to an output stream. + + .. note:: That data_offset is included in ``bytesused``. So the + size of the image in the plane is ``bytesused``-``data_offset`` + at offset ``data_offset`` from the start of the plane. - .. row 8 diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst index 51b19491c3021a269e7ab9395e5f919b69d895ac..0913822347af617e1d791993301c4ae246f41e2f 100644 --- a/Documentation/media/uapi/v4l/crop.rst +++ b/Documentation/media/uapi/v4l/crop.rst @@ -15,9 +15,9 @@ offset into a video signal. Applications can use the following API to select an area in the video signal, query the default area and the hardware limits. -**NOTE**: Despite their name, the :ref:`VIDIOC_CROPCAP `, -:ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP -` ioctls apply to input as well as output devices. +.. note:: Despite their name, the :ref:`VIDIOC_CROPCAP `, + :ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP + ` ioctls apply to input as well as output devices. Scaling requires a source and a target. On a video capture or overlay device the source is the video signal, and the cropping ioctls determine @@ -38,9 +38,9 @@ support scaling or the :ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP ` ioctls. Their size (and position where applicable) will be fixed in this case. -**NOTE:** All capture and output devices must support the -:ref:`VIDIOC_CROPCAP ` ioctl such that applications can -determine if scaling takes place. +.. note:: All capture and output devices must support the + :ref:`VIDIOC_CROPCAP ` ioctl such that applications + can determine if scaling takes place. Cropping Structures @@ -144,8 +144,8 @@ reopening a device, such that piping data into or out of a device will work without special preparations. More advanced applications should ensure the parameters are suitable before starting I/O. -**NOTE:** on the next two examples, a video capture device is assumed; -change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. +.. note:: On the next two examples, a video capture device is assumed; + change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. Example: Resetting the cropping parameters ========================================== @@ -207,7 +207,7 @@ Example: Simple downscaling Example: Selecting an output area ================================= -**NOTE:** This example assumes an output device. +.. note:: This example assumes an output device. .. code-block:: c @@ -246,7 +246,7 @@ Example: Selecting an output area Example: Current scaling factor and pixel aspect ================================================ -**NOTE:** This example assumes a video capture device. +.. note:: This example assumes a video capture device. .. code-block:: c diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst index 16030a8354fd53117ef5643958aeff1a48070a43..8d049471e1c2baa6301660ee0d2c33e6a48d3bf0 100644 --- a/Documentation/media/uapi/v4l/dev-capture.rst +++ b/Documentation/media/uapi/v4l/dev-capture.rst @@ -15,7 +15,9 @@ Conventionally V4L2 video capture devices are accessed through character device special files named ``/dev/video`` and ``/dev/video0`` to ``/dev/video63`` with major number 81 and minor numbers 0 to 63. ``/dev/video`` is typically a symbolic link to the preferred video -device. Note the same device files are used for video output devices. +device. + +.. note:: The same device file names are used for video output devices. Querying Capabilities diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-codec.rst index 7fd28d085c2cadf64aece9fa21d703b980e6915a..dfb20328e34dbedb6194de56eeb61c322e8f21eb 100644 --- a/Documentation/media/uapi/v4l/dev-codec.rst +++ b/Documentation/media/uapi/v4l/dev-codec.rst @@ -19,8 +19,10 @@ both sides and finally call :ref:`VIDIOC_STREAMON ` for both capture and output to start the codec. Video compression codecs use the MPEG controls to setup their codec -parameters (note that the MPEG controls actually support many more -codecs than just MPEG). See :ref:`mpeg-controls`. +parameters + +.. note:: The MPEG controls actually support many more codecs than + just MPEG. See :ref:`mpeg-controls`. Memory-to-memory devices can often be used as a shared resource: you can open the video node multiple times, each application setting up their diff --git a/Documentation/media/uapi/v4l/dev-effect.rst b/Documentation/media/uapi/v4l/dev-effect.rst index be4de3b0a025408ef0ac64ab5f0cb31faa03819e..b946cc9e1064bb1603cd272a85e9a93ece5516e7 100644 --- a/Documentation/media/uapi/v4l/dev-effect.rst +++ b/Documentation/media/uapi/v4l/dev-effect.rst @@ -6,11 +6,10 @@ Effect Devices Interface ************************ - **Note** - - This interface has been be suspended from the V4L2 API implemented - in Linux 2.6 until we have more experience with effect device - interfaces. +.. note:: + This interface has been be suspended from the V4L2 API. + The implementation for such effects should be done + via mem2mem devices. A V4L2 video effect device can do image effects, filtering, or combine two or more images or image streams. For example video transitions or diff --git a/Documentation/media/uapi/v4l/dev-osd.rst b/Documentation/media/uapi/v4l/dev-osd.rst index 98570cea63a5b6d01353bfab1438f81992c4103e..fadda131f02016b158bf20cfcd17a59f742ea576 100644 --- a/Documentation/media/uapi/v4l/dev-osd.rst +++ b/Documentation/media/uapi/v4l/dev-osd.rst @@ -14,10 +14,11 @@ this interface, which borrows structures and ioctls of the :ref:`Video Overlay ` interface. The OSD function is accessible through the same character special file -as the :ref:`Video Output ` function. Note the default -function of such a ``/dev/video`` device is video capturing or output. -The OSD function is only available after calling the -:ref:`VIDIOC_S_FMT ` ioctl. +as the :ref:`Video Output ` function. + +.. note:: The default function of such a ``/dev/video`` device is video + capturing or output. The OSD function is only available after calling + the :ref:`VIDIOC_S_FMT ` ioctl. Querying Capabilities diff --git a/Documentation/media/uapi/v4l/dev-output.rst b/Documentation/media/uapi/v4l/dev-output.rst index 5063be7d493847d2a21f3bc95ed1dbd4fcb3be7c..4f1123a0b40de4224bb0dcba4d63495d77bc73d4 100644 --- a/Documentation/media/uapi/v4l/dev-output.rst +++ b/Documentation/media/uapi/v4l/dev-output.rst @@ -14,7 +14,9 @@ Conventionally V4L2 video output devices are accessed through character device special files named ``/dev/video`` and ``/dev/video0`` to ``/dev/video63`` with major number 81 and minor numbers 0 to 63. ``/dev/video`` is typically a symbolic link to the preferred video -device. Note the same device files are used for video capture devices. +device. + +..note:: The same device file names are used also for video capture devices. Querying Capabilities diff --git a/Documentation/media/uapi/v4l/dev-overlay.rst b/Documentation/media/uapi/v4l/dev-overlay.rst index bed00bf3498217e76ccccbf71a7e129e5363ccbe..bf8a418e7554d0aea800d28da2fdc0bbe2257a4d 100644 --- a/Documentation/media/uapi/v4l/dev-overlay.rst +++ b/Documentation/media/uapi/v4l/dev-overlay.rst @@ -17,10 +17,11 @@ plants needed cooling towers this used to be the only way to put live video into a window. Video overlay devices are accessed through the same character special -files as :ref:`video capture ` devices. Note the default -function of a ``/dev/video`` device is video capturing. The overlay -function is only available after calling the -:ref:`VIDIOC_S_FMT ` ioctl. +files as :ref:`video capture ` devices. + +.. note:: The default function of a ``/dev/video`` device is video + capturing. The overlay function is only available after calling + the :ref:`VIDIOC_S_FMT ` ioctl. The driver may support simultaneous overlay and capturing using the read/write and streaming I/O methods. If so, operation at the nominal @@ -235,10 +236,10 @@ exceeded are undefined. [3]_ :ref:`VIDIOC_S_FBUF `, :ref:`framebuffer-flags`). - **Note**: this field was added in Linux 2.6.23, extending the structure. - However the :ref:`VIDIOC_[G|S|TRY]_FMT ` - ioctls, which take a pointer to a :ref:`v4l2_format ` - parent structure with padding bytes at the end, are not affected. + .. note:: This field was added in Linux 2.6.23, extending the + structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT ` + ioctls, which take a pointer to a :ref:`v4l2_format ` + parent structure with padding bytes at the end, are not affected. .. _v4l2-clip: diff --git a/Documentation/media/uapi/v4l/dev-rds.rst b/Documentation/media/uapi/v4l/dev-rds.rst index 6a0b1a874668dba552259eaea039caed80bcce7b..cd6ad63cb90b5b8e10959d2e6fb1ccabf0c19dc2 100644 --- a/Documentation/media/uapi/v4l/dev-rds.rst +++ b/Documentation/media/uapi/v4l/dev-rds.rst @@ -14,10 +14,10 @@ at devices capable of receiving and/or transmitting RDS information. For more information see the core RDS standard :ref:`iec62106` and the RBDS standard :ref:`nrsc4`. -Note that the RBDS standard as is used in the USA is almost identical to -the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only -some of the fields have slightly different meanings. See the RBDS -standard for more information. +.. note:: Note that the RBDS standard as is used in the USA is almost + identical to the RDS standard. Any RDS decoder/encoder can also handle + RBDS. Only some of the fields have slightly different meanings. See the + RBDS standard for more information. The RBDS standard also specifies support for MMBS (Modified Mobile Search). This is a proprietary format which seems to be discontinued. diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst index 39d3d860dda4c60e002f9bc4a2922759eabfcd88..5a112eb7a2451e96fcfd9eeb70ad1d4cabe334a3 100644 --- a/Documentation/media/uapi/v4l/dev-subdev.rst +++ b/Documentation/media/uapi/v4l/dev-subdev.rst @@ -72,14 +72,14 @@ reported on one (or several) V4L2 device nodes. Pad-level Formats ================= - **Warning** +.. warning:: - Pad-level formats are only applicable to very complex device that + Pad-level formats are only applicable to very complex devices that need to expose low-level format configuration to user space. Generic V4L2 applications do *not* need to use the API described in this section. - **Note** +.. note:: For the purpose of this section, the term *format* means the combination of media bus data format, frame width and frame height. diff --git a/Documentation/media/uapi/v4l/dmabuf.rst b/Documentation/media/uapi/v4l/dmabuf.rst index 57917fb98c7a29afdebca6f5c85cb290582949eb..675768f7c66a0aab9b4dfe2ceddafc31338487b5 100644 --- a/Documentation/media/uapi/v4l/dmabuf.rst +++ b/Documentation/media/uapi/v4l/dmabuf.rst @@ -143,13 +143,16 @@ functions are always available. To start and stop capturing or displaying applications call the :ref:`VIDIOC_STREAMON ` and -:ref:`VIDIOC_STREAMOFF ` ioctls. Note that -:ref:`VIDIOC_STREAMOFF ` removes all buffers from -both queues and unlocks all buffers as a side effect. Since there is no -notion of doing anything "now" on a multitasking system, if an -application needs to synchronize with another event it should examine -the struct :ref:`v4l2_buffer ` ``timestamp`` of captured or -outputted buffers. +:ref:`VIDIOC_STREAMOFF ` ioctls. + +.. note:: + + :ref:`VIDIOC_STREAMOFF ` removes all buffers from + both queues and unlocks all buffers as a side effect. Since there is no + notion of doing anything "now" on a multitasking system, if an + application needs to synchronize with another event it should examine + the struct :ref:`v4l2_buffer ` ``timestamp`` of captured or + outputted buffers. Drivers implementing DMABUF importing I/O must support the :ref:`VIDIOC_REQBUFS `, :ref:`VIDIOC_QBUF `, diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 26eb6ee851c3d1308f71d68cdee9ec9f70b2a916..11d15d3190e9589df1f1b9d8f788570d5efdd688 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -84,17 +84,20 @@ themselves than is possible with particular, this ioctl gives the dimensions of the N-dimensional array if this control consists of more than one element. -It is important to realize that due to the flexibility of controls it is -necessary to check whether the control you want to set actually is -supported in the driver and what the valid range of values is. So use -the :ref:`VIDIOC_QUERYCTRL` (or -:ref:`VIDIOC_QUERY_EXT_CTRL `) and -:ref:`VIDIOC_QUERYMENU ` ioctls to check this. Also -note that it is possible that some of the menu indices in a control of -type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` -will return an error). A good example is the list of supported MPEG -audio bitrates. Some drivers only support one or two bitrates, others -support a wider range. +.. note:: + + #. It is important to realize that due to the flexibility of controls it is + necessary to check whether the control you want to set actually is + supported in the driver and what the valid range of values is. So use + the :ref:`VIDIOC_QUERYCTRL` (or :ref:`VIDIOC_QUERY_EXT_CTRL + `) and :ref:`VIDIOC_QUERYMENU ` + ioctls to check this. + + #. It is possible that some of the menu indices in a control of + type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` + will return an error). A good example is the list of supported MPEG + audio bitrates. Some drivers only support one or two bitrates, others + support a wider range. All controls use machine endianness. @@ -181,10 +184,10 @@ Codec Control Reference Below all controls within the Codec control class are described. First the generic controls, then controls specific for certain hardware. -Note: These controls are applicable to all codecs and not just MPEG. The -defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls -were originally made for MPEG codecs and later extended to cover all -encoding formats. +.. note:: These controls are applicable to all codecs and not just MPEG. The + defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls + were originally made for MPEG codecs and later extended to cover all + encoding formats. Generic Codec Controls @@ -2282,13 +2285,15 @@ MFC 5.1 Control IDs ``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)`` Reaction coefficient for MFC rate control. Applicable to encoders. - Note 1: Valid only when the frame level RC is enabled. + .. note:: - Note 2: For tight CBR, this field must be small (ex. 2 ~ 10). For - VBR, this field must be large (ex. 100 ~ 1000). + #. Valid only when the frame level RC is enabled. - Note 3: It is not recommended to use the greater number than - FRAME_RATE * (10^9 / BIT_RATE). + #. For tight CBR, this field must be small (ex. 2 ~ 10). For + VBR, this field must be large (ex. 100 ~ 1000). + + #. It is not recommended to use the greater number than + FRAME_RATE * (10^9 / BIT_RATE). ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)`` Adaptive rate control for dark region. Valid only when H.264 and @@ -4107,14 +4112,16 @@ transmitters for `VGA `__, the receiver or transmitter subdevice that implements them, so they are only exposed on the ``/dev/v4l-subdev*`` device node. -Note that these devices can have multiple input or output pads which are -hooked up to e.g. HDMI connectors. Even though the subdevice will -receive or transmit video from/to only one of those pads, the other pads -can still be active when it comes to EDID (Extended Display -Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital -Content Protection System, :ref:`hdcp`) processing, allowing the -device to do the fairly slow EDID/HDCP handling in advance. This allows -for quick switching between connectors. +.. note:: + + Note that these devices can have multiple input or output pads which are + hooked up to e.g. HDMI connectors. Even though the subdevice will + receive or transmit video from/to only one of those pads, the other pads + can still be active when it comes to EDID (Extended Display + Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital + Content Protection System, :ref:`hdcp`) processing, allowing the + device to do the fairly slow EDID/HDCP handling in advance. This allows + for quick switching between connectors. These pads appear in several of the controls in this section as bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad diff --git a/Documentation/media/uapi/v4l/func-mmap.rst b/Documentation/media/uapi/v4l/func-mmap.rst index 3502c2afd894e4da032cbc8244a9c0f6f7bce60e..c156fb7b7422d6bdcc492ac345e72a81ff76d7e7 100644 --- a/Documentation/media/uapi/v4l/func-mmap.rst +++ b/Documentation/media/uapi/v4l/func-mmap.rst @@ -47,17 +47,20 @@ Arguments Regardless of the device type and the direction of data exchange it should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read and write access to image buffers. Drivers should support at least - this combination of flags. Note the Linux ``video-buf`` kernel - module, which is used by the bttv, saa7134, saa7146, cx88 and vivi - driver supports only ``PROT_READ`` | ``PROT_WRITE``. When the - driver does not support the desired protection the - :ref:`mmap() ` function fails. - - Note device memory accesses (e. g. the memory on a graphics card - with video capturing hardware) may incur a performance penalty - compared to main memory accesses, or reads may be significantly - slower than writes or vice versa. Other I/O methods may be more - efficient in this case. + this combination of flags. + + .. note:: + + #. The Linux ``videobuf`` kernel module, which is used by some + drivers supports only ``PROT_READ`` | ``PROT_WRITE``. When the + driver does not support the desired protection, the + :ref:`mmap() ` function fails. + + #. Device memory accesses (e. g. the memory on a graphics card + with video capturing hardware) may incur a performance penalty + compared to main memory accesses, or reads may be significantly + slower than writes or vice versa. Other I/O methods may be more + efficient in such case. ``flags`` The ``flags`` parameter specifies the type of the mapped object, @@ -73,11 +76,13 @@ Arguments One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. ``MAP_SHARED`` allows applications to share the mapped memory with - other (e. g. child-) processes. Note the Linux ``video-buf`` module - which is used by the bttv, saa7134, saa7146, cx88 and vivi driver - supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write - semantics. V4L2 applications should not set the ``MAP_PRIVATE``, - ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` flag. + other (e. g. child-) processes. + + .. note:: The Linux ``videobuf`` module which is used by some + drivers supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests + copy-on-write semantics. V4L2 applications should not set the + ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` + flags. ``fd`` File descriptor returned by :ref:`open() `. diff --git a/Documentation/media/uapi/v4l/mmap.rst b/Documentation/media/uapi/v4l/mmap.rst index b01f4486499a3999a968011199dc0210adb0d8f7..260c2db8916b3af795fab6b384c2e526f06d4eb6 100644 --- a/Documentation/media/uapi/v4l/mmap.rst +++ b/Documentation/media/uapi/v4l/mmap.rst @@ -245,12 +245,14 @@ available. The :ref:`select() ` or :ref:`poll() To start and stop capturing or output applications call the :ref:`VIDIOC_STREAMON ` and :ref:`VIDIOC_STREAMOFF -` ioctl. Note :ref:`VIDIOC_STREAMOFF ` -removes all buffers from both queues as a side effect. Since there is -no notion of doing anything "now" on a multitasking system, if an -application needs to synchronize with another event it should examine -the struct ::ref:`v4l2_buffer ` ``timestamp`` of captured -or outputted buffers. +` ioctl. + +.. note:::ref:`VIDIOC_STREAMOFF ` + removes all buffers from both queues as a side effect. Since there is + no notion of doing anything "now" on a multitasking system, if an + application needs to synchronize with another event it should examine + the struct ::ref:`v4l2_buffer ` ``timestamp`` of captured + or outputted buffers. Drivers implementing memory mapping I/O must support the :ref:`VIDIOC_REQBUFS `, :ref:`VIDIOC_QUERYBUF diff --git a/Documentation/media/uapi/v4l/pixfmt-006.rst b/Documentation/media/uapi/v4l/pixfmt-006.rst index b9e7c6844020e1e216a111fab37a8a3b4fb19c06..9a0f494e285101fe5f347d7f5d8e626481f7060e 100644 --- a/Documentation/media/uapi/v4l/pixfmt-006.rst +++ b/Documentation/media/uapi/v4l/pixfmt-006.rst @@ -17,9 +17,11 @@ identifier (enum :ref:`v4l2_quantization `) to specify non-standard quantization methods. Most of the time only the colorspace field of struct :ref:`v4l2_pix_format ` or struct :ref:`v4l2_pix_format_mplane ` -needs to be filled in. Note that the default R'G'B' quantization is full -range for all colorspaces except for BT.2020 which uses limited range -R'G'B' quantization. +needs to be filled in. + +.. note:: The default R'G'B' quantization is full range for all + colorspaces except for BT.2020 which uses limited range R'G'B' + quantization. .. _v4l2-colorspace: diff --git a/Documentation/media/uapi/v4l/pixfmt-007.rst b/Documentation/media/uapi/v4l/pixfmt-007.rst index 5e39cda6147a7fdd1519c12040c36946f4b76d02..8c946b0c63a0b1593bb11e9c1f5adc4ae7c96d62 100644 --- a/Documentation/media/uapi/v4l/pixfmt-007.rst +++ b/Documentation/media/uapi/v4l/pixfmt-007.rst @@ -536,11 +536,13 @@ Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3) The :ref:`smpte431` standard defines the colorspace used by cinema projectors that use the DCI-P3 colorspace. The default transfer function is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_709``. Note that this colorspace does not specify a -Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this -default Y'CbCr encoding was picked because it is the HDTV encoding. The -default Y'CbCr quantization is limited range. The chromaticities of the -primary colors and the white reference are: +``V4L2_YCBCR_ENC_709``. + +.. note:: Note that this colorspace does not specify a + Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this + default Y'CbCr encoding was picked because it is the HDTV encoding. The + default Y'CbCr quantization is limited range. The chromaticities of the + primary colors and the white reference are: @@ -752,10 +754,10 @@ reference are: - 0.316 -Note that this colorspace uses Illuminant C instead of D65 as the white -reference. To correctly convert an image in this colorspace to another -that uses D65 you need to apply a chromatic adaptation algorithm such as -the Bradford method. +.. note:: This colorspace uses Illuminant C instead of D65 as the white + reference. To correctly convert an image in this colorspace to another + that uses D65 you need to apply a chromatic adaptation algorithm such as + the Bradford method. The transfer function was never properly defined for NTSC 1953. The Rec. 709 transfer function is recommended in the literature: @@ -886,9 +888,9 @@ reference are identical to sRGB. The transfer function use is with full range quantization where Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and then clipped to [-128…127]. -Note that the JPEG standard does not actually store colorspace -information. So if something other than sRGB is used, then the driver -will have to set that information explicitly. Effectively -``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for -``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and -``V4L2_QUANTIZATION_FULL_RANGE``. +.. note:: The JPEG standard does not actually store colorspace + information. So if something other than sRGB is used, then the driver + will have to set that information explicitly. Effectively + ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for + ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and + ``V4L2_QUANTIZATION_FULL_RANGE``. diff --git a/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst b/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst index 2cfcc97b3c9674ffcfcafe118795d2c13913049f..14446ed7f65049883d8959b4661aea779baa2882 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst @@ -17,9 +17,10 @@ Description This format is similar to :ref:`V4L2_PIX_FMT_SBGGR8 `, except each pixel has a depth of 16 bits. The least significant byte is stored at lower -memory addresses (little-endian). Note the actual sampling precision may -be lower than 16 bits, for example 10 bits per pixel with values in -range 0 to 1023. +memory addresses (little-endian). + +..note:: The actual sampling precision may be lower than 16 bits, + for example 10 bits per pixel with values in tange 0 to 1023. **Byte Order.** Each cell is one byte. diff --git a/Documentation/media/uapi/v4l/pixfmt-y16-be.rst b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst index 0c61a10018c27aea5aa6dbb4ae0a6de678f4fda3..37fa099c16a603fe21091dfe19745d54fc692d79 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y16-be.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst @@ -15,9 +15,10 @@ Description =========== This is a grey-scale image with a depth of 16 bits per pixel. The most -significant byte is stored at lower memory addresses (big-endian). Note -the actual sampling precision may be lower than 16 bits, for example 10 -bits per pixel with values in range 0 to 1023. +significant byte is stored at lower memory addresses (big-endian). + +.. note:: Tthe actual sampling precision may be lower than 16 bits, for + example 10 bits per pixel with values in range 0 to 1023. **Byte Order.** Each cell is one byte. diff --git a/Documentation/media/uapi/v4l/pixfmt-y16.rst b/Documentation/media/uapi/v4l/pixfmt-y16.rst index a8d4b7192ae316c66b083643e2304346c3e0bbe7..4c41c042188b4497382b53366047b956d049242e 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y16.rst @@ -16,8 +16,9 @@ Description This is a grey-scale image with a depth of 16 bits per pixel. The least significant byte is stored at lower memory addresses (little-endian). -Note the actual sampling precision may be lower than 16 bits, for -example 10 bits per pixel with values in range 0 to 1023. + +.. note:: The actual sampling precision may be lower than 16 bits, for + example 10 bits per pixel with values in range 0 to 1023. **Byte Order.** Each cell is one byte. diff --git a/Documentation/media/uapi/v4l/standard.rst b/Documentation/media/uapi/v4l/standard.rst index 529891cf3af2c44dc7e925749f8e614c02e4add2..9c390c2a128ae1197c3f00246aaa38214221fe17 100644 --- a/Documentation/media/uapi/v4l/standard.rst +++ b/Documentation/media/uapi/v4l/standard.rst @@ -39,11 +39,12 @@ To query and select the standard used by the current video input or output applications call the :ref:`VIDIOC_G_STD ` and :ref:`VIDIOC_S_STD ` ioctl, respectively. The *received* standard can be sensed with the -:ref:`VIDIOC_QUERYSTD` ioctl. Note that the -parameter of all these ioctls is a pointer to a -:ref:`v4l2_std_id ` type (a standard set), *not* an -index into the standard enumeration. Drivers must implement all video -standard ioctls when the device has one or more video inputs or outputs. +:ref:`VIDIOC_QUERYSTD` ioctl. + +..note:: The parameter of all these ioctls is a pointer to a + :ref:`v4l2_std_id ` type (a standard set), *not* an + index into the standard enumeration. Drivers must implement all video + standard ioctls when the device has one or more video inputs or outputs. Special rules apply to devices such as USB cameras where the notion of video standards makes little sense. More generally for any capture or diff --git a/Documentation/media/uapi/v4l/tuner.rst b/Documentation/media/uapi/v4l/tuner.rst index 23d0e00aefdd3c471222ec12a3747c9c5c328ca9..37eb4b9b95fb4e25ee22db16aa22538300d27f46 100644 --- a/Documentation/media/uapi/v4l/tuner.rst +++ b/Documentation/media/uapi/v4l/tuner.rst @@ -26,13 +26,14 @@ To query and change tuner properties applications use the :ref:`VIDIOC_S_TUNER ` ioctls, respectively. The struct :ref:`v4l2_tuner ` returned by :ref:`VIDIOC_G_TUNER ` also contains signal status information applicable when the tuner of the -current video or radio input is queried. Note that :ref:`VIDIOC_S_TUNER ` -does not switch the current tuner, when there is more than one at all. -The tuner is solely determined by the current video input. Drivers must -support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct -:ref:`v4l2_capability ` returned by the -:ref:`VIDIOC_QUERYCAP` ioctl when the device has -one or more tuners. +current video or radio input is queried. + +.. note:: :ref:`VIDIOC_S_TUNER ` does not switch the + current tuner, when there is more than one at all. The tuner is solely + determined by the current video input. Drivers must support both ioctls + and set the ``V4L2_CAP_TUNER`` flag in the struct :ref:`v4l2_capability + ` returned by the :ref:`VIDIOC_QUERYCAP` ioctl when the + device has one or more tuners. Modulators diff --git a/Documentation/media/uapi/v4l/userp.rst b/Documentation/media/uapi/v4l/userp.rst index 0871c204dc6c97fdd56a34a04a25d415ba1a890a..601963a33acbde2d85cb400e1b2f1a7404cd60cc 100644 --- a/Documentation/media/uapi/v4l/userp.rst +++ b/Documentation/media/uapi/v4l/userp.rst @@ -86,13 +86,14 @@ available. To start and stop capturing or output applications call the :ref:`VIDIOC_STREAMON ` and -:ref:`VIDIOC_STREAMOFF ` ioctl. Note -:ref:`VIDIOC_STREAMOFF ` removes all buffers from both -queues and unlocks all buffers as a side effect. Since there is no -notion of doing anything "now" on a multitasking system, if an -application needs to synchronize with another event it should examine -the struct :ref:`v4l2_buffer ` ``timestamp`` of captured or -outputted buffers. +:ref:`VIDIOC_STREAMOFF ` ioctl. + +.. note:: ref:`VIDIOC_STREAMOFF ` removes all buffers from + both queues and unlocks all buffers as a side effect. Since there is no + notion of doing anything "now" on a multitasking system, if an + application needs to synchronize with another event it should examine + the struct :ref:`v4l2_buffer ` ``timestamp`` of captured or + outputted buffers. Drivers implementing user pointer I/O must support the :ref:`VIDIOC_REQBUFS `, :ref:`VIDIOC_QBUF `, diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst index efa911c0fb194321977a7c7f5ba6e8c9b63021cb..f7e1b80af29ea8630f3cadcee022547932958c8d 100644 --- a/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst +++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst @@ -33,7 +33,7 @@ Arguments Description =========== - **Note** +.. note:: This is an :ref:`experimental` interface and may change in the future. diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst index 345aa321f38083b26405094c908a52c6fc2ac683..09d2880e6170b581cbbbb1b1a10aedb5b0d5af54 100644 --- a/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst +++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst @@ -35,7 +35,7 @@ Arguments Description =========== - **Note** +.. note:: This is an :ref:`experimental` interface and may change in the future. diff --git a/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst index 5a35bb254b4bae2488e68ac2df7ce4b4f9eba9f5..6e05957013bb4bdeccf5c559f216ada32d8c43f6 100644 --- a/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst +++ b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst @@ -37,8 +37,10 @@ To query the capabilities of the DV receiver/transmitter applications initialize the ``pad`` field to 0, zero the reserved array of struct :ref:`v4l2_dv_timings_cap ` and call the ``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill -in the structure. Note that drivers may return different values after -switching the video input or output. +in the structure. + +.. note:: Drivers may return different values after + switching the video input or output. When implemented by the driver DV capabilities of subdevices can be queried by calling the ``VIDIOC_SUBDEV_DV_TIMINGS_CAP`` ioctl directly diff --git a/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst index f0dd0c4ca7d0d9d1687d93a063244d36714185c9..3ba75d3fb93c27179c7fd885779ea98547da5bd2 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst @@ -47,8 +47,10 @@ field, set the ``pad`` field to 0, zero the reserved array of struct structure. Drivers fill the rest of the structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all supported DV timings, applications shall begin at index zero, incrementing by one -until the driver returns ``EINVAL``. Note that drivers may enumerate a -different set of DV timings after switching the video input or output. +until the driver returns ``EINVAL``. + +.. note:: Drivers may enumerate a different set of DV timings after + switching the video input or output. When implemented by the driver DV timings of subdevices can be queried by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst index 257c624e27be0001bcaa744a51397be3d15e9e3d..90996f69d6ae7885e89084abddb7bd825e3118a2 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst @@ -40,8 +40,8 @@ fill the rest of the structure or return an ``EINVAL`` error code. All formats are enumerable by beginning at index zero and incrementing by one until ``EINVAL`` is returned. -Note that after switching input or output the list of enumerated image -formats may be different. +.. note:: After switching input or output the list of enumerated image + formats may be different. .. _v4l2-fmtdesc: @@ -111,8 +111,10 @@ formats may be different. #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) Several image formats are already defined by this specification in - :ref:`pixfmt`. Note these codes are not the same as those used - in the Windows world. + :ref:`pixfmt`. + + .. attention:: These codes are not the same as those used + in the Windows world. - .. row 7 diff --git a/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst index 5d5de535a0fe20a840abe52bb5d4365b68e1796b..ceae6003039e114d67f983e9ce2ae378f9c14917 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst @@ -73,25 +73,21 @@ the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type does it make sense to increase the index value to receive more frame intervals. -Note that the order in which the frame intervals are returned has no -special meaning. In particular does it not say anything about potential -default frame intervals. +.. note:: The order in which the frame intervals are returned has no + special meaning. In particular does it not say anything about potential + default frame intervals. Applications can assume that the enumeration data does not change without any interaction from the application itself. This means that the enumeration data is consistent if the application does not perform any other ioctl calls while it runs the frame interval enumeration. +.. note:: -Notes -===== - -- **Frame intervals and frame rates:** The V4L2 API uses frame + **Frame intervals and frame rates:** The V4L2 API uses frame intervals instead of frame rates. Given the frame interval the frame rate can be computed as follows: - - :: frame_rate = 1 / frame_interval diff --git a/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst index d3b2e97df6c9c967640ef22191b493a1c8d7b13d..8b268354d44270cc9b419ca0164bcf8a7f68512c 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst @@ -72,9 +72,9 @@ the ``type`` field to determine the type of frame size enumeration the device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does it make sense to increase the index value to receive more frame sizes. -Note that the order in which the frame sizes are returned has no special -meaning. In particular does it not say anything about potential default -format sizes. +.. note:: The order in which the frame sizes are returned has no special + meaning. In particular does it not say anything about potential default + format sizes. Applications can assume that the enumeration data does not change without any interaction from the application itself. This means that the diff --git a/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst index ea754f4f55323657619c1603d613001521cafdb7..00ab5e19cc1d5d83609011302ffec71aadb23b16 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst @@ -127,12 +127,14 @@ of the corresponding tuner/modulator is set. - ``modulation`` - :cspan:`2` The supported modulation systems of this frequency - band. See :ref:`band-modulation`. Note that currently only one - modulation system per frequency band is supported. More work will - need to be done if multiple modulation systems are possible. - Contact the linux-media mailing list - (`https://linuxtv.org/lists.php `__) - if you need that functionality. + band. See :ref:`band-modulation`. + + .. note:: Currently only one modulation system per frequency band + is supported. More work will need to be done if multiple + modulation systems are possible. Contact the linux-media + mailing list + (`https://linuxtv.org/lists.php `__) + if you need such functionality. - .. row 8 diff --git a/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst index 15bc5a40f4a65f7c3ba20413332cbd83b94da6d4..cde1db55834f96e69d7cf5becba53fc8914285c2 100644 --- a/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst +++ b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst @@ -41,8 +41,8 @@ structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all audio outputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. -Note connectors on a TV card to loop back the received audio signal to a -sound card are not audio outputs in this sense. +.. note:: Connectors on a TV card to loop back the received audio signal + to a sound card are not audio outputs in this sense. See :ref:`VIDIOC_G_AUDIOout ` for a description of struct :ref:`v4l2_audioout `. diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst index c1fc2e1f1d98b0f3720aaaef4dd15e3c35da5e61..5060f54e3d18be165c008a31b88d354bc805e6eb 100644 --- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst +++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst @@ -233,8 +233,8 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - The input is connected to a device that produces a signal that is flipped vertically and does not correct this before passing the - signal to userspace. Note that a 180 degree rotation is the same - as HFLIP | VFLIP + signal to userspace. + .. note:: A 180 degree rotation is the same as HFLIP | VFLIP - .. row 8 diff --git a/Documentation/media/uapi/v4l/vidioc-g-audioout.rst b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst index bee5f78ed7c1dbba8cbea1cb68c1ca59648eca09..b1c1bfeb251e79ceefe8f259536ef6a9ca9426cc 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-audioout.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst @@ -51,8 +51,8 @@ return the ``EINVAL`` error code when the index is out of bounds. This is a write-only ioctl, it does not return the current audio output attributes as ``VIDIOC_G_AUDOUT`` does. -Note connectors on a TV card to loop back the received audio signal to a -sound card are not audio outputs in this sense. +.. note:: Connectors on a TV card to loop back the received audio signal + to a sound card are not audio outputs in this sense. .. _v4l2-audioout: diff --git a/Documentation/media/uapi/v4l/vidioc-g-edid.rst b/Documentation/media/uapi/v4l/vidioc-g-edid.rst index 907b2c1764a33a2554ebee677d0a55f2331a97eb..1a982b68a72f779f5563220af27963e5f1650c4f 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-edid.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-edid.rst @@ -65,8 +65,10 @@ If ``start_block`` and ``blocks`` are both set to 0 when :ref:`VIDIOC_G_EDID ` is called, then the driver will set ``blocks`` to the total number of available EDID blocks and it will return 0 without copying any data. This is an easy way to discover how many EDID blocks -there are. Note that if there are no EDID blocks available at all, then -the driver will set ``blocks`` to 0 and it returns 0. +there are. + +.. note:: If there are no EDID blocks available at all, then + the driver will set ``blocks`` to 0 and it returns 0. To set the EDID blocks of a receiver the application has to fill in the ``pad``, ``blocks`` and ``edid`` fields, set ``start_block`` to 0 and diff --git a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst index 96b6eaca755c2433110f8b19b23a8c4291cff7a3..39e24ad4b825c7c2fc46c8c2c962db5ef403cc85 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst @@ -125,10 +125,12 @@ still cause this situation. the payload. If :ref:`VIDIOC_G_EXT_CTRLS ` finds that this value is less than is required to store the payload result, then it is set to a value large enough to store the payload result and ``ENOSPC`` is - returned. Note that for string controls this ``size`` field should - not be confused with the length of the string. This field refers - to the size of the memory that contains the string. The actual - *length* of the string may well be much smaller. + returned. + + .. note:: For string controls, this ``size`` field should + not be confused with the length of the string. This field refers + to the size of the memory that contains the string. The actual + *length* of the string may well be much smaller. - .. row 3 @@ -261,8 +263,10 @@ still cause this situation. - Which value of the control to get/set/try. ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default - value of the control. Please note that you can only get the - default value of the control, you cannot set or try it. + value of the control. + + .. note:: You can only get the default value of the control, + you cannot set or try it. For backwards compatibility you can also use a control class here (see :ref:`ctrl-class`). In that case all controls have to diff --git a/Documentation/media/uapi/v4l/vidioc-g-modulator.rst b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst index 05d83610bdc5bf24f58be4a0a7be8ca4a69f2e0b..a2e8c73f06786a5d701b3e38bc41d6ec0ee9392a 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-modulator.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst @@ -128,12 +128,14 @@ To change the radio frequency the - With this field applications can determine how audio sub-carriers shall be modulated. It contains a set of flags as defined in - :ref:`modulator-txsubchans`. Note the tuner ``rxsubchans`` flags - are reused, but the semantics are different. Video output devices - are assumed to have an analog or PCM audio input with 1-3 - channels. The ``txsubchans`` flags select one or more channels for - modulation, together with some audio subprogram indicator, for - example a stereo pilot tone. + :ref:`modulator-txsubchans`. + + .. note:: The tuner ``rxsubchans`` flags are reused, but the + semantics are different. Video output devices + are assumed to have an analog or PCM audio input with 1-3 + channels. The ``txsubchans`` flags select one or more channels + for modulation, together with some audio subprogram indicator, + for example, a stereo pilot tone. - .. row 7 diff --git a/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst index 76dd4ba3254f6bc1432b1c579f0ccfb644e01b09..f1f661d0200c7dacfeebbec73adea0948d4db7fc 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst @@ -40,8 +40,8 @@ output device, applications initialize the ``type`` field of a struct driver fills in the remaining fields or returns an ``EINVAL`` error code if the sliced VBI API is unsupported or ``type`` is invalid. -Note the ``type`` field was added, and the ioctl changed from read-only -to write-read, in Linux 2.6.19. +.. note:: The ``type`` field was added, and the ioctl changed from read-only + to write-read, in Linux 2.6.19. .. _v4l2-sliced-vbi-cap: diff --git a/Documentation/media/uapi/v4l/vidioc-g-tuner.rst b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst index a8d7ebd73e8a3bb0b78f6a280ae6faf908657e3b..c82085513beeac4de7b1c1f6bf16dc03fbc24046 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-tuner.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst @@ -391,9 +391,9 @@ To change the radio frequency the carrier for a monaural secondary language. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability. - Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags - are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner - supports the ``V4L2_STD_NTSC_M`` video standard. + .. note:: The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` + flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner + supports the ``V4L2_STD_NTSC_M`` video standard. - .. row 9 @@ -500,10 +500,11 @@ To change the radio frequency the - 0x0004 - - The tuner receives a Second Audio Program. Note the - ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are - synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current - video standard is ``V4L2_STD_NTSC_M``. + - The tuner receives a Second Audio Program. + + .. note:: The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` + flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies + when the current video standard is ``V4L2_STD_NTSC_M``. - .. row 6 @@ -578,9 +579,10 @@ To change the radio frequency the - Play the Second Audio Program. When the tuner receives no bilingual audio or SAP, or their reception is not supported the driver shall fall back to mono or stereo mode. Only - ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the - ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are - synonyms. + ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. + + .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` + are synonyms. - .. row 6 diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst index 9870d243131ae8b328c00ec0e053db85988bc756..3b927f36fb5b07ff80980d90bee31b8307af3ccc 100644 --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -135,14 +135,15 @@ EINVAL EIO ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate - temporary problems like signal loss. Note the driver might dequeue - an (empty) buffer despite returning an error, or even stop - capturing. Reusing such buffer may be unsafe though and its details - (e.g. ``index``) may not be returned either. It is recommended that - drivers indicate recoverable errors by setting the - ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the - application should be able to safely reuse the buffer and continue - streaming. + temporary problems like signal loss. + + .. note:: The driver might dequeue an (empty) buffer despite returning + an error, or even stop capturing. Reusing such buffer may be unsafe + though and its details (e.g. ``index``) may not be returned either. + It is recommended that drivers indicate recoverable errors by setting + the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the + application should be able to safely reuse the buffer and continue + streaming. EPIPE ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem diff --git a/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst index 338b80df5b9b8caae3e491be10ec08f9ed37c4e9..416d8d604af47075cb57799e47e702d5d5ee71fe 100644 --- a/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst @@ -39,16 +39,16 @@ similar to sensing the video standard. To do so, applications call :ref:`v4l2_dv_timings `. Once the hardware detects the timings, it will fill in the timings structure. -Please note that drivers shall *not* switch timings automatically if new -timings are detected. Instead, drivers should send the -``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect -that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`. -The reason is that new timings usually mean different buffer sizes as -well, and you cannot change buffer sizes on the fly. In general, -applications that receive the Source Change event will have to call -:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they -will have to stop streaming, set the new timings, allocate new buffers -and start streaming again. +.. note:: Drivers shall *not* switch timings automatically if new + timings are detected. Instead, drivers should send the + ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect + that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`. + The reason is that new timings usually mean different buffer sizes as + well, and you cannot change buffer sizes on the fly. In general, + applications that receive the Source Change event will have to call + :ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they + will have to stop streaming, set the new timings, allocate new buffers + and start streaming again. If the timings could not be detected because there was no signal, then ENOLINK is returned. If a signal was detected, but it was unstable and diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst index 0f27e712eec98bebb39f3b91811093f11a4433c5..4342aceddd57eb36031c4157b5edff5bbe6bc2f7 100644 --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -82,10 +82,12 @@ fills the rest of the structure or returns an ``EINVAL`` error code when the ``id`` or ``index`` is invalid. Menu items are enumerated by calling ``VIDIOC_QUERYMENU`` with successive ``index`` values from struct :ref:`v4l2_queryctrl ` ``minimum`` to ``maximum``, -inclusive. Note that it is possible for ``VIDIOC_QUERYMENU`` to return -an ``EINVAL`` error code for some indices between ``minimum`` and -``maximum``. In that case that particular menu item is not supported by -this driver. Also note that the ``minimum`` value is not necessarily 0. +inclusive. + +.. note:: It is possible for ``VIDIOC_QUERYMENU`` to return + an ``EINVAL`` error code for some indices between ``minimum`` and + ``maximum``. In that case that particular menu item is not supported by + this driver. Also note that the ``minimum`` value is not necessarily 0. See also the examples in :ref:`control`. @@ -184,9 +186,10 @@ See also the examples in :ref:`control`. - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``, ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid - for other types of controls. Note that drivers reset controls to - their default value only when the driver is first loaded, never - afterwards. + for other types of controls. + + .. note:: Drivers reset controls to their default value only when + the driver is first loaded, never afterwards. - .. row 8 @@ -301,9 +304,10 @@ See also the examples in :ref:`control`. - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``, ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8`` - or ``_U16`` control. Not valid for other types of controls. Note - that drivers reset controls to their default value only when the - driver is first loaded, never afterwards. + or ``_U16`` control. Not valid for other types of controls. + + .. note:: Drivers reset controls to their default value only when + the driver is first loaded, never afterwards. - .. row 8 @@ -722,11 +726,12 @@ See also the examples in :ref:`control`. control changes continuously. A typical example would be the current gain value if the device is in auto-gain mode. In such a case the hardware calculates the gain value based on the lighting - conditions which can change over time. Note that setting a new - value for a volatile control will have no effect and no - ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless the - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is also set. - Otherwise the new value will just be ignored. + conditions which can change over time. + + .. note:: Setting a new value for a volatile control will have no + effect and no ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless + the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is + also set. Otherwise the new value will just be ignored. - .. row 9 diff --git a/Documentation/media/uapi/v4l/vidioc-querystd.rst b/Documentation/media/uapi/v4l/vidioc-querystd.rst index 5bf62775c7409ccfc525948ec55fc477fba5de79..b4a4e222c7b0c1c9bc64f3c80a1f402dddd34360 100644 --- a/Documentation/media/uapi/v4l/vidioc-querystd.rst +++ b/Documentation/media/uapi/v4l/vidioc-querystd.rst @@ -43,16 +43,16 @@ will return V4L2_STD_UNKNOWN. When detection is not possible or fails, the set must contain all standards supported by the current video input or output. -Please note that drivers shall *not* switch the video standard -automatically if a new video standard is detected. Instead, drivers -should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support -this) and expect that userspace will take action by calling -:ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean -different buffer sizes as well, and you cannot change buffer sizes on -the fly. In general, applications that receive the Source Change event -will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video -standard is valid they will have to stop streaming, set the new -standard, allocate new buffers and start streaming again. +.. note:: Drivers shall *not* switch the video standard + automatically if a new video standard is detected. Instead, drivers + should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support + this) and expect that userspace will take action by calling + :ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean + different buffer sizes as well, and you cannot change buffer sizes on + the fly. In general, applications that receive the Source Change event + will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video + standard is valid they will have to stop streaming, set the new + standard, allocate new buffers and start streaming again. Return Value diff --git a/Documentation/media/uapi/v4l/vidioc-streamon.rst b/Documentation/media/uapi/v4l/vidioc-streamon.rst index e87500e608e1578ffde4a809eda14e56157c5a9d..bb23745ebcaf41ea331725a0c0a5d60104e9734c 100644 --- a/Documentation/media/uapi/v4l/vidioc-streamon.rst +++ b/Documentation/media/uapi/v4l/vidioc-streamon.rst @@ -76,10 +76,10 @@ then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``, but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting state as mentioned above. -Note that applications can be preempted for unknown periods right before -or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is -no notion of starting or stopping "now". Buffer timestamps can be used -to synchronize with other events. +.. note:: Applications can be preempted for unknown periods right before + or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is + no notion of starting or stopping "now". Buffer timestamps can be used + to synchronize with other events. Return Value diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst index 690034a391d37b04f93e0d3d5f0a344dc757c0f4..ae802f1594e76f5563e2df32bfaa7a0c870f03c9 100644 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst @@ -35,7 +35,7 @@ Arguments Description =========== - **Note** +.. note:: This is an :ref:`obsolete` interface and may be removed in the future. It is superseded by diff --git a/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst index a027f602de3d42235a12510c20aa2f74e129ed0e..3ed91c6277022bd618cd0425804bc575c7ba7739 100644 --- a/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst +++ b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst @@ -51,9 +51,11 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. - ``type`` - - Type of the event, see :ref:`event-type`. Note that - ``V4L2_EVENT_ALL`` can be used with VIDIOC_UNSUBSCRIBE_EVENT for - unsubscribing all events at once. + - Type of the event, see :ref:`event-type`. + + .. note:: ``V4L2_EVENT_ALL`` can be used with + :ref:`VIDIOC_UNSUBSCRIBE_EVENT` for unsubscribing all events + at once. - .. row 2