diff options
Diffstat (limited to 'Documentation/userspace-api/media')
472 files changed, 17656 insertions, 15294 deletions
diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile index 81a4a1a53bce..3d8aaf5c253b 100644 --- a/Documentation/userspace-api/media/Makefile +++ b/Documentation/userspace-api/media/Makefile @@ -7,8 +7,8 @@ PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl UAPI = $(srctree)/include/uapi/linux KAPI = $(srctree)/include/linux -FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \ - videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst +FILES = ca.h.rst dmx.h.rst frontend.h.rst net.h.rst \ + videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) @@ -21,9 +21,6 @@ quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \ silent_gen_rst = ${gen_rst} -$(BUILDDIR)/audio.h.rst: ${UAPI}/dvb/audio.h ${PARSER} $(SRC_DIR)/audio.h.rst.exceptions - @$($(quiet)gen_rst) - $(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions @$($(quiet)gen_rst) @@ -36,9 +33,6 @@ $(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend $(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions @$($(quiet)gen_rst) -$(BUILDDIR)/video.h.rst: ${UAPI}/dvb/video.h ${PARSER} $(SRC_DIR)/video.h.rst.exceptions - @$($(quiet)gen_rst) - $(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions @$($(quiet)gen_rst) @@ -53,10 +47,11 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception # Media build rules -.PHONY: all html epub xml latex +.PHONY: all html texinfo epub xml latex all: $(IMGDOT) $(BUILDDIR) ${TARGETS} html: all +texinfo: all epub: all xml: all latex: $(IMGPDF) all diff --git a/Documentation/userspace-api/media/audio.h.rst.exceptions b/Documentation/userspace-api/media/audio.h.rst.exceptions deleted file mode 100644 index cf6620477f73..000000000000 --- a/Documentation/userspace-api/media/audio.h.rst.exceptions +++ /dev/null @@ -1,19 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _DVBAUDIO_H_ - -# Undocumented audio caps, as this is a deprecated API anyway -ignore define AUDIO_CAP_DTS -ignore define AUDIO_CAP_LPCM -ignore define AUDIO_CAP_MP1 -ignore define AUDIO_CAP_MP2 -ignore define AUDIO_CAP_MP3 -ignore define AUDIO_CAP_AAC -ignore define AUDIO_CAP_OGG -ignore define AUDIO_CAP_SDDS -ignore define AUDIO_CAP_AC3 - -# some typedefs should point to struct/enums -replace typedef audio_mixer_t :c:type:`audio_mixer` -replace typedef audio_status_t :c:type:`audio_status` diff --git a/Documentation/userspace-api/media/cec.h.rst.exceptions b/Documentation/userspace-api/media/cec.h.rst.exceptions index d83790ccac8e..15fa1752d4ef 100644 --- a/Documentation/userspace-api/media/cec.h.rst.exceptions +++ b/Documentation/userspace-api/media/cec.h.rst.exceptions @@ -140,7 +140,7 @@ ignore define CEC_OP_REC_SEQ_TUESDAY ignore define CEC_OP_REC_SEQ_WEDNESDAY ignore define CEC_OP_REC_SEQ_THURSDAY ignore define CEC_OP_REC_SEQ_FRIDAY -ignore define CEC_OP_REC_SEQ_SATERDAY +ignore define CEC_OP_REC_SEQ_SATURDAY ignore define CEC_OP_REC_SEQ_ONCE_ONLY ignore define CEC_MSG_CLEAR_DIGITAL_TIMER @@ -239,6 +239,7 @@ ignore define CEC_OP_FEAT_DEV_HAS_DECK_CONTROL ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_RATE ignore define CEC_OP_FEAT_DEV_SINK_HAS_ARC_TX ignore define CEC_OP_FEAT_DEV_SOURCE_HAS_ARC_RX +ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_VOLUME_LEVEL ignore define CEC_MSG_GIVE_FEATURES @@ -487,6 +488,7 @@ ignore define CEC_OP_SYS_AUD_STATUS_ON ignore define CEC_MSG_SYSTEM_AUDIO_MODE_REQUEST ignore define CEC_MSG_SYSTEM_AUDIO_MODE_STATUS +ignore define CEC_MSG_SET_AUDIO_VOLUME_LEVEL ignore define CEC_OP_AUD_FMT_ID_CEA861 ignore define CEC_OP_AUD_FMT_ID_CEA861_CXT diff --git a/Documentation/userspace-api/media/cec/cec-api.rst b/Documentation/userspace-api/media/cec/cec-api.rst index 871db54dfd24..578303d484f3 100644 --- a/Documentation/userspace-api/media/cec/cec-api.rst +++ b/Documentation/userspace-api/media/cec/cec-api.rst @@ -1,12 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. include:: <isonum.txt> .. _cec: @@ -18,13 +10,8 @@ Part V - Consumer Electronics Control API This part describes the CEC: Consumer Electronics Control -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/cec/cec-func-close.rst b/Documentation/userspace-api/media/cec/cec-func-close.rst index b89e06a43dad..409e70a5f80f 100644 --- a/Documentation/userspace-api/media/cec/cec-func-close.rst +++ b/Documentation/userspace-api/media/cec/cec-func-close.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _cec-func-close: @@ -18,7 +12,6 @@ Name cec-close - Close a cec device - Synopsis ======== @@ -26,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: cec-close Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -43,11 +33,10 @@ Description Closes the cec device. Resources associated with the file descriptor are freed. The device configuration remain unchanged. - Return Value ============ -:c:func:`close() <cec-close>` returns 0 on success. On error, -1 is returned, and +:c:func:`close()` returns 0 on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: ``EBADF`` diff --git a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst index d16a479aacb1..7c93f86de6cc 100644 --- a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst +++ b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _cec-func-ioctl: @@ -25,15 +19,13 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: cec-ioctl +``int ioctl(int fd, int request, void *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``request`` CEC ioctl request code as defined in the cec.h header file, for @@ -42,11 +34,10 @@ Arguments ``argp`` Pointer to a request-specific structure. - Description =========== -The :c:func:`ioctl() <cec-ioctl>` function manipulates cec device parameters. The +The :c:func:`ioctl()` function manipulates cec device parameters. The argument ``fd`` must be an open file descriptor. The ioctl ``request`` code specifies the cec function to be called. It @@ -58,7 +49,6 @@ their parameters are located in the cec.h header file. All cec ioctl requests, their respective function and parameters are specified in :ref:`cec-user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-func-open.rst b/Documentation/userspace-api/media/cec/cec-func-open.rst index 67fd021556b2..d86563a34b9e 100644 --- a/Documentation/userspace-api/media/cec/cec-func-open.rst +++ b/Documentation/userspace-api/media/cec/cec-func-open.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _cec-func-open: @@ -25,10 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: cec-open - Arguments ========= @@ -49,11 +40,10 @@ Arguments Other flags have no effect. - Description =========== -To open a cec device applications call :c:func:`open() <cec-open>` with the +To open a cec device applications call :c:func:`open()` with the desired device name. The function has no side effects; the device configuration remain unchanged. @@ -61,11 +51,10 @@ When the device is opened in read-only mode, attempts to modify its configuration will result in an error, and ``errno`` will be set to EBADF. - Return Value ============ -:c:func:`open() <cec-open>` returns the new file descriptor on success. On error, +:c:func:`open()` returns the new file descriptor on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes include: diff --git a/Documentation/userspace-api/media/cec/cec-func-poll.rst b/Documentation/userspace-api/media/cec/cec-func-poll.rst index ed3652d9bf17..980bbfc0bcce 100644 --- a/Documentation/userspace-api/media/cec/cec-func-poll.rst +++ b/Documentation/userspace-api/media/cec/cec-func-poll.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _cec-func-poll: @@ -18,7 +12,6 @@ Name cec-poll - Wait for some event on a file descriptor - Synopsis ======== @@ -26,9 +19,7 @@ Synopsis #include <sys/poll.h> - .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: cec-poll Arguments ========= @@ -42,14 +33,13 @@ Arguments ``timeout`` Timeout to wait for events - Description =========== -With the :c:func:`poll() <cec-poll>` function applications can wait for CEC +With the :c:func:`poll()` function applications can wait for CEC events. -On success :c:func:`poll() <cec-poll>` returns the number of file descriptors +On success :c:func:`poll()` returns the number of file descriptors that have been selected (that is, file descriptors for which the ``revents`` field of the respective struct :c:type:`pollfd` is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in @@ -60,13 +50,12 @@ then the ``POLLPRI`` flag is set. When the function times out it returns a value of zero, on failure it returns -1 and the ``errno`` variable is set appropriately. -For more details see the :c:func:`poll() <cec-poll>` manual page. - +For more details see the :c:func:`poll()` manual page. Return Value ============ -On success, :c:func:`poll() <cec-poll>` returns the number structures which have +On success, :c:func:`poll()` returns the number structures which have non-zero ``revents`` fields, or zero if the call timed out. On error -1 is returned, and the ``errno`` variable is set appropriately: diff --git a/Documentation/userspace-api/media/cec/cec-funcs.rst b/Documentation/userspace-api/media/cec/cec-funcs.rst index 88966b5175d2..aa6b790e8400 100644 --- a/Documentation/userspace-api/media/cec/cec-funcs.rst +++ b/Documentation/userspace-api/media/cec/cec-funcs.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _cec-user-func: diff --git a/Documentation/userspace-api/media/cec/cec-header.rst b/Documentation/userspace-api/media/cec/cec-header.rst index 24a83b0c35af..d70736ac2b1d 100644 --- a/Documentation/userspace-api/media/cec/cec-header.rst +++ b/Documentation/userspace-api/media/cec/cec-header.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _cec_header: diff --git a/Documentation/userspace-api/media/cec/cec-intro.rst b/Documentation/userspace-api/media/cec/cec-intro.rst index a4db82388202..1884ea090f12 100644 --- a/Documentation/userspace-api/media/cec/cec-intro.rst +++ b/Documentation/userspace-api/media/cec/cec-intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _cec-intro: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst index 94e46a11d68d..d5e014ce19b5 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_ADAP_G_CAPS: @@ -21,18 +15,18 @@ CEC_ADAP_G_CAPS - Query device capabilities Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp ) - :name: CEC_ADAP_G_CAPS +.. c:macro:: CEC_ADAP_G_CAPS + +``int ioctl(int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` - Description =========== @@ -41,7 +35,7 @@ device information, applications call the ioctl with a pointer to a struct :c:type:`cec_caps`. The driver fills the structure and returns the information to the application. The ioctl never fails. -.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.8cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.6cm}| .. c:type:: cec_caps @@ -58,6 +52,9 @@ returns the information to the application. The ioctl never fails. - The name of this CEC adapter. The combination ``driver`` and ``name`` must be unique. * - __u32 + - ``available_log_addrs`` + - The maximum number of logical addresses that can be configured. + * - __u32 - ``capabilities`` - The capabilities of the CEC adapter, see :ref:`cec-capabilities`. @@ -66,8 +63,7 @@ returns the information to the application. The ioctl never fails. - CEC Framework API version, formatted with the ``KERNEL_VERSION()`` macro. - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. _cec-capabilities: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst index 6818ddf1495c..0e19855730e1 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst @@ -2,6 +2,8 @@ .. .. Copyright 2019 Google LLC .. +.. c:namespace:: CEC + .. _CEC_ADAP_G_CONNECTOR_INFO: ******************************* @@ -16,18 +18,18 @@ CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp ) - :name: CEC_ADAP_G_CONNECTOR_INFO +.. c:macro:: CEC_ADAP_G_CONNECTOR_INFO + +``int ioctl(int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` - Description =========== @@ -37,7 +39,7 @@ provide a pointer to a cec_connector_info struct which will be populated by the kernel with the info provided by the adapter's driver. This ioctl is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}| .. c:type:: cec_connector_info @@ -57,8 +59,7 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. * - } - - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. _connector-type: @@ -81,7 +82,7 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. Information about the connector can be found in :ref:`cec-drm-connector-info`. -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. c:type:: cec_drm_connector_info diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst index 8ba3511c88b8..f3293a589dd6 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_ADAP_LOG_ADDRS: .. _CEC_ADAP_G_LOG_ADDRS: @@ -20,21 +14,22 @@ Name CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses - Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp ) - :name: CEC_ADAP_G_LOG_ADDRS +.. c:macro:: CEC_ADAP_G_LOG_ADDRS + +``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)`` + +.. c:macro:: CEC_ADAP_S_LOG_ADDRS -.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp ) - :name: CEC_ADAP_S_LOG_ADDRS +``int ioctl(int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`cec_log_addrs`. @@ -72,7 +67,7 @@ logical address types are already defined will return with error ``EBUSY``. .. c:type:: cec_log_addrs -.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{7.5cm}| +.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{8.0cm}| .. cssclass:: longtable @@ -155,8 +150,7 @@ logical address types are already defined will return with error ``EBUSY``. give the CEC framework more information about the device type, even though the framework won't use it directly in the CEC message. - -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}| .. _cec-log-addrs-flags: @@ -192,8 +186,7 @@ logical address types are already defined will return with error ``EBUSY``. All other messages are ignored. - -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}| .. _cec-versions: @@ -218,8 +211,7 @@ logical address types are already defined will return with error ``EBUSY``. - 6 - CEC version according to the HDMI 2.0 standard. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-prim-dev-types: @@ -264,8 +256,7 @@ logical address types are already defined will return with error ``EBUSY``. - 7 - Use for a video processor device. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-log-addr-types: @@ -313,8 +304,7 @@ logical address types are already defined will return with error ``EBUSY``. Control). - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-all-dev-types-flags: @@ -355,7 +345,6 @@ logical address types are already defined will return with error ``EBUSY``. - This supports the CEC Switch or Video Processing type. - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst index ce8f64c3e060..fb22f6894f26 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_ADAP_PHYS_ADDR: .. _CEC_ADAP_G_PHYS_ADDR: @@ -20,21 +14,22 @@ Name CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address - Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_G_PHYS_ADDR +.. c:macro:: CEC_ADAP_G_PHYS_ADDR + +``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)`` -.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_S_PHYS_ADDR +.. c:macro:: CEC_ADAP_S_PHYS_ADDR + +``int ioctl(int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to the CEC address. @@ -78,7 +73,6 @@ For example, the EDID for each HDMI input of the TV will have a different physical address of the form a.0.0.0 that the sources will read out and use as their physical address. - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst index 4a535fb64b4b..71d6a9e81f75 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_DQEVENT: @@ -18,22 +12,21 @@ Name CEC_DQEVENT - Dequeue a CEC event - Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp ) - :name: CEC_DQEVENT +.. c:macro:: CEC_DQEVENT + +``int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` - Description =========== @@ -51,7 +44,7 @@ two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with the same state). In that case the intermediate state changes were lost but it is guaranteed that the state did change in between the two events. -.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.2cm}| .. c:type:: cec_event_state_change @@ -79,10 +72,9 @@ it is guaranteed that the state did change in between the two events. the HDMI driver is still configuring the device or because the HDMI device was unbound. - .. c:type:: cec_event_lost_msgs -.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| +.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}| .. flat-table:: struct cec_event_lost_msgs :header-rows: 0 @@ -101,8 +93,7 @@ it is guaranteed that the state did change in between the two events. replied to within a second according to the CEC specification, this is more than enough. - -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}| .. c:type:: cec_event @@ -137,8 +128,7 @@ it is guaranteed that the state did change in between the two events. * - } - - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-events: @@ -211,8 +201,7 @@ it is guaranteed that the state did change in between the two events. if the 5V is high, then an initial event will be generated for that filehandle. - -.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| +.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.7cm}| .. _cec-event-flags: @@ -237,7 +226,6 @@ it is guaranteed that the state did change in between the two events. This is an indication that the application cannot keep up. - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst index 2d3227e80b4f..5fe105a13a6e 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_MODE: .. _CEC_G_MODE: @@ -20,17 +14,19 @@ CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp ) - :name: CEC_G_MODE +.. c:macro:: CEC_G_MODE -.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp ) - :name: CEC_S_MODE +``int ioctl(int fd, CEC_G_MODE, __u32 *argp)`` + +.. c:macro:: CEC_S_MODE + +``int ioctl(int fd, CEC_S_MODE, __u32 *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to CEC mode. @@ -76,7 +72,7 @@ always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. Available initiator modes are: -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-mode-initiator_e: @@ -108,10 +104,9 @@ Available initiator modes are: then an attempt to become one will return the ``EBUSY`` error code error. - Available follower modes are: -.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}| +.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{9.8cm}| .. _cec-mode-follower_e: @@ -193,14 +188,13 @@ Available follower modes are: in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise the ``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 + directed messages for other CEC devices, will be reported. This is very useful for debugging, but not all devices support this. This mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set, otherwise the ``EINVAL`` error code is returned. This is only allowed if the process has the ``CAP_NET_ADMIN`` capability. If that is not set, then the ``EPERM`` error code is returned. - Core message processing details: .. tabularcolumns:: |p{6.6cm}|p{10.9cm}| @@ -279,7 +273,6 @@ Core message processing details: and then just pass the message on to the follower(s). - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst index e456b2bc92a1..364938ad34df 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC .. _CEC_TRANSMIT: .. _CEC_RECEIVE: @@ -19,21 +13,22 @@ Name CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message - Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp ) - :name: CEC_RECEIVE +.. c:macro:: CEC_RECEIVE + +``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)`` + +.. c:macro:: CEC_TRANSMIT -.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp ) - :name: CEC_TRANSMIT +``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <cec-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct cec_msg. @@ -53,9 +48,12 @@ it will return -1 and set errno to the ``ETIMEDOUT`` error code. A received message can be: 1. a message received from another CEC device (the ``sequence`` field will - be 0). -2. the result of an earlier non-blocking transmit (the ``sequence`` field will - be non-zero). + be 0, ``tx_status`` will be 0 and ``rx_status`` will be non-zero). +2. the transmit result of an earlier non-blocking transmit (the ``sequence`` + field will be non-zero, ``tx_status`` will be non-zero and ``rx_status`` + will be 0). +3. the reply to an earlier non-blocking transmit (the ``sequence`` field will + be non-zero, ``tx_status`` will be 0 and ``rx_status`` will be non-zero). To send a CEC message the application has to fill in the struct :c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. @@ -69,12 +67,11 @@ idea to fully fill up the transmit queue. If the file descriptor is in non-blocking mode then the transmit will return 0 and the result of the transmit will be available via -:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished -(including waiting for a reply, if requested). - -The ``sequence`` field is filled in for every transmit and this can be -checked against the received messages to find the corresponding transmit -result. +:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished. +If a non-blocking transmit also specified waiting for a reply, then +the reply will arrive in a later message. The ``sequence`` field can +be used to associate both transmit results and replies with the original +transmit. Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical address is invalid (due to e.g. a disconnect) will return ``ENONET``. @@ -89,7 +86,7 @@ physical address, but the cable is still connected and CEC still works. In order to detect/wake up the device it is allowed to send poll and 'Image/Text View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). -.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}| +.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{12.8cm}| .. c:type:: cec_msg @@ -128,18 +125,17 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - ``sequence`` - A non-zero sequence number is automatically assigned by the CEC framework for all transmitted messages. It is used by the CEC framework when it queues - the transmit result (when transmit was called in non-blocking mode). This - allows the application to associate the received message with the original - transmit. + the transmit result for a non-blocking transmit. This allows the application + to associate the received message with the original transmit. + + In addition, if a non-blocking transmit will wait for a reply (ii.e. ``timeout`` + was not 0), then the ``sequence`` field of the reply will be set to the sequence + value of the original transmit. This allows the application to associate the + received message with the original transmit. * - __u32 - ``flags`` - Flags. See :ref:`cec-msg-flags` for a list of available flags. * - __u8 - - ``tx_status`` - - The status bits of the transmitted message. See - :ref:`cec-tx-status` for the possible status values. It is 0 if - this message was received, not transmitted. - * - __u8 - ``msg[16]`` - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. @@ -167,15 +163,17 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). * - __u8 - ``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. * - __u8 - ``tx_status`` - The status bits of the transmitted message. See - :ref:`cec-tx-status` for the possible status values. It is 0 if - this message was received, not transmitted. + :ref:`cec-tx-status` for the possible status values. + When calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` in non-blocking mode, + this field will be 0 if the transmit started, or non-0 if the transmit + result is known immediately. The latter would be the case when attempting + to transmit a Poll message to yourself. That results in a + :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` without ever actually + transmitting the Poll message. * - __u8 - ``tx_arb_lost_cnt`` - A counter of the number of transmit attempts that resulted in the @@ -201,8 +199,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). supports this, otherwise it is always 0. This counter is only valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. - -.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}| +.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.1cm}| .. _cec-msg-flags: @@ -235,8 +232,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). capability. If that is not set, then the ``EPERM`` error code is returned. - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-tx-status: @@ -305,8 +301,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - The transmit timed out. This should not normally happen and this indicates a driver problem. - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-rx-status: @@ -342,7 +337,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). reply was interrupted. - Return Value ============ diff --git a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst index 78632199324d..411d42a742f3 100644 --- a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst +++ b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst @@ -1,11 +1,6 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _cec_pin_error_inj: CEC Pin Framework Error Injection ================================= @@ -51,7 +46,7 @@ error injection status:: # <op>[,<mode>] rx-low-drive <bit> force a low-drive condition at this bit position # <op>[,<mode>] rx-add-byte add a spurious byte to the received CEC message # <op>[,<mode>] rx-remove-byte remove the last byte from the received CEC message - # <op>[,<mode>] rx-arb-lost <poll> generate a POLL message to trigger an arbitration lost + # any[,<mode>] rx-arb-lost [<poll>] generate a POLL message to trigger an arbitration lost # # TX error injection settings: # tx-ignore-nack-until-eom ignore early NACKs until EOM diff --git a/Documentation/userspace-api/media/drivers/aspeed-video.rst b/Documentation/userspace-api/media/drivers/aspeed-video.rst new file mode 100644 index 000000000000..567387aca6b0 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/aspeed-video.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +ASPEED video driver +=================== + +ASPEED Video Engine found on AST2400/2500/2600 SoC supports high performance +video compressions with a wide range of video quality and compression ratio +options. The adopted compressing algorithm is a modified JPEG algorithm. + +There are 2 types of compressions in this IP. + +* JPEG JFIF standard mode: for single frame and management compression +* ASPEED proprietary mode: for multi-frame and differential compression. + Support 2-pass (high quality) video compression scheme (Patent pending by + ASPEED). Provide visually lossless video compression quality or to reduce + the network average loading under intranet KVM applications. + +VIDIOC_S_FMT can be used to choose which format you want. V4L2_PIX_FMT_JPEG +stands for JPEG JFIF standard mode; V4L2_PIX_FMT_AJPG stands for ASPEED +proprietary mode. + +More details on the ASPEED video hardware operations can be found in +*chapter 6.2.16 KVM Video Driver* of SDK_User_Guide which available on +`github <https://github.com/AspeedTech-BMC/openbmc/releases/>`__. + +The ASPEED video driver implements the following driver-specific control: + +``V4L2_CID_ASPEED_HQ_MODE`` +--------------------------- + Enable/Disable ASPEED's High quality mode. This is a private control + that can be used to enable high quality for aspeed proprietary mode. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(0)`` + - ASPEED HQ mode is disabled. + * - ``(1)`` + - ASPEED HQ mode is enabled. + +``V4L2_CID_ASPEED_HQ_JPEG_QUALITY`` +----------------------------------- + Define the quality of ASPEED's High quality mode. This is a private control + that can be used to decide compression quality if High quality mode enabled + . Higher the value, better the quality and bigger the size. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(1)`` + - minimum + * - ``(12)`` + - maximum + * - ``(1)`` + - step + * - ``(1)`` + - default + +**Copyright** |copy| 2022 ASPEED Technology Inc. diff --git a/Documentation/userspace-api/media/drivers/camera-sensor.rst b/Documentation/userspace-api/media/drivers/camera-sensor.rst new file mode 100644 index 000000000000..919a50e8b9d9 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/camera-sensor.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _media_using_camera_sensor_drivers: + +Using camera sensor drivers +=========================== + +This section describes common practices for how the V4L2 sub-device interface is +used to control the camera sensor drivers. + +You may also find :ref:`media_writing_camera_sensor_drivers` useful. + +Frame size +---------- + +There are two distinct ways to configure the frame size produced by camera +sensors. + +Freely configurable camera sensor drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Freely configurable camera sensor drivers expose the device's internal +processing pipeline as one or more sub-devices with different cropping and +scaling configurations. The output size of the device is the result of a series +of cropping and scaling operations from the device's pixel array's size. + +An example of such a driver is the CCS driver. + +Register list based drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Register list based drivers generally, instead of able to configure the device +they control based on user requests, are limited to a number of preset +configurations that combine a number of different parameters that on hardware +level are independent. How a driver picks such configuration is based on the +format set on a source pad at the end of the device's internal pipeline. + +Most sensor drivers are implemented this way. + +Frame interval configuration +---------------------------- + +There are two different methods for obtaining possibilities for different frame +intervals as well as configuring the frame interval. Which one to implement +depends on the type of the device. + +Raw camera sensors +~~~~~~~~~~~~~~~~~~ + +Instead of a high level parameter such as frame interval, the frame interval is +a result of the configuration of a number of camera sensor implementation +specific parameters. Luckily, these parameters tend to be the same for more or +less all modern raw camera sensors. + +The frame interval is calculated using the following equation:: + + frame interval = (analogue crop width + horizontal blanking) * + (analogue crop height + vertical blanking) / pixel rate + +The formula is bus independent and is applicable for raw timing parameters on +large variety of devices beyond camera sensors. Devices that have no analogue +crop, use the full source image size, i.e. pixel array size. + +Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and +``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control +is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in +the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same +sub-device. The unit of that control is pixels per second. + +Register list based drivers need to implement read-only sub-device nodes for the +purpose. Devices that are not register list based need these to configure the +device's internal processing pipeline. + +The first entity in the linear pipeline is the pixel array. The pixel array may +be followed by other entities that are there to allow configuring binning, +skipping, scaling or digital crop, see :ref:`VIDIOC_SUBDEV_G_SELECTION +<VIDIOC_SUBDEV_G_SELECTION>`. + +USB cameras etc. devices +~~~~~~~~~~~~~~~~~~~~~~~~ + +USB video class hardware, as well as many cameras offering a similar higher +level interface natively, generally use the concept of frame interval (or frame +rate) on device level in firmware or hardware. This means lower level controls +implemented by raw cameras may not be used on uAPI (or even kAPI) to control the +frame interval on these devices. + +Rotation, orientation and flipping +---------------------------------- + +Some systems have the camera sensor mounted upside down compared to its natural +mounting rotation. In such cases, drivers shall expose the information to +userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION +<v4l2-camera-sensor-rotation>` control. + +Sensor drivers shall also report the sensor's mounting orientation with the +:ref:`V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>`. + +Sensor drivers that have any vertical or horizontal flips embedded in the +register programming sequences shall initialize the :ref:`V4L2_CID_HFLIP +<v4l2-cid-hflip>` and :ref:`V4L2_CID_VFLIP <v4l2-cid-vflip>` controls with the +values programmed by the register sequences. The default values of these +controls shall be 0 (disabled). Especially these controls shall not be inverted, +independently of the sensor's mounting rotation. diff --git a/Documentation/userspace-api/media/drivers/ccs.rst b/Documentation/userspace-api/media/drivers/ccs.rst new file mode 100644 index 000000000000..03015b33d5ab --- /dev/null +++ b/Documentation/userspace-api/media/drivers/ccs.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +.. include:: <isonum.txt> + +.. _media-ccs-uapi: + +MIPI CCS camera sensor driver +============================= + +The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS +<https://www.mipi.org/specifications/camera-command-set>`_ compliant +camera sensors. It exposes three sub-devices representing the pixel array, +the binner and the scaler. + +As the capabilities of individual devices vary, the driver exposes +interfaces based on the capabilities that exist in hardware. + +Also see :ref:`the CCS driver kernel documentation <media-ccs-driver>`. + +Pixel Array sub-device +---------------------- + +The pixel array sub-device represents the camera sensor's pixel matrix, as well +as analogue crop functionality present in many compliant devices. The analogue +crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the +entity. The size of the pixel matrix can be obtained by getting the +``V4L2_SEL_TGT_NATIVE_SIZE`` target. + +Binner +------ + +The binner sub-device represents the binning functionality on the sensor. For +that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the +sink pad (0). + +Additionally, if a device has no scaler or digital crop functionality, the +source pad (1) exposes another digital crop selection rectangle that can only +crop at the end of the lines and frames. + +Scaler +------ + +The scaler sub-device represents the digital crop and scaling functionality of +the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to +configure the digital crop on the sink pad (0) when digital crop is supported. +Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the +sink pad (0) as well. + +Additionally, if the scaler sub-device exists, its source pad (1) exposes +another digital crop selection rectangle that can only crop at the end of the +lines and frames. + +Digital and analogue crop +------------------------- + +Digital crop functionality is referred to as cropping that effectively works by +dropping some data on the floor. Analogue crop, on the other hand, means that +the cropped information is never retrieved. In case of camera sensors, the +analogue data is never read from the pixel matrix that are outside the +configured selection rectangle that designates crop. The difference has an +effect in device timing and likely also in power consumption. + +Private controls +---------------- + +The MIPI CCS driver implements a number of private controls under +``V4L2_CID_USER_BASE_CCS`` to control the MIPI CCS compliant camera sensors. + +Analogue gain model +~~~~~~~~~~~~~~~~~~~ + +The CCS defines an analogue gain model where the gain can be calculated using +the following formula: + + gain = m0 * x + c0 / (m1 * x + c1) + +Either m0 or c0 will be zero. The constants that are device specific, can be +obtained from the following controls: + + V4L2_CID_CCS_ANALOGUE_GAIN_M0 + V4L2_CID_CCS_ANALOGUE_GAIN_M1 + V4L2_CID_CCS_ANALOGUE_GAIN_C0 + V4L2_CID_CCS_ANALOGUE_GAIN_C1 + +The analogue gain (``x`` in the formula) is controlled through +``V4L2_CID_ANALOGUE_GAIN`` in this case. + +Alternate analogue gain model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CCS defines another analogue gain model called alternate analogue gain. In +this case, the formula to calculate actual gain consists of linear and +exponential parts: + + gain = linear * 2 ^ exponent + +The ``linear`` and ``exponent`` factors can be set using the +``V4L2_CID_CCS_ANALOGUE_LINEAR_GAIN`` and +``V4L2_CID_CCS_ANALOGUE_EXPONENTIAL_GAIN`` controls, respectively + +Shading correction +~~~~~~~~~~~~~~~~~~ + +The CCS standard supports lens shading correction. The feature can be controlled +using ``V4L2_CID_CCS_SHADING_CORRECTION``. Additionally, the luminance +correction level may be changed using +``V4L2_CID_CCS_LUMINANCE_CORRECTION_LEVEL``, where value 0 indicates no +correction and 128 indicates correcting the luminance in corners to 10 % less +than in the centre. + +Shading correction needs to be enabled for luminance correction level to have an +effect. + +**Copyright** |copy| 2020 Intel Corporation diff --git a/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst b/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst index 8a7977af79d5..debde65fb8cd 100644 --- a/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst +++ b/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst @@ -7,9 +7,7 @@ Non-compressed file format -------------------------- The cx23416 can produce (and the cx23415 can also read) raw YUV output. The -format of a YUV frame is specific to this chip and is called HM12. 'HM' stands -for 'Hauppauge Macroblock', which is a misnomer as 'Conexant Macroblock' would -be more accurate. +format of a YUV frame is 16x16 linear tiled NV12 (V4L2_PIX_FMT_NV12_16L16). The format is YUV 4:2:0 which uses 1 Y byte per pixel and 1 U and V byte per four pixels. @@ -34,8 +32,8 @@ second line of 8 UV pairs of the top-left block, etc. After transmitting this block the first line of the block on the right to the first block is transmitted, etc. -The code below is given as an example on how to convert HM12 to separate -Y, U and V planes. This code assumes frames of 720x576 (PAL) pixels. +The code below is given as an example on how to convert V4L2_PIX_FMT_NV12_16L16 +to separate Y, U and V planes. This code assumes frames of 720x576 (PAL) pixels. The width of a frame is always 720 pixels, regardless of the actual specified width. diff --git a/Documentation/userspace-api/media/drivers/dw100.rst b/Documentation/userspace-api/media/drivers/dw100.rst new file mode 100644 index 000000000000..fceea6ece622 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/dw100.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +DW100 dewarp driver +=================== + +The Vivante DW100 Dewarp Processor IP core found on i.MX8MP SoC applies a +programmable geometrical transformation on the input image to correct distortion +introduced by lenses. + +The transformation function is exposed by the hardware as a grid map with 16x16 +pixel macroblocks indexed using X, Y vertex coordinates. +:: + + Image width + <---------------------------------------> + + ^ .-------.-------.-------.-------.-------. + | | 16x16 | | | | | + I | | pixel | | | | | + m | | block | | | | | + a | .-------.-------.-------.-------.-------. + g | | | | | | | + e | | | | | | | + | | | | | | | + h | .-------.-------.-------.-------.-------. + e | | | | | | | + i | | | | | | | + g | | | | | | | + h | .-------.-------.-------.-------.-------. + t | | | | | | | + | | | | | | | + | | | | | | | + v '-------'-------'-------'-------'-------' + + Grid of Image Blocks for Dewarping Map + + +Each x, y coordinate register uses 16 bits to record the coordinate address in +an unsigned 12.4 fixed point format (UQ12.4). +:: + + .----------------------.--------..----------------------.--------. + | 31~20 | 19~16 || 15~4 | 3~0 | + | (integer) | (frac) || (integer) | (frac) | + '----------------------'--------''----------------------'--------' + <-------------------------------><-------------------------------> + Y coordinate X coordinate + + Remap Register Layout + +The dewarping map is set from applications using the +V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP control. The control contains +an array of u32 values storing (x, y) destination coordinates for each +vertex of the grid. The x coordinate is stored in the 16 LSBs and the y +coordinate in the 16 MSBs. + +The number of elements in the array must match the image size: + +.. code-block:: C + + elems = (DIV_ROUND_UP(width, 16) + 1) * (DIV_ROUND_UP(height, 16) + 1); + +If the control has not been set by the application, the driver uses an identity +map. + +More details on the DW100 hardware operations can be found in +*chapter 13.15 DeWarp* of IMX8MP_ reference manual. + +The Vivante DW100 m2m driver implements the following driver-specific control: + +``V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP (__u32 array)`` + Specifies to DW100 driver its dewarping map (aka LUT) blob as described in + *chapter 13.15.2.3 Dewarping Remap* of IMX8MP_ reference manual as an U32 + dynamic array. The image is divided into many small 16x16 blocks. If the + width/height of the image is not divisible by 16, the size of the + rightmost/bottommost block is the remainder. The dewarping map only saves + the vertex coordinates of the block. The dewarping grid map is comprised of + vertex coordinates for x and y. Each x, y coordinate register uses 16 bits + (UQ12.4) to record the coordinate address, with the Y coordinate in the + upper bits and X in the lower bits. The driver modifies the dimensions of + this control when the sink format is changed, to reflect the new input + resolution. + +.. _IMX8MP: https://www.nxp.com/webapp/Download?colCode=IMX8MPRM diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst index 05a82f8c0c99..2252063593bf 100644 --- a/Documentation/userspace-api/media/drivers/index.rst +++ b/Documentation/userspace-api/media/drivers/index.rst @@ -21,19 +21,20 @@ more details. For more details see the file COPYING in the source distribution of Linux. -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: + aspeed-video + camera-sensor + ccs cx2341x-uapi + dw100 imx-uapi max2175 - meye-uapi + npcm-video omap3isp-uapi + st-vgxy61 + thp7312 uvcvideo diff --git a/Documentation/userspace-api/media/drivers/meye-uapi.rst b/Documentation/userspace-api/media/drivers/meye-uapi.rst deleted file mode 100644 index 66b1c142f920..000000000000 --- a/Documentation/userspace-api/media/drivers/meye-uapi.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. include:: <isonum.txt> - -Vaio Picturebook Motion Eye Camera Driver -========================================= - -Copyright |copy| 2001-2004 Stelian Pop <stelian@popies.net> - -Copyright |copy| 2001-2002 Alcôve <www.alcove.com> - -Copyright |copy| 2000 Andrew Tridgell <tridge@samba.org> - -Private API ------------ - -The driver supports frame grabbing with the video4linux API, -so all video4linux tools (like xawtv) should work with this driver. - -Besides the video4linux interface, the driver has a private interface -for accessing the Motion Eye extended parameters (camera sharpness, -agc, video framerate), the snapshot and the MJPEG capture facilities. - -This interface consists of several ioctls (prototypes and structures -can be found in include/linux/meye.h): - -MEYEIOC_G_PARAMS and MEYEIOC_S_PARAMS - Get and set the extended parameters of the motion eye camera. - The user should always query the current parameters with - MEYEIOC_G_PARAMS, change what he likes and then issue the - MEYEIOC_S_PARAMS call (checking for -EINVAL). The extended - parameters are described by the meye_params structure. - - -MEYEIOC_QBUF_CAPT - Queue a buffer for capture (the buffers must have been - obtained with a VIDIOCGMBUF call and mmap'ed by the - application). The argument to MEYEIOC_QBUF_CAPT is the - buffer number to queue (or -1 to end capture). The first - call to MEYEIOC_QBUF_CAPT starts the streaming capture. - -MEYEIOC_SYNC - Takes as an argument the buffer number you want to sync. - This ioctl blocks until the buffer is filled and ready - for the application to use. It returns the buffer size. - -MEYEIOC_STILLCAPT and MEYEIOC_STILLJCAPT - Takes a snapshot in an uncompressed or compressed jpeg format. - This ioctl blocks until the snapshot is done and returns (for - jpeg snapshot) the size of the image. The image data is - available from the first mmap'ed buffer. - -Look at the 'motioneye' application code for an actual example. diff --git a/Documentation/userspace-api/media/drivers/npcm-video.rst b/Documentation/userspace-api/media/drivers/npcm-video.rst new file mode 100644 index 000000000000..b47771dd8b27 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/npcm-video.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +NPCM video driver +================= + +This driver is used to control the Video Capture/Differentiation (VCD) engine +and Encoding Compression Engine (ECE) present on Nuvoton NPCM SoCs. The VCD can +capture a frame from digital video input and compare two frames in memory, and +the ECE can compress the frame data into HEXTILE format. + +Driver-specific Controls +------------------------ + +V4L2_CID_NPCM_CAPTURE_MODE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The VCD engine supports two modes: + +- COMPLETE mode: + + Capture the next complete frame into memory. + +- DIFF mode: + + Compare the incoming frame with the frame stored in memory, and updates the + differentiated frame in memory. + +Application can use ``V4L2_CID_NPCM_CAPTURE_MODE`` control to set the VCD mode +with different control values (enum v4l2_npcm_capture_mode): + +- ``V4L2_NPCM_CAPTURE_MODE_COMPLETE``: will set VCD to COMPLETE mode. +- ``V4L2_NPCM_CAPTURE_MODE_DIFF``: will set VCD to DIFF mode. + +V4L2_CID_NPCM_RECT_COUNT +~~~~~~~~~~~~~~~~~~~~~~~~ + +If using V4L2_PIX_FMT_HEXTILE format, VCD will capture frame data and then ECE +will compress the data into HEXTILE rectangles and store them in V4L2 video +buffer with the layout defined in Remote Framebuffer Protocol: +:: + + (RFC 6143, https://www.rfc-editor.org/rfc/rfc6143.html#section-7.6.1) + + +--------------+--------------+-------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------------+ + | 2 | U16 | x-position | + | 2 | U16 | y-position | + | 2 | U16 | width | + | 2 | U16 | height | + | 4 | S32 | encoding-type (5) | + +--------------+--------------+-------------------+ + | HEXTILE rectangle data | + +-------------------------------------------------+ + +Application can get the video buffer through VIDIOC_DQBUF, and followed by +calling ``V4L2_CID_NPCM_RECT_COUNT`` control to get the number of HEXTILE +rectangles in this buffer. + +References +---------- +include/uapi/linux/npcm-video.h + +**Copyright** |copy| 2022 Nuvoton Technologies diff --git a/Documentation/userspace-api/media/drivers/st-vgxy61.rst b/Documentation/userspace-api/media/drivers/st-vgxy61.rst new file mode 100644 index 000000000000..17ac15afa77c --- /dev/null +++ b/Documentation/userspace-api/media/drivers/st-vgxy61.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +ST VGXY61 camera sensor driver +============================== + +The ST VGXY61 driver implements the following controls: + +``V4L2_CID_HDR_SENSOR_MODE`` +------------------------------- + Change the sensor HDR mode. A HDR picture is obtained by merging two + captures of the same scene using two different exposure periods. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - HDR linearize + - The merger outputs a long exposure capture as long as it is not + saturated. + * - HDR subtraction + - This involves subtracting the short exposure frame from the long + exposure frame. + * - No HDR + - This mode is used for standard dynamic range (SDR) exposures. diff --git a/Documentation/userspace-api/media/drivers/thp7312.rst b/Documentation/userspace-api/media/drivers/thp7312.rst new file mode 100644 index 000000000000..7c777e6fb7d2 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/thp7312.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +THine THP7312 ISP driver +======================== + +The THP7312 driver implements the following driver-specific controls: + +``V4L2_CID_THP7312_LOW_LIGHT_COMPENSATION`` + Enable/Disable auto-adjustment, based on lighting conditions, of the frame + rate when auto-exposure is enabled. + +``V4L2_CID_THP7312_AUTO_FOCUS_METHOD`` + Set method of auto-focus. Only takes effect when auto-focus is enabled. + + .. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``0`` + - Contrast-based auto-focus + * - ``1`` + - PDAF + * - ``2`` + - Hybrid of contrast-based and PDAF + + Supported values for the control depend on the camera sensor module + connected to the THP7312. If the module doesn't have a focus lens actuator, + this control will not be exposed by the THP7312 driver. If the module has a + controllable focus lens but the sensor doesn't support PDAF, only the + contrast-based auto-focus value will be valid. Otherwise all values for the + controls will be supported. + +``V4L2_CID_THP7312_NOISE_REDUCTION_AUTO`` + Enable/Disable auto noise reduction. + +``V4L2_CID_THP7312_NOISE_REDUCTION_ABSOLUTE`` + Set the noise reduction strength, where 0 is the weakest and 10 is the + strongest. diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst index e5fd8fad333c..a290f9fadae9 100644 --- a/Documentation/userspace-api/media/drivers/uvcvideo.rst +++ b/Documentation/userspace-api/media/drivers/uvcvideo.rst @@ -7,7 +7,7 @@ This file documents some driver-specific aspects of the UVC driver, such as driver-specific ioctls and implementation notes. Questions and remarks can be sent to the Linux UVC development mailing list at -linux-uvc-devel@lists.berlios.de. +linux-media@vger.kernel.org. Extension Unit (XU) support diff --git a/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst b/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst deleted file mode 100644 index 6841233f3fee..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_BILINGUAL_CHANNEL_SELECT: - -============================== -AUDIO_BILINGUAL_CHANNEL_SELECT -============================== - -Name ----- - -AUDIO_BILINGUAL_CHANNEL_SELECT - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_BILINGUAL_CHANNEL_SELECT, struct *audio_channel_select) - :name: AUDIO_BILINGUAL_CHANNEL_SELECT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_channel_select_t ch - - - Select the output format of the audio (mono left/right, stereo). - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. It has been replaced -by the V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control -for MPEG decoders controlled through V4L2. - -This ioctl call asks the Audio Device to select the requested channel -for bilingual streams if possible. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-channel-select.rst b/Documentation/userspace-api/media/dvb/audio-channel-select.rst deleted file mode 100644 index 18e880e7eab4..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-channel-select.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CHANNEL_SELECT: - -==================== -AUDIO_CHANNEL_SELECT -==================== - -Name ----- - -AUDIO_CHANNEL_SELECT - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CHANNEL_SELECT, struct *audio_channel_select) - :name: AUDIO_CHANNEL_SELECT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_channel_select_t ch - - - Select the output format of the audio (mono left/right, stereo). - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead. - -This ioctl call asks the Audio Device to select the requested channel if -possible. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst b/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst deleted file mode 100644 index 19f2ed752ce2..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CLEAR_BUFFER: - -================== -AUDIO_CLEAR_BUFFER -================== - -Name ----- - -AUDIO_CLEAR_BUFFER - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CLEAR_BUFFER) - :name: AUDIO_CLEAR_BUFFER - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - -Description ------------ - -This ioctl call asks the Audio Device to clear all software and hardware -buffers of the audio decoder device. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-continue.rst b/Documentation/userspace-api/media/dvb/audio-continue.rst deleted file mode 100644 index b9a2b1e608b6..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-continue.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CONTINUE: - -============== -AUDIO_CONTINUE -============== - -Name ----- - -AUDIO_CONTINUE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CONTINUE) - :name: AUDIO_CONTINUE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - -Description ------------ - -This ioctl restarts the decoding and playing process previously paused -with AUDIO_PAUSE command. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-fclose.rst b/Documentation/userspace-api/media/dvb/audio-fclose.rst deleted file mode 100644 index 448471d2f570..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-fclose.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fclose: - -======================== -Digital TV audio close() -======================== - -Name ----- - -Digital TV audio close() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int close(int fd) - :name: dvb-audio-close - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This system call closes a previously opened audio device. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/audio-fopen.rst b/Documentation/userspace-api/media/dvb/audio-fopen.rst deleted file mode 100644 index f7ae94378f92..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-fopen.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fopen: - -======================= -Digital TV audio open() -======================= - -Name ----- - -Digital TV audio open() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int open(const char *deviceName, int flags) - :name: dvb-audio-open - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - const char \*deviceName - - - Name of specific audio device. - - - .. row 2 - - - int flags - - - A bit-wise OR of the following flags: - - - .. row 3 - - - - - O_RDONLY read-only access - - - .. row 4 - - - - - O_RDWR read/write access - - - .. row 5 - - - - - O_NONBLOCK open in non-blocking mode - - - .. row 6 - - - - - (blocking mode is the default) - - -Description ------------ - -This system call opens a named audio device (e.g. -/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has -succeeded, the device will be ready for use. The significance of -blocking or non-blocking mode is described in the documentation for -functions where there is a difference. It does not affect the semantics -of the open() call itself. A device opened in blocking mode can later be -put into non-blocking mode (and vice versa) using the F_SETFL command -of the fcntl system call. This is a standard system call, documented in -the Linux manual page for fcntl. Only one user can open the Audio Device -in O_RDWR mode. All other attempts to open the device in this mode will -fail, and an error code will be returned. If the Audio Device is opened -in O_RDONLY mode, the only ioctl call that can be used is -AUDIO_GET_STATUS. All other call will return with an error code. - - -Return Value ------------- - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device driver not loaded/available. - - - .. row 2 - - - ``EBUSY`` - - - Device or resource busy. - - - .. row 3 - - - ``EINVAL`` - - - Invalid argument. diff --git a/Documentation/userspace-api/media/dvb/audio-fwrite.rst b/Documentation/userspace-api/media/dvb/audio-fwrite.rst deleted file mode 100644 index 1482636f9b1a..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-fwrite.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fwrite: - -========================= -Digital TV audio write() -========================= - -Name ----- - -Digital TV audio write() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: size_t write(int fd, const void *buf, size_t count) - :name: dvb-audio-write - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - void \*buf - - - Pointer to the buffer containing the PES data. - - - .. row 3 - - - size_t count - - - Size of buf. - - -Description ------------ - -This system call can only be used if AUDIO_SOURCE_MEMORY is selected -in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in -PES format. If O_NONBLOCK is not specified the function will block -until buffer space is available. The amount of data to be transferred is -implied by count. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode AUDIO_SOURCE_MEMORY not selected. - - - .. row 2 - - - ``ENOMEM`` - - - Attempted to write more data than the internal buffer can hold. - - - .. row 3 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst b/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst deleted file mode 100644 index 4e70d82969ad..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_GET_CAPABILITIES: - -====================== -AUDIO_GET_CAPABILITIES -====================== - -Name ----- - -AUDIO_GET_CAPABILITIES - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_GET_CAPABILITIES, unsigned int *cap) - :name: AUDIO_GET_CAPABILITIES - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - unsigned int \*cap - - - Returns a bit array of supported sound formats. - - -Description ------------ - -This ioctl call asks the Audio Device to tell us about the decoding -capabilities of the audio hardware. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-get-status.rst b/Documentation/userspace-api/media/dvb/audio-get-status.rst deleted file mode 100644 index 5a5180d642d4..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-get-status.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_GET_STATUS: - -================ -AUDIO_GET_STATUS -================ - -Name ----- - -AUDIO_GET_STATUS - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_GET_STATUS, struct audio_status *status) - :name: AUDIO_GET_STATUS - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - struct audio_status \*status - - - Returns the current state of Audio Device. - - -Description ------------ - -This ioctl call asks the Audio Device to return the current state of the -Audio Device. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-pause.rst b/Documentation/userspace-api/media/dvb/audio-pause.rst deleted file mode 100644 index 3e9fe06d3a0f..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-pause.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_PAUSE: - -=========== -AUDIO_PAUSE -=========== - -Name ----- - -AUDIO_PAUSE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_PAUSE) - :name: AUDIO_PAUSE - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This ioctl call suspends the audio stream being played. Decoding and -playing are paused. It is then possible to restart again decoding and -playing process of the audio stream using AUDIO_CONTINUE command. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-play.rst b/Documentation/userspace-api/media/dvb/audio-play.rst deleted file mode 100644 index 388a581a19f2..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-play.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_PLAY: - -========== -AUDIO_PLAY -========== - -Name ----- - -AUDIO_PLAY - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_PLAY) - :name: AUDIO_PLAY - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - -Description ------------ - -This ioctl call asks the Audio Device to start playing an audio stream -from the selected source. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-select-source.rst b/Documentation/userspace-api/media/dvb/audio-select-source.rst deleted file mode 100644 index 1ce64507de93..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-select-source.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SELECT_SOURCE: - -=================== -AUDIO_SELECT_SOURCE -=================== - -Name ----- - -AUDIO_SELECT_SOURCE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SELECT_SOURCE, struct audio_stream_source *source) - :name: AUDIO_SELECT_SOURCE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_stream_source_t source - - - Indicates the source that shall be used for the Audio stream. - - -Description ------------ - -This ioctl call informs the audio device which source shall be used for -the input data. The possible sources are demux or memory. If -AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device -through the write command. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst b/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst deleted file mode 100644 index 3a0400dcfae4..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_AV_SYNC: - -================= -AUDIO_SET_AV_SYNC -================= - -Name ----- - -AUDIO_SET_AV_SYNC - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_AV_SYNC, boolean state) - :name: AUDIO_SET_AV_SYNC - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean state - - - Tells the Digital TV subsystem if A/V synchronization shall be ON or OFF. - - TRUE: AV-sync ON - - FALSE: AV-sync OFF - - -Description ------------ - -This ioctl call asks the Audio Device to turn ON or OFF A/V -synchronization. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst b/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst deleted file mode 100644 index 0d2f23cc2f16..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_BYPASS_MODE: - -===================== -AUDIO_SET_BYPASS_MODE -===================== - -Name ----- - -AUDIO_SET_BYPASS_MODE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_BYPASS_MODE, boolean mode) - :name: AUDIO_SET_BYPASS_MODE - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean mode - - - Enables or disables the decoding of the current Audio stream in - the Digital TV subsystem. - - TRUE: Bypass is disabled - - FALSE: Bypass is enabled - - -Description ------------ - -This ioctl call asks the Audio Device to bypass the Audio decoder and -forward the stream without decoding. This mode shall be used if streams -that can’t be handled by the Digital TV system shall be decoded. Dolby -DigitalTM streams are automatically forwarded by the Digital TV subsystem if -the hardware can handle it. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-set-id.rst b/Documentation/userspace-api/media/dvb/audio-set-id.rst deleted file mode 100644 index 83fc1217fda0..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-set-id.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_ID: - -============ -AUDIO_SET_ID -============ - -Name ----- - -AUDIO_SET_ID - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_ID, int id) - :name: AUDIO_SET_ID - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - int id - - - audio sub-stream id - - -Description ------------ - -This ioctl selects which sub-stream is to be decoded if a program or -system stream is sent to the video device. If no audio stream type is -set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for -AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for -other stream types. If the stream type is set the id just specifies the -substream id of the audio stream and only the first 5 bits are -recognized. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-set-mixer.rst b/Documentation/userspace-api/media/dvb/audio-set-mixer.rst deleted file mode 100644 index 52bfc3af79dc..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-set-mixer.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_MIXER: - -=============== -AUDIO_SET_MIXER -=============== - -Name ----- - -AUDIO_SET_MIXER - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_MIXER, struct audio_mixer *mix) - :name: AUDIO_SET_MIXER - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_mixer_t \*mix - - - mixer settings. - - -Description ------------ - -This ioctl lets you adjust the mixer settings of the audio decoder. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-set-mute.rst b/Documentation/userspace-api/media/dvb/audio-set-mute.rst deleted file mode 100644 index 8f3a8332cebc..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-set-mute.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_MUTE: - -============== -AUDIO_SET_MUTE -============== - -Name ----- - -AUDIO_SET_MUTE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_MUTE, boolean state) - :name: AUDIO_SET_MUTE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean state - - - Indicates if audio device shall mute or not. - - TRUE: Audio Mute - - FALSE: Audio Un-mute - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` with the -``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead. - -This ioctl call asks the audio device to mute the stream that is -currently being played. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst b/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst deleted file mode 100644 index c22bd247f03d..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_STREAMTYPE: - -==================== -AUDIO_SET_STREAMTYPE -==================== - -Name ----- - -AUDIO_SET_STREAMTYPE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(fd, AUDIO_SET_STREAMTYPE, int type) - :name: AUDIO_SET_STREAMTYPE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - int type - - - stream type - - -Description ------------ - -This ioctl tells the driver which kind of audio stream to expect. This -is useful if the stream offers several audio sub-streams like LPCM and -AC3. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - type is not a valid or supported stream type. diff --git a/Documentation/userspace-api/media/dvb/audio-stop.rst b/Documentation/userspace-api/media/dvb/audio-stop.rst deleted file mode 100644 index 291b6a42efac..000000000000 --- a/Documentation/userspace-api/media/dvb/audio-stop.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_STOP: - -========== -AUDIO_STOP -========== - -Name ----- - -AUDIO_STOP - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_STOP) - :name: AUDIO_STOP - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This ioctl call asks the Audio Device to stop playing the current -stream. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/audio.rst b/Documentation/userspace-api/media/dvb/audio.rst deleted file mode 100644 index e137c151335d..000000000000 --- a/Documentation/userspace-api/media/dvb/audio.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_audio: - -####################### -Digital TV Audio Device -####################### - -The Digital TV audio device controls the MPEG2 audio decoder of the Digital -TV hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data -types and and ioctl definitions can be accessed by including -``linux/dvb/audio.h`` in your application. - -Please note that some Digital TV cards don’t have their own MPEG decoder, which -results in the omission of the audio and video device. - -These ioctls were also used by V4L2 to control MPEG decoders implemented -in V4L2. The use of these ioctls for that purpose has been made obsolete -and proper V4L2 ioctls or controls have been created to replace that -functionality. - - -.. toctree:: - :maxdepth: 1 - - audio_data_types - audio_function_calls diff --git a/Documentation/userspace-api/media/dvb/audio_data_types.rst b/Documentation/userspace-api/media/dvb/audio_data_types.rst deleted file mode 100644 index effe265b12d5..000000000000 --- a/Documentation/userspace-api/media/dvb/audio_data_types.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_data_types: - -**************** -Audio Data Types -**************** - -This section describes the structures, data types and defines used when -talking to the audio device. - -.. c:type:: audio_stream_source - -The audio stream source is set through the AUDIO_SELECT_SOURCE call -and can take the following values, depending on whether we are replaying -from an internal (demux) or external (user write) source. - - -.. code-block:: c - - typedef enum { - AUDIO_SOURCE_DEMUX, - AUDIO_SOURCE_MEMORY - } audio_stream_source_t; - -AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the -frontend or the DVR device) as the source of the video stream. If -AUDIO_SOURCE_MEMORY is selected the stream comes from the application -through the ``write()`` system call. - - -.. c:type:: audio_play_state - -The following values can be returned by the AUDIO_GET_STATUS call -representing the state of audio playback. - - -.. code-block:: c - - typedef enum { - AUDIO_STOPPED, - AUDIO_PLAYING, - AUDIO_PAUSED - } audio_play_state_t; - - -.. c:type:: audio_channel_select - -The audio channel selected via AUDIO_CHANNEL_SELECT is determined by -the following values. - - -.. code-block:: c - - typedef enum { - AUDIO_STEREO, - AUDIO_MONO_LEFT, - AUDIO_MONO_RIGHT, - AUDIO_MONO, - AUDIO_STEREO_SWAPPED - } audio_channel_select_t; - - -.. c:type:: audio_status - -The AUDIO_GET_STATUS call returns the following structure informing -about various states of the playback operation. - - -.. code-block:: c - - typedef struct audio_status { - boolean AV_sync_state; - boolean mute_state; - audio_play_state_t play_state; - audio_stream_source_t stream_source; - audio_channel_select_t channel_select; - boolean bypass_mode; - audio_mixer_t mixer_state; - } audio_status_t; - - -.. c:type:: audio_mixer - -The following structure is used by the AUDIO_SET_MIXER call to set the -audio volume. - - -.. code-block:: c - - typedef struct audio_mixer { - unsigned int volume_left; - unsigned int volume_right; - } audio_mixer_t; - - -.. _audio_encodings: - -audio encodings -=============== - -A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the -following bits set according to the hardwares capabilities. - - -.. code-block:: c - - #define AUDIO_CAP_DTS 1 - #define AUDIO_CAP_LPCM 2 - #define AUDIO_CAP_MP1 4 - #define AUDIO_CAP_MP2 8 - #define AUDIO_CAP_MP3 16 - #define AUDIO_CAP_AAC 32 - #define AUDIO_CAP_OGG 64 - #define AUDIO_CAP_SDDS 128 - #define AUDIO_CAP_AC3 256 diff --git a/Documentation/userspace-api/media/dvb/audio_function_calls.rst b/Documentation/userspace-api/media/dvb/audio_function_calls.rst deleted file mode 100644 index be90a828fe29..000000000000 --- a/Documentation/userspace-api/media/dvb/audio_function_calls.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_function_calls: - -******************** -Audio Function Calls -******************** - -.. toctree:: - :maxdepth: 1 - - audio-fopen - audio-fclose - audio-fwrite - audio-stop - audio-play - audio-pause - audio-continue - audio-select-source - audio-set-mute - audio-set-av-sync - audio-set-bypass-mode - audio-channel-select - audio-bilingual-channel-select - audio-get-status - audio-get-capabilities - audio-clear-buffer - audio-set-id - audio-set-mixer - audio-set-streamtype diff --git a/Documentation/userspace-api/media/dvb/ca-fclose.rst b/Documentation/userspace-api/media/dvb/ca-fclose.rst index cedfb7ee6a01..27f217a350e7 100644 --- a/Documentation/userspace-api/media/dvb/ca-fclose.rst +++ b/Documentation/userspace-api/media/dvb/ca-fclose.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _ca_fclose: @@ -18,26 +12,22 @@ Name Digital TV CA close() - Synopsis -------- .. c:function:: int close(int fd) - :name: dvb-ca-close - Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. Description ----------- This system call closes a previously opened CA device. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/ca-fopen.rst b/Documentation/userspace-api/media/dvb/ca-fopen.rst index aa0fde1739a8..7f99908fff2c 100644 --- a/Documentation/userspace-api/media/dvb/ca-fopen.rst +++ b/Documentation/userspace-api/media/dvb/ca-fopen.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _ca_fopen: @@ -18,13 +12,10 @@ Name Digital TV CA open() - Synopsis -------- .. c:function:: int open(const char *name, int flags) - :name: dvb-ca-open - Arguments --------- @@ -52,7 +43,6 @@ Arguments - open in non-blocking mode (blocking mode is the default) - Description ----------- @@ -70,11 +60,9 @@ Only one user can open the CA Device in ``O_RDWR`` mode. All other attempts to open the device in this mode will fail, and an error code will be returned. - Return Value ------------ - On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set diff --git a/Documentation/userspace-api/media/dvb/ca-get-cap.rst b/Documentation/userspace-api/media/dvb/ca-get-cap.rst index b808d0592371..9b29513eeda8 100644 --- a/Documentation/userspace-api/media/dvb/ca-get-cap.rst +++ b/Documentation/userspace-api/media/dvb/ca-get-cap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_GET_CAP: @@ -18,19 +12,18 @@ Name CA_GET_CAP - Synopsis -------- -.. c:function:: int ioctl(fd, CA_GET_CAP, struct ca_caps *caps) - :name: CA_GET_CAP +.. c:macro:: CA_GET_CAP +``int ioctl(fd, CA_GET_CAP, struct ca_caps *caps)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``caps`` Pointer to struct :c:type:`ca_caps`. diff --git a/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst index 396cc66a8243..0cfdcdab33a8 100644 --- a/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst +++ b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_GET_DESCR_INFO: @@ -18,18 +12,18 @@ Name CA_GET_DESCR_INFO - Synopsis -------- -.. c:function:: int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc) - :name: CA_GET_DESCR_INFO +.. c:macro:: CA_GET_DESCR_INFO + +``int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``desc`` Pointer to struct :c:type:`ca_descr_info`. diff --git a/Documentation/userspace-api/media/dvb/ca-get-msg.rst b/Documentation/userspace-api/media/dvb/ca-get-msg.rst index 995f461d6879..7c9a8d197343 100644 --- a/Documentation/userspace-api/media/dvb/ca-get-msg.rst +++ b/Documentation/userspace-api/media/dvb/ca-get-msg.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_GET_MSG: @@ -18,19 +12,18 @@ Name CA_GET_MSG - Synopsis -------- -.. c:function:: int ioctl(fd, CA_GET_MSG, struct ca_msg *msg) - :name: CA_GET_MSG +.. c:macro:: CA_GET_MSG +``int ioctl(fd, CA_GET_MSG, struct ca_msg *msg)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``msg`` Pointer to struct :c:type:`ca_msg`. @@ -45,11 +38,9 @@ Receives a message via a CI CA module. Please notice that, on most drivers, this is done by reading from the /dev/adapter?/ca? device node. - Return Value ------------ - On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set diff --git a/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst index c65987ff9cb3..582444af7003 100644 --- a/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst +++ b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_GET_SLOT_INFO: @@ -18,19 +12,18 @@ Name CA_GET_SLOT_INFO - Synopsis -------- -.. c:function:: int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info) - :name: CA_GET_SLOT_INFO +.. c:macro:: CA_GET_SLOT_INFO +``int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <cec-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``info`` Pointer to struct :c:type:`ca_slot_info`. @@ -41,7 +34,6 @@ Description Returns information about a CA slot identified by :c:type:`ca_slot_info`.slot_num. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/ca-reset.rst b/Documentation/userspace-api/media/dvb/ca-reset.rst index 116a5a8eeb5d..b01ca48f0b50 100644 --- a/Documentation/userspace-api/media/dvb/ca-reset.rst +++ b/Documentation/userspace-api/media/dvb/ca-reset.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_RESET: @@ -18,19 +12,18 @@ Name CA_RESET - Synopsis -------- -.. c:function:: int ioctl(fd, CA_RESET) - :name: CA_RESET +.. c:macro:: CA_RESET +``int ioctl(fd, CA_RESET)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <cec-open>`. + File descriptor returned by a previous call to :c:func:`open()`. Description ----------- @@ -38,7 +31,6 @@ Description Puts the Conditional Access hardware on its initial state. It should be called before start using the CA hardware. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/ca-send-msg.rst b/Documentation/userspace-api/media/dvb/ca-send-msg.rst index 716d88e0fdc5..7dd2ab4ef675 100644 --- a/Documentation/userspace-api/media/dvb/ca-send-msg.rst +++ b/Documentation/userspace-api/media/dvb/ca-send-msg.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_SEND_MSG: @@ -18,24 +12,22 @@ Name CA_SEND_MSG - Synopsis -------- -.. c:function:: int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg) - :name: CA_SEND_MSG +.. c:macro:: CA_SEND_MSG +``int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <cec-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``msg`` Pointer to struct :c:type:`ca_msg`. - Description ----------- diff --git a/Documentation/userspace-api/media/dvb/ca-set-descr.rst b/Documentation/userspace-api/media/dvb/ca-set-descr.rst index 2c57371675e2..a740af34c872 100644 --- a/Documentation/userspace-api/media/dvb/ca-set-descr.rst +++ b/Documentation/userspace-api/media/dvb/ca-set-descr.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca .. _CA_SET_DESCR: @@ -18,19 +12,18 @@ Name CA_SET_DESCR - Synopsis -------- -.. c:function:: int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc) - :name: CA_SET_DESCR +.. c:macro:: CA_SET_DESCR +``int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc)`` Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <cec-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``msg`` Pointer to struct :c:type:`ca_descr`. diff --git a/Documentation/userspace-api/media/dvb/ca.rst b/Documentation/userspace-api/media/dvb/ca.rst index 643b7c414943..0dc00e5e4a8c 100644 --- a/Documentation/userspace-api/media/dvb/ca.rst +++ b/Documentation/userspace-api/media/dvb/ca.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dvb_ca: @@ -14,7 +7,7 @@ Digital TV CA Device #################### The Digital TV CA device controls the conditional access hardware. It -can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl +can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and ioctl definitions can be accessed by including ``linux/dvb/ca.h`` in your application. diff --git a/Documentation/userspace-api/media/dvb/ca_data_types.rst b/Documentation/userspace-api/media/dvb/ca_data_types.rst index 20e2b552144f..54ea2a987546 100644 --- a/Documentation/userspace-api/media/dvb/ca_data_types.rst +++ b/Documentation/userspace-api/media/dvb/ca_data_types.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _ca_data_types: diff --git a/Documentation/userspace-api/media/dvb/ca_function_calls.rst b/Documentation/userspace-api/media/dvb/ca_function_calls.rst index b8aceb1895b6..3b893fbd502d 100644 --- a/Documentation/userspace-api/media/dvb/ca_function_calls.rst +++ b/Documentation/userspace-api/media/dvb/ca_function_calls.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _ca_function_calls: diff --git a/Documentation/userspace-api/media/dvb/demux.rst b/Documentation/userspace-api/media/dvb/demux.rst index 00397b075e0f..ef05abcf14d1 100644 --- a/Documentation/userspace-api/media/dvb/demux.rst +++ b/Documentation/userspace-api/media/dvb/demux.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dvb_demux: @@ -18,7 +11,7 @@ digital TV. If the driver and hardware supports, those filters are implemented at the hardware. Otherwise, the Kernel provides a software emulation. -It can be accessed through ``/dev/adapter?/demux?``. Data types and and +It can be accessed through ``/dev/adapter?/demux?``. Data types and ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in your application. diff --git a/Documentation/userspace-api/media/dvb/dmx-add-pid.rst b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst index e309cd56fdf0..ea0c7dd91e05 100644 --- a/Documentation/userspace-api/media/dvb/dmx-add-pid.rst +++ b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_ADD_PID: @@ -18,24 +12,22 @@ Name DMX_ADD_PID - Synopsis -------- -.. c:function:: int ioctl(fd, DMX_ADD_PID, __u16 *pid) - :name: DMX_ADD_PID +.. c:macro:: DMX_ADD_PID +``int ioctl(fd, DMX_ADD_PID, __u16 *pid)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``pid`` PID number to be filtered. - Description ----------- @@ -43,7 +35,6 @@ This ioctl call allows to add multiple PIDs to a transport stream filter previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to :c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-expbuf.rst b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst index f76db8ce3cfa..5cdc2035e3b7 100644 --- a/Documentation/userspace-api/media/dvb/dmx-expbuf.rst +++ b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_EXPBUF: @@ -20,24 +14,22 @@ DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. .. warning:: this API is still experimental - Synopsis ======== -.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp ) - :name: DMX_EXPBUF +.. c:macro:: DMX_EXPBUF +``int ioctl(int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dmx_exportbuffer`. - Description =========== @@ -61,11 +53,9 @@ driver, on success. This is a DMABUF file descriptor. The application may pass it to other DMABUF-aware devices. It is recommended to close a DMABUF file when it is no longer used to allow the associated memory to be reclaimed. - Examples ======== - .. code-block:: c int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) diff --git a/Documentation/userspace-api/media/dvb/dmx-fclose.rst b/Documentation/userspace-api/media/dvb/dmx-fclose.rst index e93bc60da508..719ac1d4f686 100644 --- a/Documentation/userspace-api/media/dvb/dmx-fclose.rst +++ b/Documentation/userspace-api/media/dvb/dmx-fclose.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_fclose: @@ -18,27 +12,23 @@ Name Digital TV demux close() - Synopsis -------- .. c:function:: int close(int fd) - :name: dvb-dmx-close - Arguments --------- ``fd`` File descriptor returned by a previous call to - :c:func:`open() <dvb-dmx-open>`. + :c:func:`open()`. Description ----------- This system call deactivates and deallocates a filter that was -previously allocated via the :c:func:`open() <dvb-dmx-open>` call. - +previously allocated via the :c:func:`open()` call. Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-fopen.rst b/Documentation/userspace-api/media/dvb/dmx-fopen.rst index ea988714558e..50b36eb4371e 100644 --- a/Documentation/userspace-api/media/dvb/dmx-fopen.rst +++ b/Documentation/userspace-api/media/dvb/dmx-fopen.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_fopen: @@ -18,12 +12,10 @@ Name Digital TV demux open() - Synopsis -------- .. c:function:: int open(const char *deviceName, int flags) - :name: dvb-dmx-open Arguments --------- @@ -54,7 +46,6 @@ Arguments - open in non-blocking mode (blocking mode is the default) - Description ----------- @@ -75,7 +66,6 @@ affect the semantics of the ``open()`` call itself. A device opened in blocking mode can later be put into non-blocking mode (and vice versa) using the ``F_SETFL`` command of the fcntl system call. - Return Value ------------ @@ -92,7 +82,7 @@ appropriately. :widths: 1 16 - - ``EMFILE`` - - “Too many open files”, i.e. no more filters available. + - "Too many open files", i.e. no more filters available. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fread.rst b/Documentation/userspace-api/media/dvb/dmx-fread.rst index 25501be818f8..88c4cddf7c30 100644 --- a/Documentation/userspace-api/media/dvb/dmx-fread.rst +++ b/Documentation/userspace-api/media/dvb/dmx-fread.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_fread: @@ -18,18 +12,16 @@ Name Digital TV demux read() - Synopsis -------- .. c:function:: size_t read(int fd, void *buf, size_t count) - :name: dvb-dmx-read Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``buf`` Buffer to be filled @@ -42,7 +34,7 @@ Description This system call returns filtered data, which might be section or Packetized Elementary Stream (PES) data. The filtered data is transferred from -the driver’s internal circular buffer to ``buf``. The maximum amount of data +the driver's internal circular buffer to ``buf``. The maximum amount of data to be transferred is implied by count. .. note:: @@ -51,7 +43,6 @@ to be transferred is implied by count. :c:type:`DMX_CHECK_CRC <dmx_sct_filter_params>` flag set, data that fails on CRC check will be silently ignored. - Return Value ------------ @@ -82,6 +73,5 @@ appropriately. - The driver failed to write to the callers buffer due to an invalid \*buf pointer. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fwrite.rst b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst index 4400f4ef8c65..e11ee0ba84a5 100644 --- a/Documentation/userspace-api/media/dvb/dmx-fwrite.rst +++ b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_fwrite: @@ -18,18 +12,16 @@ Name Digital TV demux write() - Synopsis -------- .. c:function:: ssize_t write(int fd, const void *buf, size_t count) - :name: dvb-dmx-write Arguments --------- ``fd`` - File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`. + File descriptor returned by a previous call to :c:func:`open()`. ``buf`` Buffer with data to be written @@ -47,7 +39,6 @@ digitally recorded Transport Stream. Matching filters have to be defined in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``. The amount of data to be transferred is implied by count. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst index e1873e3fdc01..4f5f0505c0d5 100644 --- a/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst +++ b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_GET_PES_PIDS: @@ -18,23 +12,22 @@ Name DMX_GET_PES_PIDS - Synopsis -------- -.. c:function:: int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5]) - :name: DMX_GET_PES_PIDS +.. c:macro:: DMX_GET_PES_PIDS + +``int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5])`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``pids`` Array used to store 5 Program IDs. - Description ----------- @@ -52,13 +45,11 @@ pids[DMX_PES_SUBTITLE] 3 first subtitle PID pids[DMX_PES_PCR] 4 first Program Clock Reference PID ======================= ======== ======================================= - .. note:: A value equal to 0xffff means that the PID was not filled by the Kernel. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-get-stc.rst b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst index 026a884edb0a..6ada74f6eb18 100644 --- a/Documentation/userspace-api/media/dvb/dmx-get-stc.rst +++ b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_GET_STC: @@ -18,23 +12,22 @@ Name DMX_GET_STC - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_GET_STC, struct dmx_stc *stc) - :name: DMX_GET_STC +.. c:macro:: DMX_GET_STC + +``int ioctl(int fd, DMX_GET_STC, struct dmx_stc *stc)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``stc`` Pointer to :c:type:`dmx_stc` where the stc data is to be stored. - Description ----------- @@ -46,7 +39,6 @@ The result is returned in form of a ratio with a 64 bit numerator and a 32 bit denominator, so the real 90kHz STC value is ``stc->stc / stc->base``. - Return Value ------------ @@ -68,6 +60,5 @@ appropriately. - Invalid stc number. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-mmap.rst b/Documentation/userspace-api/media/dvb/dmx-mmap.rst index 828ba9df73e2..8826c6226fb0 100644 --- a/Documentation/userspace-api/media/dvb/dmx-mmap.rst +++ b/Documentation/userspace-api/media/dvb/dmx-mmap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx-mmap: @@ -28,9 +22,7 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) - :name: dmx-mmap Arguments ========= @@ -61,7 +53,7 @@ Arguments ``MAP_FIXED`` requests that the driver selects no other address than the one specified. If the specified address cannot be used, - :ref:`mmap() <dmx-mmap>` will fail. If ``MAP_FIXED`` is specified, + :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified, ``start`` must be a multiple of the pagesize. Use of this option is discouraged. @@ -76,17 +68,16 @@ Arguments flags. ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``offset`` Offset of the buffer in device memory, as returned by :ref:`DMX_QUERYBUF` ioctl. - Description =========== -The :ref:`mmap() <dmx-mmap>` function asks to map ``length`` bytes starting at +The :c:func:`mmap()` function asks to map ``length`` bytes starting at ``offset`` in the memory of the device specified by ``fd`` into the application address space, preferably at address ``start``. This latter address is a hint only, and is usually specified as 0. @@ -95,13 +86,12 @@ Suitable length and offset parameters are queried with the :ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the :ref:`DMX_REQBUFS` ioctl before they can be queried. -To unmap buffers the :ref:`munmap() <dmx-munmap>` function is used. - +To unmap buffers the :c:func:`munmap()` function is used. Return Value ============ -On success :ref:`mmap() <dmx-mmap>` returns a pointer to the mapped buffer. On +On success :c:func:`mmap()` returns a pointer to the mapped buffer. On error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/dvb/dmx-munmap.rst b/Documentation/userspace-api/media/dvb/dmx-munmap.rst index 905fdd585a86..66bbc11e5c40 100644 --- a/Documentation/userspace-api/media/dvb/dmx-munmap.rst +++ b/Documentation/userspace-api/media/dvb/dmx-munmap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx-munmap: @@ -20,7 +14,6 @@ dmx-munmap - Unmap device memory .. warning:: This API is still experimental. - Synopsis ======== @@ -29,33 +22,29 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: int munmap( void *start, size_t length ) - :name: dmx-munmap Arguments ========= ``start`` Address of the mapped buffer as returned by the - :ref:`mmap() <dmx-mmap>` function. + :c:func:`mmap()` function. ``length`` Length of the mapped buffer. This must be the same value as given to - :ref:`mmap() <dmx-mmap>`. - + :c:func:`mmap()`. Description =========== -Unmaps a previously with the :ref:`mmap() <dmx-mmap>` function mapped +Unmaps a previously with the :c:func:`mmap()` function mapped buffer and frees it, if possible. - Return Value ============ -On success :ref:`munmap() <dmx-munmap>` returns 0, on failure -1 and the +On success :c:func:`munmap()` returns 0, on failure -1 and the ``errno`` variable is set appropriately: EINVAL diff --git a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst index 2c4657c2c86d..1a13a33834db 100644 --- a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst +++ b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_QBUF: @@ -20,27 +14,26 @@ DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver .. warning:: this API is still experimental - Synopsis ======== -.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) - :name: DMX_QBUF +.. c:macro:: DMX_QBUF + +``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)`` -.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) - :name: DMX_DQBUF +.. c:macro:: DMX_DQBUF +``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dmx_buffer`. - Description =========== @@ -57,7 +50,7 @@ by a :ref:`DMX_QUERYBUF` ioctl will do as well. When ``DMX_QBUF`` is called with a pointer to this structure, it locks the memory pages of the buffer in physical memory, so they cannot be swapped out to disk. Buffers remain locked until dequeued, until the -the device is closed. +device is closed. Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled (capturing) buffer from the driver's outgoing queue. @@ -67,13 +60,12 @@ the driver fills the remaining fields or returns an error code. By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the -:ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns +:c:func:`open()` function, ``DMX_DQBUF`` returns immediately with an ``EAGAIN`` error code when no buffer is available. The struct :c:type:`dmx_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/dmx-querybuf.rst b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst index 6e234daf1c44..08ee9853d6b4 100644 --- a/Documentation/userspace-api/media/dvb/dmx-querybuf.rst +++ b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_QUERYBUF: @@ -20,24 +14,22 @@ DMX_QUERYBUF - Query the status of a buffer .. warning:: this API is still experimental - Synopsis ======== -.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp ) - :name: DMX_QUERYBUF +.. c:macro:: DMX_QUERYBUF +``int ioctl(int fd, DMX_QUERYBUF, struct dvb_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dvb_buffer`. - Description =========== diff --git a/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst index dee553a48b63..f75b33e5e49a 100644 --- a/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst +++ b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_REMOVE_PID: @@ -18,24 +12,22 @@ Name DMX_REMOVE_PID - Synopsis -------- -.. c:function:: int ioctl(fd, DMX_REMOVE_PID, __u16 *pid) - :name: DMX_REMOVE_PID +.. c:macro:: DMX_REMOVE_PID +``int ioctl(fd, DMX_REMOVE_PID, __u16 *pid)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``pid`` PID of the PES filter to be removed. - Description ----------- @@ -44,7 +36,6 @@ transport stream filter, e. g. a filter previously set up with output equal to :c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`, created via either :ref:`DMX_SET_PES_FILTER` or :ref:`DMX_ADD_PID`. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst index 9b9be45d2b0b..d2bb1909ec98 100644 --- a/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst +++ b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_REQBUFS: @@ -20,19 +14,18 @@ DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O .. warning:: this API is still experimental - Synopsis ======== -.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp ) - :name: DMX_REQBUFS +.. c:macro:: DMX_REQBUFS +``int ioctl(int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <dmx_fopen>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dmx_requestbuffers`. @@ -71,7 +64,6 @@ buffers, however this cannot succeed when any buffers are still mapped. A ``count`` value of zero frees all buffers, after aborting or finishing any DMA in progress. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst index 7c91da1da4be..13ce4092c2d2 100644 --- a/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst +++ b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_SET_BUFFER_SIZE: @@ -18,19 +12,18 @@ Name DMX_SET_BUFFER_SIZE - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_SET_BUFFER_SIZE, unsigned long size) - :name: DMX_SET_BUFFER_SIZE +.. c:macro:: DMX_SET_BUFFER_SIZE +``int ioctl(int fd, DMX_SET_BUFFER_SIZE, unsigned long size)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``size`` Unsigned long size @@ -43,11 +36,9 @@ filtered data. The default size is two maximum sized sections, i.e. if this function is not called a buffer size of ``2 * 4096`` bytes will be used. - Return Value ------------ - On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set diff --git a/Documentation/userspace-api/media/dvb/dmx-set-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst index cb3333349bd0..1b8c8071b14f 100644 --- a/Documentation/userspace-api/media/dvb/dmx-set-filter.rst +++ b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_SET_FILTER: @@ -18,24 +12,23 @@ Name DMX_SET_FILTER - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params) - :name: DMX_SET_FILTER +.. c:macro:: DMX_SET_FILTER + +``int ioctl(int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``params`` Pointer to structure containing filter parameters. - Description ----------- @@ -44,17 +37,15 @@ parameters provided. A timeout may be defined stating number of seconds to wait for a section to be loaded. A value of 0 means that no timeout should be applied. Finally there is a flag field where it is possible to state whether a section should be CRC-checked, whether the filter should -be a ”one-shot” filter, i.e. if the filtering operation should be +be a "one-shot" filter, i.e. if the filtering operation should be stopped after the first section is received, and whether the filtering operation should be started immediately (without waiting for a :ref:`DMX_START` ioctl call). If a filter was previously set-up, this filter will be canceled, and the receive buffer will be flushed. - Return Value ------------ - On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set diff --git a/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst index 26da56947652..5bb682e4a88f 100644 --- a/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst +++ b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_SET_PES_FILTER: @@ -18,25 +12,22 @@ Name DMX_SET_PES_FILTER - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params) - :name: DMX_SET_PES_FILTER +.. c:macro:: DMX_SET_PES_FILTER +``int ioctl(int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)`` Arguments --------- - ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. ``params`` Pointer to structure containing filter parameters. - Description ----------- @@ -45,7 +36,6 @@ provided. By a PES filter is meant a filter that is based just on the packet identifier (PID), i.e. no PES header or payload filtering capability is supported. - Return Value ------------ @@ -61,7 +51,6 @@ appropriately. :stub-columns: 0 :widths: 1 16 - - .. row 1 - ``EBUSY`` @@ -71,6 +60,5 @@ appropriately. Make sure that these filters are stopped before starting this filter. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-start.rst b/Documentation/userspace-api/media/dvb/dmx-start.rst index a1d35f01fc95..aedccf952a14 100644 --- a/Documentation/userspace-api/media/dvb/dmx-start.rst +++ b/Documentation/userspace-api/media/dvb/dmx-start.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_START: @@ -18,19 +12,18 @@ Name DMX_START - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_START) - :name: DMX_START +.. c:macro:: DMX_START +``int ioctl(int fd, DMX_START)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. Description ----------- @@ -38,7 +31,6 @@ Description This ioctl call is used to start the actual filtering operation defined via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`. - Return Value ------------ @@ -53,7 +45,6 @@ appropriately. :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EINVAL`` @@ -70,6 +61,5 @@ appropriately. Make sure that these filters are stopped before starting this filter. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-stop.rst b/Documentation/userspace-api/media/dvb/dmx-stop.rst index 5e6e805010d0..8661e6772104 100644 --- a/Documentation/userspace-api/media/dvb/dmx-stop.rst +++ b/Documentation/userspace-api/media/dvb/dmx-stop.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _DMX_STOP: @@ -18,19 +12,18 @@ Name DMX_STOP - Synopsis -------- -.. c:function:: int ioctl( int fd, DMX_STOP) - :name: DMX_STOP +.. c:macro:: DMX_STOP +``int ioctl(int fd, DMX_STOP)`` Arguments --------- ``fd`` - File descriptor returned by :c:func:`open() <dvb-dmx-open>`. + File descriptor returned by :c:func:`open()`. Description ----------- @@ -39,7 +32,6 @@ This ioctl call is used to stop the actual filtering operation defined via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and started via the :ref:`DMX_START` command. - Return Value ------------ diff --git a/Documentation/userspace-api/media/dvb/dmx_fcalls.rst b/Documentation/userspace-api/media/dvb/dmx_fcalls.rst index 04e150f00f84..a14e7a61f90b 100644 --- a/Documentation/userspace-api/media/dvb/dmx_fcalls.rst +++ b/Documentation/userspace-api/media/dvb/dmx_fcalls.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dmx_fcalls: diff --git a/Documentation/userspace-api/media/dvb/dmx_types.rst b/Documentation/userspace-api/media/dvb/dmx_types.rst index 635b8fd363be..33458fbb84ab 100644 --- a/Documentation/userspace-api/media/dvb/dmx_types.rst +++ b/Documentation/userspace-api/media/dvb/dmx_types.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dmx_types: diff --git a/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst b/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst index 5d6a7735a9d1..fbd0548f5fb9 100644 --- a/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst +++ b/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dvb-fe-read-status: diff --git a/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst b/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst index 7f5e56cf75cb..0e2fd3a0a7c0 100644 --- a/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst +++ b/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. c:type:: dvb_frontend_event diff --git a/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst b/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst index 83b1bcc6ef54..9dd2f542441e 100644 --- a/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst +++ b/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. c:type:: dvb_frontend_parameters diff --git a/Documentation/userspace-api/media/dvb/dvbapi.rst b/Documentation/userspace-api/media/dvb/dvbapi.rst index 74b16ab3fd94..4ac0c1bc54ca 100644 --- a/Documentation/userspace-api/media/dvb/dvbapi.rst +++ b/Documentation/userspace-api/media/dvb/dvbapi.rst @@ -1,12 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. include:: <isonum.txt> .. _dvbapi: @@ -35,13 +27,8 @@ Part II - Digital TV API **Version 5.10** -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/dvb/dvbproperty.rst b/Documentation/userspace-api/media/dvb/dvbproperty.rst index 1716733d24ba..981da20afd49 100644 --- a/Documentation/userspace-api/media/dvb/dvbproperty.rst +++ b/Documentation/userspace-api/media/dvb/dvbproperty.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _frontend-properties: diff --git a/Documentation/userspace-api/media/dvb/dvbstb.svg b/Documentation/userspace-api/media/dvb/dvbstb.svg index b333d0ff944f..6f0ba98f9bf9 100644 --- a/Documentation/userspace-api/media/dvb/dvbstb.svg +++ b/Documentation/userspace-api/media/dvb/dvbstb.svg @@ -1,34 +1,8 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg id="svg2" width="15.847cm" height="8.4187cm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 23770.123 12628.122" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><defs id="defs142"><marker id="Arrow1Lend" overflow="visible" orient="auto"><path id="path954" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker><marker id="marker1243" overflow="visible" orient="auto"><path id="path1241" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker></defs><metadata id="metadata519"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><rect id="rect197" class="BoundingBox" x="5355.1" y="13.122" width="18403" height="9603" fill="none"/><path id="path199" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="#fff"/><path id="path201" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="none" stroke="#000"/><rect id="rect206" class="BoundingBox" x="13.122" y="4013.1" width="4544" height="2403" fill="none"/><path id="path208" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path210" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text212" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan214" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan216" class="TextPosition" -x="1281.1219" y="5435.1221"><tspan id="tspan218" fill="#000000">Antena</tspan></tspan></tspan></text> +x="1013.1317" y="5435.1221"><tspan id="tspan218" fill="#000000">Antenna</tspan></tspan></tspan></text> <rect id="rect223" class="BoundingBox" x="6213.1" y="1813.1" width="4544" height="2403" fill="none"/><path id="path225" d="m8485.1 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path227" d="m8485.1 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text229" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan231" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan233" class="TextPosition" x="7217.1221" y="3235.1221"><tspan id="tspan235" fill="#000000">Frontend</tspan></tspan></tspan></text> <rect id="rect240" class="BoundingBox" x="12113" y="1813.1" width="4544" height="2403" fill="none"/><path id="path242" d="m14385 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path244" d="m14385 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text246" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan248" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan250" class="TextPosition" x="13944.122" y="3235.1221"><tspan id="tspan252" fill="#000000">CA</tspan></tspan></tspan></text> <rect id="rect257" class="BoundingBox" x="18113" y="1813.1" width="4544" height="2403" fill="none"/><path id="path259" d="m20385 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path261" d="m20385 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text263" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan265" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan267" class="TextPosition" x="19384.123" y="3235.1221"><tspan id="tspan269" fill="#000000">Demux</tspan></tspan></tspan></text> diff --git a/Documentation/userspace-api/media/dvb/examples.rst b/Documentation/userspace-api/media/dvb/examples.rst index bd0adde86b96..086587c65a57 100644 --- a/Documentation/userspace-api/media/dvb/examples.rst +++ b/Documentation/userspace-api/media/dvb/examples.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dvb_examples: diff --git a/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst b/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst index 6293287af67c..904b0c33a3ec 100644 --- a/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst +++ b/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ****************** Frontend bandwidth diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst index b520974e8c46..d9be817f0390 100644 --- a/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISEQC_RECV_SLAVE_REPLY: @@ -18,24 +12,22 @@ Name FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp ) - :name: FE_DISEQC_RECV_SLAVE_REPLY +.. c:macro:: FE_DISEQC_RECV_SLAVE_REPLY +``int ioctl(int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``argp`` pointer to struct :c:type:`dvb_diseqc_slave_reply`. - Description =========== diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst index c59af46b8e87..d36f7d1157c6 100644 --- a/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISEQC_RESET_OVERLOAD: @@ -18,19 +12,18 @@ Name FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_RESET_OVERLOAD, NULL ) - :name: FE_DISEQC_RESET_OVERLOAD +.. c:macro:: FE_DISEQC_RESET_OVERLOAD +``int ioctl(int fd, FE_DISEQC_RESET_OVERLOAD, NULL)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. Description =========== @@ -40,7 +33,6 @@ this ioctl call restores the power to the bus. The call requires read/write access to the device. This call has no effect if the device is manually powered off. Not all Digital TV adapters support this ioctl. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst index 19b51d0550f7..8fb73ee29951 100644 --- a/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISEQC_SEND_BURST: @@ -18,24 +12,22 @@ Name FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone ) - :name: FE_DISEQC_SEND_BURST +.. c:macro:: FE_DISEQC_SEND_BURST +``int ioctl(int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``tone`` An integer enumered value described at :c:type:`fe_sec_mini_cmd`. - Description =========== @@ -46,7 +38,6 @@ read/write permissions. It provides support for what's specified at `Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. <http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf>`__ - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst index f75513d018c8..c97029def2ee 100644 --- a/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISEQC_SEND_MASTER_CMD: @@ -18,25 +12,23 @@ Name FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp ) - :name: FE_DISEQC_SEND_MASTER_CMD +.. c:macro:: FE_DISEQC_SEND_MASTER_CMD +``int ioctl(int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``argp`` pointer to struct :c:type:`dvb_diseqc_master_cmd` - Description =========== diff --git a/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst index ea66f72fe5f8..d1dba74c55a9 100644 --- a/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst +++ b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_DISHNETWORK_SEND_LEGACY_CMD: @@ -18,24 +12,22 @@ Name FE_DISHNETWORK_SEND_LEGACY_CMD - Synopsis ======== -.. c:function:: int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd) - :name: FE_DISHNETWORK_SEND_LEGACY_CMD +.. c:macro:: FE_DISHNETWORK_SEND_LEGACY_CMD +``int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``cmd`` Sends the specified raw cmd to the dish via DISEqC. - Description =========== @@ -49,7 +41,6 @@ frontend, for Dish Network legacy switches. As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst index 9bdf1e898ddc..40d7320f82f7 100644 --- a/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst +++ b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_ENABLE_HIGH_LNB_VOLTAGE: @@ -18,19 +12,18 @@ Name FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high ) - :name: FE_ENABLE_HIGH_LNB_VOLTAGE +.. c:macro:: FE_ENABLE_HIGH_LNB_VOLTAGE +``int ioctl(int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``high`` Valid flags: @@ -40,7 +33,6 @@ Arguments - >0 - enables slightly higher voltages instead of 13/18V, in order to compensate for long antenna cables. - Description =========== @@ -48,7 +40,6 @@ Select output DC level between normal LNBf voltages or higher LNBf voltages between 0 (normal) or a value grater than 0 for higher voltages. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-get-event.rst b/Documentation/userspace-api/media/dvb/fe-get-event.rst index 19df41dca238..f63029eca90e 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-event.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-event.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_GET_EVENT: @@ -20,24 +14,22 @@ FE_GET_EVENT .. attention:: This ioctl is deprecated. - Synopsis ======== -.. c:function:: int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev) - :name: FE_GET_EVENT +.. c:macro:: FE_GET_EVENT +``int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``ev`` Points to the location where the event, if any, is to be stored. - Description =========== @@ -47,7 +39,6 @@ or non-blocking mode. In the latter case, the call fails immediately with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until an event becomes available. - Return Value ============ @@ -56,12 +47,10 @@ On success 0 is returned. On error -1 is returned, and the ``errno`` variable is set appropriately. - .. flat-table:: :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EWOULDBLOCK`` diff --git a/Documentation/userspace-api/media/dvb/fe-get-frontend.rst b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst index 7968adc8e982..40700533e7e7 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-frontend.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_GET_FRONTEND: @@ -20,32 +14,28 @@ FE_GET_FRONTEND .. attention:: This ioctl is deprecated. - Synopsis ======== -.. c:function:: int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p) - :name: FE_GET_FRONTEND +.. c:macro:: FE_GET_FRONTEND +``int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. - + File descriptor returned by :c:func:`open()`. ``p`` Points to parameters for tuning operation. - Description =========== This ioctl call queries the currently effective frontend parameters. For this command, read-only access to the device is sufficient. - Return Value ============ @@ -58,7 +48,6 @@ appropriately. :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``EINVAL`` diff --git a/Documentation/userspace-api/media/dvb/fe-get-info.rst b/Documentation/userspace-api/media/dvb/fe-get-info.rst index 80d9f8195ac4..2e5f0209846f 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-info.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-info.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_GET_INFO: @@ -19,24 +13,21 @@ Name FE_GET_INFO - Query Digital TV frontend capabilities and returns information about the - front-end. This call only requires read-only access to the device. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_GET_INFO, struct dvb_frontend_info *argp ) - :name: FE_GET_INFO +.. c:macro:: FE_GET_INFO +``int ioctl(int fd, FE_GET_INFO, struct dvb_frontend_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``argp`` - pointer to struct struct - :c:type:`dvb_frontend_info` - + pointer to struct :c:type:`dvb_frontend_info` Description =========== @@ -48,7 +39,6 @@ takes a pointer to dvb_frontend_info which is filled by the driver. When the driver is not compatible with this specification the ioctl returns an error. - frontend capabilities ===================== @@ -57,7 +47,6 @@ supported only on some specific frontend types. The frontend capabilities are described at :c:type:`fe_caps`. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-get-property.rst b/Documentation/userspace-api/media/dvb/fe-get-property.rst index 088d4e319405..29363dc4a0c3 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-property.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-property.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_GET_PROPERTY: @@ -18,27 +12,26 @@ Name FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_GET_PROPERTY, struct dtv_properties *argp ) - :name: FE_GET_PROPERTY +.. c:macro:: FE_GET_PROPERTY + +``int ioctl(int fd, FE_GET_PROPERTY, struct dtv_properties *argp)`` -.. c:function:: int ioctl( int fd, FE_SET_PROPERTY, struct dtv_properties *argp ) - :name: FE_SET_PROPERTY +.. c:macro:: FE_SET_PROPERTY +``int ioctl(int fd, FE_SET_PROPERTY, struct dtv_properties *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`dtv_properties`. - Description =========== @@ -70,7 +63,6 @@ depends on the delivery system and on the device: - This call only requires read-only access to the device. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-ber.rst b/Documentation/userspace-api/media/dvb/fe-read-ber.rst index d0a706ac9011..f33f1dd20501 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-ber.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-ber.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_BER: @@ -23,20 +17,19 @@ FE_READ_BER Synopsis ======== -.. c:function:: int ioctl(int fd, FE_READ_BER, uint32_t *ber) - :name: FE_READ_BER +.. c:macro:: FE_READ_BER +``int ioctl(int fd, FE_READ_BER, uint32_t *ber)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``ber`` The bit error rate is stored into \*ber. - Description =========== @@ -44,7 +37,6 @@ This ioctl call returns the bit error rate for the signal currently received/demodulated by the front-end. For this command, read-only access to the device is sufficient. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst index df79837de47d..2b7d06145cb1 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_SIGNAL_STRENGTH: @@ -23,20 +17,19 @@ FE_READ_SIGNAL_STRENGTH Synopsis ======== -.. c:function:: int ioctl( int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength) - :name: FE_READ_SIGNAL_STRENGTH +.. c:macro:: FE_READ_SIGNAL_STRENGTH +``int ioctl(int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``strength`` The signal strength value is stored into \*strength. - Description =========== @@ -44,7 +37,6 @@ This ioctl call returns the signal strength value for the signal currently received by the front-end. For this command, read-only access to the device is sufficient. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-snr.rst b/Documentation/userspace-api/media/dvb/fe-read-snr.rst index e56147a40e23..e44e559ab7e8 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-snr.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-snr.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_SNR: @@ -23,20 +17,19 @@ FE_READ_SNR Synopsis ======== -.. c:function:: int ioctl(int fd, FE_READ_SNR, int16_t *snr) - :name: FE_READ_SNR +.. c:macro:: FE_READ_SNR +``int ioctl(int fd, FE_READ_SNR, int16_t *snr)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``snr`` The signal-to-noise ratio is stored into \*snr. - Description =========== @@ -44,7 +37,6 @@ This ioctl call returns the signal-to-noise ratio for the signal currently received by the front-end. For this command, read-only access to the device is sufficient. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-status.rst b/Documentation/userspace-api/media/dvb/fe-read-status.rst index cf781d463a20..75c6ee60ac9c 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-status.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-status.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_STATUS: @@ -18,25 +12,23 @@ Name FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_READ_STATUS, unsigned int *status ) - :name: FE_READ_STATUS +.. c:macro:: FE_READ_STATUS +``int ioctl(int fd, FE_READ_STATUS, unsigned int *status)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``status`` pointer to a bitmask integer filled with the values defined by enum :c:type:`fe_status`. - Description =========== @@ -51,7 +43,6 @@ written. varies according with the architecture. This needs to be fixed in the future. - int fe_status ============= @@ -59,7 +50,6 @@ The fe_status parameter is used to indicate the current state and/or state changes of the frontend hardware. It is produced using the enum :c:type:`fe_status` values on a bitmask - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst index d042e8c86930..653cd99a66f5 100644 --- a/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst +++ b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_READ_UNCORRECTED_BLOCKS: @@ -23,20 +17,19 @@ FE_READ_UNCORRECTED_BLOCKS Synopsis ======== -.. c:function:: int ioctl( int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks) - :name: FE_READ_UNCORRECTED_BLOCKS +.. c:macro:: FE_READ_UNCORRECTED_BLOCKS +``int ioctl(int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``ublocks`` The total number of uncorrected blocks seen by the driver so far. - Description =========== @@ -46,7 +39,6 @@ increment in block count during a specific time interval should be calculated. For this command, read-only access to the device is sufficient. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst index 8e059967f49c..56923c1a66b0 100644 --- a/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst +++ b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_SET_FRONTEND_TUNE_MODE: @@ -18,19 +12,18 @@ Name FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags ) - :name: FE_SET_FRONTEND_TUNE_MODE +.. c:macro:: FE_SET_FRONTEND_TUNE_MODE +``int ioctl(int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``flags`` Valid flags: @@ -44,14 +37,12 @@ Arguments is closed, this flag will be automatically turned off when the device is reopened read-write. - Description =========== Allow setting tuner mode flags to the frontend, between 0 (normal) or ``FE_TUNE_MODE_ONESHOT`` mode - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst index 960c95cb18a0..d1b857632059 100644 --- a/Documentation/userspace-api/media/dvb/fe-set-frontend.rst +++ b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_SET_FRONTEND: @@ -20,24 +14,22 @@ Name FE_SET_FRONTEND - Synopsis ======== -.. c:function:: int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p) - :name: FE_SET_FRONTEND +.. c:macro:: FE_SET_FRONTEND +``int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. + File descriptor returned by :c:func:`open()`. ``p`` Points to parameters for tuning operation. - Description =========== @@ -51,7 +43,6 @@ operation is initiated before the previous one was completed, the previous operation will be aborted in favor of the new one. This command requires read/write access to the device. - Return Value ============ @@ -73,6 +64,5 @@ appropriately. - Maximum supported symbol rate reached. - Generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-tone.rst b/Documentation/userspace-api/media/dvb/fe-set-tone.rst index 5726a20c7991..9f44bf946183 100644 --- a/Documentation/userspace-api/media/dvb/fe-set-tone.rst +++ b/Documentation/userspace-api/media/dvb/fe-set-tone.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_SET_TONE: @@ -18,24 +12,22 @@ Name FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_SET_TONE, enum fe_sec_tone_mode tone ) - :name: FE_SET_TONE +.. c:macro:: FE_SET_TONE +``int ioctl(int fd, FE_SET_TONE, enum fe_sec_tone_mode tone)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``tone`` an integer enumered value described at :c:type:`fe_sec_tone_mode` - Description =========== @@ -52,7 +44,6 @@ this is done using the DiSEqC ioctls. capability of selecting the band. So, it is recommended that applications would change to SEC_TONE_OFF when the device is not used. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-set-voltage.rst b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst index f3191808f4fd..c66771830be1 100644 --- a/Documentation/userspace-api/media/dvb/fe-set-voltage.rst +++ b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _FE_SET_VOLTAGE: @@ -18,24 +12,22 @@ Name FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem. - Synopsis ======== -.. c:function:: int ioctl( int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage ) - :name: FE_SET_VOLTAGE +.. c:macro:: FE_SET_VOLTAGE +``int ioctl(int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``voltage`` an integer enumered value described at :c:type:`fe_sec_voltage` - Description =========== @@ -56,7 +48,6 @@ power up the LNBf. the voltage to SEC_VOLTAGE_OFF while the device is not is used is recommended. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/fe-type-t.rst b/Documentation/userspace-api/media/dvb/fe-type-t.rst index 1617a8cc9045..e8986254897f 100644 --- a/Documentation/userspace-api/media/dvb/fe-type-t.rst +++ b/Documentation/userspace-api/media/dvb/fe-type-t.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ************* Frontend type @@ -18,7 +11,7 @@ fe_type_t type, defined as: .. c:type:: fe_type -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: Frontend types :header-rows: 1 diff --git a/Documentation/userspace-api/media/dvb/fe_property_parameters.rst b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst index 3f4ced2800e3..1717a0565fe8 100644 --- a/Documentation/userspace-api/media/dvb/fe_property_parameters.rst +++ b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _fe_property_parameters: @@ -96,16 +89,21 @@ ATSC (version 1) 8-VSB and 16-VSB. DMTB 4-QAM, 16-QAM, 32-QAM, 64-QAM and 4-QAM-NR. DVB-C Annex A/C 16-QAM, 32-QAM, 64-QAM and 256-QAM. DVB-C Annex B 64-QAM. +DVB-C2 QPSK, 16-QAM, 64-QAM, 256-QAM, 1024-QAM and 4096-QAM. DVB-T QPSK, 16-QAM and 64-QAM. DVB-T2 QPSK, 16-QAM, 64-QAM and 256-QAM. DVB-S No need to set. It supports only QPSK. DVB-S2 QPSK, 8-PSK, 16-APSK and 32-APSK. +DVB-S2X 8-APSK-L, 16-APSK-L, 32-APSK-L, 64-APSK and 64-APSK-L. ISDB-T QPSK, DQPSK, 16-QAM and 64-QAM. ISDB-S 8-PSK, QPSK and BPSK. ======================= ======================================================= .. note:: + As DVB-S2X specifies extensions to the DVB-S2 standard, the same + delivery system enum value is used (SYS_DVBS2). + Please notice that some of the above modulation types may not be defined currently at the Kernel. The reason is simple: no driver needed such definition yet. @@ -861,9 +859,10 @@ The acceptable values are defined by :c:type:`fe_guard_interval`. #. If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the hardware will try to find the correct guard interval (if capable) and will use TMCC to fill in the missing parameters. - #. Intervals ``GUARD_INTERVAL_1_128``, ``GUARD_INTERVAL_19_128`` - and ``GUARD_INTERVAL_19_256`` are used only for DVB-T2 at - present. + #. Interval ``GUARD_INTERVAL_1_64`` is used only for DVB-C2. + #. Interval ``GUARD_INTERVAL_1_128`` is used for both DVB-C2 and DVB_T2. + #. Intervals ``GUARD_INTERVAL_19_128`` and ``GUARD_INTERVAL_19_256`` are + used only for DVB-T2. #. Intervals ``GUARD_INTERVAL_PN420``, ``GUARD_INTERVAL_PN595`` and ``GUARD_INTERVAL_PN945`` are used only for DMTB at the present. On such standard, only those intervals and ``GUARD_INTERVAL_AUTO`` @@ -923,14 +922,15 @@ The acceptable values are defined by :c:type:`fe_hierarchy`. DTV_STREAM_ID ============= -Used on DVB-S2, DVB-T2 and ISDB-S. +Used on DVB-C2, DVB-S2, DVB-T2 and ISDB-S. -DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on -a single transport stream. This property enables the digital TV driver to -handle substream filtering, when supported by the hardware. By default, -substream filtering is disabled. +DVB-C2, DVB-S2, DVB-T2 and ISDB-S support the transmission of several +streams on a single transport stream. This property enables the digital +TV driver to handle substream filtering, when supported by the hardware. +By default, substream filtering is disabled. -For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255. +For DVB-C2, DVB-S2 and DVB-T2, the valid substream id range is from 0 to +255. For ISDB, the valid substream id range is from 1 to 65535. diff --git a/Documentation/userspace-api/media/dvb/frontend-header.rst b/Documentation/userspace-api/media/dvb/frontend-header.rst index cf8e515e5e1f..77f403361432 100644 --- a/Documentation/userspace-api/media/dvb/frontend-header.rst +++ b/Documentation/userspace-api/media/dvb/frontend-header.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later Frontend uAPI data types ======================== diff --git a/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst index 56657a6ec6ff..92ef98964140 100644 --- a/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst +++ b/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _frontend-property-cable-systems: diff --git a/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst index e64fd625c476..13b344b286b3 100644 --- a/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst +++ b/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _frontend-property-satellite-systems: diff --git a/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst index 1079522b2425..8cd461ceeea7 100644 --- a/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst +++ b/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _frontend-property-terrestrial-systems: diff --git a/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst b/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst index ae6ed5128deb..223c1c56c9d3 100644 --- a/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst +++ b/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _frontend-stat-properties: diff --git a/Documentation/userspace-api/media/dvb/frontend.rst b/Documentation/userspace-api/media/dvb/frontend.rst index 41ad519ca502..1df68730f181 100644 --- a/Documentation/userspace-api/media/dvb/frontend.rst +++ b/Documentation/userspace-api/media/dvb/frontend.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dvb_frontend: diff --git a/Documentation/userspace-api/media/dvb/frontend_f_close.rst b/Documentation/userspace-api/media/dvb/frontend_f_close.rst index 582e19a83c1a..52c323a85014 100644 --- a/Documentation/userspace-api/media/dvb/frontend_f_close.rst +++ b/Documentation/userspace-api/media/dvb/frontend_f_close.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _frontend_f_close: @@ -18,7 +12,6 @@ Name fe-close - Close a frontend device - Synopsis ======== @@ -26,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: dvb-fe-close Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <dvb-fe-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -44,7 +34,6 @@ This system call closes a previously opened front-end device. After closing a front-end device, its corresponding hardware might be powered down automatically. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/frontend_f_open.rst b/Documentation/userspace-api/media/dvb/frontend_f_open.rst index 0be3b249d33b..bb37eded0870 100644 --- a/Documentation/userspace-api/media/dvb/frontend_f_open.rst +++ b/Documentation/userspace-api/media/dvb/frontend_f_open.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe .. _frontend_f_open: @@ -18,7 +12,6 @@ Name fe-open - Open a frontend device - Synopsis ======== @@ -26,9 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: dvb-fe-open Arguments ========= @@ -51,7 +42,6 @@ Arguments Other flags have no effect. - Description =========== @@ -77,16 +67,14 @@ the specified mode. This implies that the corresponding hardware is powered up, and that other front-ends may have been powered down to make that possible. - Return Value ============ -On success :ref:`open() <frontend_f_open>` returns the new file descriptor. +On success :c:func:`open()` returns the new file descriptor. On error, -1 is returned, and the ``errno`` variable is set appropriately. Possible error codes are: - On success 0 is returned, and :c:type:`ca_slot_info` is filled. On error -1 is returned, and the ``errno`` variable is set @@ -112,6 +100,5 @@ appropriately. - The limit on the total number of files open on the system has been reached. - The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/frontend_fcalls.rst b/Documentation/userspace-api/media/dvb/frontend_fcalls.rst index 2b5e7a4dba9e..1df27b6e84f9 100644 --- a/Documentation/userspace-api/media/dvb/frontend_fcalls.rst +++ b/Documentation/userspace-api/media/dvb/frontend_fcalls.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _frontend_fcalls: diff --git a/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst b/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst index 1bd804f9b364..535828c002d6 100644 --- a/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst +++ b/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _frontend_legacy_types: diff --git a/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst b/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst index 29ad0f9b90a4..09de723c2c27 100644 --- a/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst +++ b/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _frontend_legacy_dvbv3_api: diff --git a/Documentation/userspace-api/media/dvb/headers.rst b/Documentation/userspace-api/media/dvb/headers.rst index ffd8f432484a..88c3eb33a89e 100644 --- a/Documentation/userspace-api/media/dvb/headers.rst +++ b/Documentation/userspace-api/media/dvb/headers.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later **************************** Digital TV uAPI header files @@ -21,10 +14,3 @@ Digital TV uAPI headers .. kernel-include:: $BUILDDIR/ca.h.rst .. kernel-include:: $BUILDDIR/net.h.rst - -Legacy uAPI -*********** - -.. kernel-include:: $BUILDDIR/audio.h.rst - -.. kernel-include:: $BUILDDIR/video.h.rst diff --git a/Documentation/userspace-api/media/dvb/intro.rst b/Documentation/userspace-api/media/dvb/intro.rst index f1235ef4599e..6784ae79657c 100644 --- a/Documentation/userspace-api/media/dvb/intro.rst +++ b/Documentation/userspace-api/media/dvb/intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dvb_introdution: @@ -114,7 +107,7 @@ Audio and video decoder a Systems on a Chip (SoC) integrated circuit. It may also not be needed for certain usages (e.g. for data-only - uses like “internet over satellite”). + uses like "internet over satellite"). :ref:`stb_components` shows a crude schematic of the control and data flow between those components. @@ -155,9 +148,9 @@ individual devices are called: - ``/dev/dvb/adapterN/caM``, -where ``N`` enumerates the Digital TV cards in a system starting from 0, and +where ``N`` enumerates the Digital TV cards in a system starting from 0, and ``M`` enumerates the devices of each type within each adapter, starting -from 0, too. We will omit the “``/dev/dvb/adapterN/``\ ” in the further +from 0, too. We will omit the "``/dev/dvb/adapterN/``\ " in the further discussion of these devices. More details about the data structures and function calls of all the diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst index 17c3b062afb3..ffe8325749e5 100644 --- a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _legacy_dvb_apis: @@ -18,11 +11,6 @@ The APIs described here **should not** be used on new drivers or applications. The DVBv3 frontend API has issues with new delivery systems, including DVB-S2, DVB-T2, ISDB, etc. -There's just one driver for a very legacy hardware using the Digital TV -audio and video APIs. No modern drivers should use it. Instead, audio and -video should be using the V4L2 and ALSA APIs, and the pipelines should -be set via the Media Controller API. - .. attention:: The APIs described here doesn't necessarily reflect the current @@ -35,5 +23,4 @@ be set via the Media Controller API. :maxdepth: 1 frontend_legacy_dvbv3_api - video - audio + legacy_dvb_decoder_api diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst new file mode 100644 index 000000000000..b46fe2becd02 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst @@ -0,0 +1,1642 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.audio + +.. _dvb_audio: + +================ +DVB Audio Device +================ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB audio device controls the MPEG2 audio decoder of the DVB +hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data +types and ioctl definitions can be accessed by including +``linux/dvb/audio.h`` in your application. + +Please note that most DVB cards don’t have their own MPEG decoder, which +results in the omission of the audio and video device. + +These ioctls were also used by V4L2 to control MPEG decoders implemented +in V4L2. The use of these ioctls for that purpose has been made obsolete +and proper V4L2 ioctls or controls have been created to replace that +functionality. Use :ref:`V4L2 ioctls<audio>` for new drivers! + + +Audio Data Types +================ + +This section describes the structures, data types and defines used when +talking to the audio device. + + +----- + + +audio_stream_source_t +--------------------- + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_stream_source_t + +.. code-block:: c + + typedef enum { + AUDIO_SOURCE_DEMUX, + AUDIO_SOURCE_MEMORY + } audio_stream_source_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_SOURCE_DEMUX`` + + - :cspan:`1` Selects the demultiplexer (fed either by the frontend + or the DVR device) as the source of the video stream. + + - .. + + - ``AUDIO_SOURCE_MEMORY`` + + - Selects the stream from the application that comes through + the `write()`_ system call. + +Description +~~~~~~~~~~~ + +The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call +and can take the following values, depending on whether we are replaying +from an internal (demux) or external (user write) source. + +The data fed to the decoder is also controlled by the PID-filter. +Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``. + + +----- + + +audio_play_state_t +------------------ + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_play_state_t + +.. code-block:: c + + typedef enum { + AUDIO_STOPPED, + AUDIO_PLAYING, + AUDIO_PAUSED + } audio_play_state_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_STOPPED`` + + - Audio is stopped. + + - .. + + - ``AUDIO_PLAYING`` + + - Audio is currently playing. + + - .. + + - ``AUDIO_PAUSE`` + + - Audio is frozen. + +Description +~~~~~~~~~~~ + +This values can be returned by the `AUDIO_GET_STATUS`_ call +representing the state of audio playback. + + +----- + + +audio_channel_select_t +---------------------- + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_channel_select_t + +.. code-block:: c + + typedef enum { + AUDIO_STEREO, + AUDIO_MONO_LEFT, + AUDIO_MONO_RIGHT, + AUDIO_MONO, + AUDIO_STEREO_SWAPPED + } audio_channel_select_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_STEREO`` + + - Stereo. + + - .. + + - ``AUDIO_MONO_LEFT`` + + - Mono, select left stereo channel as source. + + - .. + + - ``AUDIO_MONO_RIGHT`` + + - Mono, select right stereo channel as source. + + - .. + + - ``AUDIO_MONO`` + + - Mono source only. + + - .. + + - ``AUDIO_STEREO_SWAPPED`` + + - Stereo, swap L & R. + +Description +~~~~~~~~~~~ + +The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by +this values. + + +----- + + +audio_mixer_t +------------- + +Synopsis +~~~~~~~~ + +.. c:struct:: audio_mixer + +.. code-block:: c + + typedef struct audio_mixer { + unsigned int volume_left; + unsigned int volume_right; + } audio_mixer_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``unsigned int volume_left`` + + - Volume left channel. + Valid range: 0 ... 255 + + - .. + + - ``unsigned int volume_right`` + + - Volume right channel. + Valid range: 0 ... 255 + +Description +~~~~~~~~~~~ + +This structure is used by the `AUDIO_SET_MIXER`_ call to set the +audio volume. + + +----- + + +audio_status +------------ + +Synopsis +~~~~~~~~ + +.. c:struct:: audio_status + +.. code-block:: c + + typedef struct audio_status { + int AV_sync_state; + int mute_state; + audio_play_state_t play_state; + audio_stream_source_t stream_source; + audio_channel_select_t channel_select; + int bypass_mode; + audio_mixer_t mixer_state; + } audio_status_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`2` ``int AV_sync_state`` + + - :cspan:`1` Shows if A/V synchronization is ON or OFF. + + - .. + + - TRUE ( != 0 ) + + - AV-sync ON. + + - .. + + - FALSE ( == 0 ) + + - AV-sync OFF. + + - .. + + - :rspan:`2` ``int mute_state`` + + - :cspan:`1` Indicates if audio is muted or not. + + - .. + + - TRUE ( != 0 ) + + - mute audio + + - .. + + - FALSE ( == 0 ) + + - unmute audio + + - .. + + - `audio_play_state_t`_ ``play_state`` + + - Current playback state. + + - .. + + - `audio_stream_source_t`_ ``stream_source`` + + - Current source of the data. + + - .. + + - :rspan:`2` ``int bypass_mode`` + + - :cspan:`1` Is the decoding of the current Audio stream in + the DVB subsystem enabled or disabled. + + - .. + + - TRUE ( != 0 ) + + - Bypass disabled. + + - .. + + - FALSE ( == 0 ) + + - Bypass enabled. + + - .. + + - `audio_mixer_t`_ ``mixer_state`` + + - Current volume settings. + +Description +~~~~~~~~~~~ + +The `AUDIO_GET_STATUS`_ call returns this structure as information +about various states of the playback operation. + + +----- + + +audio encodings +--------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define AUDIO_CAP_DTS 1 + #define AUDIO_CAP_LPCM 2 + #define AUDIO_CAP_MP1 4 + #define AUDIO_CAP_MP2 8 + #define AUDIO_CAP_MP3 16 + #define AUDIO_CAP_AAC 32 + #define AUDIO_CAP_OGG 64 + #define AUDIO_CAP_SDDS 128 + #define AUDIO_CAP_AC3 256 + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_CAP_DTS`` + + - :cspan:`1` The hardware accepts DTS audio tracks. + + - .. + + - ``AUDIO_CAP_LPCM`` + + - The hardware accepts uncompressed audio with + Linear Pulse-Code Modulation (LPCM) + + - .. + + - ``AUDIO_CAP_MP1`` + + - The hardware accepts MPEG-1 Audio Layer 1. + + - .. + + - ``AUDIO_CAP_MP2`` + + - The hardware accepts MPEG-1 Audio Layer 2. + Also known as MUSICAM. + + - .. + + - ``AUDIO_CAP_MP3`` + + - The hardware accepts MPEG-1 Audio Layer III. + Commomly known as .mp3. + + - .. + + - ``AUDIO_CAP_AAC`` + + - The hardware accepts AAC (Advanced Audio Coding). + + - .. + + - ``AUDIO_CAP_OGG`` + + - The hardware accepts Vorbis audio tracks. + + - .. + + - ``AUDIO_CAP_SDDS`` + + - The hardware accepts Sony Dynamic Digital Sound (SDDS). + + - .. + + - ``AUDIO_CAP_AC3`` + + - The hardware accepts Dolby Digital ATSC A/52 audio. + Also known as AC-3. + +Description +~~~~~~~~~~~ + +A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the +following bits set according to the hardwares capabilities. + + +----- + + +Audio Function Calls +==================== + + +AUDIO_STOP +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_STOP + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_STOP) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - File descriptor returned by a previous call to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_STOP`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to stop playing the current +stream. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_PLAY +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_PLAY + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_PLAY) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - File descriptor returned by a previous call to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_PLAY`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to start playing an audio stream +from the selected source. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_PAUSE +----------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_PAUSE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_PAUSE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_PAUSE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call suspends the audio stream being played. Decoding and +playing are paused. It is then possible to restart again decoding and +playing process of the audio stream using `AUDIO_CONTINUE`_ command. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_CONTINUE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CONTINUE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CONTINUE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CONTINUE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl restarts the decoding and playing process previously paused +with `AUDIO_PAUSE`_ command. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_SELECT_SOURCE +------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SELECT_SOURCE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, + audio_stream_source_t source) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SELECT_SOURCE`` for this command. + + - .. + + - `audio_stream_source_t`_ ``source`` + + - Indicates the source that shall be used for the Audio stream. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call informs the audio device which source shall be used for +the input data. The possible sources are demux or memory. If +``AUDIO_SOURCE_MEMORY`` is selected, the data is fed to the Audio Device +through the write command. If ``AUDIO_SOURCE_DEMUX`` is selected, the data +is directly transferred from the onboard demux-device to the decoder. +Note: This only supports DVB-devices with one demux and one decoder so far. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_SET_MUTE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_MUTE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_MUTE, int state) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_SET_MUTE`` for this command. + + - .. + + - :rspan:`2` ``int state`` + + - :cspan:`1` Indicates if audio device shall mute or not. + + - .. + + - TRUE ( != 0 ) + + - mute audio + + - .. + + - FALSE ( == 0 ) + + - unmute audio + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To control a V4L2 decoder use the +V4L2 :ref:`VIDIOC_DECODER_CMD` with the +``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead. + +This ioctl call asks the audio device to mute the stream that is +currently being played. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_SET_AV_SYNC +----------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_AV_SYNC + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, int state) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_AV_SYNC`` for this command. + + - .. + + - :rspan:`2` ``int state`` + + - :cspan:`1` Tells the DVB subsystem if A/V synchronization + shall be ON or OFF. + + - .. + + - TRUE ( != 0 ) + + - AV-sync ON. + + - .. + + - FALSE ( == 0 ) + + - AV-sync OFF. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to turn ON or OFF A/V +synchronization. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_SET_BYPASS_MODE +--------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_BYPASS_MODE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_SET_BYPASS_MODE`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Enables or disables the decoding of the current + Audio stream in the DVB subsystem. + - .. + + - TRUE ( != 0 ) + + - Disable bypass + + - .. + + - FALSE ( == 0 ) + + - Enable bypass + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to bypass the Audio decoder and +forward the stream without decoding. This mode shall be used if streams +that can’t be handled by the DVB system shall be decoded. Dolby +DigitalTM streams are automatically forwarded by the DVB subsystem if +the hardware can handle it. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_CHANNEL_SELECT +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CHANNEL_SELECT + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, + audio_channel_select_t) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CHANNEL_SELECT`` for this command. + + - .. + + - `audio_channel_select_t`_ ``ch`` + + - Select the output format of the audio (mono left/right, stereo). + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To control a V4L2 decoder use the +V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead. + +This ioctl call asks the Audio Device to select the requested channel if +possible. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_GET_STATUS +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_GET_STATUS + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_GET_STATUS, + struct audio_status *status) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals AUDIO_GET_STATUS for this command. + + - .. + + - ``struct`` `audio_status`_ ``*status`` + + - Returns the current state of Audio Device. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to return the current state of the +Audio Device. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_GET_CAPABILITIES +---------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_GET_CAPABILITIES + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, + unsigned int *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_GET_CAPABILITIES`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Returns a bit array of supported sound formats. + Bits are defined in `audio encodings`_. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to tell us about the decoding +capabilities of the audio hardware. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_CLEAR_BUFFER +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CLEAR_BUFFER + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CLEAR_BUFFER`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to clear all software and hardware +buffers of the audio decoder device. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_SET_ID +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_ID + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_ID, int id) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_ID`` for this command. + + - .. + + - ``int id`` + + - Audio sub-stream id. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl selects which sub-stream is to be decoded if a program or +system stream is sent to the video device. + +If no audio stream type is set the id has to be in range [0xC0,0xDF] +for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] for LPCM. +See ITU-T H.222.0 | ISO/IEC 13818-1 for further description. + +If the stream type is set with `AUDIO_SET_STREAMTYPE`_, specifies the +id just the sub-stream id of the audio stream and only the first 5 bits +(& 0x1F) are recognized. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_SET_MIXER +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_MIXER + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_MIXER`` for this command. + + - .. + + - ``audio_mixer_t *mix`` + + - Mixer settings. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl lets you adjust the mixer settings of the audio decoder. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +AUDIO_SET_STREAMTYPE +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_STREAMTYPE + +.. code-block:: c + + int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_STREAMTYPE`` for this command. + + - .. + + - ``int type`` + + - Stream type. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl tells the driver which kind of audio stream to expect. This +is useful if the stream offers several audio sub-streams like LPCM and +AC3. + +Stream types defined in ITU-T H.222.0 | ISO/IEC 13818-1 are used. + + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EINVAL`` + + - Type is not a valid or supported stream type. + + +----- + + +AUDIO_BILINGUAL_CHANNEL_SELECT +------------------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, + audio_channel_select_t) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_BILINGUAL_CHANNEL_SELECT`` for this command. + + - .. + + - ``audio_channel_select_t ch`` + + - Select the output format of the audio (mono left/right, stereo). + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl has been replaced by the V4L2 +``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control +for MPEG decoders controlled through V4L2. + +This ioctl call asks the Audio Device to select the requested channel +for bilingual streams if possible. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific audio device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named audio device (e.g. +``/dev/dvb/adapter0/audio0``) for subsequent use. When an open() call has +succeeded, the device will be ready for use. The significance of +blocking or non-blocking mode is described in the documentation for +functions where there is a difference. It does not affect the semantics +of the open() call itself. A device opened in blocking mode can later be +put into non-blocking mode (and vice versa) using the F_SETFL command +of the fcntl system call. This is a standard system call, documented in +the Linux manual page for fcntl. Only one user can open the Audio Device +in O_RDWR mode. All other attempts to open the device in this mode will +fail, and an error code will be returned. If the Audio Device is opened +in O_RDONLY mode, the only ioctl call that can be used is +`AUDIO_GET_STATUS`_. All other call will return with an error code. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - Device driver not loaded/available. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + +Description +~~~~~~~~~~~ + +This system call closes a previously opened audio device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - Fd is not a valid open file descriptor. + +----- + + +write() +------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + size_t write(int fd, const void *buf, size_t count) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``void *buf`` + + - Pointer to the buffer containing the PES data. + + - .. + + - ``size_t count`` + + - Size of buf. + +Description +~~~~~~~~~~~ + +This system call can only be used if ``AUDIO_SOURCE_MEMORY`` is selected +in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in +PES format. If ``O_NONBLOCK`` is not specified the function will block +until buffer space is available. The amount of data to be transferred is +implied by count. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - :cspan:`1` Mode ``AUDIO_SOURCE_MEMORY`` not selected. + + - .. + + - ``ENOMEM`` + + - Attempted to write more data than the internal buffer can hold. + + - .. + + - ``EBADF`` + + - Fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst new file mode 100644 index 000000000000..f58985a6e63c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. _legacy_dvb_decoder_api: + +============================ +Legacy DVB MPEG Decoder APIs +============================ + +.. _legacy_dvb_decoder_notes: + +General Notes +============= + +This API has originally been designed for DVB only and is therefore limited to +the :ref:`legacy_dvb_decoder_formats` used in such digital TV-broadcastsystems. + +To circumvent this limitations the more versatile :ref:`V4L2 <v4l2spec>` API has +been designed. Which replaces this part of the DVB API. + +Nevertheless there have been projects build around this API. +To ensure compatibility this API is kept as it is. + +.. attention:: Do **not** use this API in new drivers! + + For audio and video use the :ref:`V4L2 <v4l2spec>` and ALSA APIs. + + Pipelines should be set up using the :ref:`Media Controller API<media_controller>`. + +Practically the decoders seem to be treated differently. The application typically +knows which decoder is in use or it is specially written for one decoder type. +Querying capabilities are rarely used because they are already known. + + +.. _legacy_dvb_decoder_formats: + +Data Formats +============ + +The API has been designed for DVB and compatible broadcastsystems. +Because of that fact the only supported data formats are ISO/IEC 13818-1 +compatible MPEG streams. The supported payloads may vary depending on the +used decoder. + +Timestamps are always MPEG PTS as defined in ITU T-REC-H.222.0 / +ISO/IEC 13818-1, if not otherwise noted. + +For storing recordings typically TS streams are used, in lesser extent PES. +Both variants are commonly accepted for playback, but it may be driver dependent. + + + + +Table of Contents +================= + +.. toctree:: + :maxdepth: 2 + + legacy_dvb_video + legacy_dvb_audio + legacy_dvb_osd diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst new file mode 100644 index 000000000000..179b66a8016a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst @@ -0,0 +1,883 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.osd + +.. _dvb_osd: + +============== +DVB OSD Device +============== + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB OSD device controls the OnScreen-Display of the AV7110 based +DVB-cards with hardware MPEG2 decoder. It can be accessed through +``/dev/dvb/adapter?/osd0``. +Data types and ioctl definitions can be accessed by including +``linux/dvb/osd.h`` in your application. + +The OSD is not a frame-buffer like on many other cards. +It is a kind of canvas one can draw on. +The color-depth is limited depending on the memory size installed. +An appropriate palette of colors has to be set up. +The installed memory size can be identified with the `OSD_GET_CAPABILITY`_ +ioctl. + +OSD Data Types +============== + +OSD_Command +----------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + /* All functions return -2 on "not open" */ + OSD_Close = 1, + OSD_Open, + OSD_Show, + OSD_Hide, + OSD_Clear, + OSD_Fill, + OSD_SetColor, + OSD_SetPalette, + OSD_SetTrans, + OSD_SetPixel, + OSD_GetPixel, + OSD_SetRow, + OSD_SetBlock, + OSD_FillRow, + OSD_FillBlock, + OSD_Line, + OSD_Query, + OSD_Test, + OSD_Text, + OSD_SetWindow, + OSD_MoveWindow, + OSD_OpenRaw, + } OSD_Command; + +Commands +~~~~~~~~ + +.. note:: All functions return -2 on "not open" + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + - .. + + - Command + + - | Used variables of ``struct`` `osd_cmd_t`_. + | Usage{variable} if alternative use. + + - :cspan:`2` Description + + + + - .. + + - ``OSD_Close`` + + - - + + - | Disables OSD and releases the buffers. + | Returns 0 on success. + + - .. + + - ``OSD_Open`` + + - | x0,y0,x1,y1, + | BitPerPixel[2/4/8]{color&0x0F}, + | mix[0..15]{color&0xF0} + + - | Opens OSD with this size and bit depth + | Returns 0 on success, + | -1 on DRAM allocation error, + | -2 on "already open". + + - .. + + - ``OSD_Show`` + + - - + + - | Enables OSD mode. + | Returns 0 on success. + + - .. + + - ``OSD_Hide`` + + - - + + - | Disables OSD mode. + | Returns 0 on success. + + - .. + + - ``OSD_Clear`` + + - - + + - | Sets all pixel to color 0. + | Returns 0 on success. + + - .. + + - ``OSD_Fill`` + + - color + + - | Sets all pixel to color <color>. + | Returns 0 on success. + + - .. + + - ``OSD_SetColor`` + + - | color, + | R{x0},G{y0},B{x1}, + | opacity{y1} + + - | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply + | R,G,B: 0..255 + | R=Red, G=Green, B=Blue + | opacity=0: pixel opacity 0% (only video pixel shows) + | opacity=1..254: pixel opacity as specified in header + | opacity=255: pixel opacity 100% (only OSD pixel shows) + | Returns 0 on success, -1 on error. + + - .. + + - ``OSD_SetPalette`` + + - | firstcolor{color}, + | lastcolor{x0},data + + - | Set a number of entries in the palette. + | Sets the entries "firstcolor" through "lastcolor" from the + array "data". + | Data has 4 byte for each color: + | R,G,B, and a opacity value: 0->transparent, 1..254->mix, + 255->pixel + + - .. + + - ``OSD_SetTrans`` + + - transparency{color} + + - | Sets transparency of mixed pixel (0..15). + | Returns 0 on success. + + - .. + + - ``OSD_SetPixel`` + + - x0,y0,color + + - | Sets pixel <x>,<y> to color number <color>. + | Returns 0 on success, -1 on error. + + - .. + + - ``OSD_GetPixel`` + + - x0,y0 + + - | Returns color number of pixel <x>,<y>, or -1. + | Command currently not supported by the AV7110! + + - .. + + - ``OSD_SetRow`` + + - x0,y0,x1,data + + - | Fills pixels x0,y through x1,y with the content of data[]. + | Returns 0 on success, -1 on clipping all pixel (no pixel + drawn). + + - .. + + - ``OSD_SetBlock`` + + - | x0,y0,x1,y1, + | increment{color}, + | data + + - | Fills pixels x0,y0 through x1,y1 with the content of data[]. + | Inc contains the width of one line in the data block, + | inc<=0 uses block width as line width. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_FillRow`` + + - x0,y0,x1,color + + - | Fills pixels x0,y through x1,y with the color <color>. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_FillBlock`` + + - x0,y0,x1,y1,color + + - | Fills pixels x0,y0 through x1,y1 with the color <color>. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_Line`` + + - x0,y0,x1,y1,color + + - | Draw a line from x0,y0 to x1,y1 with the color <color>. + | Returns 0 on success. + + - .. + + - ``OSD_Query`` + + - | x0,y0,x1,y1, + | xasp{color}; yasp=11 + + - | Fills parameters with the picture dimensions and the pixel + aspect ratio. + | Returns 0 on success. + | Command currently not supported by the AV7110! + + - .. + + - ``OSD_Test`` + + - - + + - | Draws a test picture. + | For debugging purposes only. + | Returns 0 on success. + - .. + + - ``OSD_Text`` + + - x0,y0,size,color,text + + - Draws a text at position x0,y0 with the color <color>. + + - .. + + - ``OSD_SetWindow`` + + - x0 + + - Set window with number 0<x0<8 as current. + + - .. + + - ``OSD_MoveWindow`` + + - x0,y0 + + - Move current window to (x0, y0). + + - .. + + - ``OSD_OpenRaw`` + + - | x0,y0,x1,y1, + | `osd_raw_window_t`_ {color} + + - Open other types of OSD windows. + +Description +~~~~~~~~~~~ + +The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to +tell the driver which OSD_Command to execute. + + +----- + +osd_cmd_t +--------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct osd_cmd_s { + OSD_Command cmd; + int x0; + int y0; + int x1; + int y1; + int color; + void __user *data; + } osd_cmd_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_Command cmd`` + + - `OSD_Command`_ to be executed. + + - .. + + - ``int x0`` + + - First horizontal position. + + - .. + + - ``int y0`` + + - First vertical position. + + - .. + + - ``int x1`` + + - Second horizontal position. + + - .. + + - ``int y1`` + + - Second vertical position. + + - .. + + - ``int color`` + + - Number of the color in the palette. + + - .. + + - ``void __user *data`` + + - Command specific Data. + +Description +~~~~~~~~~~~ + +The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl. +It contains the data for the OSD_Command and the `OSD_Command`_ itself. +The structure has to be passed to the driver and the components may be +modified by it. + + +----- + + +osd_raw_window_t +---------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + OSD_BITMAP1, + OSD_BITMAP2, + OSD_BITMAP4, + OSD_BITMAP8, + OSD_BITMAP1HR, + OSD_BITMAP2HR, + OSD_BITMAP4HR, + OSD_BITMAP8HR, + OSD_YCRCB422, + OSD_YCRCB444, + OSD_YCRCB444HR, + OSD_VIDEOTSIZE, + OSD_VIDEOHSIZE, + OSD_VIDEOQSIZE, + OSD_VIDEODSIZE, + OSD_VIDEOTHSIZE, + OSD_VIDEOTQSIZE, + OSD_VIDEOTDSIZE, + OSD_VIDEONSIZE, + OSD_CURSOR + } osd_raw_window_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_BITMAP1`` + + - :cspan:`1` 1 bit bitmap + + - .. + + - ``OSD_BITMAP2`` + + - 2 bit bitmap + + - .. + + - ``OSD_BITMAP4`` + + - 4 bit bitmap + + - .. + + - ``OSD_BITMAP8`` + + - 8 bit bitmap + + - .. + + - ``OSD_BITMAP1HR`` + + - 1 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP2HR`` + + - 2 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP4HR`` + + - 4 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP8HR`` + + - 8 Bit bitmap half resolution + + - .. + + - ``OSD_YCRCB422`` + + - 4:2:2 YCRCB Graphic Display + + - .. + + - ``OSD_YCRCB444`` + + - 4:4:4 YCRCB Graphic Display + + - .. + + - ``OSD_YCRCB444HR`` + + - 4:4:4 YCRCB graphic half resolution + + - .. + + - ``OSD_VIDEOTSIZE`` + + - True Size Normal MPEG Video Display + + - .. + + - ``OSD_VIDEOHSIZE`` + + - MPEG Video Display Half Resolution + + - .. + + - ``OSD_VIDEOQSIZE`` + + - MPEG Video Display Quarter Resolution + + - .. + + - ``OSD_VIDEODSIZE`` + + - MPEG Video Display Double Resolution + + - .. + + - ``OSD_VIDEOTHSIZE`` + + - True Size MPEG Video Display Half Resolution + + - .. + + - ``OSD_VIDEOTQSIZE`` + + - True Size MPEG Video Display Quarter Resolution + + - .. + + - ``OSD_VIDEOTDSIZE`` + + - True Size MPEG Video Display Double Resolution + + - .. + + - ``OSD_VIDEONSIZE`` + + - Full Size MPEG Video Display + + - .. + + - ``OSD_CURSOR`` + + - Cursor + +Description +~~~~~~~~~~~ + +The ``osd_raw_window_t`` data type is used with the `OSD_Command`_ +OSD_OpenRaw to tell the driver which type of OSD to open. + + +----- + + +osd_cap_t +--------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct osd_cap_s { + int cmd; + #define OSD_CAP_MEMSIZE 1 + long val; + } osd_cap_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int cmd`` + + - Capability to query. + + - .. + + - ``long val`` + + - Used to store the Data. + +Supported capabilities +~~~~~~~~~~~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_CAP_MEMSIZE`` + + - Memory size installed on the card. + +Description +~~~~~~~~~~~ + +This structure of data used with the `OSD_GET_CAPABILITY`_ call. + + +----- + + +OSD Function Calls +================== + +OSD_SEND_CMD +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: OSD_SEND_CMD + +.. code-block:: c + + int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd) + + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Pointer to the location of the structure `osd_cmd_t`_ for this + command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl sends the `OSD_Command`_ to the card. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EINVAL`` + + - Command is out of range. + + +----- + + +OSD_GET_CAPABILITY +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: OSD_GET_CAPABILITY + +.. code-block:: c + + int ioctl(int fd, int request = OSD_GET_CAPABILITY, + struct osd_cap_t *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``OSD_GET_CAPABILITY`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Pointer to the location of the structure `osd_cap_t`_ for this + command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is used to get the capabilities of the OSD of the AV7110 based +DVB-decoder-card in use. + +.. note:: + The structure osd_cap_t has to be setup by the user and passed to the + driver. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. + + - ``EINVAL`` + + - Unsupported capability. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific OSD device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named OSD device (e.g. +``/dev/dvb/adapter?/osd0``) for subsequent use. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - Device driver not loaded/available. + + - .. + + - ``EINTERNAL`` + + - Internal error. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_ . + +Description +~~~~~~~~~~~ + +This system call closes a previously opened OSD device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst new file mode 100644 index 000000000000..b9fd5cadae24 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst @@ -0,0 +1,2430 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.video + +.. _dvb_video: + +================ +DVB Video Device +================ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB video device controls the MPEG2 video decoder of the DVB +hardware. It can be accessed through ``/dev/dvb/adapter0/video0``. Data +types and ioctl definitions can be accessed by including +``linux/dvb/video.h`` in your application. + +Note that the DVB video device only controls decoding of the MPEG video +stream, not its presentation on the TV or computer screen. On PCs this +is typically handled by an associated video4linux device, e.g. +``/dev/video``, which allows scaling and defining output windows. + +Most DVB cards don’t have their own MPEG decoder, which results in the +omission of the audio and video device as well as the video4linux +device. + +These ioctls were also used by V4L2 to control MPEG decoders implemented +in V4L2. The use of these ioctls for that purpose has been made obsolete +and proper V4L2 ioctls or controls have been created to replace that +functionality. Use :ref:`V4L2 ioctls<video>` for new drivers! + + +Video Data Types +================ + + + +video_format_t +-------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_FORMAT_4_3, + VIDEO_FORMAT_16_9, + VIDEO_FORMAT_221_1 + } video_format_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_FORMAT_4_3`` + + - Select 4:3 format. + + - .. + + - ``VIDEO_FORMAT_16_9`` + + - Select 16:9 format. + + - .. + + - ``VIDEO_FORMAT_221_1`` + + - Select 2.21:1 format. + +Description +~~~~~~~~~~~ + +The ``video_format_t`` data type +is used in the `VIDEO_SET_FORMAT`_ function to tell the driver which +aspect ratio the output hardware (e.g. TV) has. It is also used in the +data structures `video_status`_ returned by `VIDEO_GET_STATUS`_ +and `video_event`_ returned by `VIDEO_GET_EVENT`_ which report +about the display format of the current video stream. + + +----- + + +video_displayformat_t +--------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_PAN_SCAN, + VIDEO_LETTER_BOX, + VIDEO_CENTER_CUT_OUT + } video_displayformat_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_PAN_SCAN`` + + - Use pan and scan format. + + - .. + + - ``VIDEO_LETTER_BOX`` + + - Use letterbox format. + + - .. + + - ``VIDEO_CENTER_CUT_OUT`` + + - Use center cut out format. + +Description +~~~~~~~~~~~ + +In case the display format of the video stream and of the display +hardware differ the application has to specify how to handle the +cropping of the picture. This can be done using the +`VIDEO_SET_DISPLAY_FORMAT`_ call which accepts this enum as argument. + + +----- + + +video_size_t +------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct { + int w; + int h; + video_format_t aspect_ratio; + } video_size_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int w`` + + - Video width in pixels. + + - .. + + - ``int h`` + + - Video height in pixels. + + - .. + + - `video_format_t`_ ``aspect_ratio`` + + - Aspect ratio. + +Description +~~~~~~~~~~~ + +Used in the struct `video_event`_. It stores the resolution and +aspect ratio of the video. + + +----- + + +video_stream_source_t +--------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_SOURCE_DEMUX, + VIDEO_SOURCE_MEMORY + } video_stream_source_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_SOURCE_DEMUX`` + + - :cspan:`1` Select the demux as the main source. + + - .. + + - ``VIDEO_SOURCE_MEMORY`` + + - If this source is selected, the stream + comes from the user through the write + system call. + +Description +~~~~~~~~~~~ + +The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call +and can take the following values, depending on whether we are replaying +from an internal (demuxer) or external (user write) source. +VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the +frontend or the DVR device) as the source of the video stream. If +VIDEO_SOURCE_MEMORY is selected the stream comes from the application +through the `write()`_ system call. + + +----- + + +video_play_state_t +------------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_STOPPED, + VIDEO_PLAYING, + VIDEO_FREEZED + } video_play_state_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_STOPPED`` + + - Video is stopped. + + - .. + + - ``VIDEO_PLAYING`` + + - Video is currently playing. + + - .. + + - ``VIDEO_FREEZED`` + + - Video is frozen. + +Description +~~~~~~~~~~~ + +This values can be returned by the `VIDEO_GET_STATUS`_ call +representing the state of video playback. + + +----- + + +struct video_command +-------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_command { + __u32 cmd; + __u32 flags; + union { + struct { + __u64 pts; + } stop; + + struct { + __s32 speed; + __u32 format; + } play; + + struct { + __u32 data[16]; + } raw; + }; + }; + + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``__u32 cmd`` + + - `Decoder command`_ + + - .. + + - ``__u32 flags`` + + - Flags for the `Decoder command`_. + + - .. + + - ``struct stop`` + + - ``__u64 pts`` + + - MPEG PTS + + - .. + + - :rspan:`5` ``stuct play`` + + - :rspan:`4` ``__s32 speed`` + + - 0 or 1000 specifies normal speed, + + - .. + + - 1: specifies forward single stepping, + + - .. + + - -1: specifies backward single stepping, + + - .. + + - >1: playback at speed / 1000 of the normal speed + + - .. + + - <-1: reverse playback at ( -speed / 1000 ) of the normal speed. + + - .. + + - ``__u32 format`` + + - `Play input formats`_ + + - .. + + - ``__u32 data[16]`` + + - Reserved + +Description +~~~~~~~~~~~ + +The structure must be zeroed before use by the application. This ensures +it can be extended safely in the future. + + +----- + + +Predefined decoder commands and flags +------------------------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define VIDEO_CMD_PLAY (0) + #define VIDEO_CMD_STOP (1) + #define VIDEO_CMD_FREEZE (2) + #define VIDEO_CMD_CONTINUE (3) + + #define VIDEO_CMD_FREEZE_TO_BLACK (1 << 0) + + #define VIDEO_CMD_STOP_TO_BLACK (1 << 0) + #define VIDEO_CMD_STOP_IMMEDIATELY (1 << 1) + + #define VIDEO_PLAY_FMT_NONE (0) + #define VIDEO_PLAY_FMT_GOP (1) + + #define VIDEO_VSYNC_FIELD_UNKNOWN (0) + #define VIDEO_VSYNC_FIELD_ODD (1) + #define VIDEO_VSYNC_FIELD_EVEN (2) + #define VIDEO_VSYNC_FIELD_PROGRESSIVE (3) + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`3` _`Decoder command` + + - ``VIDEO_CMD_PLAY`` + + - Start playback. + + - .. + + - ``VIDEO_CMD_STOP`` + + - Stop playback. + + - .. + + - ``VIDEO_CMD_FREEZE`` + + - Freeze playback. + + - .. + + - ``VIDEO_CMD_CONTINUE`` + + - Continue playback after freeze. + + - .. + + - Flags for ``VIDEO_CMD_FREEZE`` + + - ``VIDEO_CMD_FREEZE_TO_BLACK`` + + - Show black picture on freeze. + + - .. + + - :rspan:`1` Flags for ``VIDEO_CMD_STOP`` + + - ``VIDEO_CMD_STOP_TO_BLACK`` + + - Show black picture on stop. + + - .. + + - ``VIDEO_CMD_STOP_IMMEDIATELY`` + + - Stop immediately, without emptying buffers. + + - .. + + - :rspan:`1` _`Play input formats` + + - ``VIDEO_PLAY_FMT_NONE`` + + - The decoder has no special format requirements + + - .. + + - ``VIDEO_PLAY_FMT_GOP`` + + - The decoder requires full GOPs + + - .. + + - :rspan:`3` Field order + + - ``VIDEO_VSYNC_FIELD_UNKNOWN`` + + - FIELD_UNKNOWN can be used if the hardware does not know + whether the Vsync is for an odd, even or progressive + (i.e. non-interlaced) field. + + - .. + + - ``VIDEO_VSYNC_FIELD_ODD`` + + - Vsync is for an odd field. + + - .. + + - ``VIDEO_VSYNC_FIELD_EVEN`` + + - Vsync is for an even field. + + - .. + + - ``VIDEO_VSYNC_FIELD_PROGRESSIVE`` + + - progressive (i.e. non-interlaced) + + +----- + + +video_event +----------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_event { + __s32 type; + #define VIDEO_EVENT_SIZE_CHANGED 1 + #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 + #define VIDEO_EVENT_DECODER_STOPPED 3 + #define VIDEO_EVENT_VSYNC 4 + long timestamp; + union { + video_size_t size; + unsigned int frame_rate; + unsigned char vsync_field; + } u; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`4` ``__s32 type`` + + - :cspan:`1` Event type. + + - .. + + - ``VIDEO_EVENT_SIZE_CHANGED`` + + - Size changed. + + - .. + + - ``VIDEO_EVENT_FRAME_RATE_CHANGED`` + + - Framerate changed. + + - .. + + - ``VIDEO_EVENT_DECODER_STOPPED`` + + - Decoder stopped. + + - .. + + - ``VIDEO_EVENT_VSYNC`` + + - Vsync occurred. + + - .. + + - ``long timestamp`` + + - :cspan:`1` MPEG PTS at occurrence. + + - .. + + - :rspan:`2` ``union u`` + + - `video_size_t`_ size + + - Resolution and aspect ratio of the video. + + - .. + + - ``unsigned int frame_rate`` + + - in frames per 1000sec + + - .. + + - ``unsigned char vsync_field`` + + - | unknown / odd / even / progressive + | See: `Predefined decoder commands and flags`_ + +Description +~~~~~~~~~~~ + +This is the structure of a video event as it is returned by the +`VIDEO_GET_EVENT`_ call. See there for more details. + + +----- + + +video_status +------------ + +Synopsis +~~~~~~~~ + +The `VIDEO_GET_STATUS`_ call returns the following structure informing +about various states of the playback operation. + +.. code-block:: c + + struct video_status { + int video_blank; + video_play_state_t play_state; + video_stream_source_t stream_source; + video_format_t video_format; + video_displayformat_t display_format; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`2` ``int video_blank`` + + - :cspan:`1` Show blank video on freeze? + + - .. + + - TRUE ( != 0 ) + + - Blank screen when freeze. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + + - .. + + - `video_play_state_t`_ ``play_state`` + + - Current state of playback. + + - .. + + - `video_stream_source_t`_ ``stream_source`` + + - Current source (demux/memory). + + - .. + + - `video_format_t`_ ``video_format`` + + - Current aspect ratio of stream. + + - .. + + - `video_displayformat_t`_ ``display_format`` + + - Applied cropping mode. + +Description +~~~~~~~~~~~ + +If ``video_blank`` is set ``TRUE`` video will be blanked out if the +channel is changed or if playback is stopped. Otherwise, the last picture +will be displayed. ``play_state`` indicates if the video is currently +frozen, stopped, or being played back. The ``stream_source`` corresponds +to the selected source for the video stream. It can come either from the +demultiplexer or from memory. The ``video_format`` indicates the aspect +ratio (one of 4:3 or 16:9) of the currently played video stream. +Finally, ``display_format`` corresponds to the applied cropping mode in +case the source video format is not the same as the format of the output +device. + + +----- + + +video_still_picture +------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_still_picture { + char *iFrame; + int32_t size; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``char *iFrame`` + + - Pointer to a single iframe in memory. + + - .. + + - ``int32_t size`` + + - Size of the iframe. + + +Description +~~~~~~~~~~~ + +An I-frame displayed via the `VIDEO_STILLPICTURE`_ call is passed on +within this structure. + + +----- + + +video capabilities +------------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define VIDEO_CAP_MPEG1 1 + #define VIDEO_CAP_MPEG2 2 + #define VIDEO_CAP_SYS 4 + #define VIDEO_CAP_PROG 8 + +Constants +~~~~~~~~~ +Bit definitions for capabilities: + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_CAP_MPEG1`` + + - :cspan:`1` The hardware can decode MPEG1. + + - .. + + - ``VIDEO_CAP_MPEG2`` + + - The hardware can decode MPEG2. + + - .. + + - ``VIDEO_CAP_SYS`` + + - The video device accepts system stream. + + You still have to open the video and the audio device + but only send the stream to the video device. + + - .. + + - ``VIDEO_CAP_PROG`` + + - The video device accepts program stream. + + You still have to open the video and the audio device + but only send the stream to the video device. + +Description +~~~~~~~~~~~ + +A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the +following bits set according to the hardware's capabilities. + + +----- + + +Video Function Calls +==================== + + +VIDEO_STOP +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_STOP + +.. code-block:: c + + int ioctl(fd, VIDEO_STOP, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``VIDEO_STOP`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Indicates how the screen shall be handled. + + - .. + + - TRUE ( != 0 ) + + - Blank screen when stop. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call asks the Video Device to stop playing the current +stream. Depending on the input parameter, the screen can be blanked out +or displaying the last decoded frame. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_PLAY +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_PLAY + +.. code-block:: c + + int ioctl(fd, VIDEO_PLAY) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_PLAY`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call asks the Video Device to start playing a video stream +from the selected source. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_FREEZE +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_FREEZE + +.. code-block:: c + + int ioctl(fd, VIDEO_FREEZE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_FREEZE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call suspends the live video stream being played, if +VIDEO_SOURCE_DEMUX is selected. Decoding and playing are frozen. +It is then possible to restart the decoding and playing process of the +video stream using the `VIDEO_CONTINUE`_ command. +If VIDEO_SOURCE_MEMORY is selected in the ioctl call +`VIDEO_SELECT_SOURCE`_, the Digital TV subsystem will not decode any more +data until the ioctl call `VIDEO_CONTINUE`_ or `VIDEO_PLAY`_ is performed. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_CONTINUE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_CONTINUE + +.. code-block:: c + + int ioctl(fd, VIDEO_CONTINUE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_CONTINUE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call restarts decoding and playing processes of the video +stream which was played before a call to `VIDEO_FREEZE`_ was made. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_SELECT_SOURCE +------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SELECT_SOURCE + +.. code-block:: c + + int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SELECT_SOURCE`` for this command. + + - .. + + - `video_stream_source_t`_ ``source`` + + - Indicates which source shall be used for the Video stream. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. This ioctl was also supported +by the V4L2 ivtv driver, but that has been replaced by the ivtv-specific +``IVTV_IOC_PASSTHROUGH_MODE`` ioctl. + +This ioctl call informs the video device which source shall be used for +the input data. The possible sources are demux or memory. If memory is +selected, the data is fed to the video device through the write command +using the struct `video_stream_source_t`_. If demux is selected, the data +is directly transferred from the onboard demux-device to the decoder. + +The data fed to the decoder is also controlled by the PID-filter. +Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``. + + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_SET_BLANK +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_BLANK + +.. code-block:: c + + int ioctl(fd, VIDEO_SET_BLANK, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``VIDEO_SET_BLANK`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Indicates if the screen shall be blanked. + + - .. + + - TRUE ( != 0 ) + + - Blank screen when stop. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to blank out the picture. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_GET_STATUS +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_STATUS + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_STATUS, + struct video_status *status) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_STATUS`` for this command. + + - .. + + - ``struct`` `video_status`_ ``*status`` + + - Returns the current status of the Video Device. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to return the current status of +the device. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_GET_EVENT +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_EVENT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_EVENT, + struct video_event *ev) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_EVENT`` for this command. + + - .. + + - ``struct`` `video_event`_ ``*ev`` + + - Points to the location where the event, if any, is to be stored. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To get events from a V4L2 decoder +use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead. + +This ioctl call returns an event of type `video_event`_ if available. A +certain number of the latest events will be cued and returned in order of +occurrence. Older events may be discarded if not fetched in time. If +an event is not available, the behavior depends on whether the device is +in blocking or non-blocking mode. In the latter case, the call fails +immediately with errno set to ``EWOULDBLOCK``. In the former case, the +call blocks until an event becomes available. The standard Linux poll() +and/or select() system calls can be used with the device file descriptor +to watch for new events. For select(), the file descriptor should be +included in the exceptfds argument, and for poll(), POLLPRI should be +specified as the wake-up condition. Read-only permissions are sufficient +for this ioctl call. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EWOULDBLOCK`` + + - :cspan:`1` There is no event pending, and the device is in + non-blocking mode. + + - .. + + - ``EOVERFLOW`` + + - Overflow in event queue - one or more events were lost. + + +----- + + +VIDEO_SET_DISPLAY_FORMAT +------------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_DISPLAY_FORMAT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, + video_display_format_t format) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_DISPLAY_FORMAT`` for this command. + + - .. + + - `video_displayformat_t`_ ``format`` + + - Selects the video format to be used. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to select the video format to be +applied by the MPEG chip on the video. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_STILLPICTURE +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_STILLPICTURE + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_STILLPICTURE, + struct video_still_picture *sp) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_STILLPICTURE`` for this command. + + - .. + + - ``struct`` `video_still_picture`_ ``*sp`` + + - Pointer to the location where the struct with the I-frame + and size is stored. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to display a still picture +(I-frame). The input data shall be the section of an elementary video +stream containing an I-frame. Typically this section is extracted from a +TS or PES recording. Resolution and codec (see `video capabilities`_) must +be supported by the device. If the pointer is NULL, then the current +displayed still picture is blanked. + +e.g. The AV7110 supports MPEG1 and MPEG2 with the common PAL-SD +resolutions. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_FAST_FORWARD +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_FAST_FORWARD + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_FAST_FORWARD`` for this command. + + - .. + + - ``int nFrames`` + + - The number of frames to skip. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to skip decoding of N number of +I-frames. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is +selected. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + +----- + + +VIDEO_SLOWMOTION +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SLOWMOTION + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SLOWMOTION`` for this command. + + - .. + + - ``int nFrames`` + + - The number of times to repeat each frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the video device to repeat decoding frames N number +of times. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is +selected. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + +----- + + +VIDEO_GET_CAPABILITIES +---------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_CAPABILITIES + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_CAPABILITIES`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Pointer to a location where to store the capability information. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the video device about its decoding capabilities. +On success it returns an integer which has bits set according to the +defines in `video capabilities`_. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_CLEAR_BUFFER +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_CLEAR_BUFFER + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_CLEAR_BUFFER) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_CLEAR_BUFFER`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call clears all video buffers in the driver and in the +decoder hardware. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_SET_STREAMTYPE +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_STREAMTYPE + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_STREAMTYPE`` for this command. + + - .. + + - ``int type`` + + - Stream type. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl tells the driver which kind of stream to expect being written +to it. +Intelligent decoder might also not support or ignore (like the AV7110) +this call and determine the stream type themselves. + +Currently used stream types: + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + - .. + + - Codec + + - Stream type + + - .. + + - MPEG2 + + - 0 + + - .. + + - MPEG4 h.264 + + - 1 + + - .. + + - VC1 + + - 3 + + - .. + + - MPEG4 Part2 + + - 4 + + - .. + + - VC1 SM + + - 5 + + - .. + + - MPEG1 + + - 6 + + - .. + + - HEVC h.265 + + - | 7 + | DREAMBOX: 22 + + - .. + + - AVS + + - 16 + + - .. + + - AVS2 + + - 40 + +Not every decoder supports all stream types. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_SET_FORMAT +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_FORMAT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_FORMAT`` for this command. + + - .. + + - `video_format_t`_ ``format`` + + - Video format of TV as defined in section `video_format_t`_. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl sets the screen format (aspect ratio) of the connected output +device (TV) so that the output of the decoder can be adjusted +accordingly. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_GET_SIZE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_SIZE + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call, + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_SIZE`` for this command. + + - .. + + - `video_size_t`_ ``*size`` + + - Returns the size and aspect ratio. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl returns the size and aspect ratio. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_GET_PTS +------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_PTS + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_PTS`` for this command. + + - .. + + - ``__u64 *pts`` + + - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / + ISO/IEC 13818-1. + + The PTS should belong to the currently played frame if possible, + but may also be a value close to it like the PTS of the last + decoded frame or the last PTS extracted by the PES parser. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +``V4L2_CID_MPEG_VIDEO_DEC_PTS`` control. + +This ioctl call asks the Video Device to return the current PTS +timestamp. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_GET_FRAME_COUNT +--------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_FRAME_COUNT + +.. code-block:: c + + int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_FRAME_COUNT`` for this command. + + - .. + + - ``__u64 *pts`` + + - Returns the number of frames displayed since the decoder was + started. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +``V4L2_CID_MPEG_VIDEO_DEC_FRAME`` control. + +This ioctl call asks the Video Device to return the number of displayed +frames since the decoder was started. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_COMMAND +------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_COMMAND + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_COMMAND, + struct video_command *cmd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_COMMAND`` for this command. + + - .. + + - `struct video_command`_ ``*cmd`` + + - Commands the decoder. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +:ref:`VIDIOC_DECODER_CMD` ioctl. + +This ioctl commands the decoder. The `struct video_command`_ is a +subset of the ``v4l2_decoder_cmd`` struct, so refer to the +:ref:`VIDIOC_DECODER_CMD` documentation for +more information. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +VIDEO_TRY_COMMAND +----------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_TRY_COMMAND + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_TRY_COMMAND, + struct video_command *cmd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_TRY_COMMAND`` for this command. + + - .. + + - `struct video_command`_ ``*cmd`` + + - Try a decoder command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl. + +This ioctl tries a decoder command. The `struct video_command`_ is a +subset of the ``v4l2_decoder_cmd`` struct, so refer to the +:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation +for more information. + +Return Value +~~~~~~~~~~~~ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific video device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named video device (e.g. +/dev/dvb/adapter?/video?) for subsequent use. + +When an open() call has succeeded, the device will be ready for use. The +significance of blocking or non-blocking mode is described in the +documentation for functions where there is a difference. It does not +affect the semantics of the open() call itself. A device opened in +blocking mode can later be put into non-blocking mode (and vice versa) +using the F_SETFL command of the fcntl system call. This is a standard +system call, documented in the Linux manual page for fcntl. Only one +user can open the Video Device in O_RDWR mode. All other attempts to +open the device in this mode will fail, and an error-code will be +returned. If the Video Device is opened in O_RDONLY mode, the only +ioctl call that can be used is `VIDEO_GET_STATUS`_. All other call will +return an error code. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - :cspan:`1` Device driver not loaded/available. + + - .. + + - ``EINTERNAL`` + + - Internal error. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + +Description +~~~~~~~~~~~ + +This system call closes a previously opened video device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. + + +----- + + +write() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: size_t write(int fd, const void *buf, size_t count) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``void *buf`` + + - Pointer to the buffer containing the PES data. + + - .. + + - ``size_t count`` + + - Size of buf. + +Description +~~~~~~~~~~~ + +This system call can only be used if VIDEO_SOURCE_MEMORY is selected +in the ioctl call `VIDEO_SELECT_SOURCE`_. The data provided shall be in +PES format, unless the capability allows other formats. TS is the +most common format for storing DVB-data, it is usually supported too. +If O_NONBLOCK is not specified the function will block until buffer space +is available. The amount of data to be transferred is implied by count. + +.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>` + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - :cspan:`1` Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + - .. + + - ``ENOMEM`` + + - Attempted to write more data than the internal buffer can hold. + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/net-add-if.rst b/Documentation/userspace-api/media/dvb/net-add-if.rst index e75ec4d80a08..022b4c626249 100644 --- a/Documentation/userspace-api/media/dvb/net-add-if.rst +++ b/Documentation/userspace-api/media/dvb/net-add-if.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net .. _NET_ADD_IF: @@ -18,24 +12,22 @@ Name NET_ADD_IF - Creates a new network interface for a given Packet ID. - Synopsis ======== -.. c:function:: int ioctl( int fd, NET_ADD_IF, struct dvb_net_if *net_if ) - :name: NET_ADD_IF +.. c:macro:: NET_ADD_IF +``int ioctl(int fd, NET_ADD_IF, struct dvb_net_if *net_if)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``net_if`` pointer to struct :c:type:`dvb_net_if` - Description =========== diff --git a/Documentation/userspace-api/media/dvb/net-get-if.rst b/Documentation/userspace-api/media/dvb/net-get-if.rst index c5421d9a8c0b..e99696c9db74 100644 --- a/Documentation/userspace-api/media/dvb/net-get-if.rst +++ b/Documentation/userspace-api/media/dvb/net-get-if.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net .. _NET_GET_IF: @@ -18,24 +12,22 @@ Name NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF <net>`. - Synopsis ======== -.. c:function:: int ioctl( int fd, NET_GET_IF, struct dvb_net_if *net_if ) - :name: NET_GET_IF +.. c:macro:: NET_GET_IF +``int ioctl(int fd, NET_GET_IF, struct dvb_net_if *net_if)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``net_if`` pointer to struct :c:type:`dvb_net_if` - Description =========== @@ -46,7 +38,6 @@ encapsulation type used on such interface. If the interface was not created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill the ``errno`` with ``EINVAL`` error code. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/net-remove-if.rst b/Documentation/userspace-api/media/dvb/net-remove-if.rst index d530559f66f1..ac88691c0423 100644 --- a/Documentation/userspace-api/media/dvb/net-remove-if.rst +++ b/Documentation/userspace-api/media/dvb/net-remove-if.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net .. _NET_REMOVE_IF: @@ -18,31 +12,28 @@ Name NET_REMOVE_IF - Removes a network interface. - Synopsis ======== -.. c:function:: int ioctl( int fd, NET_REMOVE_IF, int ifnum ) - :name: NET_REMOVE_IF +.. c:macro:: NET_REMOVE_IF +``int ioctl(int fd, NET_REMOVE_IF, int ifnum)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <frontend_f_open>`. + File descriptor returned by :c:func:`open()`. ``net_if`` number of the interface to be removed - Description =========== The NET_REMOVE_IF ioctl deletes an interface previously created via :ref:`NET_ADD_IF <net>`. - Return Value ============ diff --git a/Documentation/userspace-api/media/dvb/net-types.rst b/Documentation/userspace-api/media/dvb/net-types.rst index 94323cffe8af..075264bc0394 100644 --- a/Documentation/userspace-api/media/dvb/net-types.rst +++ b/Documentation/userspace-api/media/dvb/net-types.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _net_types: diff --git a/Documentation/userspace-api/media/dvb/net.rst b/Documentation/userspace-api/media/dvb/net.rst index 084f33d1ba28..020a023d3b61 100644 --- a/Documentation/userspace-api/media/dvb/net.rst +++ b/Documentation/userspace-api/media/dvb/net.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _net: @@ -30,7 +23,7 @@ types that are present on the transport stream. This is done through virtual ``dvb?_?`` network interfaces, and will be controlled/routed via the standard ip tools (like ip, route, netstat, ifconfig, etc). -Data types and and ioctl definitions are defined via ``linux/dvb/net.h`` +Data types and ioctl definitions are defined via ``linux/dvb/net.h`` header. diff --git a/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst b/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst index d854ccf42ccf..f099b49357ed 100644 --- a/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst +++ b/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _query-dvb-frontend-info: diff --git a/Documentation/userspace-api/media/dvb/video-clear-buffer.rst b/Documentation/userspace-api/media/dvb/video-clear-buffer.rst deleted file mode 100644 index ba7a13302862..000000000000 --- a/Documentation/userspace-api/media/dvb/video-clear-buffer.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_CLEAR_BUFFER: - -================== -VIDEO_CLEAR_BUFFER -================== - -Name ----- - -VIDEO_CLEAR_BUFFER - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_CLEAR_BUFFER) - :name: VIDEO_CLEAR_BUFFER - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_CLEAR_BUFFER for this command. - - -Description ------------ - -This ioctl call clears all video buffers in the driver and in the -decoder hardware. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-command.rst b/Documentation/userspace-api/media/dvb/video-command.rst deleted file mode 100644 index d96d764d0eef..000000000000 --- a/Documentation/userspace-api/media/dvb/video-command.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_COMMAND: - -============= -VIDEO_COMMAND -============= - -Name ----- - -VIDEO_COMMAND - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_COMMAND, struct video_command *cmd) - :name: VIDEO_COMMAND - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_COMMAND for this command. - - - .. row 3 - - - struct video_command \*cmd - - - Commands the decoder. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the -:ref:`VIDIOC_DECODER_CMD` ioctl. - -This ioctl commands the decoder. The ``video_command`` struct is a -subset of the ``v4l2_decoder_cmd`` struct, so refer to the -:ref:`VIDIOC_DECODER_CMD` documentation for -more information. - -.. c:type:: struct video_command - -.. code-block:: c - - /* The structure must be zeroed before use by the application - This ensures it can be extended safely in the future. */ - struct video_command { - __u32 cmd; - __u32 flags; - union { - struct { - __u64 pts; - } stop; - - struct { - /* 0 or 1000 specifies normal speed, - 1 specifies forward single stepping, - -1 specifies backward single stepping, - >1: playback at speed/1000 of the normal speed, - <-1: reverse playback at (-speed/1000) of the normal speed. */ - __s32 speed; - __u32 format; - } play; - - struct { - __u32 data[16]; - } raw; - }; - }; - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-continue.rst b/Documentation/userspace-api/media/dvb/video-continue.rst deleted file mode 100644 index bb18514ac5e9..000000000000 --- a/Documentation/userspace-api/media/dvb/video-continue.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_CONTINUE: - -============== -VIDEO_CONTINUE -============== - -Name ----- - -VIDEO_CONTINUE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_CONTINUE) - :name: VIDEO_CONTINUE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_CONTINUE for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call restarts decoding and playing processes of the video -stream which was played before a call to VIDEO_FREEZE was made. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-fast-forward.rst b/Documentation/userspace-api/media/dvb/video-fast-forward.rst deleted file mode 100644 index 1f6ec89574d1..000000000000 --- a/Documentation/userspace-api/media/dvb/video-fast-forward.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_FAST_FORWARD: - -================== -VIDEO_FAST_FORWARD -================== - -Name ----- - -VIDEO_FAST_FORWARD - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_FAST_FORWARD, int nFrames) - :name: VIDEO_FAST_FORWARD - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_FAST_FORWARD for this command. - - - .. row 3 - - - int nFrames - - - The number of frames to skip. - - -Description ------------ - -This ioctl call asks the Video Device to skip decoding of N number of -I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is -selected. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode VIDEO_SOURCE_MEMORY not selected. diff --git a/Documentation/userspace-api/media/dvb/video-fclose.rst b/Documentation/userspace-api/media/dvb/video-fclose.rst deleted file mode 100644 index f9d2a8ebe4a4..000000000000 --- a/Documentation/userspace-api/media/dvb/video-fclose.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fclose: - -================= -dvb video close() -================= - -Name ----- - -dvb video close() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int close(int fd) - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This system call closes a previously opened video device. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/video-fopen.rst b/Documentation/userspace-api/media/dvb/video-fopen.rst deleted file mode 100644 index a418cf6d772e..000000000000 --- a/Documentation/userspace-api/media/dvb/video-fopen.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fopen: - -================ -dvb video open() -================ - -Name ----- - -dvb video open() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int open(const char *deviceName, int flags) - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - const char \*deviceName - - - Name of specific video device. - - - .. row 2 - - - int flags - - - A bit-wise OR of the following flags: - - - .. row 3 - - - - - O_RDONLY read-only access - - - .. row 4 - - - - - O_RDWR read/write access - - - .. row 5 - - - - - O_NONBLOCK open in non-blocking mode - - - .. row 6 - - - - - (blocking mode is the default) - - -Description ------------ - -This system call opens a named video device (e.g. -/dev/dvb/adapter0/video0) for subsequent use. - -When an open() call has succeeded, the device will be ready for use. The -significance of blocking or non-blocking mode is described in the -documentation for functions where there is a difference. It does not -affect the semantics of the open() call itself. A device opened in -blocking mode can later be put into non-blocking mode (and vice versa) -using the F_SETFL command of the fcntl system call. This is a standard -system call, documented in the Linux manual page for fcntl. Only one -user can open the Video Device in O_RDWR mode. All other attempts to -open the device in this mode will fail, and an error-code will be -returned. If the Video Device is opened in O_RDONLY mode, the only -ioctl call that can be used is VIDEO_GET_STATUS. All other call will -return an error code. - - -Return Value ------------- - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device driver not loaded/available. - - - .. row 2 - - - ``EINTERNAL`` - - - Internal error. - - - .. row 3 - - - ``EBUSY`` - - - Device or resource busy. - - - .. row 4 - - - ``EINVAL`` - - - Invalid argument. diff --git a/Documentation/userspace-api/media/dvb/video-freeze.rst b/Documentation/userspace-api/media/dvb/video-freeze.rst deleted file mode 100644 index 46f287faa7fe..000000000000 --- a/Documentation/userspace-api/media/dvb/video-freeze.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_FREEZE: - -============ -VIDEO_FREEZE -============ - -Name ----- - -VIDEO_FREEZE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_FREEZE) - :name: VIDEO_FREEZE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_FREEZE for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call suspends the live video stream being played. Decoding -and playing are frozen. It is then possible to restart the decoding and -playing process of the video stream using the VIDEO_CONTINUE command. -If VIDEO_SOURCE_MEMORY is selected in the ioctl call -VIDEO_SELECT_SOURCE, the Digital TV subsystem will not decode any more data -until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-fwrite.rst b/Documentation/userspace-api/media/dvb/video-fwrite.rst deleted file mode 100644 index 08dfafa9c6a1..000000000000 --- a/Documentation/userspace-api/media/dvb/video-fwrite.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fwrite: - -================= -dvb video write() -================= - -Name ----- - -dvb video write() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: size_t write(int fd, const void *buf, size_t count) - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - void \*buf - - - Pointer to the buffer containing the PES data. - - - .. row 3 - - - size_t count - - - Size of buf. - - -Description ------------ - -This system call can only be used if VIDEO_SOURCE_MEMORY is selected -in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in -PES format, unless the capability allows other formats. If O_NONBLOCK -is not specified the function will block until buffer space is -available. The amount of data to be transferred is implied by count. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode VIDEO_SOURCE_MEMORY not selected. - - - .. row 2 - - - ``ENOMEM`` - - - Attempted to write more data than the internal buffer can hold. - - - .. row 3 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/video-get-capabilities.rst b/Documentation/userspace-api/media/dvb/video-get-capabilities.rst deleted file mode 100644 index f6f19df5a3b4..000000000000 --- a/Documentation/userspace-api/media/dvb/video-get-capabilities.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_CAPABILITIES: - -====================== -VIDEO_GET_CAPABILITIES -====================== - -Name ----- - -VIDEO_GET_CAPABILITIES - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_CAPABILITIES, unsigned int *cap) - :name: VIDEO_GET_CAPABILITIES - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_CAPABILITIES for this command. - - - .. row 3 - - - unsigned int \*cap - - - Pointer to a location where to store the capability information. - - -Description ------------ - -This ioctl call asks the video device about its decoding capabilities. -On success it returns and integer which has bits set according to the -defines in section ??. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-get-event.rst b/Documentation/userspace-api/media/dvb/video-get-event.rst deleted file mode 100644 index 6db8e6337c4f..000000000000 --- a/Documentation/userspace-api/media/dvb/video-get-event.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_EVENT: - -=============== -VIDEO_GET_EVENT -=============== - -Name ----- - -VIDEO_GET_EVENT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_EVENT, struct video_event *ev) - :name: VIDEO_GET_EVENT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_EVENT for this command. - - - .. row 3 - - - struct video_event \*ev - - - Points to the location where the event, if any, is to be stored. - - -Description ------------ - -This ioctl is for Digital TV devices only. To get events from a V4L2 decoder -use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead. - -This ioctl call returns an event of type video_event if available. If -an event is not available, the behavior depends on whether the device is -in blocking or non-blocking mode. In the latter case, the call fails -immediately with errno set to ``EWOULDBLOCK``. In the former case, the call -blocks until an event becomes available. The standard Linux poll() -and/or select() system calls can be used with the device file descriptor -to watch for new events. For select(), the file descriptor should be -included in the exceptfds argument, and for poll(), POLLPRI should be -specified as the wake-up condition. Read-only permissions are sufficient -for this ioctl call. - -.. c:type:: video_event - -.. code-block:: c - - struct video_event { - __s32 type; - #define VIDEO_EVENT_SIZE_CHANGED 1 - #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 - #define VIDEO_EVENT_DECODER_STOPPED 3 - #define VIDEO_EVENT_VSYNC 4 - long timestamp; - union { - video_size_t size; - unsigned int frame_rate; /* in frames per 1000sec */ - unsigned char vsync_field; /* unknown/odd/even/progressive */ - } u; - }; - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EWOULDBLOCK`` - - - There is no event pending, and the device is in non-blocking mode. - - - .. row 2 - - - ``EOVERFLOW`` - - - Overflow in event queue - one or more events were lost. diff --git a/Documentation/userspace-api/media/dvb/video-get-frame-count.rst b/Documentation/userspace-api/media/dvb/video-get-frame-count.rst deleted file mode 100644 index 4152a42daeb3..000000000000 --- a/Documentation/userspace-api/media/dvb/video-get-frame-count.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_FRAME_COUNT: - -===================== -VIDEO_GET_FRAME_COUNT -===================== - -Name ----- - -VIDEO_GET_FRAME_COUNT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts) - :name: VIDEO_GET_FRAME_COUNT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_FRAME_COUNT for this command. - - - .. row 3 - - - __u64 \*pts - - - Returns the number of frames displayed since the decoder was - started. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_FRAME`` -control. - -This ioctl call asks the Video Device to return the number of displayed -frames since the decoder was started. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-get-pts.rst b/Documentation/userspace-api/media/dvb/video-get-pts.rst deleted file mode 100644 index f957df792ae1..000000000000 --- a/Documentation/userspace-api/media/dvb/video-get-pts.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_PTS: - -============= -VIDEO_GET_PTS -============= - -Name ----- - -VIDEO_GET_PTS - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_PTS, __u64 *pts) - :name: VIDEO_GET_PTS - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_PTS for this command. - - - .. row 3 - - - __u64 \*pts - - - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / - ISO/IEC 13818-1. - - The PTS should belong to the currently played frame if possible, - but may also be a value close to it like the PTS of the last - decoded frame or the last PTS extracted by the PES parser. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_PTS`` -control. - -This ioctl call asks the Video Device to return the current PTS -timestamp. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-get-size.rst b/Documentation/userspace-api/media/dvb/video-get-size.rst deleted file mode 100644 index 376745550eb5..000000000000 --- a/Documentation/userspace-api/media/dvb/video-get-size.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_SIZE: - -============== -VIDEO_GET_SIZE -============== - -Name ----- - -VIDEO_GET_SIZE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_SIZE, video_size_t *size) - :name: VIDEO_GET_SIZE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_SIZE for this command. - - - .. row 3 - - - video_size_t \*size - - - Returns the size and aspect ratio. - - -Description ------------ - -This ioctl returns the size and aspect ratio. - -.. c:type:: video_size_t - -.. code-block::c - - typedef struct { - int w; - int h; - video_format_t aspect_ratio; - } video_size_t; - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-get-status.rst b/Documentation/userspace-api/media/dvb/video-get-status.rst deleted file mode 100644 index d0172593e557..000000000000 --- a/Documentation/userspace-api/media/dvb/video-get-status.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_STATUS: - -================ -VIDEO_GET_STATUS -================ - -Name ----- - -VIDEO_GET_STATUS - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_STATUS, struct video_status *status) - :name: VIDEO_GET_STATUS - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_STATUS for this command. - - - .. row 3 - - - struct video_status \*status - - - Returns the current status of the Video Device. - - -Description ------------ - -This ioctl call asks the Video Device to return the current status of -the device. - -.. c:type:: video_status - -.. code-block:: c - - struct video_status { - int video_blank; /* blank video on freeze? */ - video_play_state_t play_state; /* current state of playback */ - video_stream_source_t stream_source; /* current source (demux/memory) */ - video_format_t video_format; /* current aspect ratio of stream*/ - video_displayformat_t display_format;/* selected cropping mode */ - }; - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-play.rst b/Documentation/userspace-api/media/dvb/video-play.rst deleted file mode 100644 index 2b6b4e93bd93..000000000000 --- a/Documentation/userspace-api/media/dvb/video-play.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_PLAY: - -========== -VIDEO_PLAY -========== - -Name ----- - -VIDEO_PLAY - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_PLAY) - :name: VIDEO_PLAY - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_PLAY for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call asks the Video Device to start playing a video stream -from the selected source. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-select-source.rst b/Documentation/userspace-api/media/dvb/video-select-source.rst deleted file mode 100644 index 504f768da00c..000000000000 --- a/Documentation/userspace-api/media/dvb/video-select-source.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SELECT_SOURCE: - -=================== -VIDEO_SELECT_SOURCE -=================== - -Name ----- - -VIDEO_SELECT_SOURCE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source) - :name: VIDEO_SELECT_SOURCE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SELECT_SOURCE for this command. - - - .. row 3 - - - video_stream_source_t source - - - Indicates which source shall be used for the Video stream. - - -Description ------------ - -This ioctl is for Digital TV devices only. This ioctl was also supported by the -V4L2 ivtv driver, but that has been replaced by the ivtv-specific -``IVTV_IOC_PASSTHROUGH_MODE`` ioctl. - -This ioctl call informs the video device which source shall be used for -the input data. The possible sources are demux or memory. If memory is -selected, the data is fed to the video device through the write command. - -.. c:type:: video_stream_source_t - -.. code-block:: c - - typedef enum { - VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */ - VIDEO_SOURCE_MEMORY /* If this source is selected, the stream - comes from the user through the write - system call */ - } video_stream_source_t; - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-set-blank.rst b/Documentation/userspace-api/media/dvb/video-set-blank.rst deleted file mode 100644 index a2608df94d3e..000000000000 --- a/Documentation/userspace-api/media/dvb/video-set-blank.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_BLANK: - -=============== -VIDEO_SET_BLANK -=============== - -Name ----- - -VIDEO_SET_BLANK - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_BLANK, boolean mode) - :name: VIDEO_SET_BLANK - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SET_BLANK for this command. - - - .. row 3 - - - boolean mode - - - TRUE: Blank screen when stop. - - - .. row 4 - - - - - FALSE: Show last decoded frame. - - -Description ------------ - -This ioctl call asks the Video Device to blank out the picture. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-set-display-format.rst b/Documentation/userspace-api/media/dvb/video-set-display-format.rst deleted file mode 100644 index c587b3d15e30..000000000000 --- a/Documentation/userspace-api/media/dvb/video-set-display-format.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_DISPLAY_FORMAT: - -======================== -VIDEO_SET_DISPLAY_FORMAT -======================== - -Name ----- - -VIDEO_SET_DISPLAY_FORMAT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_DISPLAY_FORMAT) - :name: VIDEO_SET_DISPLAY_FORMAT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SET_DISPLAY_FORMAT for this command. - - - .. row 3 - - - video_display_format_t format - - - Selects the video format to be used. - - -Description ------------ - -This ioctl call asks the Video Device to select the video format to be -applied by the MPEG chip on the video. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-set-format.rst b/Documentation/userspace-api/media/dvb/video-set-format.rst deleted file mode 100644 index ced74edb74eb..000000000000 --- a/Documentation/userspace-api/media/dvb/video-set-format.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_FORMAT: - -================ -VIDEO_SET_FORMAT -================ - -Name ----- - -VIDEO_SET_FORMAT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_FORMAT, video_format_t format) - :name: VIDEO_SET_FORMAT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SET_FORMAT for this command. - - - .. row 3 - - - video_format_t format - - - video format of TV as defined in section ??. - - -Description ------------ - -This ioctl sets the screen format (aspect ratio) of the connected output -device (TV) so that the output of the decoder can be adjusted -accordingly. - -.. c:type:: video_format_t - -.. code-block:: c - - typedef enum { - VIDEO_FORMAT_4_3, /* Select 4:3 format */ - VIDEO_FORMAT_16_9, /* Select 16:9 format. */ - VIDEO_FORMAT_221_1 /* 2.21:1 */ - } video_format_t; - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - format is not a valid video format. diff --git a/Documentation/userspace-api/media/dvb/video-set-streamtype.rst b/Documentation/userspace-api/media/dvb/video-set-streamtype.rst deleted file mode 100644 index 1729bc04e4f7..000000000000 --- a/Documentation/userspace-api/media/dvb/video-set-streamtype.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_STREAMTYPE: - -==================== -VIDEO_SET_STREAMTYPE -==================== - -Name ----- - -VIDEO_SET_STREAMTYPE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_STREAMTYPE, int type) - :name: VIDEO_SET_STREAMTYPE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SET_STREAMTYPE for this command. - - - .. row 3 - - - int type - - - stream type - - -Description ------------ - -This ioctl tells the driver which kind of stream to expect being written -to it. If this call is not used the default of video PES is used. Some -drivers might not support this call and always expect PES. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-slowmotion.rst b/Documentation/userspace-api/media/dvb/video-slowmotion.rst deleted file mode 100644 index b8cfba7bbfb3..000000000000 --- a/Documentation/userspace-api/media/dvb/video-slowmotion.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SLOWMOTION: - -================ -VIDEO_SLOWMOTION -================ - -Name ----- - -VIDEO_SLOWMOTION - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SLOWMOTION, int nFrames) - :name: VIDEO_SLOWMOTION - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SLOWMOTION for this command. - - - .. row 3 - - - int nFrames - - - The number of times to repeat each frame. - - -Description ------------ - -This ioctl call asks the video device to repeat decoding frames N number -of times. This call can only be used if VIDEO_SOURCE_MEMORY is -selected. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode VIDEO_SOURCE_MEMORY not selected. diff --git a/Documentation/userspace-api/media/dvb/video-stillpicture.rst b/Documentation/userspace-api/media/dvb/video-stillpicture.rst deleted file mode 100644 index 5432619a63a1..000000000000 --- a/Documentation/userspace-api/media/dvb/video-stillpicture.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_STILLPICTURE: - -================== -VIDEO_STILLPICTURE -================== - -Name ----- - -VIDEO_STILLPICTURE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_STILLPICTURE, struct video_still_picture *sp) - :name: VIDEO_STILLPICTURE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_STILLPICTURE for this command. - - - .. row 3 - - - struct video_still_picture \*sp - - - Pointer to a location where an I-frame and size is stored. - - -Description ------------ - -This ioctl call asks the Video Device to display a still picture -(I-frame). The input data shall contain an I-frame. If the pointer is -NULL, then the current displayed still picture is blanked. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-stop.rst b/Documentation/userspace-api/media/dvb/video-stop.rst deleted file mode 100644 index 9a53fe7f2fd0..000000000000 --- a/Documentation/userspace-api/media/dvb/video-stop.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_STOP: - -========== -VIDEO_STOP -========== - -Name ----- - -VIDEO_STOP - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_STOP, boolean mode) - :name: VIDEO_STOP - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_STOP for this command. - - - .. row 3 - - - Boolean mode - - - Indicates how the screen shall be handled. - - - .. row 4 - - - - - TRUE: Blank screen when stop. - - - .. row 5 - - - - - FALSE: Show last decoded frame. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call asks the Video Device to stop playing the current -stream. Depending on the input parameter, the screen can be blanked out -or displaying the last decoded frame. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video-try-command.rst b/Documentation/userspace-api/media/dvb/video-try-command.rst deleted file mode 100644 index 61667952030f..000000000000 --- a/Documentation/userspace-api/media/dvb/video-try-command.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_TRY_COMMAND: - -================= -VIDEO_TRY_COMMAND -================= - -Name ----- - -VIDEO_TRY_COMMAND - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_TRY_COMMAND, struct video_command *cmd) - :name: VIDEO_TRY_COMMAND - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_TRY_COMMAND for this command. - - - .. row 3 - - - struct video_command \*cmd - - - Try a decoder command. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the -:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl. - -This ioctl tries a decoder command. The ``video_command`` struct is a -subset of the ``v4l2_decoder_cmd`` struct, so refer to the -:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation -for more information. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/video.rst b/Documentation/userspace-api/media/dvb/video.rst deleted file mode 100644 index 537eae1b0723..000000000000 --- a/Documentation/userspace-api/media/dvb/video.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_video: - -####################### -Digital TV Video Device -####################### - -The Digital TV video device controls the MPEG2 video decoder of the Digital -TV hardware. It can be accessed through **/dev/dvb/adapter0/video0**. Data -types and and ioctl definitions can be accessed by including -**linux/dvb/video.h** in your application. - -Note that the Digital TV video device only controls decoding of the MPEG video -stream, not its presentation on the TV or computer screen. On PCs this -is typically handled by an associated video4linux device, e.g. -**/dev/video**, which allows scaling and defining output windows. - -Some Digital TV cards don’t have their own MPEG decoder, which results in the -omission of the audio and video device as well as the video4linux -device. - -The ioctls that deal with SPUs (sub picture units) and navigation -packets are only supported on some MPEG decoders made for DVD playback. - -These ioctls were also used by V4L2 to control MPEG decoders implemented -in V4L2. The use of these ioctls for that purpose has been made obsolete -and proper V4L2 ioctls or controls have been created to replace that -functionality. - - -.. toctree:: - :maxdepth: 1 - - video_types - video_function_calls diff --git a/Documentation/userspace-api/media/dvb/video_function_calls.rst b/Documentation/userspace-api/media/dvb/video_function_calls.rst deleted file mode 100644 index 4902a40d65ba..000000000000 --- a/Documentation/userspace-api/media/dvb/video_function_calls.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_function_calls: - -******************** -Video Function Calls -******************** - -.. toctree:: - :maxdepth: 1 - - video-fopen - video-fclose - video-fwrite - video-stop - video-play - video-freeze - video-continue - video-select-source - video-set-blank - video-get-status - video-get-frame-count - video-get-pts - video-get-event - video-command - video-try-command - video-get-size - video-set-display-format - video-stillpicture - video-fast-forward - video-slowmotion - video-get-capabilities - video-clear-buffer - video-set-streamtype - video-set-format diff --git a/Documentation/userspace-api/media/dvb/video_types.rst b/Documentation/userspace-api/media/dvb/video_types.rst deleted file mode 100644 index bdba1d48f647..000000000000 --- a/Documentation/userspace-api/media/dvb/video_types.rst +++ /dev/null @@ -1,255 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_types: - -**************** -Video Data Types -**************** - - -.. _video-format-t: - -video_format_t -============== - -The ``video_format_t`` data type defined by - - -.. code-block:: c - - typedef enum { - VIDEO_FORMAT_4_3, /* Select 4:3 format */ - VIDEO_FORMAT_16_9, /* Select 16:9 format. */ - VIDEO_FORMAT_221_1 /* 2.21:1 */ - } video_format_t; - -is used in the VIDEO_SET_FORMAT function (??) to tell the driver which -aspect ratio the output hardware (e.g. TV) has. It is also used in the -data structures video_status (??) returned by VIDEO_GET_STATUS (??) -and video_event (??) returned by VIDEO_GET_EVENT (??) which report -about the display format of the current video stream. - - -.. _video-displayformat-t: - -video_displayformat_t -===================== - -In case the display format of the video stream and of the display -hardware differ the application has to specify how to handle the -cropping of the picture. This can be done using the -VIDEO_SET_DISPLAY_FORMAT call (??) which accepts - - -.. code-block:: c - - typedef enum { - VIDEO_PAN_SCAN, /* use pan and scan format */ - VIDEO_LETTER_BOX, /* use letterbox format */ - VIDEO_CENTER_CUT_OUT /* use center cut out format */ - } video_displayformat_t; - -as argument. - - -.. _video-stream-source-t: - -video_stream_source_t -===================== - -The video stream source is set through the VIDEO_SELECT_SOURCE call -and can take the following values, depending on whether we are replaying -from an internal (demuxer) or external (user write) source. - - -.. code-block:: c - - typedef enum { - VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */ - VIDEO_SOURCE_MEMORY /* If this source is selected, the stream - comes from the user through the write - system call */ - } video_stream_source_t; - -VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the -frontend or the DVR device) as the source of the video stream. If -VIDEO_SOURCE_MEMORY is selected the stream comes from the application -through the **write()** system call. - - -.. _video-play-state-t: - -video_play_state_t -================== - -The following values can be returned by the VIDEO_GET_STATUS call -representing the state of video playback. - - -.. code-block:: c - - typedef enum { - VIDEO_STOPPED, /* Video is stopped */ - VIDEO_PLAYING, /* Video is currently playing */ - VIDEO_FREEZED /* Video is freezed */ - } video_play_state_t; - - -.. c:type:: video_command - -struct video_command -==================== - -The structure must be zeroed before use by the application This ensures -it can be extended safely in the future. - - -.. code-block:: c - - struct video_command { - __u32 cmd; - __u32 flags; - union { - struct { - __u64 pts; - } stop; - - struct { - /* 0 or 1000 specifies normal speed, - 1 specifies forward single stepping, - -1 specifies backward single stepping, - >>1: playback at speed/1000 of the normal speed, - <-1: reverse playback at (-speed/1000) of the normal speed. */ - __s32 speed; - __u32 format; - } play; - - struct { - __u32 data[16]; - } raw; - }; - }; - - -.. _video-size-t: - -video_size_t -============ - - -.. code-block:: c - - typedef struct { - int w; - int h; - video_format_t aspect_ratio; - } video_size_t; - - -.. c:type:: video_event - -struct video_event -================== - -The following is the structure of a video event as it is returned by the -VIDEO_GET_EVENT call. - - -.. code-block:: c - - struct video_event { - __s32 type; - #define VIDEO_EVENT_SIZE_CHANGED 1 - #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 - #define VIDEO_EVENT_DECODER_STOPPED 3 - #define VIDEO_EVENT_VSYNC 4 - long timestamp; - union { - video_size_t size; - unsigned int frame_rate; /* in frames per 1000sec */ - unsigned char vsync_field; /* unknown/odd/even/progressive */ - } u; - }; - - -.. c:type:: video_status - -struct video_status -=================== - -The VIDEO_GET_STATUS call returns the following structure informing -about various states of the playback operation. - - -.. code-block:: c - - struct video_status { - int video_blank; /* blank video on freeze? */ - video_play_state_t play_state; /* current state of playback */ - video_stream_source_t stream_source; /* current source (demux/memory) */ - video_format_t video_format; /* current aspect ratio of stream */ - video_displayformat_t display_format;/* selected cropping mode */ - }; - -If video_blank is set video will be blanked out if the channel is -changed or if playback is stopped. Otherwise, the last picture will be -displayed. play_state indicates if the video is currently frozen, -stopped, or being played back. The stream_source corresponds to the -selected source for the video stream. It can come either from the -demultiplexer or from memory. The video_format indicates the aspect -ratio (one of 4:3 or 16:9) of the currently played video stream. -Finally, display_format corresponds to the selected cropping mode in -case the source video format is not the same as the format of the output -device. - - -.. c:type:: video_still_picture - -struct video_still_picture -========================== - -An I-frame displayed via the VIDEO_STILLPICTURE call is passed on -within the following structure. - - -.. code-block:: c - - /* pointer to and size of a single iframe in memory */ - struct video_still_picture { - char *iFrame; /* pointer to a single iframe in memory */ - int32_t size; - }; - - -.. _video_caps: - -video capabilities -================== - -A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the -following bits set according to the hardwares capabilities. - - -.. code-block:: c - - /* bit definitions for capabilities: */ - /* can the hardware decode MPEG1 and/or MPEG2? */ - #define VIDEO_CAP_MPEG1 1 - #define VIDEO_CAP_MPEG2 2 - /* can you send a system and/or program stream to video device? - (you still have to open the video and the audio device but only - send the stream to the video device) */ - #define VIDEO_CAP_SYS 4 - #define VIDEO_CAP_PROG 8 - /* can the driver also handle SPU, NAVI and CSS encoded data? - (CSS API is not present yet) */ - #define VIDEO_CAP_SPU 16 - #define VIDEO_CAP_NAVI 32 - #define VIDEO_CAP_CSS 64 diff --git a/Documentation/userspace-api/media/fdl-appendix.rst b/Documentation/userspace-api/media/fdl-appendix.rst index 70c8cda10814..b1bc725b4ec7 100644 --- a/Documentation/userspace-api/media/fdl-appendix.rst +++ b/Documentation/userspace-api/media/fdl-appendix.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _fdl: @@ -20,14 +13,14 @@ GNU Free Documentation License =========== The purpose of this License is to make a manual, textbook, or other -written document “free” in the sense of freedom: to assure everyone the +written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. -This License is a kind of “copyleft”, which means that derivative works +This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. @@ -51,21 +44,21 @@ works whose purpose is instruction or reference. This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the -terms of this License. The “Document”, below, refers to any such manual +terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as -“you”. +"you". .. _fdl-modified: -A “Modified Version” of the Document means any work containing the +A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. .. _fdl-secondary: -A “Secondary Section” is a named appendix or a front-matter section of +A "Secondary Section" is a named appendix or a front-matter section of the :ref:`Document <fdl-document>` that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing @@ -79,7 +72,7 @@ regarding them. .. _fdl-invariant: -The “Invariant Sections” are certain +The "Invariant Sections" are certain :ref:`Secondary Sections <fdl-secondary>` whose titles are designated, as being those of Invariant Sections, in the notice that says that the :ref:`Document <fdl-document>` is released under this License. @@ -87,14 +80,14 @@ as being those of Invariant Sections, in the notice that says that the .. _fdl-cover-texts: -The “Cover Texts” are certain short passages of text that are listed, as +The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the :ref:`Document <fdl-document>` is released under this License. .. _fdl-transparent: -A “Transparent” copy of the :ref:`Document <fdl-document>` means a +A "Transparent" copy of the :ref:`Document <fdl-document>` means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images @@ -104,7 +97,7 @@ formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is -not “Transparent” is called “Opaque”. +not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML @@ -118,10 +111,10 @@ word processors for output purposes only. .. _fdl-title-page: -The “Title Page” means, for a printed book, the title page itself, plus +The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which -do not have any title page as such, “Title Page” means the text near the +do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. @@ -249,11 +242,11 @@ Modified Version: Include an unaltered copy of this License. - **I.** - Preserve the section entitled “History”, and its title, and add to it + Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the :ref:`Modified Version <fdl-modified>` as given on the :ref:`Title Page <fdl-title-page>`. If there is no section entitled - “History” in the :ref:`Document <fdl-document>`, create one stating + "History" in the :ref:`Document <fdl-document>`, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. @@ -263,13 +256,13 @@ Modified Version: :ref:`Document <fdl-document>` for public access to a :ref:`Transparent <fdl-transparent>` copy of the Document, and likewise the network locations given in the Document for previous - versions it was based on. These may be placed in the “History” + versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. - **K.** - In any section entitled “Acknowledgements” or “Dedications”, preserve + In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. @@ -281,11 +274,11 @@ Modified Version: part of the section titles. - **M.** - Delete any section entitled “Endorsements”. Such a section may not be + Delete any section entitled "Endorsements". Such a section may not be included in the :ref:`Modified Version <fdl-modified>`. - **N.** - Do not retitle any existing section as “Endorsements” or to conflict + Do not retitle any existing section as "Endorsements" or to conflict in title with any :ref:`Invariant Section <fdl-invariant>`. If the :ref:`Modified Version <fdl-modified>` includes new @@ -297,7 +290,7 @@ of :ref:`Invariant Sections <fdl-invariant>` in the Modified Version's license notice. These titles must be distinct from any other section titles. -You may add a section entitled “Endorsements”, provided it contains +You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your :ref:`Modified Version <fdl-modified>` by various parties--for example, statements of peer review or that the text has been approved by @@ -344,11 +337,11 @@ the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. -In the combination, you must combine any sections entitled “History” in -the various original documents, forming one section entitled “History”; -likewise combine any sections entitled “Acknowledgements”, and any -sections entitled “Dedications”. You must delete all sections entitled -“Endorsements.” +In the combination, you must combine any sections entitled "History" in +the various original documents, forming one section entitled "History"; +likewise combine any sections entitled "Acknowledgements", and any +sections entitled "Dedications". You must delete all sections entitled +"Endorsements." .. _fdl-section6: @@ -379,7 +372,7 @@ with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a :ref:`Modified Version <fdl-modified>` of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation -is called an “aggregate”, and this License does not apply to the other +is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the :ref:`Cover Text <fdl-cover-texts>` @@ -436,7 +429,7 @@ concerns. See Each version of the License is given a distinguishing version number. If the :ref:`Document <fdl-document>` specifies that a particular -numbered version of this License “or any later version” applies to it, +numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not @@ -462,13 +455,13 @@ notices just after the title page: being LIST THEIR TITLES, with the :ref:`Front-Cover Texts <fdl-cover-texts>` being LIST, and with the :ref:`Back-Cover Texts <fdl-cover-texts>` being LIST. A copy - of the license is included in the section entitled “GNU Free - Documentation License”. + of the license is included in the section entitled "GNU Free + Documentation License". -If you have no :ref:`Invariant Sections <fdl-invariant>`, write “with -no Invariant Sections” instead of saying which ones are invariant. If -you have no :ref:`Front-Cover Texts <fdl-cover-texts>`, write “no -Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise +If you have no :ref:`Invariant Sections <fdl-invariant>`, write "with +no Invariant Sections" instead of saying which ones are invariant. If +you have no :ref:`Front-Cover Texts <fdl-cover-texts>`, write "no +Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for :ref:`Back-Cover Texts <fdl-cover-texts>`. If your document contains nontrivial examples of program code, we diff --git a/Documentation/userspace-api/media/frontend.h.rst.exceptions b/Documentation/userspace-api/media/frontend.h.rst.exceptions index 6283702c08c8..dcaf5740de7e 100644 --- a/Documentation/userspace-api/media/frontend.h.rst.exceptions +++ b/Documentation/userspace-api/media/frontend.h.rst.exceptions @@ -86,6 +86,13 @@ ignore symbol APSK_16 ignore symbol APSK_32 ignore symbol DQPSK ignore symbol QAM_4_NR +ignore symbol QAM_1024 +ignore symbol QAM_4096 +ignore symbol APSK_8_L +ignore symbol APSK_16_L +ignore symbol APSK_32_L +ignore symbol APSK_64 +ignore symbol APSK_64_L ignore symbol SEC_VOLTAGE_13 ignore symbol SEC_VOLTAGE_18 @@ -119,6 +126,26 @@ ignore symbol FEC_AUTO ignore symbol FEC_3_5 ignore symbol FEC_9_10 ignore symbol FEC_2_5 +ignore symbol FEC_1_3 +ignore symbol FEC_1_4 +ignore symbol FEC_5_9 +ignore symbol FEC_7_9 +ignore symbol FEC_8_15 +ignore symbol FEC_11_15 +ignore symbol FEC_13_18 +ignore symbol FEC_9_20 +ignore symbol FEC_11_20 +ignore symbol FEC_23_36 +ignore symbol FEC_25_36 +ignore symbol FEC_13_45 +ignore symbol FEC_26_45 +ignore symbol FEC_28_45 +ignore symbol FEC_32_45 +ignore symbol FEC_77_90 +ignore symbol FEC_11_45 +ignore symbol FEC_4_15 +ignore symbol FEC_14_45 +ignore symbol FEC_7_15 ignore symbol TRANSMISSION_MODE_AUTO ignore symbol TRANSMISSION_MODE_1K @@ -143,6 +170,7 @@ ignore symbol GUARD_INTERVAL_19_256 ignore symbol GUARD_INTERVAL_PN420 ignore symbol GUARD_INTERVAL_PN595 ignore symbol GUARD_INTERVAL_PN945 +ignore symbol GUARD_INTERVAL_1_64 ignore symbol HIERARCHY_NONE ignore symbol HIERARCHY_AUTO @@ -163,6 +191,9 @@ ignore symbol ROLLOFF_35 ignore symbol ROLLOFF_20 ignore symbol ROLLOFF_25 ignore symbol ROLLOFF_AUTO +ignore symbol ROLLOFF_15 +ignore symbol ROLLOFF_10 +ignore symbol ROLLOFF_5 ignore symbol INVERSION_ON ignore symbol INVERSION_OFF @@ -187,6 +218,7 @@ ignore symbol SYS_DAB ignore symbol SYS_DSS ignore symbol SYS_CMMB ignore symbol SYS_DVBH +ignore symbol SYS_DVBC2 ignore symbol ATSCMH_SCCC_BLK_SEP ignore symbol ATSCMH_SCCC_BLK_COMB diff --git a/Documentation/userspace-api/media/gen-errors.rst b/Documentation/userspace-api/media/gen-errors.rst index abae4dbed549..4e8defd3612b 100644 --- a/Documentation/userspace-api/media/gen-errors.rst +++ b/Documentation/userspace-api/media/gen-errors.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _gen_errors: @@ -66,9 +59,7 @@ Generic Error Codes - - ``ENOTTY`` - - The ioctl is not supported by the driver, actually meaning that - the required functionality is not available, or the file - descriptor is not for a media device. + - The ioctl is not supported by the file descriptor. - - ``ENOSPC`` diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst new file mode 100644 index 000000000000..96a360edbf3b --- /dev/null +++ b/Documentation/userspace-api/media/glossary.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +======== +Glossary +======== + +.. note:: + + The goal of this section is to standardize the terms used within the media + userspace API documentation. This is Work In Progress. + +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + + Bridge Driver + A :term:`Device Driver` that implements the main logic to talk with + media hardware. + + CEC API + **Consumer Electronics Control API** + + An API designed to receive and transmit data via an HDMI + CEC interface. + + See :ref:`cec`. + + Device Driver + Part of the Linux Kernel that implements support for a hardware + component. + + Device Node + A character device node in the file system used to control and + transfer data in and out of a Kernel driver. + + Digital TV API + **Previously known as DVB API** + + An API designed to control a subset of the :term:`Media Hardware` + that implements digital TV (e. g. DVB, ATSC, ISDB, etc). + + See :ref:`dvbapi`. + + DSP + **Digital Signal Processor** + + A specialized :term:`Microprocessor`, with its architecture + optimized for the operational needs of digital signal processing. + + FPGA + **Field-programmable Gate Array** + + An :term:`IC` circuit designed to be configured by a customer or + a designer after manufacturing. + + See https://en.wikipedia.org/wiki/Field-programmable_gate_array. + + Hardware Component + A subset of the :term:`Media Hardware`. For example an :term:`I²C` or + :term:`SPI` device, or an :term:`IP Block` inside an + :term:`SoC` or :term:`FPGA`. + + Hardware Peripheral + A group of :term:`hardware components <Hardware Component>` that + together make a larger user-facing functional peripheral. For + instance, the :term:`SoC` :term:`ISP` :term:`IP Block` + and the external camera sensors together make a camera hardware + peripheral. + + Also known as :term:`Peripheral`. + + I²C + **Inter-Integrated Circuit** + + A multi-master, multi-slave, packet switched, single-ended, + serial computer bus used to control some hardware components + like sub-device hardware components. + + See http://www.nxp.com/docs/en/user-guide/UM10204.pdf. + + IC + **Integrated circuit** + + A set of electronic circuits on one small flat piece of + semiconductor material, normally silicon. + + Also known as chip. + + IP Block + **Intellectual property core** + + In electronic design a semiconductor intellectual property core, + is a reusable unit of logic, cell, or integrated circuit layout + design that is the intellectual property of one party. + IP Blocks may be licensed to another party or can be owned + and used by a single party alone. + + See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core). + + ISP + **Image Signal Processor** + + A specialized processor that implements a set of algorithms for + processing image data. ISPs may implement algorithms for lens + shading correction, demosaicing, scaling and pixel format conversion + as well as produce statistics for the use of the control + algorithms (e.g. automatic exposure, white balance and focus). + + Media API + A set of userspace APIs used to control the media hardware. It is + composed by: + + - :term:`CEC API`; + - :term:`Digital TV API`; + - :term:`MC API`; + - :term:`RC API`; and + - :term:`V4L2 API`. + + See Documentation/userspace-api/media/index.rst. + + MC API + **Media Controller API** + + An API designed to expose and control the relationships between + multimedia devices and sub-devices. + + See :ref:`media_controller`. + + MC-centric + :term:`V4L2 Hardware` device driver that requires :term:`MC API`. + + Such drivers have ``V4L2_CAP_IO_MC`` device_caps field set + (see :ref:`VIDIOC_QUERYCAP`). + + See :ref:`v4l2_hardware_control` for more details. + + Media Hardware + Subset of the hardware that is supported by the Linux Media API. + + This includes audio and video capture and playback hardware, + digital and analog TV, camera sensors, ISPs, remote controllers, + codecs, HDMI Consumer Electronics Control, HDMI capture, etc. + + Microprocessor + Electronic circuitry that carries out the instructions of a + computer program by performing the basic arithmetic, logical, + control and input/output (I/O) operations specified by the + instructions on a single integrated circuit. + + Peripheral + The same as :term:`Hardware Peripheral`. + + RC API + **Remote Controller API** + + An API designed to receive and transmit data from remote + controllers. + + See :ref:`remote_controllers`. + + SMBus + A subset of I²C, which defines a stricter usage of the bus. + + SPI + **Serial Peripheral Interface Bus** + + Synchronous serial communication interface specification used for + short distance communication, primarily in embedded systems. + + SoC + **System on a Chip** + + An integrated circuit that integrates all components of a computer + or other electronic systems. + + V4L2 API + **V4L2 userspace API** + + The userspace API defined in :ref:`v4l2spec`, which is used to + control a V4L2 hardware. + + V4L2 Device Node + A :term:`Device Node` that is associated to a V4L driver. + + The V4L2 device node naming is specified at :ref:`v4l2_device_naming`. + + V4L2 Hardware + Part of the media hardware which is supported by the :term:`V4L2 API`. + + V4L2 Sub-device + V4L2 hardware components that aren't controlled by a + :term:`Bridge Driver`. See :ref:`subdev`. + + Video-node-centric + V4L2 device driver that doesn't require a media controller to be used. + + Such drivers have the ``V4L2_CAP_IO_MC`` device_caps field unset + (see :ref:`VIDIOC_QUERYCAP`). + + V4L2 Sub-device API + Part of the :term:`V4L2 API` which control + :term:`V4L2 sub-devices <V4L2 Sub-device>`, like sensors, + HDMI receivers, scalers, deinterlacers. + + See :ref:`v4l2_hardware_control` for more details. diff --git a/Documentation/userspace-api/media/index.rst b/Documentation/userspace-api/media/index.rst index 70a3f3d73698..337ef6c7c47f 100644 --- a/Documentation/userspace-api/media/index.rst +++ b/Documentation/userspace-api/media/index.rst @@ -11,21 +11,18 @@ used by media devices. Please see: -- :doc:`/admin-guide/media/index` - for usage information about media subsystem and supported drivers; +Documentation/admin-guide/media/index.rst -- :doc:`/driver-api/media/index` - for driver development information and Kernel APIs used by - media devices; + - for usage information about media subsystem and supported drivers; +Documentation/driver-api/media/index.rst -.. only:: html + - for driver development information and Kernel APIs used by + media devices; - .. class:: toc-title - - Table of Contents .. toctree:: + :caption: Table of Contents :maxdepth: 1 intro @@ -35,6 +32,9 @@ Please see: mediactl/media-controller cec/cec-api gen-errors + + glossary + fdl-appendix drivers/index diff --git a/Documentation/userspace-api/media/lirc.h.rst.exceptions b/Documentation/userspace-api/media/lirc.h.rst.exceptions index ac768d769113..1aeb7d7afe13 100644 --- a/Documentation/userspace-api/media/lirc.h.rst.exceptions +++ b/Documentation/userspace-api/media/lirc.h.rst.exceptions @@ -11,12 +11,14 @@ ignore define LIRC_SPACE ignore define LIRC_PULSE ignore define LIRC_FREQUENCY ignore define LIRC_TIMEOUT +ignore define LIRC_OVERFLOW ignore define LIRC_VALUE ignore define LIRC_MODE2 ignore define LIRC_IS_SPACE ignore define LIRC_IS_PULSE ignore define LIRC_IS_FREQUENCY ignore define LIRC_IS_TIMEOUT +ignore define LIRC_IS_OVERFLOW ignore define LIRC_MODE2SEND ignore define LIRC_SEND2MODE @@ -28,11 +30,13 @@ ignore define LIRC_CAN_REC ignore define LIRC_CAN_SEND_MASK ignore define LIRC_CAN_REC_MASK -ignore define LIRC_CAN_SET_REC_DUTY_CYCLE +ignore define LIRC_CAN_SET_REC_FILTER +ignore define LIRC_CAN_NOTIFY_DECODE # Obsolete ioctls ignore ioctl LIRC_GET_LENGTH +ignore ioctl LIRC_SET_REC_TIMEOUT_REPORTS # rc protocols @@ -64,6 +68,7 @@ ignore symbol RC_PROTO_RCMM12 ignore symbol RC_PROTO_RCMM24 ignore symbol RC_PROTO_RCMM32 ignore symbol RC_PROTO_XBOX_DVD +ignore symbol RC_PROTO_MAX # Undocumented macros @@ -72,6 +77,8 @@ ignore define PULSE_MASK ignore define LIRC_MODE2_SPACE ignore define LIRC_MODE2_PULSE +ignore define LIRC_MODE2_TIMEOUT +ignore define LIRC_MODE2_OVERFLOW ignore define LIRC_VALUE_MASK ignore define LIRC_MODE2_MASK diff --git a/Documentation/userspace-api/media/mediactl/media-controller-intro.rst b/Documentation/userspace-api/media/mediactl/media-controller-intro.rst index 1d06ea4c4d09..fce7eafc37c4 100644 --- a/Documentation/userspace-api/media/mediactl/media-controller-intro.rst +++ b/Documentation/userspace-api/media/mediactl/media-controller-intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _media-controller-intro: diff --git a/Documentation/userspace-api/media/mediactl/media-controller-model.rst b/Documentation/userspace-api/media/mediactl/media-controller-model.rst index 865e73d934d6..78bfdfb2a322 100644 --- a/Documentation/userspace-api/media/mediactl/media-controller-model.rst +++ b/Documentation/userspace-api/media/mediactl/media-controller-model.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _media-controller-model: @@ -40,3 +33,9 @@ are: - An **interface link** is a point-to-point bidirectional control connection between a Linux Kernel interface and an entity. + +- An **ancillary link** is a point-to-point connection denoting that two + entities form a single logical unit. For example this could represent the + fact that a particular camera sensor and lens controller form a single + physical module, meaning this lens controller drives the lens for this + camera sensor.
\ No newline at end of file diff --git a/Documentation/userspace-api/media/mediactl/media-controller.rst b/Documentation/userspace-api/media/mediactl/media-controller.rst index 16bc3ab180d3..73a87f82f92d 100644 --- a/Documentation/userspace-api/media/mediactl/media-controller.rst +++ b/Documentation/userspace-api/media/mediactl/media-controller.rst @@ -1,12 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. include:: <isonum.txt> .. _media_controller: @@ -15,13 +7,8 @@ Part IV - Media Controller API ############################## -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/mediactl/media-func-close.rst b/Documentation/userspace-api/media/mediactl/media-func-close.rst index ceec61c9e7c5..8ac2443e76c1 100644 --- a/Documentation/userspace-api/media/mediactl/media-func-close.rst +++ b/Documentation/userspace-api/media/mediactl/media-func-close.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media-func-close: @@ -18,7 +12,6 @@ Name media-close - Close a media device - Synopsis ======== @@ -26,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: mc-close Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <mc-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -43,11 +33,10 @@ Description Closes the media device. Resources associated with the file descriptor are freed. The device configuration remain unchanged. - Return Value ============ -:ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and +:c:func:`close()` returns 0 on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: EBADF diff --git a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst index 629e7be7c5be..9e9a838f4795 100644 --- a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst +++ b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media-func-ioctl: @@ -18,7 +12,6 @@ Name media-ioctl - Control a media device - Synopsis ======== @@ -26,15 +19,13 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: mc-ioctl +``int ioctl(int fd, int request, void *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`open() <mc-open>`. + File descriptor returned by :c:func:`open()`. ``request`` Media ioctl request code as defined in the media.h header file, for @@ -43,7 +34,6 @@ Arguments ``argp`` Pointer to a request-specific structure. - Description =========== @@ -59,7 +49,6 @@ their parameters are located in the media.h header file. All media ioctl requests, their respective function and parameters are specified in :ref:`media-user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-func-open.rst b/Documentation/userspace-api/media/mediactl/media-func-open.rst index 4ade1cc5048f..24487cb0a308 100644 --- a/Documentation/userspace-api/media/mediactl/media-func-open.rst +++ b/Documentation/userspace-api/media/mediactl/media-func-open.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media-func-open: @@ -18,7 +12,6 @@ Name media-open - Open a media device - Synopsis ======== @@ -26,9 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: mc-open Arguments ========= @@ -40,11 +31,10 @@ Arguments Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``. Other flags have no effect. - Description =========== -To open a media device applications call :ref:`open() <media-func-open>` with the +To open a media device applications call :c:func:`open()` with the desired device name. The function has no side effects; the device configuration remain unchanged. @@ -52,11 +42,10 @@ When the device is opened in read-only mode, attempts to modify its configuration will result in an error, and ``errno`` will be set to EBADF. - Return Value ============ -:ref:`open() <func-open>` returns the new file descriptor on success. On error, +:c:func:`open()` returns the new file descriptor on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/mediactl/media-funcs.rst b/Documentation/userspace-api/media/mediactl/media-funcs.rst index 085e80e7fbd5..e896296812c1 100644 --- a/Documentation/userspace-api/media/mediactl/media-funcs.rst +++ b/Documentation/userspace-api/media/mediactl/media-funcs.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _media-user-func: diff --git a/Documentation/userspace-api/media/mediactl/media-header.rst b/Documentation/userspace-api/media/mediactl/media-header.rst index 7ff9d24ce65f..c674271c93f5 100644 --- a/Documentation/userspace-api/media/mediactl/media-header.rst +++ b/Documentation/userspace-api/media/mediactl/media-header.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _media_header: diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst index 9c729bdc8e85..d56ee6669ab9 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_device_info: @@ -18,24 +12,22 @@ Name MEDIA_IOC_DEVICE_INFO - Query device information - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp ) - :name: MEDIA_IOC_DEVICE_INFO +.. c:macro:: MEDIA_IOC_DEVICE_INFO +``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_device_info`. - Description =========== @@ -45,17 +37,15 @@ a struct :c:type:`media_device_info`. The driver fills the structure and returns the information to the application. The ioctl never fails. - .. c:type:: media_device_info -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_device_info :header-rows: 0 :stub-columns: 0 :widths: 1 1 2 - * - char - ``driver``\ [16] - Name of the driver implementing the media API as a NUL-terminated @@ -101,7 +91,6 @@ ioctl never fails. - Reserved for future extensions. Drivers and applications must set this array to zero. - The ``serial`` and ``bus_info`` fields can be used to distinguish between multiple instances of otherwise identical hardware. The serial number takes precedence when provided and can be assumed to be unique. @@ -109,7 +98,6 @@ If the serial number is an empty string, the ``bus_info`` field can be used instead. The ``bus_info`` field is guaranteed to be unique, but can vary across reboots or device unplug/replug. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst index 1d01de8e0f97..73bda02498af 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_enum_entities: @@ -18,24 +12,22 @@ Name MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp ) - :name: MEDIA_IOC_ENUM_ENTITIES +.. c:macro:: MEDIA_IOC_ENUM_ENTITIES +``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_entity_desc`. - Description =========== @@ -56,10 +48,9 @@ Entity IDs can be non-contiguous. Applications must *not* try to enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error. - .. c:type:: media_entity_desc -.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| +.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{10.6cm}| .. flat-table:: struct media_entity_desc :header-rows: 0 @@ -143,7 +134,6 @@ id's until they get an error. * - } - - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst index 9929b639db97..381804a91c99 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_enum_links: @@ -18,24 +12,22 @@ Name MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp ) - :name: MEDIA_IOC_ENUM_LINKS +.. c:macro:: MEDIA_IOC_ENUM_LINKS +``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_links_enum`. - Description =========== @@ -60,10 +52,9 @@ outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`. Only forward links that originate at one of the entity's source pads are returned during the enumeration process. - .. c:type:: media_links_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_links_enum :header-rows: 0 @@ -89,10 +80,9 @@ returned during the enumeration process. - Reserved for future extensions. Drivers and applications must set the array to zero. - .. c:type:: media_pad_desc -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_pad_desc :header-rows: 0 @@ -117,10 +107,9 @@ returned during the enumeration process. the array to zero. - .. c:type:: media_link_desc -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_link_desc :header-rows: 0 @@ -144,7 +133,6 @@ returned during the enumeration process. - Reserved for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst index 54e3112a3b5a..77ea5c5e9d7f 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_g_topology: @@ -18,24 +12,22 @@ Name MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp ) - :name: MEDIA_IOC_G_TOPOLOGY +.. c:macro:: MEDIA_IOC_G_TOPOLOGY +``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_v2_topology`. - Description =========== @@ -54,7 +46,7 @@ other values untouched. If the ``topology_version`` remains the same, the ioctl should fill the desired arrays with the media graph elements. -.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.5cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.3cm}| .. c:type:: media_v2_topology @@ -127,8 +119,7 @@ desired arrays with the media graph elements. converted to a 64-bits integer. It can be zero. if zero, the ioctl won't store the links. It will just update ``num_links`` - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_entity @@ -165,8 +156,7 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_interface @@ -199,8 +189,7 @@ desired arrays with the media graph elements. - Used only for device node interfaces. See :c:type:`media_v2_intf_devnode` for details. - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_intf_devnode @@ -217,7 +206,7 @@ desired arrays with the media graph elements. - ``minor`` - Device node minor number. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_pad @@ -252,8 +241,7 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_link @@ -289,7 +277,6 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst index 82f86466c7f2..9195b4b8bf20 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst @@ -1,28 +1,5 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_request_alloc: @@ -35,24 +12,22 @@ Name MEDIA_IOC_REQUEST_ALLOC - Allocate a request - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp ) - :name: MEDIA_IOC_REQUEST_ALLOC +.. c:macro:: MEDIA_IOC_REQUEST_ALLOC +``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer. - Description =========== @@ -75,7 +50,7 @@ Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait for the request to complete. The request will remain allocated until all the file descriptors associated -with it are closed by :ref:`close() <request-func-close>` and the driver no +with it are closed by :c:func:`close()` and the driver no longer uses the request internally. See also :ref:`here <media-request-life-time>` for more information. diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst index 7da3d0028285..23208300cb61 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_ioc_setup_link: @@ -18,24 +12,22 @@ Name MEDIA_IOC_SETUP_LINK - Modify the properties of a link - Synopsis ======== -.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp ) - :name: MEDIA_IOC_SETUP_LINK +.. c:macro:: MEDIA_IOC_SETUP_LINK +``int ioctl(int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <media-func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`media_link_desc`. - Description =========== @@ -60,7 +52,6 @@ non-dynamic link will return an ``EBUSY`` error code. If the specified link can't be found the driver returns with an ``EINVAL`` error code. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst index ad55b6b32616..04b33db2bb45 100644 --- a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst +++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst @@ -1,28 +1,5 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_request_ioc_queue: @@ -35,13 +12,12 @@ Name MEDIA_REQUEST_IOC_QUEUE - Queue a request - Synopsis ======== -.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) - :name: MEDIA_REQUEST_IOC_QUEUE +.. c:macro:: MEDIA_REQUEST_IOC_QUEUE +``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)`` Arguments ========= @@ -49,7 +25,6 @@ Arguments ``request_fd`` File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - Description =========== diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst index 4c43fa05c8f6..57567b87b985 100644 --- a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst +++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst @@ -1,28 +1,5 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media_request_ioc_reinit: @@ -35,13 +12,12 @@ Name MEDIA_REQUEST_IOC_REINIT - Re-initialize a request - Synopsis ======== -.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT ) - :name: MEDIA_REQUEST_IOC_REINIT +.. c:macro:: MEDIA_REQUEST_IOC_REINIT +``int ioctl(int request_fd, MEDIA_REQUEST_IOC_REINIT)`` Arguments ========= @@ -57,7 +33,7 @@ this request ioctl can be used to re-initialize a previously allocated request. Re-initializing a request will clear any existing data from the request. -This avoids having to :ref:`close() <request-func-close>` a completed +This avoids having to :c:func:`close()` a completed request and allocate a new request. Instead the completed request can just be re-initialized and it is ready to be used again. diff --git a/Documentation/userspace-api/media/mediactl/media-types.rst b/Documentation/userspace-api/media/mediactl/media-types.rst index 77fd4c0c9ebc..6332e8395263 100644 --- a/Documentation/userspace-api/media/mediactl/media-types.rst +++ b/Documentation/userspace-api/media/mediactl/media-types.rst @@ -1,18 +1,11 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _media-controller-types: Types and flags used to represent the media graph elements ========================================================== -.. tabularcolumns:: |p{8.2cm}|p{10.3cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. _media-entity-functions: .. _MEDIA-ENT-F-UNKNOWN: @@ -46,6 +39,7 @@ Types and flags used to represent the media graph elements .. _MEDIA-ENT-F-PROC-VIDEO-STATISTICS: .. _MEDIA-ENT-F-PROC-VIDEO-ENCODER: .. _MEDIA-ENT-F-PROC-VIDEO-DECODER: +.. _MEDIA-ENT-F-PROC-VIDEO-ISP: .. _MEDIA-ENT-F-VID-MUX: .. _MEDIA-ENT-F-VID-IF-BRIDGE: .. _MEDIA-ENT-F-DV-DECODER: @@ -208,6 +202,12 @@ Types and flags used to represent the media graph elements decompressing a compressed video stream into uncompressed video frames. Must have one sink pad and at least one source pad. + * - ``MEDIA_ENT_F_PROC_VIDEO_ISP`` + - An Image Signal Processor (ISP) device. ISPs generally are one of a + kind devices that have their specific control interfaces using a + combination of custom V4L2 controls and IOCTLs, and parameters + supplied in a metadata buffer. + * - ``MEDIA_ENT_F_VID_MUX`` - Video multiplexer. An entity capable of multiplexing must have at least two sink pads and one source pad, and must pass the video @@ -251,7 +251,7 @@ Types and flags used to represent the media graph elements - The entity represents a connector. -.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}| +.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{4.8cm}| .. _media-intf-type: .. _MEDIA-INTF-T-DVB-FE: @@ -375,12 +375,11 @@ Types and flags used to represent the media graph elements are origins of links. * - ``MEDIA_PAD_FL_MUST_CONNECT`` - - If this flag is set and the pad is linked to any other pad, then - at least one of those links must be enabled for the entity to be - able to stream. There could be temporary reasons (e.g. device - configuration dependent) for the pad to need enabled links even - when this flag isn't set; the absence of the flag doesn't imply - there is none. + - If this flag is set, then for this pad to be able to stream, it must + be connected by at least one enabled link. There could be temporary + reasons (e.g. device configuration dependent) for the pad to need + enabled links even when this flag isn't set; the absence of the flag + doesn't imply there is none. One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE`` @@ -412,14 +411,21 @@ must be set for every pad. is set by drivers and is read-only for applications. * - ``MEDIA_LNK_FL_LINK_TYPE`` - - This is a bitmask that defines the type of the link. Currently, - two types of links are supported: + - This is a bitmask that defines the type of the link. The following + link types are currently supported: .. _MEDIA-LNK-FL-DATA-LINK: - ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads + ``MEDIA_LNK_FL_DATA_LINK`` for links that represent a data connection + between two pads. .. _MEDIA-LNK-FL-INTERFACE-LINK: - ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an - interface and an entity + ``MEDIA_LNK_FL_INTERFACE_LINK`` for links that associate an entity to its + interface. + + .. _MEDIA-LNK-FL-ANCILLARY-LINK: + + ``MEDIA_LNK_FL_ANCILLARY_LINK`` for links that represent a physical + relationship between two entities. The link may or may not be + immutable, so applications must not assume either case. diff --git a/Documentation/userspace-api/media/mediactl/request-api.rst b/Documentation/userspace-api/media/mediactl/request-api.rst index 37d9442a541e..6c4cbd9f08a5 100644 --- a/Documentation/userspace-api/media/mediactl/request-api.rst +++ b/Documentation/userspace-api/media/mediactl/request-api.rst @@ -1,28 +1,5 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _media-request-api: @@ -117,7 +94,7 @@ regardless of whether a request is in use or not. Setting the same control through a request and also directly can lead to undefined behavior! -User-space can :ref:`poll() <request-func-poll>` a request file descriptor in +User-space can :c:func:`poll()` a request file descriptor in order to wait until the request completes. A request is considered complete once all its associated buffers are available for dequeuing and all the associated controls have been updated with the values at the time of completion. @@ -139,7 +116,7 @@ Recycling and Destruction ------------------------- Finally, a completed request can either be discarded or be reused. Calling -:ref:`close() <request-func-close>` on a request file descriptor will make +:c:func:`close()` on a request file descriptor will make that file descriptor unusable and the request will be freed once it is no longer in use by the kernel. That is, if the request is queued and then the file descriptor is closed, then it won't be freed until the driver completed diff --git a/Documentation/userspace-api/media/mediactl/request-func-close.rst b/Documentation/userspace-api/media/mediactl/request-func-close.rst index 9618b5139764..f4b8eb385ad7 100644 --- a/Documentation/userspace-api/media/mediactl/request-func-close.rst +++ b/Documentation/userspace-api/media/mediactl/request-func-close.rst @@ -1,28 +1,5 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC.request .. _request-func-close: @@ -35,7 +12,6 @@ Name request-close - Close a request file descriptor - Synopsis ======== @@ -43,9 +19,7 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: req-close Arguments ========= @@ -53,7 +27,6 @@ Arguments ``fd`` File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - Description =========== @@ -62,11 +35,10 @@ are freed once all file descriptors associated with the request are closed and the driver has completed the request. See :ref:`here <media-request-life-time>` for more information. - Return Value ============ -:ref:`close() <request-func-close>` returns 0 on success. On error, -1 is +:c:func:`close()` returns 0 on success. On error, -1 is returned, and ``errno`` is set appropriately. Possible error codes are: EBADF diff --git a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst index 4bf985205bcc..4fb3d2ef32d1 100644 --- a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst +++ b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst @@ -1,28 +1,5 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _request-func-ioctl: @@ -35,7 +12,6 @@ Name request-ioctl - Control a request file descriptor - Synopsis ======== @@ -43,9 +19,7 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int cmd, void *argp ) - :name: req-ioctl +``int ioctl(int fd, int cmd, void *argp)`` Arguments ========= @@ -60,7 +34,6 @@ Arguments ``argp`` Pointer to a request-specific structure. - Description =========== @@ -76,7 +49,6 @@ their parameters are located in the media.h header file. All request ioctl commands, their respective function and parameters are specified in :ref:`media-user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/mediactl/request-func-poll.rst b/Documentation/userspace-api/media/mediactl/request-func-poll.rst index 85a3427e5913..ce0043dbe7da 100644 --- a/Documentation/userspace-api/media/mediactl/request-func-poll.rst +++ b/Documentation/userspace-api/media/mediactl/request-func-poll.rst @@ -1,28 +1,5 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC .. _request-func-poll: @@ -35,7 +12,6 @@ Name request-poll - Wait for some event on a file descriptor - Synopsis ======== @@ -43,9 +19,7 @@ Synopsis #include <sys/poll.h> - .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: request-poll Arguments ========= @@ -59,14 +33,13 @@ Arguments ``timeout`` Timeout to wait for events - Description =========== -With the :c:func:`poll() <request-func-poll>` function applications can wait +With the :c:func:`poll()` function applications can wait for a request to complete. -On success :c:func:`poll() <request-func-poll>` returns the number of file +On success :c:func:`poll()` returns the number of file descriptors that have been selected (that is, file descriptors for which the ``revents`` field of the respective struct :c:type:`pollfd` is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents`` @@ -77,11 +50,10 @@ set appropriately. Attempting to poll for a request that is not yet queued will set the ``POLLERR`` flag in ``revents``. - Return Value ============ -On success, :c:func:`poll() <request-func-poll>` returns the number of +On success, :c:func:`poll()` returns the number of structures which have non-zero ``revents`` fields, or zero if the call timed out. On error -1 is returned, and the ``errno`` variable is set appropriately: diff --git a/Documentation/userspace-api/media/rc/keytable.c.rst b/Documentation/userspace-api/media/rc/keytable.c.rst index 901d33d37843..243e02d2611f 100644 --- a/Documentation/userspace-api/media/rc/keytable.c.rst +++ b/Documentation/userspace-api/media/rc/keytable.c.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later file: uapi/v4l/keytable.c ========================= diff --git a/Documentation/userspace-api/media/rc/lirc-dev-intro.rst b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst index 0c3d70ded55d..d899331b943f 100644 --- a/Documentation/userspace-api/media/rc/lirc-dev-intro.rst +++ b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_dev_intro: @@ -64,12 +57,12 @@ on the following table. This mode is for both sending and receiving IR. - For transmitting (aka sending), create a ``struct lirc_scancode`` with + For transmitting (aka sending), create a struct lirc_scancode with the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other members set to 0. Write this struct to the lirc device. - For receiving, you read ``struct lirc_scancode`` from the LIRC device. + For receiving, you read struct lirc_scancode from the LIRC device. The ``scancode`` field is set to the received scancode and the :ref:`IR protocol <Remote_controllers_Protocols>` is set in :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set @@ -110,11 +103,11 @@ on the following table. ``LIRC_MODE2_PULSE`` - Signifies the presence of IR in microseconds. + Signifies the presence of IR in microseconds, also known as *flash*. ``LIRC_MODE2_SPACE`` - Signifies absence of IR in microseconds. + Signifies absence of IR in microseconds, also known as *gap*. ``LIRC_MODE2_FREQUENCY`` @@ -124,11 +117,16 @@ on the following table. ``LIRC_MODE2_TIMEOUT`` - If timeout reports are enabled with - :ref:`lirc_set_rec_timeout_reports`, when the timeout set with - :ref:`lirc_set_rec_timeout` expires due to no IR being detected, - this packet will be sent, with the number of microseconds with - no IR. + When the timeout set with :ref:`lirc_set_rec_timeout` expires due + to no IR being detected, this packet will be sent, with the number + of microseconds with no IR. + + ``LIRC_MODE2_OVERFLOW`` + + Signifies that the IR receiver encounter an overflow, and some IR + is missing. The IR data after this should be correct again. The + actual value is not important, but this is set to 0xffffff by the + kernel for compatibility with lircd. .. _lirc-mode-pulse: @@ -143,6 +141,13 @@ on the following table. This mode is used only for IR send. +************************************* +Data types used by LIRC_MODE_SCANCODE +************************************* + +.. kernel-doc:: include/uapi/linux/lirc.h + :identifiers: lirc_scancode rc_proto + ******************** BPF based IR decoder ******************** diff --git a/Documentation/userspace-api/media/rc/lirc-dev.rst b/Documentation/userspace-api/media/rc/lirc-dev.rst index 7a395fa52934..978f86d30fae 100644 --- a/Documentation/userspace-api/media/rc/lirc-dev.rst +++ b/Documentation/userspace-api/media/rc/lirc-dev.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_dev: diff --git a/Documentation/userspace-api/media/rc/lirc-func.rst b/Documentation/userspace-api/media/rc/lirc-func.rst index e37c99583212..5c84888f1eca 100644 --- a/Documentation/userspace-api/media/rc/lirc-func.rst +++ b/Documentation/userspace-api/media/rc/lirc-func.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_func: @@ -29,6 +22,5 @@ LIRC Function Reference lirc-set-rec-carrier-range lirc-set-send-carrier lirc-set-transmitter-mask - lirc-set-rec-timeout-reports lirc-set-measure-carrier-mode lirc-set-wideband-receiver diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst index f4b9ca09f828..545137620ead 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-features.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_features: @@ -21,8 +15,9 @@ LIRC_GET_FEATURES - Get the underlying hardware device's features Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_FEATURES, __u32 *features) - :name: LIRC_GET_FEATURES +.. c:macro:: LIRC_GET_FEATURES + +``int ioctl(int fd, LIRC_GET_FEATURES, __u32 *features)`` Arguments ========= @@ -33,11 +28,9 @@ Arguments ``features`` Bitmask with the LIRC features. - Description =========== - Get the underlying hardware device's features. If a driver does not announce support of certain features, calling of the corresponding ioctls is undefined. @@ -109,12 +102,6 @@ LIRC features The driver supports setting the receive carrier frequency using :ref:`ioctl LIRC_SET_REC_CARRIER <LIRC_SET_REC_CARRIER>`. -.. _LIRC-CAN-SET-REC-DUTY-CYCLE-RANGE: - -``LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE`` - - Unused. Kept just to avoid breaking uAPI. - .. _LIRC-CAN-SET-REC-CARRIER-RANGE: ``LIRC_CAN_SET_REC_CARRIER_RANGE`` @@ -136,12 +123,6 @@ LIRC features The driver supports :ref:`ioctl LIRC_SET_REC_TIMEOUT <LIRC_SET_REC_TIMEOUT>`. -.. _LIRC-CAN-SET-REC-FILTER: - -``LIRC_CAN_SET_REC_FILTER`` - - Unused. Kept just to avoid breaking uAPI. - .. _LIRC-CAN-MEASURE-CARRIER: ``LIRC_CAN_MEASURE_CARRIER`` @@ -156,12 +137,6 @@ LIRC features The driver supports learning mode using :ref:`ioctl LIRC_SET_WIDEBAND_RECEIVER <LIRC_SET_WIDEBAND_RECEIVER>`. -.. _LIRC-CAN-NOTIFY-DECODE: - -``LIRC_CAN_NOTIFY_DECODE`` - - Unused. Kept just to avoid breaking uAPI. - .. _LIRC-CAN-SEND-RAW: ``LIRC_CAN_SEND_RAW`` @@ -191,7 +166,6 @@ LIRC features Unused. Kept just to avoid breaking uAPI. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst index 674ce16d5d33..628fe31792b2 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_rec_mode: .. _lirc_set_rec_mode: @@ -22,11 +16,13 @@ LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode) - :name: LIRC_GET_REC_MODE +.. c:macro:: LIRC_GET_REC_MODE -.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode) - :name: LIRC_SET_REC_MODE +``int ioctl(int fd, LIRC_GET_REC_MODE, __u32 *mode)`` + +.. c:macro:: LIRC_SET_REC_MODE + +``int ioctl(int fd, LIRC_SET_REC_MODE, __u32 *mode)`` Arguments ========= @@ -54,7 +50,6 @@ Return Value :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``ENODEV`` diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst index f20b5bf41232..4dfa9c23634b 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_rec_resolution: @@ -21,8 +15,9 @@ LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microsecond Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds) - :name: LIRC_GET_REC_RESOLUTION +.. c:macro:: LIRC_GET_REC_RESOLUTION + +``int ioctl(int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)`` Arguments ========= @@ -33,7 +28,6 @@ Arguments ``microseconds`` Resolution, in microseconds. - Description =========== @@ -45,7 +39,6 @@ This ioctl returns the integer value with such resolution, with can be used by userspace applications like lircd to automatically adjust the tolerance value. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst index 973a47bf6068..637871805be6 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_send_mode: .. _lirc_set_send_mode: @@ -22,11 +16,13 @@ LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode ) - :name: LIRC_GET_SEND_MODE +.. c:macro:: LIRC_GET_SEND_MODE -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode ) - :name: LIRC_SET_SEND_MODE +``int ioctl(int fd, LIRC_GET_SEND_MODE, __u32 *mode)`` + +.. c:macro:: LIRC_SET_SEND_MODE + +``int ioctl(int fd, LIRC_SET_SEND_MODE, __u32 *mode)`` Arguments ========= @@ -37,7 +33,6 @@ Arguments ``mode`` The mode used for transmitting. - Description =========== @@ -51,14 +46,12 @@ modes the driver supports. Return Value ============ - .. tabularcolumns:: |p{2.5cm}|p{15.0cm}| .. flat-table:: :header-rows: 0 :stub-columns: 0 - - .. row 1 - ``ENODEV`` diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst index 5db84096d7f8..597c3282ae12 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_get_min_timeout: .. _lirc_get_max_timeout: @@ -23,11 +17,13 @@ range for IR receive. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout) - :name: LIRC_GET_MIN_TIMEOUT +.. c:macro:: LIRC_GET_MIN_TIMEOUT -.. c:function:: int ioctl( int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout) - :name: LIRC_GET_MAX_TIMEOUT +``int ioctl(int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)`` + +.. c:macro:: LIRC_GET_MAX_TIMEOUT + +``int ioctl(int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)`` Arguments ========= @@ -38,7 +34,6 @@ Arguments ``timeout`` Timeout, in microseconds. - Description =========== @@ -54,7 +49,6 @@ that can be set. both ioctls will return the same value even though the timeout cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-header.rst b/Documentation/userspace-api/media/rc/lirc-header.rst index c7e0716da159..54cb40b8a065 100644 --- a/Documentation/userspace-api/media/rc/lirc-header.rst +++ b/Documentation/userspace-api/media/rc/lirc-header.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_header: diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst index 13f7f5353851..ce34318698b7 100644 --- a/Documentation/userspace-api/media/rc/lirc-read.rst +++ b/Documentation/userspace-api/media/rc/lirc-read.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc-read: @@ -18,7 +12,6 @@ Name lirc-read - Read from a LIRC device - Synopsis ======== @@ -26,10 +19,7 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t read( int fd, void *buf, size_t count ) - :name: lirc-read - Arguments ========= @@ -46,9 +36,9 @@ Arguments Description =========== -:ref:`read() <lirc-read>` attempts to read up to ``count`` bytes from file +:c:func:`read()` attempts to read up to ``count`` bytes from file descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, -:ref:`read() <lirc-read>` returns zero and has no other results. If ``count`` +:c:func:`read()` returns zero and has no other results. If ``count`` is greater than ``SSIZE_MAX``, the result is unspecified. The exact format of the data depends on what :ref:`lirc_modes` a driver @@ -66,7 +56,6 @@ by hardware decoders. The :c:type:`rc_proto` member is set to the used for transmission, and ``scancode`` to the decoded scancode, and the ``keycode`` set to the keycode or ``KEY_RESERVED``. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst index 4cf9472eb904..04ced1aa664b 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_measure_carrier_mode: @@ -21,8 +15,9 @@ LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable ) - :name: LIRC_SET_MEASURE_CARRIER_MODE +.. c:macro:: LIRC_SET_MEASURE_CARRIER_MODE + +``int ioctl(int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable)`` Arguments ========= @@ -34,7 +29,6 @@ Arguments enable = 1 means enable measure mode, enable = 0 means disable measure mode. - Description =========== @@ -44,7 +38,6 @@ Enable or disable measure mode. If enabled, from the next key press on, the driver will send ``LIRC_MODE2_FREQUENCY`` packets. By default this should be turned off. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst index 0439e93aa267..7512dc86b03a 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_rec_carrier_range: @@ -22,8 +16,9 @@ IR receive. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency ) - :name: LIRC_SET_REC_CARRIER_RANGE +.. c:macro:: LIRC_SET_REC_CARRIER_RANGE + +``int ioctl(int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency)`` Arguments ========= diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst index f4d18897cb9f..60e321446ea7 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_rec_carrier: @@ -18,12 +12,12 @@ Name LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive. - Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER, __u32 *frequency ) - :name: LIRC_SET_REC_CARRIER +.. c:macro:: LIRC_SET_REC_CARRIER + +``int ioctl(int fd, LIRC_SET_REC_CARRIER, __u32 *frequency)`` Arguments ========= @@ -44,7 +38,6 @@ Set receive carrier used to modulate IR PWM pulses and spaces. If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl sets the upper bound frequency that will be recognized by the device. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst deleted file mode 100644 index ab97f87fa757..000000000000 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_timeout_reports: - -********************************** -ioctl LIRC_SET_REC_TIMEOUT_REPORTS -********************************** - -Name -==== - -LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable ) - :name: LIRC_SET_REC_TIMEOUT_REPORTS - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``enable`` - enable = 1 means enable timeout report, enable = 0 means disable timeout - reports. - - -Description -=========== - -.. _lirc-mode2-timeout: - -Enable or disable timeout reports for IR receive. By default, timeout reports -should be turned off. - -.. note:: - - This ioctl is only valid for :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst index 227776cf7c62..bf9fb2cc61c3 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_rec_timeout: .. _lirc_get_rec_timeout: @@ -22,11 +16,13 @@ LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR ina Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout ) - :name: LIRC_GET_REC_TIMEOUT +.. c:macro:: LIRC_GET_REC_TIMEOUT -.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout ) - :name: LIRC_SET_REC_TIMEOUT +``int ioctl(int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout)`` + +.. c:macro:: LIRC_SET_REC_TIMEOUT + +``int ioctl(int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout)`` Arguments ========= @@ -37,7 +33,6 @@ Arguments ``timeout`` Timeout, in microseconds. - Description =========== @@ -52,7 +47,6 @@ given value should be set. The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst index 7eaf2b993207..a003f9447553 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_send_carrier: @@ -18,12 +12,12 @@ Name LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX. - Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency ) - :name: LIRC_SET_SEND_CARRIER +.. c:macro:: LIRC_SET_SEND_CARRIER + +``int ioctl(int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency)`` Arguments ========= @@ -39,7 +33,6 @@ Description Set send carrier used to modulate IR PWM pulses and spaces. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst index 0dee89364cde..2979752acbcd 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_send_duty_cycle: @@ -22,8 +16,9 @@ IR transmit. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle) - :name: LIRC_SET_SEND_DUTY_CYCLE +.. c:macro:: LIRC_SET_SEND_DUTY_CYCLE + +``int ioctl(int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)`` Arguments ========= @@ -35,7 +30,6 @@ Arguments Duty cicle, describing the pulse width in percent (from 1 to 99) of the total cycle. Values 0 and 100 are reserved. - Description =========== @@ -45,7 +39,6 @@ Currently, no special meaning is defined for 0 or 100, but this could be used to switch off carrier generation in the future, so these values should be reserved. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst index dcee4b71dcf6..38acbcd6e91c 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_transmitter_mask: @@ -21,8 +15,9 @@ LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask ) - :name: LIRC_SET_TRANSMITTER_MASK +.. c:macro:: LIRC_SET_TRANSMITTER_MASK + +``int ioctl(int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask)`` Arguments ========= @@ -33,7 +28,6 @@ Arguments ``mask`` Mask with channels to enable tx. Channel 0 is the least significant bit. - Description =========== @@ -49,7 +43,6 @@ When an invalid bit mask is given, i.e. a bit is set, even though the device does not have so many transitters, then this ioctl returns the number of available transitters and does nothing otherwise. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst index 22f6fe43b7e7..5ae8fac8ed4f 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc_set_wideband_receiver: @@ -21,8 +15,9 @@ LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable ) - :name: LIRC_SET_WIDEBAND_RECEIVER +.. c:macro:: LIRC_SET_WIDEBAND_RECEIVER + +``int ioctl(int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable)`` Arguments ========= @@ -34,7 +29,6 @@ Arguments enable = 1 means enable wideband receiver, enable = 0 means disable wideband receiver. - Description =========== @@ -49,12 +43,11 @@ reduced range of reception. .. note:: - Wide band receiver might be implictly enabled if you enable + Wide band receiver might be implicitly 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. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst index 96ca4a22062e..970a8b3fa1ca 100644 --- a/Documentation/userspace-api/media/rc/lirc-write.rst +++ b/Documentation/userspace-api/media/rc/lirc-write.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC .. _lirc-write: @@ -18,7 +12,6 @@ Name lirc-write - Write to a LIRC device - Synopsis ======== @@ -26,9 +19,7 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t write( int fd, void *buf, size_t count ) - :name: lirc-write Arguments ========= @@ -45,7 +36,7 @@ Arguments Description =========== -:ref:`write() <lirc-write>` writes up to ``count`` bytes to the device +:c:func:`write()` writes up to ``count`` bytes to the device referenced by the file descriptor ``fd`` from the buffer starting at ``buf``. @@ -71,7 +62,6 @@ for the protocol or the scancode is not valid for the specified protocol, ``EINVAL`` is returned. The write function blocks until the scancode is transmitted by the hardware. - Return Value ============ diff --git a/Documentation/userspace-api/media/rc/rc-intro.rst b/Documentation/userspace-api/media/rc/rc-intro.rst index 14e85157bf23..2ba62cde2369 100644 --- a/Documentation/userspace-api/media/rc/rc-intro.rst +++ b/Documentation/userspace-api/media/rc/rc-intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_Intro: diff --git a/Documentation/userspace-api/media/rc/rc-protos.rst b/Documentation/userspace-api/media/rc/rc-protos.rst index b250ebe301d5..2a888ff5829f 100644 --- a/Documentation/userspace-api/media/rc/rc-protos.rst +++ b/Documentation/userspace-api/media/rc/rc-protos.rst @@ -1,6 +1,4 @@ -.. SPDX-License-Identifier: GPL-2.0 -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_Protocols: @@ -77,7 +75,7 @@ protocol, or the manchester BPF decoder. - Command There is a variant of rc5 called either rc5x or extended rc5 -where there the second stop bit is the 6th commmand bit, but inverted. +where there the second stop bit is the 6th command bit, but inverted. This is done so it the scancodes and encoding is compatible with existing schemes. This bit is stored in bit 6 of the scancode, inverted. This is done to keep it compatible with plain rc-5 where there are two start bits. diff --git a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst index 73dd75f77d65..34d6a0a1f4d3 100644 --- a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst +++ b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _remote_controllers_sysfs_nodes: diff --git a/Documentation/userspace-api/media/rc/rc-table-change.rst b/Documentation/userspace-api/media/rc/rc-table-change.rst index f5d00a20b939..d7de8a56ddfe 100644 --- a/Documentation/userspace-api/media/rc/rc-table-change.rst +++ b/Documentation/userspace-api/media/rc/rc-table-change.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_table_change: diff --git a/Documentation/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst index 33b724b17ff3..aab99260fef5 100644 --- a/Documentation/userspace-api/media/rc/rc-tables.rst +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_tables: @@ -32,7 +25,7 @@ the remote via /dev/input/event devices. .. _rc_standard_keymap: -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: IR default keymapping :header-rows: 0 @@ -635,7 +628,7 @@ the remote via /dev/input/event devices. - Put device into zoom/full screen mode - - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH + - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANEL / SWITCH - .. row 80 diff --git a/Documentation/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst index 3ab2d6db1564..483f9ae92a90 100644 --- a/Documentation/userspace-api/media/rc/remote_controllers.rst +++ b/Documentation/userspace-api/media/rc/remote_controllers.rst @@ -1,12 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. include:: <isonum.txt> .. _remote_controllers: @@ -15,13 +7,8 @@ Part III - Remote Controller API ################################ -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/typical_media_device.svg b/Documentation/userspace-api/media/typical_media_device.svg index 3420341ff7b6..fca7af8e438b 100644 --- a/Documentation/userspace-api/media/typical_media_device.svg +++ b/Documentation/userspace-api/media/typical_media_device.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg id="svg2" width="235mm" height="179mm" clip-path="url(#a)" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 22648.239 17899.829" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><metadata id="metadata1533"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><defs id="defs4"><clipPath id="a"><rect id="rect7" width="28000" height="21000"/></clipPath></defs><path id="path11" d="m10146 2636c-518.06 0-1035.1 515-1035.1 1031v4124c0 516 517.06 1032 1035.1 1032h8572.2c518.06 0 1036.1-516 1036.1-1032v-4124c0-516-518.06-1031-1036.1-1031h-8572.2z" fill="#fcf" style=""/><path id="path15" d="m1505.5 13443c-293 0-585 292-585 585v2340c0 293 292 586 585 586h3275c293 0 586-293 586-586v-2340c0-293-293-585-586-585h-3275z" fill="#ffc" style=""/><path id="path19" d="m517.15 22.013c-461 0-922 461-922 922v11169c0 461 461 923 922 923h3692c461 0 922-462 922-923v-11169c0-461-461-922-922-922h-3692z" fill="#e6e6e6" style=""/><path id="path23" d="m2371.5 6438h-2260v-1086h4520v1086h-2260z" fill="#ff8080" style=""/><path id="path25" d="m2371.5 6438h-2260v-1086h4520v1086h-2260z" fill="none" stroke="#3465af" style=""/><text id="text27" class="TextShape" x="-2089.4541" y="-2163.9871" font-family="Serif, serif" font-size="493.88px"><tspan id="tspan29" class="TextParagraph" font-family="Serif, serif" font-size="493.88px"><tspan id="tspan31" class="TextPosition" x="489.5459" y="6111.0132" font-family="Serif, serif" font-size="493.88px"><tspan id="tspan33" fill="#000000" font-family="Serif, serif" font-size="493.88px">Audio decoder</tspan></tspan></tspan></text> diff --git a/Documentation/userspace-api/media/v4l/app-pri.rst b/Documentation/userspace-api/media/v4l/app-pri.rst index 5018ede2706f..626a42f2e138 100644 --- a/Documentation/userspace-api/media/v4l/app-pri.rst +++ b/Documentation/userspace-api/media/v4l/app-pri.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _app-pri: diff --git a/Documentation/userspace-api/media/v4l/async.rst b/Documentation/userspace-api/media/v4l/async.rst deleted file mode 100644 index 8bc4a726c95e..000000000000 --- a/Documentation/userspace-api/media/v4l/async.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _async: - -**************** -Asynchronous I/O -**************** - -This method is not defined yet. diff --git a/Documentation/userspace-api/media/v4l/audio.rst b/Documentation/userspace-api/media/v4l/audio.rst index d6bb85092e02..17f0b1c89908 100644 --- a/Documentation/userspace-api/media/v4l/audio.rst +++ b/Documentation/userspace-api/media/v4l/audio.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _audio: diff --git a/Documentation/userspace-api/media/v4l/bayer.svg b/Documentation/userspace-api/media/v4l/bayer.svg index 82e805c68c1f..c500a28f0817 100644 --- a/Documentation/userspace-api/media/v4l/bayer.svg +++ b/Documentation/userspace-api/media/v4l/bayer.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg id="svg2" width="164.15mm" height="46.771mm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 16415.333 4677.1107" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><metadata id="metadata652"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><g id="g186" class="com.sun.star.drawing.CustomShape" transform="translate(-3285.9 -3185.9)"><g id="id6"><rect id="rect189" class="BoundingBox" x="3299" y="3199" width="1303" height="1203" fill="none"/><path id="path191" d="m3950 4400h-650v-1200h1300v1200h-650z" fill="#00f"/><path id="path193" d="m3950 4400h-650v-1200h1300v1200h-650z" fill="none" stroke="#3465a4"/><text id="text195" class="TextShape"><tspan id="tspan197" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan199" class="TextPosition" x="3739" y="4021"><tspan id="tspan201" fill="#ffffff">B</tspan></tspan></tspan></text> </g></g><g id="g203" class="com.sun.star.drawing.CustomShape" transform="translate(-3285.9 -3185.9)"><g id="id7"><rect id="rect206" class="BoundingBox" x="4599" y="3199" width="1303" height="1203" fill="none"/><path id="path208" d="m5250 4400h-650v-1200h1300v1200h-650z" fill="#0c0"/><path id="path210" d="m5250 4400h-650v-1200h1300v1200h-650z" fill="none" stroke="#3465a4"/><text id="text212" class="TextShape"><tspan id="tspan214" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan216" class="TextPosition" x="5003" y="4021"><tspan id="tspan218" fill="#ffffff">G</tspan></tspan></tspan></text> diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst index 3c9634173e82..72aef1759b60 100644 --- a/Documentation/userspace-api/media/v4l/biblio.rst +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ********** References @@ -58,7 +51,7 @@ ISO 13818-1 =========== -:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology — Generic coding of moving pictures and associated audio information: Systems" +:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology --- Generic coding of moving pictures and associated audio information: Systems" :author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) @@ -68,7 +61,7 @@ ISO 13818-2 =========== -:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology — Generic coding of moving pictures and associated audio information: Video" +:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology --- Generic coding of moving pictures and associated audio information: Video" :author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) @@ -157,7 +150,7 @@ ITU-T.81 ======== -:title: ITU-T Recommendation T.81 "Information Technology — Digital Compression and Coding of Continous-Tone Still Images — Requirements and Guidelines" +:title: ITU-T Recommendation T.81 "Information Technology --- Digital Compression and Coding of Continous-Tone Still Images --- Requirements and Guidelines" :author: International Telecommunication Union (http://www.itu.int) @@ -277,7 +270,17 @@ EBU Tech 3213 ============= -:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors" +:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors + +:author: European Broadcast Union (http://www.ebu.ch) + +.. _tech3321: + +EBU Tech 3321 +============= + + +:title: E.B.U. guidelines for Consumer Flat Panel Displays (FPDs) :author: European Broadcast Union (http://www.ebu.ch) @@ -307,7 +310,7 @@ ISO 12232:2006 ============== -:title: Photography — Digital still cameras — Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index +:title: Photography --- Digital still cameras --- Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index :author: International Organization for Standardization (http://www.iso.org) @@ -414,3 +417,22 @@ VP8 :title: RFC 6386: "VP8 Data Format and Decoding Guide" :author: J. Bankoski et al. + +.. _vp9: + +VP9 +=== + + +:title: VP9 Bitstream & Decoding Process Specification + +:author: Adrian Grange (Google), Peter de Rivaz (Argon Design), Jonathan Hunt (Argon Design) + +.. _av1: + +AV1 +=== + +:title: AV1 Bitstream & Decoding Process Specification + +:author: Peter de Rivaz, Argon Design Ltd, Jack Haughton, Argon Design Ltd diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 951ae1ed485f..52bbee81c080 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _buffer: @@ -23,8 +17,8 @@ argument to the :ref:`VIDIOC_QUERYBUF`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, some plane-specific members of struct :c:type:`v4l2_buffer`, -such as pointers and sizes for each plane, are stored in struct -struct :c:type:`v4l2_plane` instead. In that case, struct +such as pointers and sizes for each plane, are stored in +struct :c:type:`v4l2_plane` instead. In that case, struct :c:type:`v4l2_buffer` contains an array of plane structures. Dequeued video buffers come with timestamps. The driver decides at which @@ -40,7 +34,6 @@ mem-to-mem devices is an exception to the rule: the timestamp source flags are copied from the OUTPUT video buffer to the CAPTURE video buffer. - Interactions between formats, controls and buffers ================================================== @@ -159,13 +152,12 @@ based on the queried sizes (for instance by allocating a set of buffers large enough for all the desired formats and controls, or by allocating separate set of appropriately sized buffers for each use case). - .. c:type:: v4l2_buffer struct v4l2_buffer ================== -.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.6cm}|p{10.2cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.4cm}|p{12.0cm}| .. cssclass:: longtable @@ -195,10 +187,8 @@ struct v4l2_buffer on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when ``type`` refers to a capture 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 buffer (see the ``length`` field of this struct) by - the driver. For multiplanar formats this field is ignored and the + when it refers to an output stream. For multiplanar formats this field + is ignored and the ``planes`` pointer is used instead. * - __u32 - ``flags`` @@ -264,7 +254,7 @@ struct v4l2_buffer ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the start of the device memory. The value is returned by the driver and apart of serving as parameter to the - :ref:`mmap() <func-mmap>` function not useful for applications. + :c:func:`mmap()` function not useful for applications. See :ref:`mmap` for details * - unsigned long - ``userptr`` @@ -317,13 +307,12 @@ struct v4l2_buffer given, then ``EINVAL`` will be returned. - .. c:type:: v4l2_plane struct v4l2_plane ================= -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{10.3cm}| .. cssclass:: longtable @@ -336,10 +325,7 @@ struct v4l2_plane - ``bytesused`` - The number of bytes occupied by data in the plane (its payload). Drivers must set this field when ``type`` refers to a capture - 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. + stream, applications when it refers to an output stream. .. note:: @@ -357,7 +343,7 @@ struct v4l2_plane - ``mem_offset`` - When the memory type in the containing struct :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this - is the value that should be passed to :ref:`mmap() <func-mmap>`, + is the value that should be passed to :c:func:`mmap()`, similar to the ``offset`` field in struct :c:type:`v4l2_buffer`. * - unsigned long @@ -391,7 +377,6 @@ struct v4l2_plane applications. - .. c:type:: v4l2_buf_type enum v4l2_buf_type @@ -399,7 +384,7 @@ enum v4l2_buf_type .. cssclass:: longtable -.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{9.1cm}| +.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{8.9cm}| .. flat-table:: :header-rows: 0 @@ -455,7 +440,6 @@ enum v4l2_buf_type - Buffer for metadata output, see :ref:`metadata`. - .. _buffer-flags: Buffer Flags @@ -463,16 +447,16 @@ Buffer Flags .. raw:: latex - \small + \footnotesize -.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| +.. tabularcolumns:: |p{6.5cm}|p{1.8cm}|p{9.0cm}| .. cssclass:: longtable .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 3 1 4 + :widths: 65 18 70 * .. _`V4L2-BUF-FLAG-MAPPED`: @@ -565,9 +549,9 @@ Buffer Flags - 0x00000400 - The buffer has been prepared for I/O and can be queued by the application. Drivers set or clear this flag when the - :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, - :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` or :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: @@ -577,7 +561,10 @@ Buffer Flags applications shall use this flag if the data captured in the buffer is not going to be touched by the CPU, instead the buffer will, probably, be passed on to a DMA-capable hardware unit for - further processing or output. + further processing or output. This flag is ignored unless the + queue is used for :ref:`memory mapping <mmap>` streaming I/O and + reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` @@ -585,12 +572,15 @@ Buffer Flags - Caches do not have to be cleaned for this buffer. Typically applications shall use this flag for output buffers if the data in this buffer has not been created by the CPU but by some - DMA-capable unit, in which case caches have not been used. + DMA-capable unit, in which case caches have not been used. This flag + is ignored unless the queue is used for :ref:`memory mapping <mmap>` + streaming I/O and reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`: - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` - 0x00000200 - - Only valid if ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is + - Only valid if struct :c:type:`v4l2_requestbuffers` flag ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is set. It is typically used with stateless decoders where multiple output buffers each decode to a slice of the decoded frame. Applications can set this flag when queueing the output buffer @@ -609,7 +599,7 @@ Buffer Flags :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to hardware limitations, the last buffer may be empty. In this case the driver will set the ``bytesused`` field to 0, regardless of - the format. Any Any subsequent call to the + the format. Any subsequent call to the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, but return an ``EPIPE`` error code. * .. _`V4L2-BUF-FLAG-REQUEST-FD`: @@ -681,13 +671,10 @@ Buffer Flags \normalsize - -.. c:type:: v4l2_memory - enum v4l2_memory ================ -.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.7cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.5cm}| .. flat-table:: :header-rows: 0 @@ -707,7 +694,44 @@ enum v4l2_memory - 4 - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. +.. _memory-flags: + +Memory Consistency Flags +------------------------ + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`V4L2-MEMORY-FLAG-NON-COHERENT`: + - ``V4L2_MEMORY_FLAG_NON_COHERENT`` + - 0x00000001 + - A buffer is allocated either in coherent (it will be automatically + coherent between the CPU and the bus) or non-coherent memory. The + latter can provide performance gains, for instance the CPU cache + sync/flush operations can be avoided if the buffer is accessed by the + corresponding device only and the CPU does not read/write to/from that + buffer. However, this requires extra care from the driver -- it must + guarantee memory consistency by issuing a cache flush/sync when + consistency is needed. If this flag is set V4L2 will attempt to + allocate the buffer in non-coherent memory. The flag takes effect + only if the buffer is used for :ref:`memory mapping <mmap>` I/O and the + queue reports the :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. + +.. raw:: latex + + \normalsize Timecodes ========= @@ -717,13 +741,12 @@ The :c:type:`v4l2_buffer_timecode` structure is designed to hold a (struct :c:type:`timeval` timestamps are stored in the struct :c:type:`v4l2_buffer` ``timestamp`` field.) - .. c:type:: v4l2_timecode struct v4l2_timecode -------------------- -.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{12.3cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| .. flat-table:: :header-rows: 0 @@ -754,14 +777,11 @@ struct v4l2_timecode - The "user group" bits from the timecode. - .. _timecode-type: Timecode Types -------------- -.. tabularcolumns:: |p{5.6cm}|p{0.8cm}|p{11.1cm}| - .. flat-table:: :header-rows: 0 :stub-columns: 0 @@ -784,13 +804,12 @@ Timecode Types - - .. _timecode-flags: Timecode Flags -------------- -.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| +.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/capture-example.rst b/Documentation/userspace-api/media/v4l/capture-example.rst index 6aa67c5aff8f..25891320b7ad 100644 --- a/Documentation/userspace-api/media/v4l/capture-example.rst +++ b/Documentation/userspace-api/media/v4l/capture-example.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _capture-example: diff --git a/Documentation/userspace-api/media/v4l/capture.c.rst b/Documentation/userspace-api/media/v4l/capture.c.rst index 30f7c816e858..eef6772967a1 100644 --- a/Documentation/userspace-api/media/v4l/capture.c.rst +++ b/Documentation/userspace-api/media/v4l/capture.c.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later file: media/v4l/capture.c ========================= @@ -63,7 +56,7 @@ file: media/v4l/capture.c static void errno_exit(const char *s) { - fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno)); + fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno)); exit(EXIT_FAILURE); } @@ -208,7 +201,7 @@ file: media/v4l/capture.c } if (0 == r) { - fprintf(stderr, "select timeout\\n"); + fprintf(stderr, "select timeout\n"); exit(EXIT_FAILURE); } @@ -314,7 +307,7 @@ file: media/v4l/capture.c buffers = calloc(1, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -322,7 +315,7 @@ file: media/v4l/capture.c buffers[0].start = malloc(buffer_size); if (!buffers[0].start) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } } @@ -348,7 +341,7 @@ file: media/v4l/capture.c } if (req.count < 2) { - fprintf(stderr, "Insufficient buffer memory on %s\\n", + fprintf(stderr, "Insufficient buffer memory on %s\n", dev_name); exit(EXIT_FAILURE); } @@ -356,7 +349,7 @@ file: media/v4l/capture.c buffers = calloc(req.count, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -408,7 +401,7 @@ file: media/v4l/capture.c buffers = calloc(4, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -417,7 +410,7 @@ file: media/v4l/capture.c buffers[n_buffers].start = malloc(buffer_size); if (!buffers[n_buffers].start) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } } @@ -433,7 +426,7 @@ file: media/v4l/capture.c if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { if (EINVAL == errno) { - fprintf(stderr, "%s is no V4L2 device\\n", + fprintf(stderr, "%s is no V4L2 device\n", dev_name); exit(EXIT_FAILURE); } else { @@ -442,7 +435,7 @@ file: media/v4l/capture.c } if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { - fprintf(stderr, "%s is no video capture device\\n", + fprintf(stderr, "%s is no video capture device\n", dev_name); exit(EXIT_FAILURE); } @@ -450,7 +443,7 @@ file: media/v4l/capture.c switch (io) { case IO_METHOD_READ: if (!(cap.capabilities & V4L2_CAP_READWRITE)) { - fprintf(stderr, "%s does not support read i/o\\n", + fprintf(stderr, "%s does not support read i/o\n", dev_name); exit(EXIT_FAILURE); } @@ -459,7 +452,7 @@ file: media/v4l/capture.c case IO_METHOD_MMAP: case IO_METHOD_USERPTR: if (!(cap.capabilities & V4L2_CAP_STREAMING)) { - fprintf(stderr, "%s does not support streaming i/o\\n", + fprintf(stderr, "%s does not support streaming i/o\n", dev_name); exit(EXIT_FAILURE); } @@ -548,7 +541,7 @@ file: media/v4l/capture.c struct stat st; if (-1 == stat(dev_name, &st)) { - fprintf(stderr, "Cannot identify '%s': %d, %s\\n", + fprintf(stderr, "Cannot identify '%s': %d, %s\n", dev_name, errno, strerror(errno)); exit(EXIT_FAILURE); } @@ -561,7 +554,7 @@ file: media/v4l/capture.c fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); if (-1 == fd) { - fprintf(stderr, "Cannot open '%s': %d, %s\\n", + fprintf(stderr, "Cannot open '%s': %d, %s\n", dev_name, errno, strerror(errno)); exit(EXIT_FAILURE); } @@ -570,17 +563,17 @@ file: media/v4l/capture.c static void usage(FILE *fp, int argc, char **argv) { fprintf(fp, - "Usage: %s [options]\\n\\n" - "Version 1.3\\n" - "Options:\\n" - "-d | --device name Video device name [%s]n" - "-h | --help Print this messagen" - "-m | --mmap Use memory mapped buffers [default]n" - "-r | --read Use read() callsn" - "-u | --userp Use application allocated buffersn" - "-o | --output Outputs stream to stdoutn" - "-f | --format Force format to 640x480 YUYVn" - "-c | --count Number of frames to grab [%i]n" + "Usage: %s [options]\n\n" + "Version 1.3\n" + "Options:\n" + "-d | --device name Video device name [%s]\n" + "-h | --help Print this message\n" + "-m | --mmap Use memory mapped buffers [default]\n" + "-r | --read Use read() calls\n" + "-u | --userp Use application allocated buffers\n" + "-o | --output Outputs stream to stdout\n" + "-f | --format Force format to 640x480 YUYV\n" + "-c | --count Number of frames to grab [%i]\n" "", argv[0], dev_name, frame_count); } @@ -666,6 +659,6 @@ file: media/v4l/capture.c stop_capturing(); uninit_device(); close_device(); - fprintf(stderr, "\\n"); + fprintf(stderr, "\n"); return 0; } diff --git a/Documentation/userspace-api/media/v4l/colorspaces-defs.rst b/Documentation/userspace-api/media/v4l/colorspaces-defs.rst index 01404e1f609a..fe9f8aa8ab9d 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-defs.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-defs.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later **************************** Defining Colorspaces in V4L2 @@ -36,8 +29,7 @@ whole range, 0-255, dividing the angular value by 1.41. The enum :c:type:`v4l2_hsv_encoding` specifies which encoding is used. .. 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. + colorspaces. HSV formats are always full range. .. tabularcolumns:: |p{6.7cm}|p{10.8cm}| @@ -169,8 +161,8 @@ whole range, 0-255, dividing the angular value by 1.41. The enum - Details * - ``V4L2_QUANTIZATION_DEFAULT`` - Use the default quantization encoding as defined by the - colorspace. This is always full range for R'G'B' (except for the - BT.2020 colorspace) and HSV. It is usually limited range for Y'CbCr. + colorspace. This is always full range for R'G'B' and HSV. + It is usually limited range for Y'CbCr. * - ``V4L2_QUANTIZATION_FULL_RANGE`` - Use the full range quantization encoding. I.e. the range [0…1] is mapped to [0…255] (with possible clipping to [1…254] to avoid the @@ -180,4 +172,4 @@ whole range, 0-255, dividing the angular value by 1.41. The enum * - ``V4L2_QUANTIZATION_LIM_RANGE`` - Use the limited range quantization encoding. I.e. the range [0…1] is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to - [16…240]. + [16…240]. Limited Range cannot be used with HSV. diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst index 79ed6f4f76eb..26a4ace42ca5 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ******************************** Detailed Colorspace Descriptions @@ -24,10 +17,6 @@ PAL and by SDTV in general. The default transfer function is range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: SMPTE 170M Chromaticities :header-rows: 1 :stub-columns: 0 @@ -105,10 +94,6 @@ default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: Rec. 709 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -232,10 +217,6 @@ would break how applications interpret the quantization range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: sRGB Chromaticities :header-rows: 1 :stub-columns: 0 @@ -315,9 +296,6 @@ would break how applications interpret the quantization range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: opRGB Chromaticities :header-rows: 1 :stub-columns: 0 @@ -377,13 +355,8 @@ Colorspace BT.2020 (V4L2_COLORSPACE_BT2020) The :ref:`itu2020` standard defines the colorspace used by Ultra-high definition television (UHDTV). The default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited -range (!), and so is the default Y'CbCr quantization. The chromaticities -of the primary colors and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +``V4L2_YCBCR_ENC_BT2020``. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are: .. flat-table:: BT.2020 Chromaticities :header-rows: 1 @@ -486,9 +459,6 @@ is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: DCI-P3 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -540,9 +510,6 @@ quantization is limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: SMPTE 240M Chromaticities :header-rows: 1 :stub-columns: 0 @@ -611,9 +578,6 @@ limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: NTSC 1953 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -682,17 +646,15 @@ Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG) ========================================================= The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM -in 1975. In practice this colorspace is obsolete and SMPTE 170M should -be used instead. The default transfer function is +in 1975. Note that this colorspace is not supported by the HDMI interface. +Instead :ref:`tech3321` recommends that Rec. 709 is used instead for HDMI. +The default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: EBU Tech. 3213 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -767,8 +729,8 @@ scaled to [-128…128] and then clipped to [-128…127]. 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``. + ``V4L2_COLORSPACE_SRGB``, ``V4L2_XFER_FUNC_SRGB``, ``V4L2_YCBCR_ENC_601`` + and ``V4L2_QUANTIZATION_FULL_RANGE``. *************************************** Detailed Transfer Function Descriptions diff --git a/Documentation/userspace-api/media/v4l/colorspaces.rst b/Documentation/userspace-api/media/v4l/colorspaces.rst index 0846df9066c5..2aa0dda4fd01 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _colorspaces: diff --git a/Documentation/userspace-api/media/v4l/common-defs.rst b/Documentation/userspace-api/media/v4l/common-defs.rst index 370a1e364a51..6ae42ac7ddb7 100644 --- a/Documentation/userspace-api/media/v4l/common-defs.rst +++ b/Documentation/userspace-api/media/v4l/common-defs.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _common-defs: diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst index 7d81c58a13cd..ea0435182e44 100644 --- a/Documentation/userspace-api/media/v4l/common.rst +++ b/Documentation/userspace-api/media/v4l/common.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _common: @@ -51,12 +44,14 @@ applicable to all devices. ext-ctrls-image-source ext-ctrls-image-process ext-ctrls-codec + ext-ctrls-codec-stateless ext-ctrls-jpeg ext-ctrls-dv ext-ctrls-rf-tuner ext-ctrls-fm-tx ext-ctrls-fm-rx ext-ctrls-detect + ext-ctrls-colorimetry fourcc format planar-apis diff --git a/Documentation/userspace-api/media/v4l/compat.rst b/Documentation/userspace-api/media/v4l/compat.rst index 055286b86e9b..b63b8392dec6 100644 --- a/Documentation/userspace-api/media/v4l/compat.rst +++ b/Documentation/userspace-api/media/v4l/compat.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _compat: diff --git a/Documentation/userspace-api/media/v4l/constraints.svg b/Documentation/userspace-api/media/v4l/constraints.svg index 1dfe51a9839d..ac5f82bc6d1a 100644 --- a/Documentation/userspace-api/media/v4l/constraints.svg +++ b/Documentation/userspace-api/media/v4l/constraints.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg id="svg2" width="249.01mm" height="143.01mm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 24900.998 14300.999" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><metadata id="metadata325"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><defs id="defs4" class="ClipPathGroup"><marker id="marker6261" overflow="visible" orient="auto"><path id="path6263" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker6125" overflow="visible" orient="auto"><path id="path6127" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker6001" overflow="visible" orient="auto"><path id="path6003" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker5693" overflow="visible" orient="auto"><path id="path5695" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker5575" overflow="visible" orient="auto"><path id="path5577" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="marker5469" overflow="visible" orient="auto"><path id="path5471" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="marker5259" overflow="visible" orient="auto"><path id="path5261" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="Arrow2Mend" overflow="visible" orient="auto"><path id="path4241" transform="scale(-.6)" d="m8.7186 4.0337-10.926-4.0177 10.926-4.0177c-1.7455 2.3721-1.7354 5.6175-6e-7 8.0354z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-linejoin="round" stroke-width=".625"/></marker></defs><g id="g204" class="com.sun.star.drawing.CustomShape" transform="translate(-1350,-3250)"><g id="id6"><rect id="rect207" class="BoundingBox" x="1350" y="3250" width="24901" height="14301" diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst index 3e991c1f7a12..57893814a1e5 100644 --- a/Documentation/userspace-api/media/v4l/control.rst +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _control: @@ -150,9 +143,13 @@ Control IDs recognise the difference between digital and analogue gain use controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. +.. _v4l2-cid-hflip: + ``V4L2_CID_HFLIP`` ``(boolean)`` Mirror the picture horizontally. +.. _v4l2-cid-vflip: + ``V4L2_CID_VFLIP`` ``(boolean)`` Mirror the picture vertically. @@ -161,10 +158,13 @@ Control IDs ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` Enables a power line frequency filter to avoid flicker. Possible values for ``enum v4l2_power_line_frequency`` are: - ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0), - ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1), - ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and - ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3). + + ========================================== == + ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` 0 + ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` 1 + ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` 2 + ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` 3 + ========================================== == ``V4L2_CID_HUE_AUTO`` ``(boolean)`` Enables automatic hue control by the device. The effect of setting @@ -204,7 +204,7 @@ Control IDs -.. tabularcolumns:: |p{5.5cm}|p{12cm}| +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| .. flat-table:: :header-rows: 0 @@ -246,8 +246,17 @@ Control IDs * - ``V4L2_COLORFX_SET_CBCR`` - The Cb and Cr chroma components are replaced by fixed coefficients determined by ``V4L2_CID_COLORFX_CBCR`` control. + * - ``V4L2_COLORFX_SET_RGB`` + - The RGB components are replaced by the fixed RGB components determined + by ``V4L2_CID_COLORFX_RGB`` control. +``V4L2_CID_COLORFX_RGB`` ``(integer)`` + Determines the Red, Green, and Blue coefficients for + ``V4L2_COLORFX_SET_RGB`` color effect. + Bits [7:0] of the supplied 32 bit value are interpreted as Blue component, + bits [15:8] as Green component, bits [23:16] as Red component, and + bits [31:24] must be zero. ``V4L2_CID_COLORFX_CBCR`` ``(integer)`` Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR`` @@ -456,10 +465,10 @@ Example: Changing controls perror("VIDIOC_QUERYCTRL"); exit(EXIT_FAILURE); } else { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } else { memset(&control, 0, sizeof (control)); control.id = V4L2_CID_BRIGHTNESS; diff --git a/Documentation/userspace-api/media/v4l/crop.rst b/Documentation/userspace-api/media/v4l/crop.rst index cb7e2341aedf..3fe185e25ccf 100644 --- a/Documentation/userspace-api/media/v4l/crop.rst +++ b/Documentation/userspace-api/media/v4l/crop.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _crop: diff --git a/Documentation/userspace-api/media/v4l/crop.svg b/Documentation/userspace-api/media/v4l/crop.svg index 4cd47f98e7c8..5483227757e7 100644 --- a/Documentation/userspace-api/media/v4l/crop.svg +++ b/Documentation/userspace-api/media/v4l/crop.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/depth-formats.rst b/Documentation/userspace-api/media/v4l/depth-formats.rst index 6742486a83b5..b4f3fc229c85 100644 --- a/Documentation/userspace-api/media/v4l/depth-formats.rst +++ b/Documentation/userspace-api/media/v4l/depth-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _depth-formats: diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst index 44d3094093ab..fe58fd450e2f 100644 --- a/Documentation/userspace-api/media/v4l/dev-capture.rst +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _capture: @@ -26,7 +20,6 @@ device. .. note:: The same device file names are used for video output devices. - Querying Capabilities ===================== @@ -41,7 +34,6 @@ functions they may also support the :ref:`video overlay <overlay>` streaming I/O methods must be supported. Tuners and audio inputs are optional. - Supplemental Functions ====================== @@ -52,7 +44,6 @@ Video capture devices shall support :ref:`audio input <audio>`, :ref:`video input <video>` ioctls must be supported by all video capture devices. - Image Format Negotiation ======================== @@ -62,7 +53,7 @@ capture, the latter how images are stored in memory, i. e. in RGB or YUV format, the number of bits per pixel or width and height. Together they also define how images are scaled in the process. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then reading from it as if it was a plain file. Well written V4L2 applications ensure they really get what they want, including cropping and scaling. @@ -102,7 +93,6 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. - Reading Images ============== diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst index 606b54947e10..ef8e8cf31f90 100644 --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst @@ -38,7 +38,7 @@ Conventions and Notations Used in This Document 6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i = [0..2]: i = 0, 1, 2. -7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE`` +7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE`` queue containing data that resulted from processing buffer A. .. _decoder-glossary: @@ -72,6 +72,12 @@ coded resolution coded width width for given coded resolution. +coding tree unit + processing unit of the HEVC codec (corresponds to macroblock units in + H.264, VP8, VP9), + can use block structures of up to 64×64 pixels. + Good at sub-partitioning the picture into variable sized structures. + decode order the order in which frames are decoded; may differ from display order if the coded format includes a feature of frame reordering; for decoders, @@ -104,7 +110,8 @@ keyframe macroblock a processing unit in image and video compression formats based on linear block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of - popular codecs the size is 16x16 samples (pixels). + popular codecs the size is 16x16 samples (pixels). The HEVC codec uses a + slightly more flexible processing unit called coding tree unit (CTU). OUTPUT the source buffer queue; for decoders, the queue of buffers containing @@ -247,7 +254,7 @@ Querying Capabilities Initialization ============== -1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT` +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`. * **Required fields:** @@ -270,7 +277,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``sizeimage`` adjusted size of ``OUTPUT`` buffers. @@ -288,7 +295,7 @@ Initialization Changing the ``OUTPUT`` format may change the currently set ``CAPTURE`` format. How the new ``CAPTURE`` format is determined is up to the decoder - and the client must ensure it matches its needs afterwards. + and the client must ensure it matches its needs afterwards. 2. Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on ``OUTPUT``. @@ -304,7 +311,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` the actual number of buffers allocated. @@ -332,7 +339,7 @@ Initialization ``format`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. @@ -403,7 +410,7 @@ Capture Setup ``type`` a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. - * **Return fields:** + * **Returned fields:** ``width``, ``height`` frame buffer resolution for the decoded frames. @@ -436,7 +443,7 @@ Capture Setup ``target`` set to ``V4L2_SEL_TGT_COMPOSE``. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` the visible rectangle; it must fit within the frame buffer resolution @@ -545,7 +552,7 @@ Capture Setup frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without additional compose/scaling capabilities. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` the visible rectangle; it must fit within the frame buffer resolution @@ -622,7 +629,7 @@ Capture Setup ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -661,7 +668,7 @@ Capture Setup a format representing the maximum framebuffer resolution to be accommodated by newly allocated buffers. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. @@ -752,6 +759,23 @@ available to dequeue. Specifically: buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps. +.. note:: + + The backing memory of ``CAPTURE`` buffers that are used as reference frames + by the stream may be read by the hardware even after they are dequeued. + Consequently, the client should avoid writing into this memory while the + ``CAPTURE`` queue is streaming. Failure to observe this may result in + corruption of decoded frames. + + Similarly, when using a memory type other than ``V4L2_MEMORY_MMAP``, the + client should make sure that each ``CAPTURE`` buffer is always queued with + the same backing memory for as long as the ``CAPTURE`` queue is streaming. + The reason for this is that V4L2 buffer indices can be used by drivers to + identify frames. Thus, if the backing memory of a reference frame is + submitted under a different buffer ID, the driver may misidentify it and + decode a new frame into it while it is still in use, resulting in corruption + of the following frames. + During the decoding, the decoder may initiate one of the special sequences, as listed below. The sequences will result in the decoder returning all the ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed @@ -803,7 +827,7 @@ it may be affected as per normal decoder operation. * The decoder will drop all the pending ``OUTPUT`` buffers and they must be treated as returned to the client (following standard semantics). -2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON` +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`. * **Required fields:** @@ -874,7 +898,7 @@ it may be affected as per normal decoder operation. any of the following results on the ``CAPTURE`` queue is allowed: - {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}. + {A', B', G', H'}, {A', G', H'}, {G', H'}. To determine the CAPTURE buffer containing the first decoded frame after the seek, the client may observe the timestamps to match the CAPTURE and OUTPUT @@ -906,7 +930,9 @@ reflected by corresponding queries): * visible resolution (selection rectangles), -* the minimum number of buffers needed for decoding. +* the minimum number of buffers needed for decoding, + +* bit-depth of the bitstream has been changed. Whenever that happens, the decoder must proceed as follows: @@ -1059,7 +1085,7 @@ sequence was started. ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they will fail with -EBUSY error code if attempted. - Although mandatory, the availability of decoder commands may be queried + Although not mandatory, the availability of decoder commands may be queried using :c:func:`VIDIOC_TRY_DECODER_CMD`. End of Stream diff --git a/Documentation/userspace-api/media/v4l/dev-encoder.rst b/Documentation/userspace-api/media/v4l/dev-encoder.rst new file mode 100644 index 000000000000..6c523c69bdce --- /dev/null +++ b/Documentation/userspace-api/media/v4l/dev-encoder.rst @@ -0,0 +1,729 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _encoder: + +************************************************* +Memory-to-Memory Stateful Video Encoder Interface +************************************************* + +A stateful video encoder takes raw video frames in display order and encodes +them into a bytestream. It generates complete chunks of the bytestream, including +all metadata, headers, etc. The resulting bytestream does not require any +further post-processing by the client. + +Performing software stream processing, header generation etc. in the driver +in order to support this interface is strongly discouraged. In case such +operations are needed, use of the Stateless Video Encoder Interface (in +development) is strongly advised. + +Conventions and Notations Used in This Document +=============================================== + +1. The general V4L2 API rules apply if not specified in this document + otherwise. + +2. The meaning of words "must", "may", "should", etc. is as per `RFC + 2119 <https://tools.ietf.org/html/rfc2119>`_. + +3. All steps not marked "optional" are required. + +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used + interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`, + unless specified otherwise. + +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be + used interchangeably with multi-planar API, unless specified otherwise, + depending on encoder capabilities and following the general V4L2 guidelines. + +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i = + [0..2]: i = 0, 1, 2. + +7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE`` + queue containing data that resulted from processing buffer A. + +Glossary +======== + +Refer to :ref:`decoder-glossary`. + +State Machine +============= + +.. kernel-render:: DOT + :alt: DOT digraph of encoder state machine + :caption: Encoder State Machine + + digraph encoder_state_machine { + node [shape = doublecircle, label="Encoding"] Encoding; + + node [shape = circle, label="Initialization"] Initialization; + node [shape = circle, label="Stopped"] Stopped; + node [shape = circle, label="Drain"] Drain; + node [shape = circle, label="Reset"] Reset; + + node [shape = point]; qi + qi -> Initialization [ label = "open()" ]; + + Initialization -> Encoding [ label = "Both queues streaming" ]; + + Encoding -> Drain [ label = "V4L2_ENC_CMD_STOP" ]; + Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + Encoding -> Encoding; + + Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ]; + Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + + Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ]; + Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ]; + + Stopped -> Encoding [ label = "V4L2_ENC_CMD_START\nor\nVIDIOC_STREAMON(OUTPUT)" ]; + Stopped -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + } + +Querying Capabilities +===================== + +1. To enumerate the set of coded formats supported by the encoder, the + client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``. + + * The full set of supported formats will be returned, regardless of the + format set on ``OUTPUT``. + +2. To enumerate the set of supported raw formats, the client may call + :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``. + + * Only the formats supported for the format currently active on ``CAPTURE`` + will be returned. + + * In order to enumerate raw formats supported by a given coded format, + the client must first set that coded format on ``CAPTURE`` and then + enumerate the formats on ``OUTPUT``. + +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported + resolutions for a given format, passing the desired pixel format in + :c:type:`v4l2_frmsizeenum` ``pixel_format``. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel + format will include all possible coded resolutions supported by the + encoder for the given coded pixel format. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format + will include all possible frame buffer resolutions supported by the + encoder for the given raw pixel format and coded format currently set on + ``CAPTURE``. + +4. The client may use :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` to detect supported + frame intervals for a given format and resolution, passing the desired pixel + format in :c:type:`v4l2_frmivalenum` ``pixel_format`` and the resolution + in :c:type:`v4l2_frmivalenum` ``width`` and :c:type:`v4l2_frmivalenum` + ``height``. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a coded pixel + format and coded resolution will include all possible frame intervals + supported by the encoder for the given coded pixel format and resolution. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a raw pixel + format and resolution will include all possible frame intervals supported + by the encoder for the given raw pixel format and resolution and for the + coded format, coded resolution and coded frame interval currently set on + ``CAPTURE``. + + * Support for :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` is optional. If it is + not implemented, then there are no special restrictions other than the + limits of the codec itself. + +5. Supported profiles and levels for the coded format currently set on + ``CAPTURE``, if applicable, may be queried using their respective controls + via :c:func:`VIDIOC_QUERYCTRL`. + +6. Any additional encoder capabilities may be discovered by querying + their respective controls. + +Initialization +============== + +1. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``pixelformat`` + the coded format to be produced. + + ``sizeimage`` + desired size of ``CAPTURE`` buffers; the encoder may adjust it to + match hardware requirements. + + ``width``, ``height`` + ignored (read-only). + + other fields + follow standard semantics. + + * **Returned fields:** + + ``sizeimage`` + adjusted size of ``CAPTURE`` buffers. + + ``width``, ``height`` + the coded size selected by the encoder based on current state, e.g. + ``OUTPUT`` format, selection rectangles, etc. (read-only). + + .. important:: + + Changing the ``CAPTURE`` format may change the currently set ``OUTPUT`` + format. How the new ``OUTPUT`` format is determined is up to the encoder + and the client must ensure it matches its needs afterwards. + +2. **Optional.** Enumerate supported ``OUTPUT`` formats (raw formats for + source) for the selected coded format via :c:func:`VIDIOC_ENUM_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + other fields + follow standard semantics. + + * **Returned fields:** + + ``pixelformat`` + raw format supported for the coded format currently selected on + the ``CAPTURE`` queue. + + other fields + follow standard semantics. + +3. Set the raw source format on the ``OUTPUT`` queue via + :c:func:`VIDIOC_S_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``pixelformat`` + raw format of the source. + + ``width``, ``height`` + source resolution. + + other fields + follow standard semantics. + + * **Returned fields:** + + ``width``, ``height`` + may be adjusted to match encoder minimums, maximums and alignment + requirements, as required by the currently selected formats, as + reported by :c:func:`VIDIOC_ENUM_FRAMESIZES`. + + other fields + follow standard semantics. + + * Setting the ``OUTPUT`` format will reset the selection rectangles to their + default values, based on the new resolution, as described in the next + step. + +4. Set the raw frame interval on the ``OUTPUT`` queue via + :c:func:`VIDIOC_S_PARM`. This also sets the coded frame interval on the + ``CAPTURE`` queue to the same value. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``parm.output`` + set all fields except ``parm.output.timeperframe`` to 0. + + ``parm.output.timeperframe`` + the desired frame interval; the encoder may adjust it to + match hardware requirements. + + * **Returned fields:** + + ``parm.output.timeperframe`` + the adjusted frame interval. + + .. important:: + + Changing the ``OUTPUT`` frame interval *also* sets the framerate that + the encoder uses to encode the video. So setting the frame interval + to 1/24 (or 24 frames per second) will produce a coded video stream + that can be played back at that speed. The frame interval for the + ``OUTPUT`` queue is just a hint, the application may provide raw + frames at a different rate. It can be used by the driver to help + schedule multiple encoders running in parallel. + + In the next step the ``CAPTURE`` frame interval can optionally be + changed to a different value. This is useful for off-line encoding + were the coded frame interval can be different from the rate at + which raw frames are supplied. + + .. important:: + + ``timeperframe`` deals with *frames*, not fields. So for interlaced + formats this is the time per two fields, since a frame consists of + a top and a bottom field. + + .. note:: + + It is due to historical reasons that changing the ``OUTPUT`` frame + interval also changes the coded frame interval on the ``CAPTURE`` + queue. Ideally these would be independent settings, but that would + break the existing API. + +5. **Optional** Set the coded frame interval on the ``CAPTURE`` queue via + :c:func:`VIDIOC_S_PARM`. This is only necessary if the coded frame + interval is different from the raw frame interval, which is typically + the case for off-line encoding. Support for this feature is signalled + by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL <fmtdesc-flags>` format flag. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``parm.capture`` + set all fields except ``parm.capture.timeperframe`` to 0. + + ``parm.capture.timeperframe`` + the desired coded frame interval; the encoder may adjust it to + match hardware requirements. + + * **Returned fields:** + + ``parm.capture.timeperframe`` + the adjusted frame interval. + + .. important:: + + Changing the ``CAPTURE`` frame interval sets the framerate for the + coded video. It does *not* set the rate at which buffers arrive on the + ``CAPTURE`` queue, that depends on how fast the encoder is and how + fast raw frames are queued on the ``OUTPUT`` queue. + + .. important:: + + ``timeperframe`` deals with *frames*, not fields. So for interlaced + formats this is the time per two fields, since a frame consists of + a top and a bottom field. + + .. note:: + + Not all drivers support this functionality, in that case just set + the desired coded frame interval for the ``OUTPUT`` queue. + + However, drivers that can schedule multiple encoders based on the + ``OUTPUT`` frame interval must support this optional feature. + +6. **Optional.** Set the visible resolution for the stream metadata via + :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue if it is desired + to be different than the full OUTPUT resolution. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``target`` + set to ``V4L2_SEL_TGT_CROP``. + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + visible rectangle; this must fit within the `V4L2_SEL_TGT_CROP_BOUNDS` + rectangle and may be subject to adjustment to match codec and + hardware constraints. + + * **Returned fields:** + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + visible rectangle adjusted by the encoder. + + * The following selection targets are supported on ``OUTPUT``: + + ``V4L2_SEL_TGT_CROP_BOUNDS`` + equal to the full source frame, matching the active ``OUTPUT`` + format. + + ``V4L2_SEL_TGT_CROP_DEFAULT`` + equal to ``V4L2_SEL_TGT_CROP_BOUNDS``. + + ``V4L2_SEL_TGT_CROP`` + rectangle within the source buffer to be encoded into the + ``CAPTURE`` stream; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``. + + .. note:: + + A common use case for this selection target is encoding a source + video with a resolution that is not a multiple of a macroblock, + e.g. the common 1920x1080 resolution may require the source + buffers to be aligned to 1920x1088 for codecs with 16x16 macroblock + size. To avoid encoding the padding, the client needs to explicitly + configure this selection target to 1920x1080. + + .. warning:: + + The encoder may adjust the crop/compose rectangles to the nearest + supported ones to meet codec and hardware requirements. The client needs + to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`. + +7. Allocate buffers for both ``OUTPUT`` and ``CAPTURE`` via + :c:func:`VIDIOC_REQBUFS`. This may be performed in any order. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT`` or + ``CAPTURE``. + + other fields + follow standard semantics. + + * **Returned fields:** + + ``count`` + actual number of buffers allocated. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + .. note:: + + To allocate more than the minimum number of OUTPUT buffers (for pipeline + depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` + control to get the minimum number of buffers required, and pass the + obtained value plus the number of additional buffers needed in the + ``count`` field to :c:func:`VIDIOC_REQBUFS`. + + Alternatively, :c:func:`VIDIOC_CREATE_BUFS` can be used to have more + control over buffer allocation. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + other fields + follow standard semantics. + + * **Returned fields:** + + ``count`` + adjusted to the number of allocated buffers. + +8. Begin streaming on both ``OUTPUT`` and ``CAPTURE`` queues via + :c:func:`VIDIOC_STREAMON`. This may be performed in any order. The actual + encoding process starts when both queues start streaming. + +.. note:: + + If the client stops the ``CAPTURE`` queue during the encode process and then + restarts it again, the encoder will begin generating a stream independent + from the stream generated before the stop. The exact constraints depend + on the coded format, but may include the following implications: + + * encoded frames produced after the restart must not reference any + frames produced before the stop, e.g. no long term references for + H.264/HEVC, + + * any headers that must be included in a standalone stream must be + produced again, e.g. SPS and PPS for H.264/HEVC. + +Encoding +======== + +This state is reached after the `Initialization` sequence finishes +successfully. In this state, the client queues and dequeues buffers to both +queues via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the +standard semantics. + +The content of encoded ``CAPTURE`` buffers depends on the active coded pixel +format and may be affected by codec-specific extended controls, as stated +in the documentation of each format. + +Both queues operate independently, following standard behavior of V4L2 buffer +queues and memory-to-memory devices. In addition, the order of encoded frames +dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw +frames to the ``OUTPUT`` queue, due to properties of the selected coded format, +e.g. frame reordering. + +The client must not assume any direct relationship between ``CAPTURE`` and +``OUTPUT`` buffers and any specific timing of buffers becoming +available to dequeue. Specifically: + +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced on + ``CAPTURE`` (for example, if returning an encoded frame allowed the encoder + to return a frame that preceded it in display, but succeeded it in the decode + order; however, there may be other reasons for this as well), + +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on + ``CAPTURE`` later into encode process, and/or after processing further + ``OUTPUT`` buffers, or be returned out of order, e.g. if display + reordering is used, + +* buffers may become available on the ``CAPTURE`` queue without additional + buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the + ``OUTPUT`` buffers queued in the past whose encoding results are only + available at later time, due to specifics of the encoding process, + +* buffers queued to ``OUTPUT`` may not become available to dequeue instantly + after being encoded into a corresponding ``CAPTURE`` buffer, e.g. if the + encoder needs to use the frame as a reference for encoding further frames. + +.. note:: + + To allow matching encoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they + originated from, the client can set the ``timestamp`` field of the + :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The + ``CAPTURE`` buffer(s), which resulted from encoding that ``OUTPUT`` buffer + will have their ``timestamp`` field set to the same value when dequeued. + + In addition to the straightforward case of one ``OUTPUT`` buffer producing + one ``CAPTURE`` buffer, the following cases are defined: + + * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same + ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers, + + * the encoding order differs from the presentation order (i.e. the + ``CAPTURE`` buffers are out-of-order compared to the ``OUTPUT`` buffers): + ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps. + +.. note:: + + To let the client distinguish between frame types (keyframes, intermediate + frames; the exact list of types depends on the coded format), the + ``CAPTURE`` buffers will have corresponding flag bits set in their + :c:type:`v4l2_buffer` struct when dequeued. See the documentation of + :c:type:`v4l2_buffer` and each coded pixel format for exact list of flags + and their meanings. + +Should an encoding error occur, it will be reported to the client with the level +of details depending on the encoder capabilities. Specifically: + +* the ``CAPTURE`` buffer (if any) that contains the results of the failed encode + operation will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag set, + +* if the encoder is able to precisely report the ``OUTPUT`` buffer(s) that triggered + the error, such buffer(s) will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag + set. + +.. note:: + + If a ``CAPTURE`` buffer is too small then it is just returned with the + ``V4L2_BUF_FLAG_ERROR`` flag set. More work is needed to detect that this + error occurred because the buffer was too small, and to provide support to + free existing buffers that were too small. + +In case of a fatal failure that does not allow the encoding to continue, any +further operations on corresponding encoder file handle will return the -EIO +error code. The client may close the file handle and open a new one, or +alternatively reinitialize the instance by stopping streaming on both queues, +releasing all buffers and performing the Initialization sequence again. + +Encoding Parameter Changes +========================== + +The client is allowed to use :c:func:`VIDIOC_S_CTRL` to change encoder +parameters at any time. The availability of parameters is encoder-specific +and the client must query the encoder to find the set of available controls. + +The ability to change each parameter during encoding is encoder-specific, as +per the standard semantics of the V4L2 control interface. The client may +attempt to set a control during encoding and if the operation fails with the +-EBUSY error code, the ``CAPTURE`` queue needs to be stopped for the +configuration change to be allowed. To do this, it may follow the `Drain` +sequence to avoid losing the already queued/encoded frames. + +The timing of parameter updates is encoder-specific, as per the standard +semantics of the V4L2 control interface. If the client needs to apply the +parameters exactly at specific frame, using the Request API +(:ref:`media-request-api`) should be considered, if supported by the encoder. + +Drain +===== + +To ensure that all the queued ``OUTPUT`` buffers have been processed and the +related ``CAPTURE`` buffers are given to the client, the client must follow the +drain sequence described below. After the drain sequence ends, the client has +received all encoded frames for all ``OUTPUT`` buffers queued before the +sequence was started. + +1. Begin the drain sequence by issuing :c:func:`VIDIOC_ENCODER_CMD`. + + * **Required fields:** + + ``cmd`` + set to ``V4L2_ENC_CMD_STOP``. + + ``flags`` + set to 0. + + ``pts`` + set to 0. + + .. warning:: + + The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE`` + queues are streaming. For compatibility reasons, the call to + :c:func:`VIDIOC_ENCODER_CMD` will not fail even if any of the queues is + not streaming, but at the same time it will not initiate the `Drain` + sequence and so the steps described below would not be applicable. + +2. Any ``OUTPUT`` buffers queued by the client before the + :c:func:`VIDIOC_ENCODER_CMD` was issued will be processed and encoded as + normal. The client must continue to handle both queues independently, + similarly to normal encode operation. This includes: + + * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the + ``V4L2_BUF_FLAG_LAST`` flag is dequeued, + + .. warning:: + + The last buffer may be empty (with :c:type:`v4l2_buffer` + ``bytesused`` = 0) and in that case it must be ignored by the client, + as it does not contain an encoded frame. + + .. note:: + + Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer + marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from + :c:func:`VIDIOC_DQBUF`. + + * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued + before the ``V4L2_ENC_CMD_STOP`` command are dequeued, + + * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribes to it. + + .. note:: + + For backwards compatibility, the encoder will signal a ``V4L2_EVENT_EOS`` + event when the last frame has been encoded and all frames are ready to be + dequeued. It is deprecated behavior and the client must not rely on it. + The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead. + +3. Once all ``OUTPUT`` buffers queued before the ``V4L2_ENC_CMD_STOP`` call are + dequeued and the last ``CAPTURE`` buffer is dequeued, the encoder is stopped + and it will accept, but not process any newly queued ``OUTPUT`` buffers + until the client issues any of the following operations: + + * ``V4L2_ENC_CMD_START`` - the encoder will not be reset and will resume + operation normally, with all the state from before the drain, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``CAPTURE`` queue - the encoder will be reset (see the `Reset` sequence) + and then resume encoding, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``OUTPUT`` queue - the encoder will resume operation normally, however any + source frames queued to the ``OUTPUT`` queue between ``V4L2_ENC_CMD_STOP`` + and :c:func:`VIDIOC_STREAMOFF` will be discarded. + +.. note:: + + Once the drain sequence is initiated, the client needs to drive it to + completion, as described by the steps above, unless it aborts the process by + issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE`` + queues. The client is not allowed to issue ``V4L2_ENC_CMD_START`` or + ``V4L2_ENC_CMD_STOP`` again while the drain sequence is in progress and they + will fail with -EBUSY error code if attempted. + + For reference, handling of various corner cases is described below: + + * In case of no buffer in the ``OUTPUT`` queue at the time the + ``V4L2_ENC_CMD_STOP`` command was issued, the drain sequence completes + immediately and the encoder returns an empty ``CAPTURE`` buffer with the + ``V4L2_BUF_FLAG_LAST`` flag set. + + * In case of no buffer in the ``CAPTURE`` queue at the time the drain + sequence completes, the next time the client queues a ``CAPTURE`` buffer + it is returned at once as an empty buffer with the ``V4L2_BUF_FLAG_LAST`` + flag set. + + * If :c:func:`VIDIOC_STREAMOFF` is called on the ``CAPTURE`` queue in the + middle of the drain sequence, the drain sequence is canceled and all + ``CAPTURE`` buffers are implicitly returned to the client. + + * If :c:func:`VIDIOC_STREAMOFF` is called on the ``OUTPUT`` queue in the + middle of the drain sequence, the drain sequence completes immediately and + next ``CAPTURE`` buffer will be returned empty with the + ``V4L2_BUF_FLAG_LAST`` flag set. + + Although not mandatory, the availability of encoder commands may be queried + using :c:func:`VIDIOC_TRY_ENCODER_CMD`. + +Reset +===== + +The client may want to request the encoder to reinitialize the encoding, so +that the following stream data becomes independent from the stream data +generated before. Depending on the coded format, that may imply that: + +* encoded frames produced after the restart must not reference any frames + produced before the stop, e.g. no long term references for H.264/HEVC, + +* any headers that must be included in a standalone stream must be produced + again, e.g. SPS and PPS for H.264/HEVC. + +This can be achieved by performing the reset sequence. + +1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes + and respective buffers are dequeued. + +2. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This + will return all currently queued ``CAPTURE`` buffers to the client, without + valid frame data. + +3. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and + continue with regular encoding sequence. The encoded frames produced into + ``CAPTURE`` buffers from now on will contain a standalone stream that can be + decoded without the need for frames encoded before the reset sequence, + starting at the first ``OUTPUT`` buffer queued after issuing the + `V4L2_ENC_CMD_STOP` of the `Drain` sequence. + +This sequence may be also used to change encoding parameters for encoders +without the ability to change the parameters on the fly. + +Commit Points +============= + +Setting formats and allocating buffers triggers changes in the behavior of the +encoder. + +1. Setting the format on the ``CAPTURE`` queue may change the set of formats + supported/advertised on the ``OUTPUT`` queue. In particular, it also means + that the ``OUTPUT`` format may be reset and the client must not rely on the + previously set format being preserved. + +2. Enumerating formats on the ``OUTPUT`` queue always returns only formats + supported for the current ``CAPTURE`` format. + +3. Setting the format on the ``OUTPUT`` queue does not change the list of + formats available on the ``CAPTURE`` queue. An attempt to set the ``OUTPUT`` + format that is not supported for the currently selected ``CAPTURE`` format + will result in the encoder adjusting the requested ``OUTPUT`` format to a + supported one. + +4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of + supported coded formats, irrespective of the current ``OUTPUT`` format. + +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues, + the client must not change the format on the ``CAPTURE`` queue. Drivers will + return the -EBUSY error code for any such format change attempt. + +To summarize, setting formats and allocation must always start with the +``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the +set of supported formats for the ``OUTPUT`` queue. diff --git a/Documentation/userspace-api/media/v4l/dev-event.rst b/Documentation/userspace-api/media/v4l/dev-event.rst index d09034fd680a..f34f9cf6ce6c 100644 --- a/Documentation/userspace-api/media/v4l/dev-event.rst +++ b/Documentation/userspace-api/media/v4l/dev-event.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _event: diff --git a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst index 9279d87c08a1..7041bb3d5b8d 100644 --- a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst +++ b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _mem2mem: @@ -39,11 +32,12 @@ file handle is visible through another file handle). One of the most common memory-to-memory device is the codec. Codecs are more complicated than most and require additional setup for their codec parameters. This is done through codec controls. -See :ref:`mpeg-controls`. More details on how to use codec memory-to-memory +See :ref:`codec-controls`. More details on how to use codec memory-to-memory devices are given in the following sections. .. toctree:: :maxdepth: 1 dev-decoder + dev-encoder dev-stateless-decoder diff --git a/Documentation/userspace-api/media/v4l/dev-meta.rst b/Documentation/userspace-api/media/v4l/dev-meta.rst index 6d2c5a79b370..0e7e1ee1471a 100644 --- a/Documentation/userspace-api/media/v4l/dev-meta.rst +++ b/Documentation/userspace-api/media/v4l/dev-meta.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _metadata: @@ -56,7 +49,7 @@ to 0. .. c:type:: v4l2_meta_format -.. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}| .. flat-table:: struct v4l2_meta_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-osd.rst b/Documentation/userspace-api/media/v4l/dev-osd.rst index 67dc46373a91..8e4be9129e75 100644 --- a/Documentation/userspace-api/media/v4l/dev-osd.rst +++ b/Documentation/userspace-api/media/v4l/dev-osd.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _osd: @@ -51,7 +44,7 @@ other information, the physical address of the framebuffer in the ``base`` field of struct :c:type:`v4l2_framebuffer`. The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same address in the ``smem_start`` field of struct -struct :c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` +:c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` ioctl and struct :c:type:`fb_fix_screeninfo` are defined in the ``linux/fb.h`` header file. diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst index e4f2a1d8b0fc..eadcb4aa813b 100644 --- a/Documentation/userspace-api/media/v4l/dev-output.rst +++ b/Documentation/userspace-api/media/v4l/dev-output.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _output: @@ -25,7 +19,6 @@ device. .. note:: The same device file names are used also for video capture devices. - Querying Capabilities ===================== @@ -39,7 +32,6 @@ functions they may also support the :ref:`raw VBI output <raw-vbi>` streaming I/O methods must be supported. Modulators and audio outputs are optional. - Supplemental Functions ====================== @@ -50,7 +42,6 @@ Video output devices shall support :ref:`audio output <audio>`, :ref:`video output <video>` ioctls must be supported by all video output devices. - Image Format Negotiation ======================== @@ -60,7 +51,7 @@ the latter how images are stored in memory, i. e. in RGB or YUV format, the number of bits per pixel or width and height. Together they also define how images are scaled in the process. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then writing to it as if it was a plain file. Well written V4L2 applications ensure they really get what they want, including cropping and scaling. @@ -99,7 +90,6 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. - Writing Images ============== diff --git a/Documentation/userspace-api/media/v4l/dev-overlay.rst b/Documentation/userspace-api/media/v4l/dev-overlay.rst index 7246d560173d..d52977120b41 100644 --- a/Documentation/userspace-api/media/v4l/dev-overlay.rst +++ b/Documentation/userspace-api/media/v4l/dev-overlay.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _overlay: @@ -44,6 +37,10 @@ capturing and overlay. Optionally these drivers may also permit capturing and overlay with a single file descriptor for compatibility with V4L and earlier versions of V4L2. [#f1]_ +A common application of two file descriptors is the X11 +:ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. +While the X server controls video overlay, the application can take +advantage of memory mapping and DMA. Querying Capabilities ===================== @@ -70,6 +67,7 @@ ioctls must be supported by all video overlay devices. Setup ===== +*Note: support for this has been removed.* Before overlay can commence applications must program the driver with frame buffer parameters, namely the address and size of the frame buffer and the image format, for example RGB 5:6:5. The @@ -95,11 +93,13 @@ A driver may support any (or none) of five clipping/blending methods: 1. Chroma-keying displays the overlaid image only where pixels in the primary graphics surface assume a certain color. -2. A bitmap can be specified where each bit corresponds to a pixel in +2. *Note: support for this has been removed.* + A bitmap can be specified where each bit corresponds to a pixel in the overlaid image. When the bit is set, the corresponding video pixel is displayed, otherwise a pixel of the graphics surface. -3. A list of clipping rectangles can be specified. In these regions *no* +3. *Note: support for this has been removed.* + A list of clipping rectangles can be specified. In these regions *no* video is displayed, so the graphics surface can be seen here. 4. The framebuffer has an alpha channel that can be used to clip or @@ -188,6 +188,7 @@ struct v4l2_window be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host. ``struct v4l2_clip * clips`` + *Note: support for this has been removed.* When chroma-keying has *not* been negotiated and :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, applications can set this field to point to an array of clipping @@ -204,6 +205,7 @@ struct v4l2_window are undefined. ``__u32 clipcount`` + *Note: support for this has been removed.* When the application set the ``clips`` field, this field must contain the number of clipping rectangles in the list. When clip lists are not supported the driver ignores this field, its contents @@ -211,6 +213,7 @@ struct v4l2_window supported but no clipping is desired this field must be set to zero. ``void * bitmap`` + *Note: support for this has been removed.* When chroma-keying has *not* been negotiated and :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, applications can set this field to point to a clipping bit mask. @@ -296,11 +299,6 @@ To start or stop the frame buffer overlay applications call the :ref:`VIDIOC_OVERLAY` ioctl. .. [#f1] - A common application of two file descriptors is the XFree86 - :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. - While the X server controls video overlay, the application can take - advantage of memory mapping and DMA. - In the opinion of the designers of this API, no driver writer taking the efforts to support simultaneous capturing and overlay will restrict this ability by requiring a single file descriptor, as in diff --git a/Documentation/userspace-api/media/v4l/dev-radio.rst b/Documentation/userspace-api/media/v4l/dev-radio.rst index c0edd7b7d201..284ce96a1637 100644 --- a/Documentation/userspace-api/media/v4l/dev-radio.rst +++ b/Documentation/userspace-api/media/v4l/dev-radio.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _radio: diff --git a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst index 0307d44e17cb..2bec20d87928 100644 --- a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _raw-vbi: @@ -39,7 +33,6 @@ applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Accessed as ``/dev/vbi``, raw VBI capturing or output is the default device function. - Querying Capabilities ===================== @@ -48,10 +41,9 @@ Devices supporting the raw VBI capturing or output API set the in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the -read/write, streaming or asynchronous I/O methods must be supported. VBI +read/write or streaming I/O methods must be supported. VBI devices may or may not have a tuner or modulator. - Supplemental Functions ====================== @@ -60,7 +52,6 @@ VBI devices shall support :ref:`video input or output <video>`, ioctls as needed. The :ref:`video standard <standard>` ioctls provide information vital to program a VBI device, therefore must be supported. - Raw VBI Format Negotiation ========================== @@ -69,7 +60,7 @@ frequency. To properly interpret the data V4L2 specifies an ioctl to query the sampling parameters. Moreover, to allow for some flexibility applications can also suggest different parameters. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then reading from it as if it was a plain file. Well written V4L2 applications should always ensure they really get what they want, requesting reasonable @@ -98,15 +89,15 @@ happen for instance when the video and VBI areas to capture would overlap, or when the driver supports multiple opens and another process already requested VBI capturing or output. Anyway, applications must expect other resource allocation points which may return ``EBUSY``, at the -:ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>` -, :ref:`write() <func-write>` and :ref:`select() <func-select>` calls. +:ref:`VIDIOC_STREAMON` ioctl and the first :c:func:`read()` +, :c:func:`write()` and :c:func:`select()` calls. VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. -.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.5cm}| .. c:type:: v4l2_vbi_format @@ -189,8 +180,7 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does - This array is reserved for future extensions. Drivers and applications must set it to zero. - -.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.4cm}| .. _vbifmt-flags: @@ -225,7 +215,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does non-zero. - .. _vbi-hsync: .. kernel-figure:: vbi_hsync.svg @@ -234,7 +223,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does **Figure 4.1. Line synchronization** - .. _vbi-525: .. kernel-figure:: vbi_525.svg @@ -258,7 +246,6 @@ negotiation, or after switching the video standard which may invalidate the negotiated VBI parameters, should be refused by the driver. A format change during active I/O is not permitted. - Reading and writing VBI images ============================== @@ -268,7 +255,6 @@ consisting of two fields of VBI images immediately following in memory. The total size of a frame computes as follows: - .. code-block:: c (count[0] + count[1]) * samples_per_line * sample size in bytes @@ -283,8 +269,8 @@ The latter bears the possibility of synchronizing video and VBI data by using buffer timestamps. Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the -first :ref:`read() <func-read>`, :ref:`write() <func-write>` and -:ref:`select() <func-select>` call can be resource allocation +first :c:func:`read()`, :c:func:`write()` and +:c:func:`select()` call can be resource allocation points returning an ``EBUSY`` error code if the required hardware resources are temporarily unavailable, for example the device is already in use by another process. diff --git a/Documentation/userspace-api/media/v4l/dev-rds.rst b/Documentation/userspace-api/media/v4l/dev-rds.rst index 13dba4a4180c..b1dadc24561f 100644 --- a/Documentation/userspace-api/media/v4l/dev-rds.rst +++ b/Documentation/userspace-api/media/v4l/dev-rds.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _rds: @@ -35,7 +29,6 @@ The RDS interface does not support this format. Should support for MMBS the linux-media mailing list: `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. - Querying Capabilities ===================== @@ -75,35 +68,29 @@ like program identification codes and radio text, the flag :ref:`Writing RDS data <writing-rds-data>` and :ref:`FM Transmitter Control Reference <fm-tx-controls>`. - .. _reading-rds-data: Reading RDS data ================ RDS data can be read from the radio device with the -:ref:`read() <func-read>` function. The data is packed in groups of +:c:func:`read()` function. The data is packed in groups of three bytes. - .. _writing-rds-data: Writing RDS data ================ RDS data can be written to the radio device with the -:ref:`write() <func-write>` function. The data is packed in groups of +:c:func:`write()` function. The data is packed in groups of three bytes, as follows: - RDS datastructures ================== - .. c:type:: v4l2_rds_data -.. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}| - .. flat-table:: struct v4l2_rds_data :header-rows: 0 :stub-columns: 0 @@ -120,7 +107,6 @@ RDS datastructures - Block description - .. _v4l2-rds-block: .. tabularcolumns:: |p{2.9cm}|p{14.6cm}| @@ -143,10 +129,9 @@ RDS datastructures reception of this block. - .. _v4l2-rds-block-codes: -.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.0cm}| .. flat-table:: Block defines :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-sdr.rst b/Documentation/userspace-api/media/v4l/dev-sdr.rst index c9563bca444e..dfdeddbca41f 100644 --- a/Documentation/userspace-api/media/v4l/dev-sdr.rst +++ b/Documentation/userspace-api/media/v4l/dev-sdr.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _sdr: @@ -41,7 +34,7 @@ Devices supporting the SDR transmitter interface set the device has an Digital to Analog Converter (DAC), which is a mandatory element for the SDR transmitter. -At least one of the read/write, streaming or asynchronous I/O methods +At least one of the read/write or streaming I/O methods must be supported. @@ -78,7 +71,7 @@ field of a struct :c:type:`v4l2_format` to ``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use the struct :c:type:`v4l2_sdr_format` ``sdr`` member of the ``fmt`` union as needed per the desired operation. Currently -there is two fields, ``pixelformat`` and ``buffersize``, of struct +there are two fields, ``pixelformat`` and ``buffersize``, of struct :c:type:`v4l2_sdr_format` which are used. Content of the ``pixelformat`` is V4L2 FourCC code of the data format. The ``buffersize`` field is maximum buffer size in bytes required for @@ -87,7 +80,7 @@ data transfer, set by the driver in order to inform application. .. c:type:: v4l2_sdr_format -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_sdr_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index dd0b6646beb5..42cdb0a9f786 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _sliced: @@ -34,7 +28,6 @@ however the default function here is video capturing or output. Different file descriptors must be used to pass raw and sliced VBI data simultaneously, if this is supported by the driver. - Querying Capabilities ===================== @@ -43,10 +36,9 @@ Devices supporting the sliced VBI capturing or output API set the respectively, in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the -read/write, streaming or asynchronous :ref:`I/O methods <io>` must be +read/write or streaming :ref:`I/O methods <io>` must be supported. Sliced VBI devices may have a tuner or modulator. - Supplemental Functions ====================== @@ -56,7 +48,6 @@ capabilities, and they may support :ref:`control` ioctls. The :ref:`video standard <standard>` ioctls provide information vital to program a sliced VBI device, therefore must be supported. - .. _sliced-vbi-format-negotitation: Sliced VBI Format Negotiation @@ -103,9 +94,8 @@ at this point, it may return an ``EBUSY`` error code if the required resources are temporarily unavailable. Other resource allocation points which may return ``EBUSY`` can be the :ref:`VIDIOC_STREAMON` ioctl and the first -:ref:`read() <func-read>`, :ref:`write() <func-write>` and -:ref:`select() <func-select>` call. - +:c:func:`read()`, :c:func:`write()` and +:c:func:`select()` call. .. c:type:: v4l2_sliced_vbi_format @@ -118,7 +108,7 @@ struct v4l2_sliced_vbi_format \scriptsize \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.4cm}|p{4.4cm}|p{4.4cm}| +.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.45cm}|p{4.45cm}|p{4.45cm}| .. cssclass:: longtable @@ -127,7 +117,7 @@ struct v4l2_sliced_vbi_format :stub-columns: 0 :widths: 3 3 2 2 2 - * - __u32 + * - __u16 - ``service_set`` - :cspan:`2` @@ -198,7 +188,7 @@ struct v4l2_sliced_vbi_format * - __u32 - ``io_size`` - :cspan:`2` Maximum number of bytes passed by one - :ref:`read() <func-read>` or :ref:`write() <func-write>` call, + :c:func:`read()` or :c:func:`write()` call, and the buffer size in bytes for the :ref:`VIDIOC_QBUF` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field @@ -223,9 +213,9 @@ Sliced VBI services .. raw:: latex - \scriptsize + \footnotesize -.. tabularcolumns:: |p{4.1cm}|p{1.1cm}|p{2.4cm}|p{2.0cm}|p{7.3cm}| +.. tabularcolumns:: |p{4.2cm}|p{1.1cm}|p{2.1cm}|p{2.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 1 @@ -263,13 +253,7 @@ Sliced VBI services :ref:`en300294` - PAL/SECAM line 23 - - - - :: - - Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + - See :ref:`v4l2-sliced-wss-625-payload` below. * - ``V4L2_SLICED_VBI_525`` - 0x1000 - :cspan:`2` Set of services applicable to 525 line systems. @@ -281,7 +265,6 @@ Sliced VBI services \normalsize - Drivers may return an ``EINVAL`` error code when applications attempt to read or write data without prior format negotiation, after switching the video standard (which may invalidate the negotiated VBI parameters) and @@ -291,13 +274,27 @@ return an ``EBUSY`` error code when applications attempt to change the format while i/o is in progress (between a :ref:`VIDIOC_STREAMON` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first -:ref:`read() <func-read>` or :ref:`write() <func-write>` call). +:c:func:`read()` or :c:func:`write()` call). + +.. _v4l2-sliced-wss-625-payload: + +V4L2_SLICED_WSS_625 payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The payload for ``V4L2_SLICED_WSS_625`` is: + +-----+------------------+-----------------------+ + |Byte | 0 | 1 | + +-----+--------+---------+-----------+-----------+ + | | msb | lsb | msb | lsb | + | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 | + +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ Reading and writing sliced VBI data =================================== -A single :ref:`read() <func-read>` or :ref:`write() <func-write>` +A single :c:func:`read()` or :c:func:`write()` call must pass all data belonging to one video frame. That is an array of struct :c:type:`v4l2_sliced_vbi_data` structures with one or more elements and a total size not exceeding ``io_size`` bytes. Likewise @@ -305,13 +302,12 @@ in streaming I/O mode one buffer of ``io_size`` bytes must contain data of one video frame. The ``id`` of unused struct :c:type:`v4l2_sliced_vbi_data` elements must be zero. - .. c:type:: v4l2_sliced_vbi_data struct v4l2_sliced_vbi_data --------------------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.2cm}|p{13.9cm}| .. flat-table:: :header-rows: 0 @@ -351,9 +347,8 @@ struct v4l2_sliced_vbi_data bytes at the end of this array are undefined, drivers and applications shall ignore them. - Packets are always passed in ascending line number order, without -duplicate line numbers. The :ref:`write() <func-write>` function and +duplicate line numbers. The :c:func:`write()` function and the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL`` error code when applications violate this rule. They must also return an EINVAL error code when applications pass an incorrect field or line @@ -377,7 +372,6 @@ streaming (:ref:`memory mapping <mmap>` and/or :ref:`user pointer <userp>`) I/O. The latter bears the possibility of synchronizing video and VBI data by using buffer timestamps. - Sliced VBI Data in MPEG Streams =============================== @@ -412,7 +406,6 @@ data insertion is not supported by the device. The following subsections specify the format of the embedded sliced VBI data. - MPEG Stream Embedded, Sliced VBI Data Format: NONE -------------------------------------------------- @@ -424,7 +417,6 @@ nor driver shall insert "empty" embedded sliced VBI data packets in the MPEG stream when this format is set. No MPEG stream data structures are specified for this format. - MPEG Stream Embedded, Sliced VBI Data Format: IVTV -------------------------------------------------- @@ -467,13 +459,12 @@ the end with unspecified fill bytes to align the end of the payload to a with 18 lines/field with 43 bytes of data/line and a 4 byte magic number). - .. c:type:: v4l2_mpeg_vbi_fmt_ivtv struct v4l2_mpeg_vbi_fmt_ivtv ----------------------------- -.. tabularcolumns:: |p{1.0cm}|p{3.8cm}|p{1.0cm}|p{11.2cm}| +.. tabularcolumns:: |p{4.2cm}|p{2.0cm}|p{11.1cm}| .. flat-table:: :header-rows: 0 @@ -499,7 +490,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv - An alternate form of the sliced VBI data payload used when 36 lines of sliced VBI data are present. No line masks are provided in this form of the payload; all valid line mask bits are - implcitly set. + implicitly set. * - } - @@ -508,7 +499,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field ------------------------------------------------------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: :header-rows: 1 @@ -530,7 +521,6 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field valid and that 36 lines of sliced VBI data are present. - .. c:type:: v4l2_mpeg_vbi_itv0 .. c:type:: v4l2_mpeg_vbi_ITV0 @@ -538,7 +528,11 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 ------------------------------------------------- -.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{4.6cm}|p{2.0cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -555,7 +549,6 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 value: - :: linemask[0] b0: line 6 first field @@ -580,14 +573,16 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 one line of unspecified data that should be ignored by applications. +.. raw:: latex + \normalsize .. _v4l2-mpeg-vbi-itv0-1: struct v4l2_mpeg_vbi_ITV0 ------------------------- -.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| +.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.7cm}| .. flat-table:: :header-rows: 0 @@ -603,13 +598,12 @@ struct v4l2_mpeg_vbi_ITV0 lines 6 through 23 of the second field. - .. c:type:: v4l2_mpeg_vbi_itv0_line struct v4l2_mpeg_vbi_itv0_line ------------------------------ -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: :header-rows: 0 @@ -626,13 +620,12 @@ struct v4l2_mpeg_vbi_itv0_line - The sliced VBI data for the line. - .. _ITV0-Line-Identifier-Constants: Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field ------------------------------------------------------------ -.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.5cm}| .. flat-table:: :header-rows: 1 @@ -660,7 +653,6 @@ Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field description of the line payload. - .. [#f1] According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first field and lines 5-22 of the second field may carry Teletext data. diff --git a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst index 4a26646eeec5..35ed05f2695e 100644 --- a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst @@ -180,7 +180,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -208,7 +208,7 @@ Initialization follows standard semantics. ``V4L2_MEMORY_USERPTR`` is not supported for ``CAPTURE`` buffers. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to allocated number of buffers, in case the codec requires diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst index 134d2fb909fa..43988516acdd 100644 --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _subdev: @@ -36,6 +29,8 @@ will feature a character device node on which ioctls can be called to - negotiate image formats on individual pads +- inspect and modify internal data routing between pads of the same entity + Sub-device character device nodes, conventionally named ``/dev/v4l-subdev*``, use major number 81. @@ -216,9 +211,11 @@ list entity names and pad numbers). .. raw:: latex + \begingroup \scriptsize + \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}| +.. tabularcolumns:: |p{2.0cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}| .. _sample-pipeline-config: @@ -305,7 +302,7 @@ list entity names and pad numbers). .. raw:: latex - \normalsize + \endgroup 1. Initial state. The sensor source pad format is set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the @@ -409,6 +406,8 @@ pixel array is not rectangular but cross-shaped or round. The maximum size may also be smaller than the BOUNDS rectangle. +.. _format-propagation: + Order of configuration and format propagation --------------------------------------------- @@ -506,3 +505,164 @@ source pads. :maxdepth: 1 subdev-formats + +Streams, multiplexed media pads and internal routing +---------------------------------------------------- + +Simple V4L2 sub-devices do not support multiple, unrelated video streams, +and only a single stream can pass through a media link and a media pad. +Thus each pad contains a format and selection configuration for that +single stream. A subdev can do stream processing and split a stream into +two or compose two streams into one, but the inputs and outputs for the +subdev are still a single stream per pad. + +Some hardware, e.g. MIPI CSI-2, support multiplexed streams, that is, multiple +data streams are transmitted on the same bus, which is represented by a media +link connecting a transmitter source pad with a sink pad on the receiver. For +example, a camera sensor can produce two distinct streams, a pixel stream and a +metadata stream, which are transmitted on the multiplexed data bus, represented +by a media link which connects the single sensor's source pad with the receiver +sink pad. The stream-aware receiver will de-multiplex the streams received on +the its sink pad and allows to route them individually to one of its source +pads. + +Subdevice drivers that support multiplexed streams are compatible with +non-multiplexed subdev drivers, but, of course, require a routing configuration +where the link between those two types of drivers contains only a single +stream. + +Understanding streams +^^^^^^^^^^^^^^^^^^^^^ + +A stream is a stream of content (e.g. pixel data or metadata) flowing through +the media pipeline from a source (e.g. a sensor) towards the final sink (e.g. a +receiver and demultiplexer in a SoC). Each media link carries all the enabled +streams from one end of the link to the other, and sub-devices have routing +tables which describe how the incoming streams from sink pads are routed to the +source pads. + +A stream ID is a media pad-local identifier for a stream. Streams IDs of +the same stream must be equal on both ends of a link. In other words, +a particular stream ID must exist on both sides of a media +link, but another stream ID can be used for the same stream at the other side +of the sub-device. + +A stream at a specific point in the media pipeline is identified by the +sub-device and a (pad, stream) pair. For sub-devices that do not support +multiplexed streams the 'stream' field is always 0. + +Interaction between routes, streams, formats and selections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The addition of streams to the V4L2 sub-device interface moves the sub-device +formats and selections from pads to (pad, stream) pairs. Besides the +usual pad, also the stream ID needs to be provided for setting formats and +selections. The order of configuring formats and selections along a stream is +the same as without streams (see :ref:`format-propagation`). + +Instead of the sub-device wide merging of streams from all sink pads +towards all source pads, data flows for each route are separate from each +other. Any number of routes from streams on sink pads towards streams on +source pads is allowed, to the extent supported by drivers. For every +stream on a source pad, however, only a single route is allowed. + +Any configurations of a stream within a pad, such as format or selections, +are independent of similar configurations on other streams. This is +subject to change in the future. + +Configuring streams +^^^^^^^^^^^^^^^^^^^ + +The configuration of the streams is done individually for each sub-device and +the validity of the streams between sub-devices is validated when the pipeline +is started. + +There are three steps in configuring the streams: + +1. Set up links. Connect the pads between sub-devices using the + :ref:`Media Controller API <media_controller>` + +2. Streams. Streams are declared and their routing is configured by setting the + routing table for the sub-device using :ref:`VIDIOC_SUBDEV_S_ROUTING + <VIDIOC_SUBDEV_G_ROUTING>` ioctl. Note that setting the routing table will + reset formats and selections in the sub-device to default values. + +3. Configure formats and selections. Formats and selections of each stream are + configured separately as documented for plain sub-devices in + :ref:`format-propagation`. The stream ID is set to the same stream ID + associated with either sink or source pads of routes configured using the + :ref:`VIDIOC_SUBDEV_S_ROUTING <VIDIOC_SUBDEV_G_ROUTING>` ioctl. + +Multiplexed streams setup example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A simple example of a multiplexed stream setup might be as follows: + +- Two identical sensors (Sensor A and Sensor B). Each sensor has a single source + pad (pad 0) which carries a pixel data stream. + +- Multiplexer bridge (Bridge). The bridge has two sink pads, connected to the + sensors (pads 0, 1), and one source pad (pad 2), which outputs two streams. + +- Receiver in the SoC (Receiver). The receiver has a single sink pad (pad 0), + connected to the bridge, and two source pads (pads 1-2), going to the DMA + engine. The receiver demultiplexes the incoming streams to the source pads. + +- DMA Engines in the SoC (DMA Engine), one for each stream. Each DMA engine is + connected to a single source pad in the receiver. + +The sensors, the bridge and the receiver are modeled as V4L2 sub-devices, +exposed to userspace via /dev/v4l-subdevX device nodes. The DMA engines are +modeled as V4L2 devices, exposed to userspace via /dev/videoX nodes. + +To configure this pipeline, the userspace must take the following steps: + +1. Set up media links between entities: connect the sensors to the bridge, + bridge to the receiver, and the receiver to the DMA engines. This step does + not differ from normal non-multiplexed media controller setup. + +2. Configure routing + +.. flat-table:: Bridge routing table + :header-rows: 1 + + * - Sink Pad/Stream + - Source Pad/Stream + - Routing Flags + - Comments + * - 0/0 + - 2/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor A + * - 1/0 + - 2/1 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor B + +.. flat-table:: Receiver routing table + :header-rows: 1 + + * - Sink Pad/Stream + - Source Pad/Stream + - Routing Flags + - Comments + * - 0/0 + - 1/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor A + * - 0/1 + - 2/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor B + +3. Configure formats and selections + + After configuring routing, the next step is configuring the formats and + selections for the streams. This is similar to performing this step without + streams, with just one exception: the ``stream`` field needs to be assigned + to the value of the stream ID. + + A common way to accomplish this is to start from the sensors and propagate + the configurations along the stream towards the receiver, using + :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls to configure each + stream endpoint in each sub-device. diff --git a/Documentation/userspace-api/media/v4l/dev-touch.rst b/Documentation/userspace-api/media/v4l/dev-touch.rst index c1ce446274f2..a71b9def5d58 100644 --- a/Documentation/userspace-api/media/v4l/dev-touch.rst +++ b/Documentation/userspace-api/media/v4l/dev-touch.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _touch: diff --git a/Documentation/userspace-api/media/v4l/devices.rst b/Documentation/userspace-api/media/v4l/devices.rst index 47ffe90753dd..8bfbad65a9d4 100644 --- a/Documentation/userspace-api/media/v4l/devices.rst +++ b/Documentation/userspace-api/media/v4l/devices.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _devices: diff --git a/Documentation/userspace-api/media/v4l/diff-v4l.rst b/Documentation/userspace-api/media/v4l/diff-v4l.rst index 37644d26c4ae..33243ecb5033 100644 --- a/Documentation/userspace-api/media/v4l/diff-v4l.rst +++ b/Documentation/userspace-api/media/v4l/diff-v4l.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _diff-v4l: @@ -20,7 +14,6 @@ the much improved V4L2 API replaces the V4L API. The support for the old V4L calls were removed from Kernel, but the library :ref:`libv4l` supports the conversion of a V4L API system call into a V4L2 one. - Opening and Closing Devices =========================== @@ -39,7 +32,6 @@ recommend that V4L2 drivers by default register devices with the same numbers, but the system administrator can assign arbitrary minor numbers using driver module options. The major device number remains 81. - .. _v4l-dev: .. flat-table:: V4L Device Types, Names and Numbers @@ -60,14 +52,12 @@ using driver module options. The major device number remains 81. - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31`` - 224-255 - V4L prohibits (or used to prohibit) multiple opens of a device file. V4L2 drivers *may* support multiple opens, see :ref:`open` for details and consequences. V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code. - Querying Capabilities ===================== @@ -82,7 +72,11 @@ and radio devices supporting a set of related functions like video capturing, video overlay and VBI capturing. See :ref:`open` for an introduction. -.. tabularcolumns:: |p{5.5cm}|p{6.5cm}|p{5.5cm} +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}| .. cssclass:: longtable @@ -158,6 +152,9 @@ introduction. - ``-`` - See above. +.. raw:: latex + + \normalsize The ``audios`` field was replaced by ``capabilities`` flag ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or @@ -171,7 +168,6 @@ were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or dimensions returns the closest size possible, taking into account the current video standard, cropping and scaling limitations. - Video Sources ============= @@ -187,7 +183,6 @@ The ``channel`` field counting inputs was renamed to ``index``, the video input types were renamed as follows: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -199,7 +194,6 @@ video input types were renamed as follows: * - ``VIDEO_TYPE_CAMERA`` - ``V4L2_INPUT_TYPE_CAMERA`` - Unlike the ``tuners`` field expressing the number of tuners of this input, V4L2 assumes each video input is connected to at most one tuner. However a tuner can have more than one input, i. e. RF connectors, and a @@ -223,7 +217,6 @@ addition together with the ``norm`` field and has been removed in the meantime. V4L2 has a similar, albeit more comprehensive approach to video standards, see :ref:`standard` for more information. - Tuning ====== @@ -267,7 +260,6 @@ frequency where renamed to to a struct :c:type:`v4l2_frequency` instead of an unsigned long integer. - .. _v4l-image-properties: Image Properties @@ -281,7 +273,6 @@ replaced by V4L2 controls accessible with the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -299,7 +290,6 @@ replaced by V4L2 controls accessible with the * - ``whiteness`` - ``V4L2_CID_WHITENESS`` - The V4L picture controls are assumed to range from 0 to 65535 with no particular reset value. The V4L2 API permits arbitrary limits and defaults which can be queried with the @@ -313,7 +303,6 @@ of the image depth and others need not know. The ``palette`` field moved into the struct :c:type:`v4l2_pix_format`: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -353,11 +342,9 @@ into the struct :c:type:`v4l2_pix_format`: * - ``VIDEO_PALETTE_YUV410P`` - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>` - V4L2 image formats are defined in :ref:`pixfmt`. The image format can be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. - Audio ===== @@ -391,7 +378,6 @@ The following fields where replaced by V4L2 controls accessible with the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -407,7 +393,6 @@ The following fields where replaced by V4L2 controls accessible with the * - ``balance`` - ``V4L2_CID_AUDIO_BALANCE`` - To determine which of these controls are supported by a driver V4L provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``, ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the @@ -423,7 +408,6 @@ V4L2 API permits arbitrary limits and defaults which can be queried with the :ref:`VIDIOC_QUERYCTRL` ioctl. For general information about controls see :ref:`control`. - Frame Buffer Overlay ==================== @@ -470,7 +454,6 @@ size is determined by ``w.width`` and ``w.height``. The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to :ref:`VIDIOC_OVERLAY`. - Cropping ======== @@ -497,21 +480,19 @@ struct :c:type:`v4l2_window`. These structures are used to select a capture or overlay format with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. - Reading Images, Memory Mapping ============================== - Capturing using the read method ------------------------------- There is no essential difference between reading images from a V4L or -V4L2 device using the :ref:`read() <func-read>` function, however V4L2 +V4L2 device using the :c:func:`read()` function, however V4L2 drivers are not required to support this I/O method. Applications can determine if the function is available with the :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices exchanging data with applications must support the -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` +:c:func:`select()` and :c:func:`poll()` functions. To select an image format and size, V4L provides the ``VIDIOCSPICT`` and @@ -524,7 +505,6 @@ negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and For more information about the V4L2 read interface see :ref:`rw`. - Capturing using memory mapping ------------------------------ @@ -535,7 +515,6 @@ read method. V4L2 supports memory mapping as well, with a few differences. - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -557,7 +536,7 @@ differences. ``VIDIOCGMBUF`` ioctl is available to query the number of buffers, the offset of each buffer from the start of the virtual file, and the overall amount of memory used, which can be used as arguments - for the :ref:`mmap() <func-mmap>` function. + for the :c:func:`mmap()` function. - Buffers are individually mapped. The offset and size of each buffer can be determined with the :ref:`VIDIOC_QUERYBUF` ioctl. @@ -575,7 +554,7 @@ differences. the incoming queue. Filled buffers are dequeued from the outgoing queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait until filled buffers become available this function, - :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can + :c:func:`select()` or :c:func:`poll()` can be used. The :ref:`VIDIOC_STREAMON` ioctl must be called once after enqueuing one or more buffers to start capturing. Its counterpart @@ -584,11 +563,9 @@ differences. signal status, if known, with the :ref:`VIDIOC_ENUMINPUT` ioctl. - For a more in-depth discussion of memory mapping and examples, see :ref:`mmap`. - Reading Raw VBI Data ==================== @@ -599,7 +576,6 @@ the V4L VBI interface. Reading from the device yields a raw VBI image with the following parameters: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -623,7 +599,6 @@ with the following parameters: * - flags - 0 - Undocumented in the V4L specification, in Linux 2.3 the ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct ``vbi_format`` were added to determine the VBI image @@ -637,11 +612,10 @@ remaining fields are probably equivalent to struct Apparently only the Zoran (ZR 36120) driver implements these ioctls. The semantics differ from those specified for V4L2 in two ways. The -parameters are reset on :ref:`open() <func-open>` and +parameters are reset on :c:func:`open()` and ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters are invalid. - Miscellaneous ============= diff --git a/Documentation/userspace-api/media/v4l/dmabuf.rst b/Documentation/userspace-api/media/v4l/dmabuf.rst index 342421ff9497..50fba11c2477 100644 --- a/Documentation/userspace-api/media/v4l/dmabuf.rst +++ b/Documentation/userspace-api/media/v4l/dmabuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _dmabuf: @@ -43,7 +37,6 @@ are passed in struct :c:type:`v4l2_buffer` (or in struct driver must be switched into DMABUF I/O mode by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type. - Example: Initiating streaming I/O with DMABUF file descriptors ============================================================== @@ -142,10 +135,10 @@ buffers it must wait until an empty buffer can be dequeued and reused. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the -``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, +``O_NONBLOCK`` flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` error code when no buffer is available. The -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` +:c:func:`select()` and :c:func:`poll()` functions are always available. To start and stop capturing or displaying applications call the @@ -165,5 +158,5 @@ Drivers implementing DMABUF importing I/O must support the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, -and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>` +and the :c:func:`select()` and :c:func:`poll()` functions. diff --git a/Documentation/userspace-api/media/v4l/dv-timings.rst b/Documentation/userspace-api/media/v4l/dv-timings.rst index e216aa9edef0..4b19bcb4bd80 100644 --- a/Documentation/userspace-api/media/v4l/dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/dv-timings.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dv-timings: @@ -40,6 +33,27 @@ current DV timings they use the the DV timings as seen by the video receiver applications use the :ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl. +When the hardware detects a video source change (e.g. the video +signal appears or disappears, or the video resolution changes), then +it will issue a `V4L2_EVENT_SOURCE_CHANGE` event. Use the +:ref:`ioctl VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` and the +:ref:`VIDIOC_DQEVENT` to check if this event was reported. + +If the video signal changed, then the application has to stop +streaming, free all buffers, and call the :ref:`VIDIOC_QUERY_DV_TIMINGS` +to obtain the new video timings, and if they are valid, it can set +those by calling the :ref:`ioctl VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`. +This will also update the format, so use the :ref:`ioctl VIDIOC_G_FMT <VIDIOC_G_FMT>` +to obtain the new format. Now the application can allocate new buffers +and start streaming again. + +The :ref:`VIDIOC_QUERY_DV_TIMINGS` will just report what the +hardware detects, it will never change the configuration. If the +currently set timings and the actually detected timings differ, then +typically this will mean that you will not be able to capture any +video. The correct approach is to rely on the `V4L2_EVENT_SOURCE_CHANGE` +event so you know when something changed. + Applications can make use of the :ref:`input-capabilities` and :ref:`output-capabilities` flags to determine whether the digital video ioctls can be used with the given input or output. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst index d9a117f75c9c..cdc515c60468 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _camera-controls: @@ -39,6 +32,7 @@ enum v4l2_exposure_auto_type - should ignore such requests. Possible values are: +.. tabularcolumns:: |p{7.1cm}|p{10.4cm}| .. flat-table:: :header-rows: 0 @@ -88,7 +82,7 @@ enum v4l2_exposure_metering - Determines how the camera measures the amount of light available for the frame exposure. Possible values are: -.. tabularcolumns:: |p{8.7cm}|p{8.8cm}| +.. tabularcolumns:: |p{8.7cm}|p{8.7cm}| .. flat-table:: :header-rows: 0 @@ -180,7 +174,7 @@ enum v4l2_exposure_metering - control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS`` control value. -.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -206,7 +200,7 @@ enum v4l2_exposure_metering - enum v4l2_auto_focus_range - Determines auto focus distance range for which lens may be adjusted. -.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| +.. tabularcolumns:: |p{6.9cm}|p{10.6cm}| .. flat-table:: :header-rows: 0 @@ -281,7 +275,7 @@ enum v4l2_auto_n_preset_white_balance - representation. The following white balance presets are listed in order of increasing color temperature. -.. tabularcolumns:: |p{7.2 cm}|p{10.3cm}| +.. tabularcolumns:: |p{7.4cm}|p{10.1cm}| .. flat-table:: :header-rows: 0 @@ -391,7 +385,9 @@ enum v4l2_scene_mode - \small -.. tabularcolumns:: |p{5.9cm}|p{11.5cm}| +.. tabularcolumns:: |p{5.9cm}|p{11.6cm}| + +.. cssclass:: longtable .. flat-table:: :header-rows: 0 @@ -510,6 +506,8 @@ enum v4l2_scene_mode - value down. A value of zero stops the motion if one is in progress and has no effect otherwise. +.. _v4l2-camera-sensor-orientation: + ``V4L2_CID_CAMERA_ORIENTATION (menu)`` This read-only control describes the camera orientation by reporting its mounting position on the device where the camera is installed. The control @@ -526,6 +524,7 @@ enum v4l2_scene_mode - have the ``V4L2_CAMERA_ORIENTATION_EXTERNAL`` orientation. +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| .. flat-table:: :header-rows: 0 @@ -539,6 +538,7 @@ enum v4l2_scene_mode - - The camera is not directly attached to the device and is freely movable. +.. _v4l2-camera-sensor-rotation: ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)`` This read-only control describes the rotation correction in degrees in the @@ -664,3 +664,11 @@ enum v4l2_scene_mode - .. [#f1] This control may be changed to a menu control in the future, if more options are required. + +``V4L2_CID_HDR_SENSOR_MODE (menu)`` + Change the sensor HDR mode. A HDR picture is obtained by merging two + captures of the same scene using two different exposure periods. HDR mode + describes the way these two captures are merged in the sensor. + + As modes differ for each sensor, menu items are not standardized by this + control and are left to the programmer. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst new file mode 100644 index 000000000000..786127b1e206 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -0,0 +1,4164 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _codec-stateless-controls: + +********************************* +Stateless Codec Control Reference +********************************* + +The Stateless Codec control class is intended to support +stateless decoder and encoders (i.e. hardware accelerators). + +These drivers are typically supported by the :ref:`stateless_decoder`, +and deal with parsed pixel formats such as V4L2_PIX_FMT_H264_SLICE. + +Stateless Codec Control ID +========================== + +.. _codec-stateless-control-id: + +``V4L2_CID_CODEC_STATELESS_CLASS (class)`` + The Stateless Codec class descriptor. + +.. _v4l2-codec-stateless-h264: + +``V4L2_CID_STATELESS_H264_SPS (struct)`` + Specifies the sequence parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_sps + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| + +.. flat-table:: struct v4l2_ctrl_h264_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``profile_idc`` + - + * - __u8 + - ``constraint_set_flags`` + - See :ref:`Sequence Parameter Set Constraints Set Flags <h264_sps_constraints_set_flags>` + * - __u8 + - ``level_idc`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``chroma_format_idc`` + - + * - __u8 + - ``bit_depth_luma_minus8`` + - + * - __u8 + - ``bit_depth_chroma_minus8`` + - + * - __u8 + - ``log2_max_frame_num_minus4`` + - + * - __u8 + - ``pic_order_cnt_type`` + - + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - + * - __u8 + - ``max_num_ref_frames`` + - + * - __u8 + - ``num_ref_frames_in_pic_order_cnt_cycle`` + - + * - __s32 + - ``offset_for_ref_frame[255]`` + - + * - __s32 + - ``offset_for_non_ref_pic`` + - + * - __s32 + - ``offset_for_top_to_bottom_field`` + - + * - __u16 + - ``pic_width_in_mbs_minus1`` + - + * - __u16 + - ``pic_height_in_map_units_minus1`` + - + * - __u32 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_sps_constraints_set_flags: + +``Sequence Parameter Set Constraints Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG`` + - 0x00000020 + - + +.. _h264_sps_flags: + +``Sequence Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD`` + - 0x00000020 + - + * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE`` + - 0x00000040 + - + +``V4L2_CID_STATELESS_H264_PPS (struct)`` + Specifies the picture parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_pps + +.. raw:: latex + + \small + +.. flat-table:: struct v4l2_ctrl_h264_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``pic_parameter_set_id`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``num_slice_groups_minus1`` + - + * - __u8 + - ``num_ref_idx_l0_default_active_minus1`` + - + * - __u8 + - ``num_ref_idx_l1_default_active_minus1`` + - + * - __u8 + - ``weighted_bipred_idc`` + - + * - __s8 + - ``pic_init_qp_minus26`` + - + * - __s8 + - ``pic_init_qs_minus26`` + - + * - __s8 + - ``chroma_qp_index_offset`` + - + * - __s8 + - ``second_chroma_qp_index_offset`` + - + * - __u16 + - ``flags`` + - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_pps_flags: + +``Picture Parameter Set Flags`` + +.. raw:: latex + + \begingroup + \scriptsize + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{9.8cm}|p{1.0cm}|p{6.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 10 1 4 + + * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` + - 0x0001 + - + * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` + - 0x0002 + - + * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` + - 0x0004 + - + * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` + - 0x0008 + - + * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x0010 + - + * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` + - 0x0020 + - + * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` + - 0x0040 + - + * - ``V4L2_H264_PPS_FLAG_SCALING_MATRIX_PRESENT`` + - 0x0080 + - ``V4L2_CID_STATELESS_H264_SCALING_MATRIX`` + must be used for this picture. + +.. raw:: latex + + \endgroup + +``V4L2_CID_STATELESS_H264_SCALING_MATRIX (struct)`` + Specifies the scaling matrix (as extracted from the bitstream) for + the associated H264 slice data. The bitstream parameters are + defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling + List Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_scaling_matrix + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{0.6cm}|p{4.8cm}|p{11.9cm}| + +.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``scaling_list_4x4[6][16]`` + - Scaling matrix after applying the inverse scanning process. + Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y, + Inter Cb, Inter Cr. The values on each scaling list are + expected in raster scan order. + * - __u8 + - ``scaling_list_8x8[6][64]`` + - Scaling matrix after applying the inverse scanning process. + Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb, + Intra Cr, Inter Cr. The values on each scaling list are + expected in raster scan order. + +``V4L2_CID_STATELESS_H264_SLICE_PARAMS (struct)`` + Specifies the slice parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further + documentation, refer to the above specification, unless there is + an explicit comment stating otherwise. + +.. c:type:: v4l2_ctrl_h264_slice_params + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}| + +.. flat-table:: struct v4l2_ctrl_h264_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``header_bit_size`` + - Offset in bits to slice_data() from the beginning of this slice. + * - __u32 + - ``first_mb_in_slice`` + - + * - __u8 + - ``slice_type`` + - + * - __u8 + - ``colour_plane_id`` + - + * - __u8 + - ``redundant_pic_cnt`` + - + * - __u8 + - ``cabac_init_idc`` + - + * - __s8 + - ``slice_qp_delta`` + - + * - __s8 + - ``slice_qs_delta`` + - + * - __u8 + - ``disable_deblocking_filter_idc`` + - + * - __s8 + - ``slice_alpha_c0_offset_div2`` + - + * - __s8 + - ``slice_beta_offset_div2`` + - + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - If num_ref_idx_active_override_flag is not set, this field must be + set to the value of num_ref_idx_l0_default_active_minus1 + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - If num_ref_idx_active_override_flag is not set, this field must be + set to the value of num_ref_idx_l1_default_active_minus1 + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_h264_reference` + - ``ref_pic_list0[32]`` + - Reference picture list after applying the per-slice modifications + * - struct :c:type:`v4l2_h264_reference` + - ``ref_pic_list1[32]`` + - Reference picture list after applying the per-slice modifications + * - __u32 + - ``flags`` + - See :ref:`Slice Parameter Flags <h264_slice_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_slice_flags: + +``Slice Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED`` + - 0x00000001 + - + * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` + - 0x00000002 + - + +``V4L2_CID_STATELESS_H264_PRED_WEIGHTS (struct)`` + Prediction weight table defined according to :ref:`h264`, + section 7.4.3.2 "Prediction Weight Table Semantics". + The prediction weight table must be passed by applications + under the conditions explained in section 7.3.3 "Slice header + syntax". + +.. c:type:: v4l2_ctrl_h264_pred_weights + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.9cm}|p{4.9cm}|p{7.5cm}| + +.. flat-table:: struct v4l2_ctrl_h264_pred_weights + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``luma_log2_weight_denom`` + - + * - __u16 + - ``chroma_log2_weight_denom`` + - + * - struct :c:type:`v4l2_h264_weight_factors` + - ``weight_factors[2]`` + - The weight factors at index 0 are the weight factors for the reference + list 0, the one at index 1 for the reference list 1. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_h264_weight_factors + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.5cm}|p{11.8cm}| + +.. flat-table:: struct v4l2_h264_weight_factors + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s16 + - ``luma_weight[32]`` + - + * - __s16 + - ``luma_offset[32]`` + - + * - __s16 + - ``chroma_weight[32][2]`` + - + * - __s16 + - ``chroma_offset[32][2]`` + - + +.. raw:: latex + + \normalsize + +``Picture Reference`` + +.. c:type:: v4l2_h264_reference + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_reference + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``fields`` + - Specifies how the picture is referenced. See :ref:`Reference Fields <h264_ref_fields>` + * - __u8 + - ``index`` + - Index into the :c:type:`v4l2_ctrl_h264_decode_params`.dpb array. + +.. _h264_ref_fields: + +``Reference Fields`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.4cm}|p{0.8cm}|p{11.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_TOP_FIELD_REF`` + - 0x1 + - The top field in field pair is used for short-term reference. + * - ``V4L2_H264_BOTTOM_FIELD_REF`` + - 0x2 + - The bottom field in field pair is used for short-term reference. + * - ``V4L2_H264_FRAME_REF`` + - 0x3 + - The frame (or the top/bottom fields, if it's a field pair) + is used for short-term reference. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_H264_DECODE_PARAMS (struct)`` + Specifies the decode parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`. For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_decode_params + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}| + +.. flat-table:: struct v4l2_ctrl_h264_decode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_h264_dpb_entry` + - ``dpb[16]`` + - + * - __u16 + - ``nal_ref_idc`` + - NAL reference ID value coming from the NAL Unit header + * - __u16 + - ``frame_num`` + - + * - __s32 + - ``top_field_order_cnt`` + - Picture Order Count for the coded top field + * - __s32 + - ``bottom_field_order_cnt`` + - Picture Order Count for the coded bottom field + * - __u16 + - ``idr_pic_id`` + - + * - __u16 + - ``pic_order_cnt_lsb`` + - + * - __s32 + - ``delta_pic_order_cnt_bottom`` + - + * - __s32 + - ``delta_pic_order_cnt0`` + - + * - __s32 + - ``delta_pic_order_cnt1`` + - + * - __u32 + - ``dec_ref_pic_marking_bit_size`` + - Size in bits of the dec_ref_pic_marking() syntax element. + * - __u32 + - ``pic_order_cnt_bit_size`` + - Combined size in bits of the picture order count related syntax + elements: pic_order_cnt_lsb, delta_pic_order_cnt_bottom, + delta_pic_order_cnt0, and delta_pic_order_cnt1. + * - __u32 + - ``slice_group_change_cycle`` + - + * - __u32 + - ``reserved`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_decode_params_flags: + +``Decode Parameters Flags`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{8.3cm}|p{2.1cm}|p{6.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC`` + - 0x00000001 + - That picture is an IDR picture + * - ``V4L2_H264_DECODE_PARAM_FLAG_FIELD_PIC`` + - 0x00000002 + - + * - ``V4L2_H264_DECODE_PARAM_FLAG_BOTTOM_FIELD`` + - 0x00000004 + - + * - ``V4L2_H264_DECODE_PARAM_FLAG_PFRAME`` + - 0x00000008 + - + * - ``V4L2_H264_DECODE_PARAM_FLAG_BFRAME`` + - 0x00000010 + - + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_h264_dpb_entry + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.9cm}|p{11.4cm}| + +.. flat-table:: struct v4l2_h264_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``reference_ts`` + - Timestamp of the V4L2 capture buffer to use as reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u32 + - ``pic_num`` + - For short term references, this must match the derived value PicNum + (8-28) and for long term references it must match the derived value + LongTermPicNum (8-29). When decoding frames (as opposed to fields) + pic_num is the same as FrameNumWrap. + * - __u16 + - ``frame_num`` + - For short term references, this must match the frame_num value from + the slice header syntax (the driver will wrap the value if needed). For + long term references, this must be set to the value of + long_term_frame_idx described in the dec_ref_pic_marking() syntax. + * - __u8 + - ``fields`` + - Specifies how the DPB entry is referenced. See :ref:`Reference Fields <h264_ref_fields>` + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + * - __s32 + - ``top_field_order_cnt`` + - + * - __s32 + - ``bottom_field_order_cnt`` + - + * - __u32 + - ``flags`` + - See :ref:`DPB Entry Flags <h264_dpb_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_dpb_flags: + +``DPB Entries Flags`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.7cm}|p{2.1cm}|p{7.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID`` + - 0x00000001 + - The DPB entry is valid (non-empty) and should be considered. + * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` + - 0x00000002 + - The DPB entry is used for reference. + * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` + - 0x00000004 + - The DPB entry is used for long-term reference. + * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD`` + - 0x00000008 + - The DPB entry is a single field or a complementary field pair. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_H264_DECODE_MODE (enum)`` + Specifies the decoding mode to use. Currently exposes slice-based and + frame-based decoding but new modes might be added later on. + This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE + pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE + are required to set this control in order to specify the decoding mode + that is expected for the buffer. + Drivers may expose a single or multiple decoding modes, depending + on what they can support. + +.. c:type:: v4l2_stateless_h264_decode_mode + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_H264_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + The OUTPUT buffer must contain a single slice. + When this mode is selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` + control shall be set. When multiple slices compose a frame, + use of ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` flag + is required. + * - ``V4L2_STATELESS_H264_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity, + The OUTPUT buffer must contain all slices needed to decode the + frame. The OUTPUT buffer must also contain both fields. + This mode will be supported by devices that + parse the slice(s) header(s) in hardware. When this mode is + selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` + control shall not be set. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_H264_START_CODE (enum)`` + Specifies the H264 slice start code expected for each slice. + This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE + pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE + are required to set this control in order to specify the start code + that is expected for the buffer. + Drivers may expose a single or multiple start codes, depending + on what they can support. + +.. c:type:: v4l2_stateless_h264_start_code + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.9cm}|p{0.4cm}|p{9.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 4 1 4 + + * - ``V4L2_STATELESS_H264_START_CODE_NONE`` + - 0 + - Selecting this value specifies that H264 slices are passed + to the driver without any start code. The bitstream data should be + according to :ref:`h264` 7.3.1 NAL unit syntax, hence contains + emulation prevention bytes when required. + * - ``V4L2_STATELESS_H264_START_CODE_ANNEX_B`` + - 1 + - Selecting this value specifies that H264 slices are expected + to be prefixed by Annex B start codes. According to :ref:`h264` + valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. + +.. raw:: latex + + \normalsize + +.. _codec-stateless-fwht: + +``V4L2_CID_STATELESS_FWHT_PARAMS (struct)`` + Specifies the FWHT (Fast Walsh Hadamard Transform) parameters (as extracted + from the bitstream) for the associated FWHT data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline for FWHT. + This codec is specific to the vicodec test driver. + +.. c:type:: v4l2_ctrl_fwht_params + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.4cm}|p{3.9cm}|p{12.0cm}| + +.. flat-table:: struct v4l2_ctrl_fwht_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u32 + - ``version`` + - The version of the codec. Set to ``V4L2_FWHT_VERSION``. + * - __u32 + - ``width`` + - The width of the frame. + * - __u32 + - ``height`` + - The height of the frame. + * - __u32 + - ``flags`` + - The flags of the frame, see :ref:`fwht-flags`. + * - __u32 + - ``colorspace`` + - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. + * - __u32 + - ``xfer_func`` + - The transfer function, from enum :c:type:`v4l2_xfer_func`. + * - __u32 + - ``ycbcr_enc`` + - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. + * - __u32 + - ``quantization`` + - The quantization range, from enum :c:type:`v4l2_quantization`. + +.. raw:: latex + + \normalsize + +.. _fwht-flags: + +FWHT Flags +========== + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.3cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_FWHT_FL_IS_INTERLACED`` + - 0x00000001 + - Set if this is an interlaced format. + * - ``V4L2_FWHT_FL_IS_BOTTOM_FIRST`` + - 0x00000002 + - Set if this is a bottom-first (NTSC) interlaced format. + * - ``V4L2_FWHT_FL_IS_ALTERNATE`` + - 0x00000004 + - Set if each 'frame' contains just one field. + * - ``V4L2_FWHT_FL_IS_BOTTOM_FIELD`` + - 0x00000008 + - If V4L2_FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the + bottom field, else it is the top field. + * - ``V4L2_FWHT_FL_LUMA_IS_UNCOMPRESSED`` + - 0x00000010 + - Set if the Y' (luma) plane is uncompressed. + * - ``V4L2_FWHT_FL_CB_IS_UNCOMPRESSED`` + - 0x00000020 + - Set if the Cb plane is uncompressed. + * - ``V4L2_FWHT_FL_CR_IS_UNCOMPRESSED`` + - 0x00000040 + - Set if the Cr plane is uncompressed. + * - ``V4L2_FWHT_FL_CHROMA_FULL_HEIGHT`` + - 0x00000080 + - Set if the chroma plane has the same height as the luma plane, + else the chroma plane is half the height of the luma plane. + * - ``V4L2_FWHT_FL_CHROMA_FULL_WIDTH`` + - 0x00000100 + - Set if the chroma plane has the same width as the luma plane, + else the chroma plane is half the width of the luma plane. + * - ``V4L2_FWHT_FL_ALPHA_IS_UNCOMPRESSED`` + - 0x00000200 + - Set if the alpha plane is uncompressed. + * - ``V4L2_FWHT_FL_I_FRAME`` + - 0x00000400 + - Set if this is an I-frame. + * - ``V4L2_FWHT_FL_COMPONENTS_NUM_MSK`` + - 0x00070000 + - The number of color components minus one. + * - ``V4L2_FWHT_FL_PIXENC_MSK`` + - 0x00180000 + - The mask for the pixel encoding. + * - ``V4L2_FWHT_FL_PIXENC_YUV`` + - 0x00080000 + - Set if the pixel encoding is YUV. + * - ``V4L2_FWHT_FL_PIXENC_RGB`` + - 0x00100000 + - Set if the pixel encoding is RGB. + * - ``V4L2_FWHT_FL_PIXENC_HSV`` + - 0x00180000 + - Set if the pixel encoding is HSV. + +.. raw:: latex + + \normalsize + +.. _v4l2-codec-stateless-vp8: + +``V4L2_CID_STATELESS_VP8_FRAME (struct)`` + Specifies the frame parameters for the associated VP8 parsed frame data. + This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for VP8. + The bitstream parameters are defined according to :ref:`vp8`. + +.. c:type:: v4l2_ctrl_vp8_frame + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{4.6cm}|p{5.7cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp8_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_vp8_segment` + - ``segment`` + - Structure with segment-based adjustments metadata. + * - struct :c:type:`v4l2_vp8_loop_filter` + - ``lf`` + - Structure with loop filter level adjustments metadata. + * - struct :c:type:`v4l2_vp8_quantization` + - ``quant`` + - Structure with VP8 dequantization indices metadata. + * - struct :c:type:`v4l2_vp8_entropy` + - ``entropy`` + - Structure with VP8 entropy coder probabilities metadata. + * - struct :c:type:`v4l2_vp8_entropy_coder_state` + - ``coder_state`` + - Structure with VP8 entropy coder state. + * - __u16 + - ``width`` + - The width of the frame. Must be set for all frames. + * - __u16 + - ``height`` + - The height of the frame. Must be set for all frames. + * - __u8 + - ``horizontal_scale`` + - Horizontal scaling factor. + * - __u8 + - ``vertical_scaling factor`` + - Vertical scale. + * - __u8 + - ``version`` + - Bitstream version. + * - __u8 + - ``prob_skip_false`` + - Indicates the probability that the macroblock is not skipped. + * - __u8 + - ``prob_intra`` + - Indicates the probability that a macroblock is intra-predicted. + * - __u8 + - ``prob_last`` + - Indicates the probability that the last reference frame is used + for inter-prediction + * - __u8 + - ``prob_gf`` + - Indicates the probability that the golden reference frame is used + for inter-prediction + * - __u8 + - ``num_dct_parts`` + - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. + * - __u32 + - ``first_part_size`` + - Size of the first partition, i.e. the control partition. + * - __u32 + - ``first_part_header_bits`` + - Size in bits of the first partition header portion. + * - __u32 + - ``dct_part_sizes[8]`` + - DCT coefficients sizes. + * - __u64 + - ``last_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``golden_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``alt_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``flags`` + - See :ref:`Frame Flags <vp8_frame_flags>` + +.. raw:: latex + + \normalsize + +.. _vp8_frame_flags: + +``Frame Flags`` + +.. tabularcolumns:: |p{9.8cm}|p{0.8cm}|p{6.7cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_FRAME_FLAG_KEY_FRAME`` + - 0x01 + - Indicates if the frame is a key frame. + * - ``V4L2_VP8_FRAME_FLAG_EXPERIMENTAL`` + - 0x02 + - Experimental bitstream. + * - ``V4L2_VP8_FRAME_FLAG_SHOW_FRAME`` + - 0x04 + - Show frame flag, indicates if the frame is for display. + * - ``V4L2_VP8_FRAME_FLAG_MB_NO_SKIP_COEFF`` + - 0x08 + - Enable/disable skipping of macroblocks with no non-zero coefficients. + * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_GOLDEN`` + - 0x10 + - Sign of motion vectors when the golden frame is referenced. + * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_ALT`` + - 0x20 + - Sign of motion vectors when the alt frame is referenced. + +.. c:type:: v4l2_vp8_entropy_coder_state + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}| + +.. flat-table:: struct v4l2_vp8_entropy_coder_state + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``range`` + - coder state value for "Range" + * - __u8 + - ``value`` + - coder state value for "Value"- + * - __u8 + - ``bit_count`` + - number of bits left. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_segment + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.2cm}|p{4.0cm}|p{12.1cm}| + +.. flat-table:: struct v4l2_vp8_segment + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``quant_update[4]`` + - Signed quantizer value update. + * - __s8 + - ``lf_update[4]`` + - Signed loop filter level value update. + * - __u8 + - ``segment_probs[3]`` + - Segment probabilities. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Segment Flags <vp8_segment_flags>` + +.. _vp8_segment_flags: + +``Segment Flags`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{10cm}|p{1.0cm}|p{6.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_SEGMENT_FLAG_ENABLED`` + - 0x01 + - Enable/disable segment-based adjustments. + * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_MAP`` + - 0x02 + - Indicates if the macroblock segmentation map is updated in this frame. + * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_FEATURE_DATA`` + - 0x04 + - Indicates if the segment feature data is updated in this frame. + * - ``V4L2_VP8_SEGMENT_FLAG_DELTA_VALUE_MODE`` + - 0x08 + - If is set, the segment feature data mode is delta-value. + If cleared, it's absolute-value. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_vp8_loop_filter + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{3.9cm}|p{11.9cm}| + +.. flat-table:: struct v4l2_vp8_loop_filter + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``ref_frm_delta[4]`` + - Reference adjustment (signed) delta value. + * - __s8 + - ``mb_mode_delta[4]`` + - Macroblock prediction mode adjustment (signed) delta value. + * - __u8 + - ``sharpness_level`` + - Sharpness level + * - __u8 + - ``level`` + - Filter level + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Loop Filter Flags <vp8_loop_filter_flags>` + +.. _vp8_loop_filter_flags: + +``Loop Filter Flags`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_LF_ADJ_ENABLE`` + - 0x01 + - Enable/disable macroblock-level loop filter adjustment. + * - ``V4L2_VP8_LF_DELTA_UPDATE`` + - 0x02 + - Indicates if the delta values used in an adjustment are updated. + * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` + - 0x04 + - If set, indicates the filter type is simple. + If cleared, the filter type is normal. + +.. c:type:: v4l2_vp8_quantization + +.. tabularcolumns:: |p{1.5cm}|p{3.5cm}|p{12.3cm}| + +.. flat-table:: struct v4l2_vp8_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``y_ac_qi`` + - Luma AC coefficient table index. + * - __s8 + - ``y_dc_delta`` + - Luma DC delta value. + * - __s8 + - ``y2_dc_delta`` + - Y2 block DC delta value. + * - __s8 + - ``y2_ac_delta`` + - Y2 block AC delta value. + * - __s8 + - ``uv_dc_delta`` + - Chroma DC delta value. + * - __s8 + - ``uv_ac_delta`` + - Chroma AC delta value. + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_entropy + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_vp8_entropy + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``coeff_probs[4][8][3][11]`` + - Coefficient update probabilities. + * - __u8 + - ``y_mode_probs[4]`` + - Luma mode update probabilities. + * - __u8 + - ``uv_mode_probs[3]`` + - Chroma mode update probabilities. + * - __u8 + - ``mv_probs[2][19]`` + - MV decoding update probabilities. + * - __u8 + - ``padding[3]`` + - Applications and drivers must set this to zero. + +.. _v4l2-codec-stateless-mpeg2: + +``V4L2_CID_STATELESS_MPEG2_SEQUENCE (struct)`` + Specifies the sequence parameters (as extracted from the bitstream) for the + associated MPEG-2 slice data. This includes fields matching the syntax + elements from the sequence header and sequence extension parts of the + bitstream as specified by :ref:`mpeg2part2`. + +.. c:type:: v4l2_ctrl_mpeg2_sequence + +.. raw:: latex + + \small + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.4cm}|p{6.5cm}|p{9.4cm}| + +.. flat-table:: struct v4l2_ctrl_mpeg2_sequence + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``horizontal_size`` + - The width of the displayable part of the frame's luminance component. + * - __u16 + - ``vertical_size`` + - The height of the displayable part of the frame's luminance component. + * - __u32 + - ``vbv_buffer_size`` + - Used to calculate the required size of the video buffering verifier, + defined (in bits) as: 16 * 1024 * vbv_buffer_size. + * - __u16 + - ``profile_and_level_indication`` + - The current profile and level indication as extracted from the + bitstream. + * - __u8 + - ``chroma_format`` + - The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4). + * - __u8 + - ``flags`` + - See :ref:`MPEG-2 Sequence Flags <mpeg2_sequence_flags>`. + +.. _mpeg2_sequence_flags: + +``MPEG-2 Sequence Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG2_SEQ_FLAG_PROGRESSIVE`` + - 0x01 + - Indication that all the frames for the sequence are progressive instead + of interlaced. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_MPEG2_PICTURE (struct)`` + Specifies the picture parameters (as extracted from the bitstream) for the + associated MPEG-2 slice data. This includes fields matching the syntax + elements from the picture header and picture coding extension parts of the + bitstream as specified by :ref:`mpeg2part2`. + +.. c:type:: v4l2_ctrl_mpeg2_picture + +.. raw:: latex + + \small + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.0cm}|p{5.6cm}|p{10.7cm}| + +.. flat-table:: struct v4l2_ctrl_mpeg2_picture + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``forward_ref_ts`` + - Timestamp for the V4L2 capture buffer to use as forward reference, used + with B-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u32 + - ``flags`` + - See :ref:`MPEG-2 Picture Flags <mpeg2_picture_flags>`. + * - __u8 + - ``f_code[2][2]`` + - Motion vector codes. + * - __u8 + - ``picture_coding_type`` + - Picture coding type for the frame covered by the current slice + (V4L2_MPEG2_PIC_CODING_TYPE_I, V4L2_MPEG2_PIC_CODING_TYPE_P or + V4L2_MPEG2_PIC_CODING_TYPE_B). + * - __u8 + - ``picture_structure`` + - Picture structure (1: interlaced top field, 2: interlaced bottom field, + 3: progressive frame). + * - __u8 + - ``intra_dc_precision`` + - Precision of Discrete Cosine transform (0: 8 bits precision, + 1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision). + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + +.. _mpeg2_picture_flags: + +``MPEG-2 Picture Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG2_PIC_FLAG_TOP_FIELD_FIRST`` + - 0x00000001 + - If set and it's an interlaced stream, top field is output first. + * - ``V4L2_MPEG2_PIC_FLAG_FRAME_PRED_DCT`` + - 0x00000002 + - If set only frame-DCT and frame prediction are used. + * - ``V4L2_MPEG2_PIC_FLAG_CONCEALMENT_MV`` + - 0x00000004 + - If set motion vectors are coded for intra macroblocks. + * - ``V4L2_MPEG2_PIC_FLAG_Q_SCALE_TYPE`` + - 0x00000008 + - This flag affects the inverse quantization process. + * - ``V4L2_MPEG2_PIC_FLAG_INTRA_VLC`` + - 0x00000010 + - This flag affects the decoding of transform coefficient data. + * - ``V4L2_MPEG2_PIC_FLAG_ALT_SCAN`` + - 0x00000020 + - This flag affects the decoding of transform coefficient data. + * - ``V4L2_MPEG2_PIC_FLAG_REPEAT_FIRST`` + - 0x00000040 + - This flag affects the decoding process of progressive frames. + * - ``V4L2_MPEG2_PIC_FLAG_PROGRESSIVE`` + - 0x00000080 + - Indicates whether the current frame is progressive. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_MPEG2_QUANTISATION (struct)`` + Specifies quantisation matrices, in zigzag scanning order, for the + associated MPEG-2 slice data. This control is initialized by the kernel + to the matrices default values. If a bitstream transmits a user-defined + quantisation matrices load, applications are expected to use this control. + Applications are also expected to set the control loading the default + values, if the quantisation matrices need to be reset, for instance on a + sequence header. This process is specified by section 6.3.7. + "Quant matrix extension" of the specification. + +.. c:type:: v4l2_ctrl_mpeg2_quantisation + +.. tabularcolumns:: |p{0.8cm}|p{8.0cm}|p{8.5cm}| + +.. cssclass:: longtable + +.. raw:: latex + + \small + +.. flat-table:: struct v4l2_ctrl_mpeg2_quantisation + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``intra_quantiser_matrix[64]`` + - The quantisation matrix coefficients for intra-coded frames, in zigzag + scanning order. It is relevant for both luma and chroma components, + although it can be superseded by the chroma-specific matrix for + non-4:2:0 YUV formats. + * - __u8 + - ``non_intra_quantiser_matrix[64]`` + - The quantisation matrix coefficients for non-intra-coded frames, in + zigzag scanning order. It is relevant for both luma and chroma + components, although it can be superseded by the chroma-specific matrix + for non-4:2:0 YUV formats. + * - __u8 + - ``chroma_intra_quantiser_matrix[64]`` + - The quantisation matrix coefficients for the chominance component of + intra-coded frames, in zigzag scanning order. Only relevant for + non-4:2:0 YUV formats. + * - __u8 + - ``chroma_non_intra_quantiser_matrix[64]`` + - The quantisation matrix coefficients for the chrominance component of + non-intra-coded frames, in zigzag scanning order. Only relevant for + non-4:2:0 YUV formats. + +.. raw:: latex + + \normalsize + +.. _v4l2-codec-stateless-vp9: + +``V4L2_CID_STATELESS_VP9_COMPRESSED_HDR (struct)`` + Stores VP9 probabilities updates as parsed from the current compressed frame + header. A value of zero in an array element means no update of the relevant + probability. Motion vector-related updates contain a new value or zero. All + other updates contain values translated with inv_map_table[] (see 6.3.5 in + :ref:`vp9`). + +.. c:type:: v4l2_ctrl_vp9_compressed_hdr + +.. tabularcolumns:: |p{1cm}|p{4.8cm}|p{11.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp9_compressed_hdr + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``tx_mode`` + - Specifies the TX mode. See :ref:`TX Mode <vp9_tx_mode>` for more details. + * - __u8 + - ``tx8[2][1]`` + - TX 8x8 probabilities delta. + * - __u8 + - ``tx16[2][2]`` + - TX 16x16 probabilities delta. + * - __u8 + - ``tx32[2][3]`` + - TX 32x32 probabilities delta. + * - __u8 + - ``coef[4][2][2][6][6][3]`` + - Coefficient probabilities delta. + * - __u8 + - ``skip[3]`` + - Skip probabilities delta. + * - __u8 + - ``inter_mode[7][3]`` + - Inter prediction mode probabilities delta. + * - __u8 + - ``interp_filter[4][2]`` + - Interpolation filter probabilities delta. + * - __u8 + - ``is_inter[4]`` + - Is inter-block probabilities delta. + * - __u8 + - ``comp_mode[5]`` + - Compound prediction mode probabilities delta. + * - __u8 + - ``single_ref[5][2]`` + - Single reference probabilities delta. + * - __u8 + - ``comp_ref[5]`` + - Compound reference probabilities delta. + * - __u8 + - ``y_mode[4][9]`` + - Y prediction mode probabilities delta. + * - __u8 + - ``uv_mode[10][9]`` + - UV prediction mode probabilities delta. + * - __u8 + - ``partition[16][3]`` + - Partition probabilities delta. + * - __u8 + - ``mv.joint[3]`` + - Motion vector joint probabilities delta. + * - __u8 + - ``mv.sign[2]`` + - Motion vector sign probabilities delta. + * - __u8 + - ``mv.classes[2][10]`` + - Motion vector class probabilities delta. + * - __u8 + - ``mv.class0_bit[2]`` + - Motion vector class0 bit probabilities delta. + * - __u8 + - ``mv.bits[2][10]`` + - Motion vector bits probabilities delta. + * - __u8 + - ``mv.class0_fr[2][2][3]`` + - Motion vector class0 fractional bit probabilities delta. + * - __u8 + - ``mv.fr[2][3]`` + - Motion vector fractional bit probabilities delta. + * - __u8 + - ``mv.class0_hp[2]`` + - Motion vector class0 high precision fractional bit probabilities delta. + * - __u8 + - ``mv.hp[2]`` + - Motion vector high precision fractional bit probabilities delta. + +.. _vp9_tx_mode: + +``TX Mode`` + +.. tabularcolumns:: |p{6.5cm}|p{0.5cm}|p{10.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_TX_MODE_ONLY_4X4`` + - 0 + - Transform size is 4x4. + * - ``V4L2_VP9_TX_MODE_ALLOW_8X8`` + - 1 + - Transform size can be up to 8x8. + * - ``V4L2_VP9_TX_MODE_ALLOW_16X16`` + - 2 + - Transform size can be up to 16x16. + * - ``V4L2_VP9_TX_MODE_ALLOW_32X32`` + - 3 + - transform size can be up to 32x32. + * - ``V4L2_VP9_TX_MODE_SELECT`` + - 4 + - Bitstream contains the transform size for each block. + +See section '7.3.1 Tx mode semantics' of the :ref:`vp9` specification for more details. + +``V4L2_CID_STATELESS_VP9_FRAME (struct)`` + Specifies the frame parameters for the associated VP9 frame decode request. + This includes the necessary parameters for configuring a stateless hardware + decoding pipeline for VP9. The bitstream parameters are defined according + to :ref:`vp9`. + +.. c:type:: v4l2_ctrl_vp9_frame + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.7cm}|p{5.5cm}|p{7.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp9_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_vp9_loop_filter` + - ``lf`` + - Loop filter parameters. See struct :c:type:`v4l2_vp9_loop_filter` for more details. + * - struct :c:type:`v4l2_vp9_quantization` + - ``quant`` + - Quantization parameters. See :c:type:`v4l2_vp9_quantization` for more details. + * - struct :c:type:`v4l2_vp9_segmentation` + - ``seg`` + - Segmentation parameters. See :c:type:`v4l2_vp9_segmentation` for more details. + * - __u32 + - ``flags`` + - Combination of V4L2_VP9_FRAME_FLAG_* flags. See :ref:`Frame Flags<vp9_frame_flags>`. + * - __u16 + - ``compressed_header_size`` + - Compressed header size in bytes. + * - __u16 + - ``uncompressed_header_size`` + - Uncompressed header size in bytes. + * - __u16 + - ``frame_width_minus_1`` + - Add 1 to get the frame width expressed in pixels. See section 7.2.3 in :ref:`vp9`. + * - __u16 + - ``frame_height_minus_1`` + - Add 1 to get the frame height expressed in pixels. See section 7.2.3 in :ref:`vp9`. + * - __u16 + - ``render_width_minus_1`` + - Add 1 to get the expected render width expressed in pixels. This is + not used during the decoding process but might be used by HW scalers to + prepare a frame that's ready for scanout. See section 7.2.4 in :ref:`vp9`. + * - __u16 + - render_height_minus_1 + - Add 1 to get the expected render height expressed in pixels. This is + not used during the decoding process but might be used by HW scalers to + prepare a frame that's ready for scanout. See section 7.2.4 in :ref:`vp9`. + * - __u64 + - ``last_frame_ts`` + - "last" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``golden_frame_ts`` + - "golden" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``alt_frame_ts`` + - "alt" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u8 + - ``ref_frame_sign_bias`` + - a bitfield specifying whether the sign bias is set for a given + reference frame. See :ref:`Reference Frame Sign Bias<vp9_ref_frame_sign_bias>` + for more details. + * - __u8 + - ``reset_frame_context`` + - specifies whether the frame context should be reset to default values. See + :ref:`Reset Frame Context<vp9_reset_frame_context>` for more details. + * - __u8 + - ``frame_context_idx`` + - Frame context that should be used/updated. + * - __u8 + - ``profile`` + - VP9 profile. Can be 0, 1, 2 or 3. + * - __u8 + - ``bit_depth`` + - Component depth in bits. Can be 8, 10 or 12. Note that not all profiles + support 10 and/or 12 bits depths. + * - __u8 + - ``interpolation_filter`` + - Specifies the filter selection used for performing inter prediction. See + :ref:`Interpolation Filter<vp9_interpolation_filter>` for more details. + * - __u8 + - ``tile_cols_log2`` + - Specifies the base 2 logarithm of the width of each tile (where the + width is measured in units of 8x8 blocks). Shall be less than or equal + to 6. + * - __u8 + - ``tile_rows_log2`` + - Specifies the base 2 logarithm of the height of each tile (where the + height is measured in units of 8x8 blocks). + * - __u8 + - ``reference_mode`` + - Specifies the type of inter prediction to be used. See + :ref:`Reference Mode<vp9_reference_mode>` for more details. Note that + this is derived as part of the compressed header parsing process and + for this reason should have been part of + :c:type: `v4l2_ctrl_vp9_compressed_hdr` optional control. It is safe to + set this value to zero if the driver does not require compressed + headers. + * - __u8 + - ``reserved[7]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +.. _vp9_frame_flags: + +``Frame Flags`` + +.. tabularcolumns:: |p{10.0cm}|p{1.2cm}|p{6.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_FRAME_FLAG_KEY_FRAME`` + - 0x001 + - The frame is a key frame. + * - ``V4L2_VP9_FRAME_FLAG_SHOW_FRAME`` + - 0x002 + - The frame should be displayed. + * - ``V4L2_VP9_FRAME_FLAG_ERROR_RESILIENT`` + - 0x004 + - The decoding should be error resilient. + * - ``V4L2_VP9_FRAME_FLAG_INTRA_ONLY`` + - 0x008 + - The frame does not reference other frames. + * - ``V4L2_VP9_FRAME_FLAG_ALLOW_HIGH_PREC_MV`` + - 0x010 + - The frame can use high precision motion vectors. + * - ``V4L2_VP9_FRAME_FLAG_REFRESH_FRAME_CTX`` + - 0x020 + - Frame context should be updated after decoding. + * - ``V4L2_VP9_FRAME_FLAG_PARALLEL_DEC_MODE`` + - 0x040 + - Parallel decoding is used. + * - ``V4L2_VP9_FRAME_FLAG_X_SUBSAMPLING`` + - 0x080 + - Vertical subsampling is enabled. + * - ``V4L2_VP9_FRAME_FLAG_Y_SUBSAMPLING`` + - 0x100 + - Horizontal subsampling is enabled. + * - ``V4L2_VP9_FRAME_FLAG_COLOR_RANGE_FULL_SWING`` + - 0x200 + - The full UV range is used. + +.. _vp9_ref_frame_sign_bias: + +``Reference Frame Sign Bias`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SIGN_BIAS_LAST`` + - 0x1 + - Sign bias is set for the last reference frame. + * - ``V4L2_VP9_SIGN_BIAS_GOLDEN`` + - 0x2 + - Sign bias is set for the golden reference frame. + * - ``V4L2_VP9_SIGN_BIAS_ALT`` + - 0x2 + - Sign bias is set for the alt reference frame. + +.. _vp9_reset_frame_context: + +``Reset Frame Context`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_RESET_FRAME_CTX_NONE`` + - 0 + - Do not reset any frame context. + * - ``V4L2_VP9_RESET_FRAME_CTX_SPEC`` + - 1 + - Reset the frame context pointed to by + :c:type:`v4l2_ctrl_vp9_frame`.frame_context_idx. + * - ``V4L2_VP9_RESET_FRAME_CTX_ALL`` + - 2 + - Reset all frame contexts. + +See section '7.2 Uncompressed header semantics' of the :ref:`vp9` specification +for more details. + +.. _vp9_interpolation_filter: + +``Interpolation Filter`` + +.. tabularcolumns:: |p{9.0cm}|p{1.2cm}|p{7.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP`` + - 0 + - Eight tap filter. + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP_SMOOTH`` + - 1 + - Eight tap smooth filter. + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP_SHARP`` + - 2 + - Eeight tap sharp filter. + * - ``V4L2_VP9_INTERP_FILTER_BILINEAR`` + - 3 + - Bilinear filter. + * - ``V4L2_VP9_INTERP_FILTER_SWITCHABLE`` + - 4 + - Filter selection is signaled at the block level. + +See section '7.2.7 Interpolation filter semantics' of the :ref:`vp9` specification +for more details. + +.. _vp9_reference_mode: + +``Reference Mode`` + +.. tabularcolumns:: |p{9.6cm}|p{0.5cm}|p{7.2cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_REFERENCE_MODE_SINGLE_REFERENCE`` + - 0 + - Indicates that all the inter blocks use only a single reference frame + to generate motion compensated prediction. + * - ``V4L2_VP9_REFERENCE_MODE_COMPOUND_REFERENCE`` + - 1 + - Requires all the inter blocks to use compound mode. Single reference + frame prediction is not allowed. + * - ``V4L2_VP9_REFERENCE_MODE_SELECT`` + - 2 + - Allows each individual inter block to select between single and + compound prediction modes. + +See section '7.3.6 Frame reference mode semantics' of the :ref:`vp9` specification for more details. + +.. c:type:: v4l2_vp9_segmentation + +Encodes the quantization parameters. See section '7.2.10 Segmentation +params syntax' of the :ref:`vp9` specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{5cm}|p{11.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_segmentation + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``feature_data[8][4]`` + - Data attached to each feature. Data entry is only valid if the feature + is enabled. The array shall be indexed with segment number as the first dimension + (0..7) and one of V4L2_VP9_SEG_* as the second dimension. + See :ref:`Segment Feature IDs<vp9_segment_feature>`. + * - __u8 + - ``feature_enabled[8]`` + - Bitmask defining which features are enabled in each segment. The value for each + segment is a combination of V4L2_VP9_SEGMENT_FEATURE_ENABLED(id) values where id is + one of V4L2_VP9_SEG_*. See :ref:`Segment Feature IDs<vp9_segment_feature>`. + * - __u8 + - ``tree_probs[7]`` + - Specifies the probability values to be used when decoding a Segment-ID. + See '5.15 Segmentation map' section of :ref:`vp9` for more details. + * - __u8 + - ``pred_probs[3]`` + - Specifies the probability values to be used when decoding a + Predicted-Segment-ID. See '6.4.14 Get segment id syntax' + section of :ref:`vp9` for more details. + * - __u8 + - ``flags`` + - Combination of V4L2_VP9_SEGMENTATION_FLAG_* flags. See + :ref:`Segmentation Flags<vp9_segmentation_flags>`. + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + +.. _vp9_segment_feature: + +``Segment feature IDs`` + +.. tabularcolumns:: |p{6.0cm}|p{1cm}|p{10.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SEG_LVL_ALT_Q`` + - 0 + - Quantizer segment feature. + * - ``V4L2_VP9_SEG_LVL_ALT_L`` + - 1 + - Loop filter segment feature. + * - ``V4L2_VP9_SEG_LVL_REF_FRAME`` + - 2 + - Reference frame segment feature. + * - ``V4L2_VP9_SEG_LVL_SKIP`` + - 3 + - Skip segment feature. + * - ``V4L2_VP9_SEG_LVL_MAX`` + - 4 + - Number of segment features. + +.. _vp9_segmentation_flags: + +``Segmentation Flags`` + +.. tabularcolumns:: |p{10.6cm}|p{0.8cm}|p{5.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SEGMENTATION_FLAG_ENABLED`` + - 0x01 + - Indicates that this frame makes use of the segmentation tool. + * - ``V4L2_VP9_SEGMENTATION_FLAG_UPDATE_MAP`` + - 0x02 + - Indicates that the segmentation map should be updated during the + decoding of this frame. + * - ``V4L2_VP9_SEGMENTATION_FLAG_TEMPORAL_UPDATE`` + - 0x04 + - Indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. + * - ``V4L2_VP9_SEGMENTATION_FLAG_UPDATE_DATA`` + - 0x08 + - Indicates that new parameters are about to be specified for each + segment. + * - ``V4L2_VP9_SEGMENTATION_FLAG_ABS_OR_DELTA_UPDATE`` + - 0x10 + - Indicates that the segmentation parameters represent the actual values + to be used. + +.. c:type:: v4l2_vp9_quantization + +Encodes the quantization parameters. See section '7.2.9 Quantization params +syntax' of the VP9 specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{4cm}|p{12.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``base_q_idx`` + - Indicates the base frame qindex. + * - __s8 + - ``delta_q_y_dc`` + - Indicates the Y DC quantizer relative to base_q_idx. + * - __s8 + - ``delta_q_uv_dc`` + - Indicates the UV DC quantizer relative to base_q_idx. + * - __s8 + - ``delta_q_uv_ac`` + - Indicates the UV AC quantizer relative to base_q_idx. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp9_loop_filter + +This structure contains all loop filter related parameters. See sections +'7.2.8 Loop filter semantics' of the :ref:`vp9` specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{4cm}|p{12.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_loop_filter + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``ref_deltas[4]`` + - Contains the adjustment needed for the filter level based on the chosen + reference frame. + * - __s8 + - ``mode_deltas[2]`` + - Contains the adjustment needed for the filter level based on the chosen + mode. + * - __u8 + - ``level`` + - Indicates the loop filter strength. + * - __u8 + - ``sharpness`` + - Indicates the sharpness level. + * - __u8 + - ``flags`` + - Combination of V4L2_VP9_LOOP_FILTER_FLAG_* flags. + See :ref:`Loop Filter Flags <vp9_loop_filter_flags>`. + * - __u8 + - ``reserved[7]`` + - Applications and drivers must set this to zero. + + +.. _vp9_loop_filter_flags: + +``Loop Filter Flags`` + +.. tabularcolumns:: |p{9.6cm}|p{0.5cm}|p{7.2cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_LOOP_FILTER_FLAG_DELTA_ENABLED`` + - 0x1 + - When set, the filter level depends on the mode and reference frame used + to predict a block. + * - ``V4L2_VP9_LOOP_FILTER_FLAG_DELTA_UPDATE`` + - 0x2 + - When set, the bitstream contains additional syntax elements that + specify which mode and reference frame deltas are to be updated. + +.. _v4l2-codec-stateless-hevc: + +``V4L2_CID_STATELESS_HEVC_SPS (struct)`` + Specifies the Sequence Parameter Set fields (as extracted from the + bitstream) for the associated HEVC slice data. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.3.2 "Sequence parameter set RBSP + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_sps + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{9.2cm}|p{6.9cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``video_parameter_set_id`` + - Specifies the value of the vps_video_parameter_set_id of the active VPS + as described in section "7.4.3.2.1 General sequence parameter set RBSP semantics" + of H.265 specifications. + * - __u8 + - ``seq_parameter_set_id`` + - Provides an identifier for the SPS for reference by other syntax elements + as described in section "7.4.3.2.1 General sequence parameter set RBSP semantics" + of H.265 specifications. + * - __u16 + - ``pic_width_in_luma_samples`` + - Specifies the width of each decoded picture in units of luma samples. + * - __u16 + - ``pic_height_in_luma_samples`` + - Specifies the height of each decoded picture in units of luma samples. + * - __u8 + - ``bit_depth_luma_minus8`` + - This value plus 8 specifies the bit depth of the samples of the luma array. + * - __u8 + - ``bit_depth_chroma_minus8`` + - This value plus 8 specifies the bit depth of the samples of the chroma arrays. + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - Specifies the value of the variable MaxPicOrderCntLsb. + * - __u8 + - ``sps_max_dec_pic_buffering_minus1`` + - This value plus 1 specifies the maximum required size of the decoded picture buffer for + the coded video sequence (CVS). + * - __u8 + - ``sps_max_num_reorder_pics`` + - Indicates the maximum allowed number of pictures. + * - __u8 + - ``sps_max_latency_increase_plus1`` + - Used to signal MaxLatencyPictures, which indicates the maximum number of + pictures that can precede any picture in output order and follow that + picture in decoding order. + * - __u8 + - ``log2_min_luma_coding_block_size_minus3`` + - This value plus 3 specifies the minimum luma coding block size. + * - __u8 + - ``log2_diff_max_min_luma_coding_block_size`` + - Specifies the difference between the maximum and minimum luma coding block size. + * - __u8 + - ``log2_min_luma_transform_block_size_minus2`` + - This value plus 2 specifies the minimum luma transform block size. + * - __u8 + - ``log2_diff_max_min_luma_transform_block_size`` + - Specifies the difference between the maximum and minimum luma transform block size. + * - __u8 + - ``max_transform_hierarchy_depth_inter`` + - Specifies the maximum hierarchy depth for transform units of coding units coded + in inter prediction mode. + * - __u8 + - ``max_transform_hierarchy_depth_intra`` + - Specifies the maximum hierarchy depth for transform units of coding units coded in + intra prediction mode. + * - __u8 + - ``pcm_sample_bit_depth_luma_minus1`` + - This value plus 1 specifies the number of bits used to represent each of PCM sample values of the + luma component. + * - __u8 + - ``pcm_sample_bit_depth_chroma_minus1`` + - Specifies the number of bits used to represent each of PCM sample values of + the chroma components. + * - __u8 + - ``log2_min_pcm_luma_coding_block_size_minus3`` + - Plus 3 specifies the minimum size of coding blocks. + * - __u8 + - ``log2_diff_max_min_pcm_luma_coding_block_size`` + - Specifies the difference between the maximum and minimum size of coding blocks. + * - __u8 + - ``num_short_term_ref_pic_sets`` + - Specifies the number of st_ref_pic_set() syntax structures included in the SPS. + * - __u8 + - ``num_long_term_ref_pics_sps`` + - Specifies the number of candidate long-term reference pictures that are + specified in the SPS. + * - __u8 + - ``chroma_format_idc`` + - Specifies the chroma sampling. + * - __u8 + - ``sps_max_sub_layers_minus1`` + - This value plus 1 specifies the maximum number of temporal sub-layers. + * - __u64 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags <hevc_sps_flags>` + +.. raw:: latex + + \normalsize + +.. _hevc_sps_flags: + +``Sequence Parameter Set Flags`` + +.. raw:: latex + + \small + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_HEVC_SPS_FLAG_SCALING_LIST_ENABLED`` + - 0x00000002 + - + * - ``V4L2_HEVC_SPS_FLAG_AMP_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_SPS_FLAG_SAMPLE_ADAPTIVE_OFFSET`` + - 0x00000008 + - + * - ``V4L2_HEVC_SPS_FLAG_PCM_ENABLED`` + - 0x00000010 + - + * - ``V4L2_HEVC_SPS_FLAG_PCM_LOOP_FILTER_DISABLED`` + - 0x00000020 + - + * - ``V4L2_HEVC_SPS_FLAG_LONG_TERM_REF_PICS_PRESENT`` + - 0x00000040 + - + * - ``V4L2_HEVC_SPS_FLAG_SPS_TEMPORAL_MVP_ENABLED`` + - 0x00000080 + - + * - ``V4L2_HEVC_SPS_FLAG_STRONG_INTRA_SMOOTHING_ENABLED`` + - 0x00000100 + - + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_PPS (struct)`` + Specifies the Picture Parameter Set fields (as extracted from the + bitstream) for the associated HEVC slice data. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.3.3 "Picture parameter set RBSP + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_pps + +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``pic_parameter_set_id`` + - Identifies the PPS for reference by other syntax elements. + * - __u8 + - ``num_extra_slice_header_bits`` + - Specifies the number of extra slice header bits that are present + in the slice header RBSP for coded pictures referring to the PPS. + * - __u8 + - ``num_ref_idx_l0_default_active_minus1`` + - This value plus 1 specifies the inferred value of num_ref_idx_l0_active_minus1. + * - __u8 + - ``num_ref_idx_l1_default_active_minus1`` + - This value plus 1 specifies the inferred value of num_ref_idx_l1_active_minus1. + * - __s8 + - ``init_qp_minus26`` + - This value plus 26 specifies the initial value of SliceQp Y for each slice + referring to the PPS. + * - __u8 + - ``diff_cu_qp_delta_depth`` + - Specifies the difference between the luma coding tree block size + and the minimum luma coding block size of coding units that + convey cu_qp_delta_abs and cu_qp_delta_sign_flag. + * - __s8 + - ``pps_cb_qp_offset`` + - Specifies the offsets to the luma quantization parameter Cb. + * - __s8 + - ``pps_cr_qp_offset`` + - Specifies the offsets to the luma quantization parameter Cr. + * - __u8 + - ``num_tile_columns_minus1`` + - This value plus 1 specifies the number of tile columns partitioning the picture. + * - __u8 + - ``num_tile_rows_minus1`` + - This value plus 1 specifies the number of tile rows partitioning the picture. + * - __u8 + - ``column_width_minus1[20]`` + - This value plus 1 specifies the width of the i-th tile column in units of + coding tree blocks. + * - __u8 + - ``row_height_minus1[22]`` + - This value plus 1 specifies the height of the i-th tile row in units of coding + tree blocks. + * - __s8 + - ``pps_beta_offset_div2`` + - Specifies the default deblocking parameter offsets for beta divided by 2. + * - __s8 + - ``pps_tc_offset_div2`` + - Specifies the default deblocking parameter offsets for tC divided by 2. + * - __u8 + - ``log2_parallel_merge_level_minus2`` + - This value plus 2 specifies the value of the variable Log2ParMrgLevel. + * - __u8 + - ``padding[4]`` + - Applications and drivers must set this to zero. + * - __u64 + - ``flags`` + - See :ref:`Picture Parameter Set Flags <hevc_pps_flags>` + +.. _hevc_pps_flags: + +``Picture Parameter Set Flags`` + +.. raw:: latex + + \small + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_PPS_FLAG_DEPENDENT_SLICE_SEGMENT_ENABLED`` + - 0x00000001 + - + * - ``V4L2_HEVC_PPS_FLAG_OUTPUT_FLAG_PRESENT`` + - 0x00000002 + - + * - ``V4L2_HEVC_PPS_FLAG_SIGN_DATA_HIDING_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_PPS_FLAG_CABAC_INIT_PRESENT`` + - 0x00000008 + - + * - ``V4L2_HEVC_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x00000010 + - + * - ``V4L2_HEVC_PPS_FLAG_TRANSFORM_SKIP_ENABLED`` + - 0x00000020 + - + * - ``V4L2_HEVC_PPS_FLAG_CU_QP_DELTA_ENABLED`` + - 0x00000040 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT`` + - 0x00000080 + - + * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_PRED`` + - 0x00000100 + - + * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_BIPRED`` + - 0x00000200 + - + * - ``V4L2_HEVC_PPS_FLAG_TRANSQUANT_BYPASS_ENABLED`` + - 0x00000400 + - + * - ``V4L2_HEVC_PPS_FLAG_TILES_ENABLED`` + - 0x00000800 + - + * - ``V4L2_HEVC_PPS_FLAG_ENTROPY_CODING_SYNC_ENABLED`` + - 0x00001000 + - + * - ``V4L2_HEVC_PPS_FLAG_LOOP_FILTER_ACROSS_TILES_ENABLED`` + - 0x00002000 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00004000 + - + * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_OVERRIDE_ENABLED`` + - 0x00008000 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_DISABLE_DEBLOCKING_FILTER`` + - 0x00010000 + - + * - ``V4L2_HEVC_PPS_FLAG_LISTS_MODIFICATION_PRESENT`` + - 0x00020000 + - + * - ``V4L2_HEVC_PPS_FLAG_SLICE_SEGMENT_HEADER_EXTENSION_PRESENT`` + - 0x00040000 + - + * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` + - 0x00080000 + - Specifies the presence of deblocking filter control syntax elements in + the PPS + * - ``V4L2_HEVC_PPS_FLAG_UNIFORM_SPACING`` + - 0x00100000 + - Specifies that tile column boundaries and likewise tile row boundaries + are distributed uniformly across the picture + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_SLICE_PARAMS (struct)`` + Specifies various slice-specific parameters, especially from the NAL unit + header, general slice segment header and weighted prediction parameter + parts of the bitstream. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.7 "General slice segment header + semantics" of the specification. + This control is a dynamically sized 1-dimensional array, + V4L2_CTRL_FLAG_DYNAMIC_ARRAY flag must be set when using it. + +.. c:type:: v4l2_ctrl_hevc_slice_params + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``bit_size`` + - Size (in bits) of the current slice data. + * - __u32 + - ``data_byte_offset`` + - Offset (in byte) to the video data in the current slice data. + * - __u32 + - ``num_entry_point_offsets`` + - Specifies the number of entry point offset syntax elements in the slice header. + When the driver supports it, the ``V4L2_CID_STATELESS_HEVC_ENTRY_POINT_OFFSETS`` + must be set. + * - __u8 + - ``nal_unit_type`` + - Specifies the coding type of the slice (B, P or I). + * - __u8 + - ``nuh_temporal_id_plus1`` + - Minus 1 specifies a temporal identifier for the NAL unit. + * - __u8 + - ``slice_type`` + - + (V4L2_HEVC_SLICE_TYPE_I, V4L2_HEVC_SLICE_TYPE_P or + V4L2_HEVC_SLICE_TYPE_B). + * - __u8 + - ``colour_plane_id`` + - Specifies the colour plane associated with the current slice. + * - __s32 + - ``slice_pic_order_cnt`` + - Specifies the picture order count. + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - This value plus 1 specifies the maximum reference index for reference picture list 0 + that may be used to decode the slice. + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - This value plus 1 specifies the maximum reference index for reference picture list 1 + that may be used to decode the slice. + * - __u8 + - ``collocated_ref_idx`` + - Specifies the reference index of the collocated picture used for + temporal motion vector prediction. + * - __u8 + - ``five_minus_max_num_merge_cand`` + - Specifies the maximum number of merging motion vector prediction + candidates supported in the slice subtracted from 5. + * - __s8 + - ``slice_qp_delta`` + - Specifies the initial value of QpY to be used for the coding blocks in the slice. + * - __s8 + - ``slice_cb_qp_offset`` + - Specifies a difference to be added to the value of pps_cb_qp_offset. + * - __s8 + - ``slice_cr_qp_offset`` + - Specifies a difference to be added to the value of pps_cr_qp_offset. + * - __s8 + - ``slice_act_y_qp_offset`` + - Specifies the offset to the luma of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_act_cb_qp_offset`` + - Specifies the offset to the cb of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_act_cr_qp_offset`` + - Specifies the offset to the cr of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_beta_offset_div2`` + - Specifies the deblocking parameter offsets for beta divided by 2. + * - __s8 + - ``slice_tc_offset_div2`` + - Specifies the deblocking parameter offsets for tC divided by 2. + * - __u8 + - ``pic_struct`` + - Indicates whether a picture should be displayed as a frame or as one or more fields. + * - __u32 + - ``slice_segment_addr`` + - Specifies the address of the first coding tree block in the slice segment. + * - __u8 + - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The list of L0 reference elements as indices in the DPB. + * - __u8 + - ``ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The list of L1 reference elements as indices in the DPB. + * - __u16 + - ``short_term_ref_pic_set_size`` + - Specifies the size, in bits, of the short-term reference picture set, described as st_ref_pic_set() + in the specification, included in the slice header or SPS (section 7.3.6.1). + * - __u16 + - ``long_term_ref_pic_set_size`` + - Specifies the size, in bits, of the long-term reference picture set include in the slice header + or SPS. It is the number of bits in the conditional block if(long_term_ref_pics_present_flag) + in section 7.3.6.1 of the specification. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_hevc_pred_weight_table` + - ``pred_weight_table`` + - The prediction weight coefficients for inter-picture prediction. + * - __u64 + - ``flags`` + - See :ref:`Slice Parameters Flags <hevc_slice_params_flags>` + +.. raw:: latex + + \normalsize + +.. _hevc_slice_params_flags: + +``Slice Parameters Flags`` + +.. raw:: latex + + \scriptsize + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_LUMA`` + - 0x00000001 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_CHROMA`` + - 0x00000002 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_TEMPORAL_MVP_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_MVD_L1_ZERO`` + - 0x00000008 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_CABAC_INIT`` + - 0x00000010 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_COLLOCATED_FROM_L0`` + - 0x00000020 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_USE_INTEGER_MV`` + - 0x00000040 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_DEBLOCKING_FILTER_DISABLED`` + - 0x00000080 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00000100 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_DEPENDENT_SLICE_SEGMENT`` + - 0x00000200 + - + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_ENTRY_POINT_OFFSETS (integer)`` + Specifies entry point offsets in bytes. + This control is a dynamically sized array. The number of entry point + offsets is reported by the ``elems`` field. + This bitstream parameter is defined according to :ref:`hevc`. + They are described in section 7.4.7.1 "General slice segment header + semantics" of the specification. + When multiple slices are submitted in a request, the length of + this array must be the sum of num_entry_point_offsets of all the + slices in the request. + +``V4L2_CID_STATELESS_HEVC_SCALING_MATRIX (struct)`` + Specifies the HEVC scaling matrix parameters used for the scaling process + for transform coefficients. + These matrix and parameters are defined according to :ref:`hevc`. + They are described in section 7.4.5 "Scaling list data semantics" of + the specification. + +.. c:type:: v4l2_ctrl_hevc_scaling_matrix + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_scaling_matrix + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``scaling_list_4x4[6][16]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_8x8[6][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_16x16[6][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_32x32[2][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_dc_coef_16x16[6]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_dc_coef_32x32[2]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_hevc_dpb_entry + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{12.1cm}| + +.. flat-table:: struct v4l2_hevc_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``timestamp`` + - Timestamp of the V4L2 capture buffer to use as reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u8 + - ``flags`` + - Long term flag for the reference frame + (V4L2_HEVC_DPB_ENTRY_LONG_TERM_REFERENCE). The flag is set as + described in the ITU HEVC specification chapter "8.3.2 Decoding + process for reference picture set". + * - __u8 + - ``field_pic`` + - Whether the reference is a field picture or a frame. + See :ref:`HEVC dpb field pic Flags <hevc_dpb_field_pic_flags>` + * - __s32 + - ``pic_order_cnt_val`` + - The picture order count of the current picture. + * - __u8 + - ``padding[2]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +.. _hevc_dpb_field_pic_flags: + +``HEVC dpb field pic Flags`` + +.. raw:: latex + + \scriptsize + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME`` + - 0 + - (progressive) Frame + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_FIELD`` + - 1 + - Top field + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_FIELD`` + - 2 + - Bottom field + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_BOTTOM`` + - 3 + - Top field, bottom field, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_TOP`` + - 4 + - Bottom field, top field, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_BOTTOM_TOP`` + - 5 + - Top field, bottom field, top field repeated, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_TOP_BOTTOM`` + - 6 + - Bottom field, top field, bottom field repeated, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME_DOUBLING`` + - 7 + - Frame doubling + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME_TRIPLING`` + - 8 + - Frame tripling + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_PAIRED_PREVIOUS_BOTTOM`` + - 9 + - Top field paired with previous bottom field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_PAIRED_PREVIOUS_TOP`` + - 10 + - Bottom field paired with previous top field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_PAIRED_NEXT_BOTTOM`` + - 11 + - Top field paired with next bottom field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_PAIRED_NEXT_TOP`` + - 12 + - Bottom field paired with next top field in output order + +.. c:type:: v4l2_hevc_pred_weight_table + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{0.8cm}|p{10.6cm}|p{5.9cm}| + +.. flat-table:: struct v4l2_hevc_pred_weight_table + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``delta_luma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The difference of the weighting factor applied to the luma + prediction value for list 0. + * - __s8 + - ``luma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The additive offset applied to the luma prediction value for list 0. + * - __s8 + - ``delta_chroma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the weighting factor applied to the chroma + prediction value for list 0. + * - __s8 + - ``chroma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the additive offset applied to the chroma + prediction values for list 0. + * - __s8 + - ``delta_luma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The difference of the weighting factor applied to the luma + prediction value for list 1. + * - __s8 + - ``luma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The additive offset applied to the luma prediction value for list 1. + * - __s8 + - ``delta_chroma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the weighting factor applied to the chroma + prediction value for list 1. + * - __s8 + - ``chroma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the additive offset applied to the chroma + prediction values for list 1. + * - __u8 + - ``luma_log2_weight_denom`` + - The base 2 logarithm of the denominator for all luma weighting + factors. + * - __s8 + - ``delta_chroma_log2_weight_denom`` + - The difference of the base 2 logarithm of the denominator for + all chroma weighting factors. + * - __u8 + - ``padding[6]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_DECODE_MODE (enum)`` + Specifies the decoding mode to use. Currently exposes slice-based and + frame-based decoding but new modes might be added later on. + This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE + pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE + are required to set this control in order to specify the decoding mode + that is expected for the buffer. + Drivers may expose a single or multiple decoding modes, depending + on what they can support. + +.. c:type:: v4l2_stateless_hevc_decode_mode + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{9.4cm}|p{0.6cm}|p{7.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_HEVC_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + The OUTPUT buffer must contain a single slice. + * - ``V4L2_STATELESS_HEVC_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity. + The OUTPUT buffer must contain all slices needed to decode the + frame. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_START_CODE (enum)`` + Specifies the HEVC slice start code expected for each slice. + This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE + pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE + are required to set this control in order to specify the start code + that is expected for the buffer. + Drivers may expose a single or multiple start codes, depending + on what they can support. + +.. c:type:: v4l2_stateless_hevc_start_code + +.. tabularcolumns:: |p{9.2cm}|p{0.6cm}|p{7.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_HEVC_START_CODE_NONE`` + - 0 + - Selecting this value specifies that HEVC slices are passed + to the driver without any start code. The bitstream data should be + according to :ref:`hevc` 7.3.1.1 General NAL unit syntax, hence + contains emulation prevention bytes when required. + * - ``V4L2_STATELESS_HEVC_START_CODE_ANNEX_B`` + - 1 + - Selecting this value specifies that HEVC slices are expected + to be prefixed by Annex B start codes. According to :ref:`hevc` + valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. + +.. raw:: latex + + \normalsize + +``V4L2_CID_MPEG_VIDEO_BASELAYER_PRIORITY_ID (integer)`` + Specifies a priority identifier for the NAL unit, which will be applied to + the base layer. By default this value is set to 0 for the base layer, + and the next layer will have the priority ID assigned as 1, 2, 3 and so on. + The video encoder can't decide the priority id to be applied to a layer, + so this has to come from client. + This is applicable to H264 and valid Range is from 0 to 63. + Source Rec. ITU-T H.264 (06/2019); G.7.4.1.1, G.8.8.1. + +``V4L2_CID_MPEG_VIDEO_LTR_COUNT (integer)`` + Specifies the maximum number of Long Term Reference (LTR) frames at any + given time that the encoder can keep. + This is applicable to the H264 and HEVC encoders. + +``V4L2_CID_MPEG_VIDEO_FRAME_LTR_INDEX (integer)`` + After setting this control the frame that will be queued next + will be marked as a Long Term Reference (LTR) frame + and given this LTR index which ranges from 0 to LTR_COUNT-1. + This is applicable to the H264 and HEVC encoders. + Source Rec. ITU-T H.264 (06/2019); Table 7.9 + +``V4L2_CID_MPEG_VIDEO_USE_LTR_FRAMES (bitmask)`` + Specifies the Long Term Reference (LTR) frame(s) to be used for + encoding the next frame queued after setting this control. + This provides a bitmask which consists of bits [0, LTR_COUNT-1]. + This is applicable to the H264 and HEVC encoders. + +``V4L2_CID_STATELESS_HEVC_DECODE_PARAMS (struct)`` + Specifies various decode parameters, especially the references picture order + count (POC) for all the lists (short, long, before, current, after) and the + number of entries for each of them. + These parameters are defined according to :ref:`hevc`. + They are described in section 8.3 "Slice decoding process" of the + specification. + +.. c:type:: v4l2_ctrl_hevc_decode_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_decode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s32 + - ``pic_order_cnt_val`` + - PicOrderCntVal as described in section 8.3.1 "Decoding process + for picture order count" of the specification. + * - __u16 + - ``short_term_ref_pic_set_size`` + - Specifies the size, in bits, of the short-term reference picture set, of the first slice + described as st_ref_pic_set() in the specification, included in the slice header + or SPS (section 7.3.6.1). + * - __u16 + - ``long_term_ref_pic_set_size`` + - Specifies the size, in bits, of the long-term reference picture set, of the first slice + included in the slice header or SPS. It is the number of bits in the conditional block + if(long_term_ref_pics_present_flag) in section 7.3.6.1 of the specification. + * - __u8 + - ``num_active_dpb_entries`` + - The number of entries in ``dpb``. + * - __u8 + - ``num_poc_st_curr_before`` + - The number of reference pictures in the short-term set that come before + the current frame. + * - __u8 + - ``num_poc_st_curr_after`` + - The number of reference pictures in the short-term set that come after + the current frame. + * - __u8 + - ``num_poc_lt_curr`` + - The number of reference pictures in the long-term set. + * - __u8 + - ``poc_st_curr_before[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocStCurrBefore as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the short term before references in DPB array. + * - __u8 + - ``poc_st_curr_after[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocStCurrAfter as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the short term after references in DPB array. + * - __u8 + - ``poc_lt_curr[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocLtCurr as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the long term references in DPB array. + * - __u8 + - ``num_delta_pocs_of_ref_rps_idx`` + - When the short_term_ref_pic_set_sps_flag in the slice header is equal to 0, + it is the same as the derived value NumDeltaPocs[RefRpsIdx]. It can be used to parse + the RPS data in slice headers instead of skipping it with @short_term_ref_pic_set_size. + When the value of short_term_ref_pic_set_sps_flag in the slice header is + equal to 1, num_delta_pocs_of_ref_rps_idx shall be set to 0. + * - struct :c:type:`v4l2_hevc_dpb_entry` + - ``dpb[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The decoded picture buffer, for meta-data about reference frames. + * - __u64 + - ``flags`` + - See :ref:`Decode Parameters Flags <hevc_decode_params_flags>` + +.. _hevc_decode_params_flags: + +``Decode Parameters Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_IRAP_PIC`` + - 0x00000001 + - + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_IDR_PIC`` + - 0x00000002 + - + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_NO_OUTPUT_OF_PRIOR`` + - 0x00000004 + - + +.. _v4l2-codec-stateless-av1: + +``V4L2_CID_STATELESS_AV1_SEQUENCE (struct)`` + Represents an AV1 Sequence OBU (Open Bitstream Unit). See section 5.5 + "Sequence header OBU syntax" in :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_sequence + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_sequence + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``flags`` + - See :ref:`AV1 Sequence Flags <av1_sequence_flags>`. + * - __u8 + - ``seq_profile`` + - Specifies the features that can be used in the coded video sequence. + * - __u8 + - ``order_hint_bits`` + - Specifies the number of bits used for the order_hint field at each frame. + * - __u8 + - ``bit_depth`` + - the bit depth to use for the sequence as described in section 5.5.2 + "Color config syntax" in :ref:`av1` for more details. + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - __u16 + - ``max_frame_width_minus_1`` + - specifies the maximum frame width minus 1 for the frames represented by + this sequence header. + +.. _av1_sequence_flags: + +``AV1 Sequence Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEQUENCE_FLAG_STILL_PICTURE`` + - 0x00000001 + - If set, specifies that the coded video sequence contains only one coded + frame. If not set, specifies that the coded video sequence contains one + or more coded frames. + * - ``V4L2_AV1_SEQUENCE_FLAG_USE_128X128_SUPERBLOCK`` + - 0x00000002 + - If set, indicates that superblocks contain 128x128 luma samples. + When equal to 0, it indicates that superblocks contain 64x64 luma + samples. The number of contained chroma samples depends on + subsampling_x and subsampling_y. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_FILTER_INTRA`` + - 0x00000004 + - If set, specifies that the use_filter_intra syntax element may be + present. If not set, specifies that the use_filter_intra syntax element + will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_INTRA_EDGE_FILTER`` + - 0x00000008 + - Specifies whether the intra edge filtering process should be enabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_INTERINTRA_COMPOUND`` + - 0x00000010 + - If set, specifies that the mode info for inter blocks may contain the + syntax element interintra. If not set, specifies that the syntax element + interintra will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_MASKED_COMPOUND`` + - 0x00000020 + - If set, specifies that the mode info for inter blocks may contain the + syntax element compound_type. If not set, specifies that the syntax + element compound_type will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_WARPED_MOTION`` + - 0x00000040 + - If set, indicates that the allow_warped_motion syntax element may be + present. If not set, indicates that the allow_warped_motion syntax + element will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_DUAL_FILTER`` + - 0x00000080 + - If set, indicates that the inter prediction filter type may be specified + independently in the horizontal and vertical directions. If the flag is + equal to 0, only one filter type may be specified, which is then used in + both directions. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_ORDER_HINT`` + - 0x00000100 + - If set, indicates that tools based on the values of order hints may be + used. If not set, indicates that tools based on order hints are + disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_JNT_COMP`` + - 0x00000200 + - If set, indicates that the distance weights process may be used for + inter prediction. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_REF_FRAME_MVS`` + - 0x00000400 + - If set, indicates that the use_ref_frame_mvs syntax element may be + present. If not set, indicates that the use_ref_frame_mvs syntax element + will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_SUPERRES`` + - 0x00000800 + - If set, specifies that the use_superres syntax element will be present + in the uncompressed header. If not set, specifies that the use_superres + syntax element will not be present (instead use_superres will be set to + 0 in the uncompressed header without being read). + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_CDEF`` + - 0x00001000 + - If set, specifies that cdef filtering may be enabled. If not set, + specifies that cdef filtering is disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_RESTORATION`` + - 0x00002000 + - If set, specifies that loop restoration filtering may be enabled. If not + set, specifies that loop restoration filtering is disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_MONO_CHROME`` + - 0x00004000 + - If set, indicates that the video does not contain U and V color planes. + If not set, indicates that the video contains Y, U, and V color planes. + * - ``V4L2_AV1_SEQUENCE_FLAG_COLOR_RANGE`` + - 0x00008000 + - If set, signals full swing representation, i.e. "Full Range + Quantization". If not set, signals studio swing representation, i.e. + "Limited Range Quantization". + * - ``V4L2_AV1_SEQUENCE_FLAG_SUBSAMPLING_X`` + - 0x00010000 + - Specify the chroma subsampling format. + * - ``V4L2_AV1_SEQUENCE_FLAG_SUBSAMPLING_Y`` + - 0x00020000 + - Specify the chroma subsampling format. + * - ``V4L2_AV1_SEQUENCE_FLAG_FILM_GRAIN_PARAMS_PRESENT`` + - 0x00040000 + - Specifies whether film grain parameters are present in the coded video + sequence. + * - ``V4L2_AV1_SEQUENCE_FLAG_SEPARATE_UV_DELTA_Q`` + - 0x00080000 + - If set, indicates that the U and V planes may have separate delta + quantizer values. If not set, indicates that the U and V planes will share + the same delta quantizer value. + +``V4L2_CID_STATELESS_AV1_TILE_GROUP_ENTRY (struct)`` + Represents a single AV1 tile inside an AV1 Tile Group. Note that MiRowStart, + MiRowEnd, MiColStart and MiColEnd can be retrieved from struct + v4l2_av1_tile_info in struct v4l2_ctrl_av1_frame using tile_row and + tile_col. See section 6.10.1 "General tile group OBU semantics" in + :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_tile_group_entry + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_tile_group_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``tile_offset`` + - Offset from the OBU data, i.e. where the coded tile data actually starts. + * - __u32 + - ``tile_size`` + - Specifies the size in bytes of the coded tile. Equivalent to "TileSize" + in :ref:`av1`. + * - __u32 + - ``tile_row`` + - Specifies the row of the current tile. Equivalent to "TileRow" in + :ref:`av1`. + * - __u32 + - ``tile_col`` + - Specifies the column of the current tile. Equivalent to "TileColumn" in + :ref:`av1`. + +.. c:type:: v4l2_av1_warp_model + + AV1 Warp Model as described in section 3 "Symbols and abbreviated terms" of + :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_WARP_MODEL_IDENTITY`` + - 0 + - Warp model is just an identity transform. + * - ``V4L2_AV1_WARP_MODEL_TRANSLATION`` + - 1 + - Warp model is a pure translation. + * - ``V4L2_AV1_WARP_MODEL_ROTZOOM`` + - 2 + - Warp model is a rotation + symmetric zoom + translation. + * - ``V4L2_AV1_WARP_MODEL_AFFINE`` + - 3 + - Warp model is a general affine transform. + +.. c:type:: v4l2_av1_reference_frame + +AV1 Reference Frames as described in section 6.10.24 "Ref frames semantics" +of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_REF_INTRA_FRAME`` + - 0 + - Intra Frame Reference. + * - ``V4L2_AV1_REF_LAST_FRAME`` + - 1 + - Last Frame Reference. + * - ``V4L2_AV1_REF_LAST2_FRAME`` + - 2 + - Last2 Frame Reference. + * - ``V4L2_AV1_REF_LAST3_FRAME`` + - 3 + - Last3 Frame Reference. + * - ``V4L2_AV1_REF_GOLDEN_FRAME`` + - 4 + - Golden Frame Reference. + * - ``V4L2_AV1_REF_BWDREF_FRAME`` + - 5 + - BWD Frame Reference. + * - ``V4L2_AV1_REF_ALTREF2_FRAME`` + - 6 + - ALTREF2 Frame Reference. + * - ``V4L2_AV1_REF_ALTREF_FRAME`` + - 7 + - ALTREF Frame Reference. + +.. c:type:: v4l2_av1_global_motion + +AV1 Global Motion parameters as described in section 6.8.17 +"Global motion params semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_global_motion + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - A bitfield containing the flags per reference frame. See + :ref:`AV1 Global Motion Flags <av1_global_motion_flags>` for more + details. + * - enum :c:type:`v4l2_av1_warp_model` + - ``type[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - The type of global motion transform used. + * - __s32 + - ``params[V4L2_AV1_TOTAL_REFS_PER_FRAME][6]`` + - This field has the same meaning as "gm_params" in :ref:`av1`. + * - __u8 + - ``invalid`` + - Bitfield indicating whether the global motion params are invalid for a + given reference frame. See section 7.11.3.6 Setup shear process and the + variable "warpValid". Use V4L2_AV1_GLOBAL_MOTION_IS_INVALID(ref) to + create a suitable mask. + * - __u8 + - ``reserved[3]`` + - Applications and drivers must set this to zero. + +.. _av1_global_motion_flags: + +``AV1 Global Motion Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_GLOBAL`` + - 0x00000001 + - Specifies whether global motion parameters are present for a particular + reference frame. + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_ROT_ZOOM`` + - 0x00000002 + - Specifies whether a particular reference frame uses rotation and zoom + global motion. + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_TRANSLATION`` + - 0x00000004 + - Specifies whether a particular reference frame uses translation global + motion + +.. c:type:: v4l2_av1_frame_restoration_type + +AV1 Frame Restoration Type. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FRAME_RESTORE_NONE`` + - 0 + - No filtering is applied. + * - ``V4L2_AV1_FRAME_RESTORE_WIENER`` + - 1 + - Wiener filter process is invoked. + * - ``V4L2_AV1_FRAME_RESTORE_SGRPROJ`` + - 2 + - Self guided filter process is invoked. + * - ``V4L2_AV1_FRAME_RESTORE_SWITCHABLE`` + - 3 + - Restoration filter is swichtable. + +.. c:type:: v4l2_av1_loop_restoration + +AV1 Loop Restoration as described in section 6.10.15 "Loop restoration params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_loop_restoration + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Loop Restoration Flags <av1_loop_restoration_flags>`. + * - __u8 + - ``lr_unit_shift`` + - Specifies if the luma restoration size should be halved. + * - __u8 + - ``lr_uv_shift`` + - Specifies if the chroma size should be half the luma size. + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - :c:type:`v4l2_av1_frame_restoration_type` + - ``frame_restoration_type[V4L2_AV1_NUM_PLANES_MAX]`` + - Specifies the type of restoration used for each plane. + * - __u8 + - ``loop_restoration_size[V4L2_AV1_MAX_NUM_PLANES]`` + - Specifies the size of loop restoration units in units of samples in the + current plane. + +.. _av1_loop_restoration_flags: + +``AV1 Loop Restoration Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_LOOP_RESTORATION_FLAG_USES_LR`` + - 0x00000001 + - Retains the same meaning as UsesLr in :ref:`av1`. + * - ``V4L2_AV1_LOOP_RESTORATION_FLAG_USES_CHROMA_LR`` + - 0x00000002 + - Retains the same meaning as UsesChromaLr in :ref:`av1`. + +.. c:type:: v4l2_av1_cdef + +AV1 CDEF params semantics as described in section 6.10.14 "CDEF params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_cdef + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``damping_minus_3`` + - Controls the amount of damping in the deringing filter. + * - __u8 + - ``bits`` + - Specifies the number of bits needed to specify which CDEF filter to + apply. + * - __u8 + - ``y_pri_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the primary filter. + * - __u8 + - ``y_sec_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the secondary filter. + * - __u8 + - ``uv_pri_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the primary filter. + * - __u8 + - ``uv_secondary_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the secondary filter. + +.. c:type:: v4l2_av1_segment_feature + +AV1 segment features as described in section 3 "Symbols and abbreviated terms" +of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEG_LVL_ALT_Q`` + - 0 + - Index for quantizer segment feature. + * - ``V4L2_AV1_SEG_LVL_ALT_LF_Y_V`` + - 1 + - Index for vertical luma loop filter segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_FRAME`` + - 5 + - Index for reference frame segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_SKIP`` + - 6 + - Index for skip segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_GLOBALMV`` + - 7 + - Index for global mv feature. + * - ``V4L2_AV1_SEG_LVL_MAX`` + - 8 + - Number of segment features. + +.. c:type:: v4l2_av1_segmentation + +AV1 Segmentation params as defined in section 6.8.13 "Segmentation params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_segmentation + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Segmentation Flags <av1_segmentation_flags>` + * - __u8 + - ``last_active_seg_id`` + - Indicates the highest numbered segment id that has some + enabled feature. This is used when decoding the segment id to only decode + choices corresponding to used segments. + * - __u8 + - ``feature_enabled[V4L2_AV1_MAX_SEGMENTS]`` + - Bitmask defining which features are enabled in each segment. Use + V4L2_AV1_SEGMENT_FEATURE_ENABLED to build a suitable mask. + * - __u16 + - `feature_data[V4L2_AV1_MAX_SEGMENTS][V4L2_AV1_SEG_LVL_MAX]`` + - Data attached to each feature. Data entry is only valid if the feature + is enabled. + +.. _av1_segmentation_flags: + +``AV1 Segmentation Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEGMENTATION_FLAG_ENABLED`` + - 0x00000001 + - If set, indicates that this frame makes use of the segmentation tool. If + not set, indicates that the frame does not use segmentation. + * - ``V4L2_AV1_SEGMENTATION_FLAG_UPDATE_MAP`` + - 0x00000002 + - If set, indicates that the segmentation map are updated during the + decoding of this frame. If not set, indicates that the segmentation map + from the previous frame is used. + * - ``V4L2_AV1_SEGMENTATION_FLAG_TEMPORAL_UPDATE`` + - 0x00000004 + - If set, indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. If not set, indicates that + the new segmentation map is coded without reference to the existing + segmentation map. + * - ``V4L2_AV1_SEGMENTATION_FLAG_UPDATE_DATA`` + - 0x00000008 + - If set, indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. If not set, indicates that + the new segmentation map is coded without reference to the existing + segmentation map. + * - ``V4L2_AV1_SEGMENTATION_FLAG_SEG_ID_PRE_SKIP`` + - 0x00000010 + - If set, indicates that the segment id will be read before the skip + syntax element. If not set, indicates that the skip syntax element will + be read first. + +.. c:type:: v4l2_av1_loop_filter + +AV1 Loop filter params as defined in section 6.8.10 "Loop filter semantics" of +:ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_global_motion + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Loop Filter flags <av1_loop_filter_flags>` for more details. + * - __u8 + - ``level[4]`` + - An array containing loop filter strength values. Different loop + filter strength values from the array are used depending on the image + plane being filtered, and the edge direction (vertical or horizontal) + being filtered. + * - __u8 + - ``sharpness`` + - indicates the sharpness level. The loop_filter_level and + loop_filter_sharpness together determine when a block edge is filtered, + and by how much the filtering can change the sample values. The loop + filter process is described in section 7.14 of :ref:`av1`. + * - __u8 + - ``ref_deltas[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - contains the adjustment needed for the filter level based on the + chosen reference frame. If this syntax element is not present, it + maintains its previous value. + * - __u8 + - ``mode_deltas[2]`` + - contains the adjustment needed for the filter level based on + the chosen mode. If this syntax element is not present, it maintains its + previous value. + * - __u8 + - ``delta_lf_res`` + - specifies the left shift which should be applied to decoded loop filter + delta values. + +.. _av1_loop_filter_flags: + +``AV1 Loop Filter Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_ENABLED`` + - 0x00000001 + - If set, means that the filter level depends on the mode and reference + frame used to predict a block. If not set, means that the filter level + does not depend on the mode and reference frame. + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_UPDATE`` + - 0x00000002 + - If set, means that additional syntax elements are present that specify + which mode and reference frame deltas are to be updated. If not set, + means that these syntax elements are not present. + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_LF_PRESENT`` + - 0x00000004 + - Specifies whether loop filter delta values are present + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_LF_MULTI`` + - 0x00000008 + - A value equal to 1 specifies that separate loop filter + deltas are sent for horizontal luma edges, vertical luma edges, + the U edges, and the V edges. A value of delta_lf_multi equal to 0 + specifies that the same loop filter delta is used for all edges. + +.. c:type:: v4l2_av1_quantization + +AV1 Quantization params as defined in section 6.8.11 "Quantization params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Loop Filter flags <av1_quantization_flags>` for more details. + * - __u8 + - ``base_q_idx`` + - Indicates the base frame qindex. This is used for Y AC coefficients and + as the base value for the other quantizers. + * - __u8 + - ``delta_q_y_dc`` + - Indicates the Y DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_u_dc`` + - Indicates the U DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_u_ac`` + - Indicates the U AC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_v_dc`` + - Indicates the V DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_v_ac`` + - Indicates the V AC quantizer relative to base_q_idx. + * - __u8 + - ``qm_y`` + - Specifies the level in the quantizer matrix that should be used for + luma plane decoding. + * - __u8 + - ``qm_u`` + - Specifies the level in the quantizer matrix that should be used for + chroma U plane decoding. + * - __u8 + - ``qm_v`` + - Specifies the level in the quantizer matrix that should be used for + chroma V plane decoding. + * - __u8 + - ``delta_q_res`` + - Specifies the left shift which should be applied to decoded quantizer + index delta values. + +.. _av1_quantization_flags: + +``AV1 Quantization Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_QUANTIZATION_FLAG_DIFF_UV_DELTA`` + - 0x00000001 + - If set, indicates that the U and V delta quantizer values are coded + separately. If not set, indicates that the U and V delta quantizer + values share a common value. + * - ``V4L2_AV1_QUANTIZATION_FLAG_USING_QMATRIX`` + - 0x00000002 + - If set, specifies that the quantizer matrix will be used to compute + quantizers. + * - ``V4L2_AV1_QUANTIZATION_FLAG_DELTA_Q_PRESENT`` + - 0x00000004 + - Specifies whether quantizer index delta values are present. + +.. c:type:: v4l2_av1_tile_info + +AV1 Tile info as defined in section 6.8.14 "Tile info semantics" of ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_tile_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Tile Info flags <av1_tile_info_flags>` for more details. + * - __u8 + - ``context_update_tile_id`` + - Specifies which tile to use for the CDF update. + * - __u8 + - ``tile_cols`` + - Specifies the number of tiles across the frame. + * - __u8 + - ``tile_rows`` + - Specifies the number of tiles down the frame. + * - __u32 + - ``mi_col_starts[V4L2_AV1_MAX_TILE_COLS + 1]`` + - An array specifying the start column (in units of 4x4 luma + samples) for each tile across the image. + * - __u32 + - ``mi_row_starts[V4L2_AV1_MAX_TILE_ROWS + 1]`` + - An array specifying the start row (in units of 4x4 luma + samples) for each tile across the image. + * - __u32 + - ``width_in_sbs_minus_1[V4L2_AV1_MAX_TILE_COLS]`` + - Specifies the width of a tile minus 1 in units of superblocks. + * - __u32 + - ``height_in_sbs_minus_1[V4L2_AV1_MAX_TILE_ROWS]`` + - Specifies the height of a tile minus 1 in units of superblocks. + * - __u8 + - ``tile_size_bytes`` + - Specifies the number of bytes needed to code each tile size. + * - __u8 + - ``reserved[3]`` + - Applications and drivers must set this to zero. + +.. _av1_tile_info_flags: + +``AV1 Tile Info Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_TILE_INFO_FLAG_UNIFORM_TILE_SPACING`` + - 0x00000001 + - If set, means that the tiles are uniformly spaced across the frame. (In + other words, all tiles are the same size except for the ones at the + right and bottom edge which can be smaller). If not set means that the + tile sizes are coded. + +.. c:type:: v4l2_av1_frame_type + +AV1 Frame Type + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_KEY_FRAME`` + - 0 + - Key frame. + * - ``V4L2_AV1_INTER_FRAME`` + - 1 + - Inter frame. + * - ``V4L2_AV1_INTRA_ONLY_FRAME`` + - 2 + - Intra-only frame. + * - ``V4L2_AV1_SWITCH_FRAME`` + - 3 + - Switch frame. + +.. c:type:: v4l2_av1_interpolation_filter + +AV1 Interpolation Filter + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP`` + - 0 + - Eight tap filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP_SMOOTH`` + - 1 + - Eight tap smooth filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP_SHARP`` + - 2 + - Eight tap sharp filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_BILINEAR`` + - 3 + - Bilinear filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_SWITCHABLE`` + - 4 + - Filter selection is signaled at the block level. + +.. c:type:: v4l2_av1_tx_mode + +AV1 Tx mode as described in section 6.8.21 "TX mode semantics" of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_TX_MODE_ONLY_4X4`` + - 0 + - The inverse transform will use only 4x4 transforms. + * - ``V4L2_AV1_TX_MODE_LARGEST`` + - 1 + - The inverse transform will use the largest transform size that fits + inside the block. + * - ``V4L2_AV1_TX_MODE_SELECT`` + - 2 + - The choice of transform size is specified explicitly for each block. + +``V4L2_CID_STATELESS_AV1_FRAME (struct)`` + Represents a Frame Header OBU. See 6.8 "Frame Header OBU semantics" of + :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_frame + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_av1_tile_info` + - ``tile_info`` + - Tile info + * - struct :c:type:`v4l2_av1_quantization` + - ``quantization`` + - Quantization parameters. + * - struct :c:type:`v4l2_av1_segmentation` + - ``segmentation`` + - Segmentation parameters. + * - __u8 + - ``superres_denom`` + - The denominator for the upscaling ratio. + * - struct :c:type:`v4l2_av1_loop_filter` + - ``loop_filter`` + - Loop filter params + * - struct :c:type:`v4l2_av1_cdef` + - ``cdef`` + - CDEF params + * - __u8 + - ``skip_mode_frame[2]`` + - Specifies the frames to use for compound prediction when skip_mode is + equal to 1. + * - __u8 + - ``primary_ref_frame`` + - Specifies which reference frame contains the CDF values and other state + that should be loaded at the start of the frame. + * - struct :c:type:`v4l2_av1_loop_restoration` + - ``loop_restoration`` + - Loop restoration parameters. + * - struct :c:type:`v4l2_av1_loop_global_motion` + - ``global_motion`` + - Global motion parameters. + * - __u32 + - ``flags`` + - See + :ref:`AV1 Frame flags <av1_frame_flags>` for more details. + * - enum :c:type:`v4l2_av1_frame_type` + - ``frame_type`` + - Specifies the AV1 frame type + * - __u32 + - ``order_hint`` + - Specifies OrderHintBits least significant bits of the expected output + order for this frame. + * - __u32 + - ``upscaled_width`` + - The upscaled width. + * - enum :c:type:`v4l2_av1_interpolation_filter` + - ``interpolation_filter`` + - Specifies the filter selection used for performing inter prediction. + * - enum :c:type:`v4l2_av1_tx_mode` + - ``tx_mode`` + - Specifies how the transform size is determined. + * - __u32 + - ``frame_width_minus_1`` + - Add 1 to get the frame's width. + * - __u32 + - ``frame_height_minus_1`` + - Add 1 to get the frame's height. + * - __u16 + - ``render_width_minus_1`` + - Add 1 to get the render width of the frame in luma samples. + * - __u16 + - ``render_height_minus_1`` + - Add 1 to get the render height of the frame in luma samples. + * - __u32 + - ``current_frame_id`` + - Specifies the frame id number for the current frame. Frame + id numbers are additional information that do not affect the decoding + process, but provide decoders with a way of detecting missing reference + frames so that appropriate action can be taken. + * - __u8 + - ``buffer_removal_time[V4L2_AV1_MAX_OPERATING_POINTS]`` + - Specifies the frame removal time in units of DecCT clock ticks counted + from the removal time of the last random access point for operating point + opNum. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + * - __u32 + - ``order_hints[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - Specifies the expected output order hint for each reference frame. + This field corresponds to the OrderHints variable from the specification + (section 5.9.2 "Uncompressed header syntax"). As such, this is only + used for non-intra frames and ignored otherwise. order_hints[0] is + always ignored. + * - __u64 + - ``reference_frame_ts[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - The V4L2 timestamp for each of the reference frames enumerated in + enum :c:type:`v4l2_av1_reference_frame` starting at + ``V4L2_AV1_REF_LAST_FRAME``. This represents the state of reference + slot as described in the spec and updated by userland through the + "Reference frame update process" in section 7.20 The timestamp refers + to the ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __s8 + - ``ref_frame_idx[V4L2_AV1_REFS_PER_FRAME]`` + - An index into ``reference_frame_ts`` representing the ordered list of + references used by inter-frame. Matches the bitstream syntax + element of the same name. + * - __u8 + - ``refresh_frame_flags`` + - Contains a bitmask that specifies which reference frame slots will be + updated with the current frame after it is decoded. + +.. _av1_frame_flags: + +``AV1 Frame Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FRAME_FLAG_SHOW_FRAME`` + - 0x00000001 + - If set, specifies that this frame should be immediately output once + decoded. If not set, specifies that this frame should not be immediately + output; it may be output later if a later uncompressed header uses + show_existing_frame equal to 1. + * - ``V4L2_AV1_FRAME_FLAG_SHOWABLE_FRAME`` + - 0x00000002 + - If set, specifies that the frame may be output using the + show_existing_frame mechanism. If not set, specifies that this frame + will not be output using the show_existing_frame mechanism. + * - ``V4L2_AV1_FRAME_FLAG_ERROR_RESILIENT_MODE`` + - 0x00000004 + - Specifies whether error resilient mode is enabled. + * - ``V4L2_AV1_FRAME_FLAG_DISABLE_CDF_UPDATE`` + - 0x00000008 + - Specifies whether the CDF update in the symbol decoding process should + be disabled. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_SCREEN_CONTENT_TOOLS`` + - 0x00000010 + - If set, indicates that intra blocks may use palette encoding. If not + set, indicates that palette encoding is never used. + * - ``V4L2_AV1_FRAME_FLAG_FORCE_INTEGER_MV`` + - 0x00000020 + - If set, specifies that motion vectors will always be integers. If not + set, specifies that motion vectors can contain fractional bits. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_INTRABC`` + - 0x00000040 + - If set, indicates that intra block copy may be used in this frame. If + not set, indicates that intra block copy is not allowed in this frame. + * - ``V4L2_AV1_FRAME_FLAG_USE_SUPERRES`` + - 0x00000080 + - If set, indicates that upscaling is needed. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_HIGH_PRECISION_MV`` + - 0x00000100 + - If set, specifies that motion vectors are specified to eighth pel + precision. If not set, specifies that motion vectors are specified to + quarter pel precision; + * - ``V4L2_AV1_FRAME_FLAG_IS_MOTION_MODE_SWITCHABLE`` + - 0x00000200 + - If not set, specifies that only the SIMPLE motion mode will be used. + * - ``V4L2_AV1_FRAME_FLAG_USE_REF_FRAME_MVS`` + - 0x00000400 + - If set specifies that motion vector information from a previous frame + can be used when decoding the current frame. If not set, specifies that + this information will not be used. + * - ``V4L2_AV1_FRAME_FLAG_DISABLE_FRAME_END_UPDATE_CDF`` + - 0x00000800 + - If set indicates that the end of frame CDF update is disabled. If not + set, indicates that the end of frame CDF update is enabled + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_WARPED_MOTION`` + - 0x00001000 + - If set, indicates that the syntax element motion_mode may be present, if + not set, indicates that the syntax element motion_mode will not be + present. + * - ``V4L2_AV1_FRAME_FLAG_REFERENCE_SELECT`` + - 0x00002000 + - If set, specifies that the mode info for inter blocks contains the + syntax element comp_mode that indicates whether to use single or + compound reference prediction. If not set, specifies that all inter + blocks will use single prediction. + * - ``V4L2_AV1_FRAME_FLAG_REDUCED_TX_SET`` + - 0x00004000 + - If set, specifies that the frame is restricted to a reduced subset of + the full set of transform types. + * - ``V4L2_AV1_FRAME_FLAG_SKIP_MODE_ALLOWED`` + - 0x00008000 + - This flag retains the same meaning as SkipModeAllowed in :ref:`av1`. + * - ``V4L2_AV1_FRAME_FLAG_SKIP_MODE_PRESENT`` + - 0x00010000 + - If set, specifies that the syntax element skip_mode will be present, if + not set, specifies that skip_mode will not be used for this frame. + * - ``V4L2_AV1_FRAME_FLAG_FRAME_SIZE_OVERRIDE`` + - 0x00020000 + - If set, specifies that the frame size will either be specified as the + size of one of the reference frames, or computed from the + frame_width_minus_1 and frame_height_minus_1 syntax elements. If not + set, specifies that the frame size is equal to the size in the sequence + header. + * - ``V4L2_AV1_FRAME_FLAG_BUFFER_REMOVAL_TIME_PRESENT`` + - 0x00040000 + - If set, specifies that buffer_removal_time is present. If not set, + specifies that buffer_removal_time is not present. + * - ``V4L2_AV1_FRAME_FLAG_FRAME_REFS_SHORT_SIGNALING`` + - 0x00080000 + - If set, indicates that only two reference frames are explicitly + signaled. If not set, indicates that all reference frames are explicitly + signaled. + +``V4L2_CID_STATELESS_AV1_FILM_GRAIN (struct)`` + Represents the optional film grain parameters. See section + 6.8.20 "Film grain params semantics" of :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_film_grain + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_ctrl_av1_film_grain + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Film Grain Flags <av1_film_grain_flags>`. + * - __u8 + - ``cr_mult`` + - Represents a multiplier for the cr component used in derivation of the + input index to the cr component scaling function. + * - __u16 + - ``grain_seed`` + - Specifies the starting value for the pseudo-random numbers used during + film grain synthesis. + * - __u8 + - ``film_grain_params_ref_idx`` + - Indicates which reference frame contains the film grain parameters to be + used for this frame. + * - __u8 + - ``num_y_points`` + - Specifies the number of points for the piece-wise linear scaling + function of the luma component. + * - __u8 + - ``point_y_value[V4L2_AV1_MAX_NUM_Y_POINTS]`` + - Represents the x (luma value) coordinate for the i-th point + of the piecewise linear scaling function for luma component. The values + are signaled on the scale of 0..255. In case of 10 bit video, these + values correspond to luma values divided by 4. In case of 12 bit video, + these values correspond to luma values divided by 16. + * - __u8 + - ``point_y_scaling[V4L2_AV1_MAX_NUM_Y_POINTS]`` + - Represents the scaling (output) value for the i-th point + of the piecewise linear scaling function for luma component. + * - __u8 + - ``num_cb_points`` + - Specifies the number of points for the piece-wise linear scaling + function of the cb component. + * - __u8 + - ``point_cb_value[V4L2_AV1_MAX_NUM_CB_POINTS]`` + - Represents the x coordinate for the i-th point of the + piece-wise linear scaling function for cb component. The values are + signaled on the scale of 0..255. + * - __u8 + - ``point_cb_scaling[V4L2_AV1_MAX_NUM_CB_POINTS]`` + - Represents the scaling (output) value for the i-th point of the + piecewise linear scaling function for cb component. + * - __u8 + - ``num_cr_points`` + - Represents the number of points for the piece-wise + linear scaling function of the cr component. + * - __u8 + - ``point_cr_value[V4L2_AV1_MAX_NUM_CR_POINTS]`` + - Represents the x coordinate for the i-th point of the + piece-wise linear scaling function for cr component. The values are + signaled on the scale of 0..255. + * - __u8 + - ``point_cr_scaling[V4L2_AV1_MAX_NUM_CR_POINTS]`` + - Represents the scaling (output) value for the i-th point of the + piecewise linear scaling function for cr component. + * - __u8 + - ``grain_scaling_minus_8`` + - Represents the shift - 8 applied to the values of the chroma component. + The grain_scaling_minus_8 can take values of 0..3 and determines the + range and quantization step of the standard deviation of film grain. + * - __u8 + - ``ar_coeff_lag`` + - Specifies the number of auto-regressive coefficients for luma and + chroma. + * - __u8 + - ``ar_coeffs_y_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the Y plane. + * - __u8 + - ``ar_coeffs_cb_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the U plane. + * - __u8 + - ``ar_coeffs_cr_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the V plane. + * - __u8 + - ``ar_coeff_shift_minus_6`` + - Specifies the range of the auto-regressive coefficients. Values of 0, + 1, 2, and 3 correspond to the ranges for auto-regressive coefficients of + [-2, 2), [-1, 1), [-0.5, 0.5) and [-0.25, 0.25) respectively. + * - __u8 + - ``grain_scale_shift`` + - Specifies how much the Gaussian random numbers should be scaled down + during the grain synthesis process. + * - __u8 + - ``cb_mult`` + - Represents a multiplier for the cb component used in derivation of the + input index to the cb component scaling function. + * - __u8 + - ``cb_luma_mult`` + - Represents a multiplier for the average luma component used in + derivation of the input index to the cb component scaling function.. + * - __u8 + - ``cr_luma_mult`` + - Represents a multiplier for the average luma component used in + derivation of the input index to the cr component scaling function. + * - __u16 + - ``cb_offset`` + - Represents an offset used in derivation of the input index to the + cb component scaling function. + * - __u16 + - ``cr_offset`` + - Represents an offset used in derivation of the input index to the + cr component scaling function. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + +.. _av1_film_grain_flags: + +``AV1 Film Grain Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FILM_GRAIN_FLAG_APPLY_GRAIN`` + - 0x00000001 + - If set, specifies that film grain should be added to this frame. If not + set, specifies that film grain should not be added. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_UPDATE_GRAIN`` + - 0x00000002 + - If set, means that a new set of parameters should be sent. If not set, + specifies that the previous set of parameters should be used. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_CHROMA_SCALING_FROM_LUMA`` + - 0x00000004 + - If set, specifies that the chroma scaling is inferred from the luma + scaling. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_OVERLAP`` + - 0x00000008 + - If set, indicates that the overlap between film grain blocks shall be + applied. If not set, indicates that the overlap between film grain blocks + shall not be applied. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_CLIP_TO_RESTRICTED_RANGE`` + - 0x00000010 + - If set, indicates that clipping to the restricted (studio, i.e. limited) + range shall be applied to the sample values after adding the film grain + (see the semantics for color_range for an explanation of studio swing). + If not set, indicates that clipping to the full range shall be applied + to the sample values after adding the film grain. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index d0d506a444b1..2a165ae063fb 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1,13 +1,6 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later -.. _mpeg-controls: +.. _codec-controls: *********************** Codec Control Reference @@ -33,7 +26,7 @@ Generic Codec Controls Codec Control IDs ----------------- -``V4L2_CID_MPEG_CLASS (class)`` +``V4L2_CID_CODEC_CLASS (class)`` The Codec class descriptor. Calling :ref:`VIDIOC_QUERYCTRL` for this control will return a description of this control class. This description can be @@ -399,7 +392,7 @@ enum v4l2_mpeg_audio_mode_extension - which subbands are in intensity stereo. All other subbands are coded in stereo. Layer III is not (yet) supported. Possible values are: - +.. tabularcolumns:: |p{9.1cm}|p{8.4cm}| .. flat-table:: :header-rows: 0 @@ -581,17 +574,61 @@ enum v4l2_mpeg_video_bitrate_mode - - Variable bitrate * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR`` - Constant bitrate + * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CQ`` + - Constant quality ``V4L2_CID_MPEG_VIDEO_BITRATE (integer)`` - Video bitrate in bits per second. + Average video bitrate in bits per second. ``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)`` Peak video bitrate in bits per second. Must be larger or equal to the average video bitrate. It is ignored if the video bitrate mode is set to constant bitrate. +``V4L2_CID_MPEG_VIDEO_CONSTANT_QUALITY (integer)`` + Constant quality level control. This control is applicable when + ``V4L2_CID_MPEG_VIDEO_BITRATE_MODE`` value is + ``V4L2_MPEG_VIDEO_BITRATE_MODE_CQ``. Valid range is 1 to 100 + where 1 indicates lowest quality and 100 indicates highest quality. + Encoder will decide the appropriate quantization parameter and + bitrate to produce requested frame quality. + + +``V4L2_CID_MPEG_VIDEO_FRAME_SKIP_MODE (enum)`` + +enum v4l2_mpeg_video_frame_skip_mode - + Indicates in what conditions the encoder should skip frames. If + encoding a frame would cause the encoded stream to be larger then a + chosen data limit then the frame will be skipped. Possible values + are: + + +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| + +.. raw:: latex + + \small + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_DISABLED`` + - Frame skip mode is disabled. + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_LEVEL_LIMIT`` + - Frame skip mode enabled and buffer limit is set by the chosen + level and is defined by the standard. + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_BUF_LIMIT`` + - Frame skip mode enabled and buffer limit is set by the + :ref:`VBV (MPEG1/2/4) <v4l2-mpeg-video-vbv-size>` or + :ref:`CPB (H264) buffer size <v4l2-mpeg-video-h264-cpb-size>` control. + +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)`` For every captured frame, skip this many subsequent frames (default 0). @@ -637,11 +674,64 @@ enum v4l2_mpeg_video_bitrate_mode - is currently displayed (decoded). This value is reset to 0 whenever the decoder is started. +``V4L2_CID_MPEG_VIDEO_DEC_CONCEAL_COLOR (integer64)`` + This control sets the conceal color in YUV color space. It describes + the client preference of the error conceal color in case of an error + where the reference frame is missing. The decoder should fill the + reference buffer with the preferred color and use it for future + decoding. The control is using 16 bits per channel. + Applicable to decoders. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - + - 8bit format + - 10bit format + - 12bit format + * - Y luminance + - Bit 0:7 + - Bit 0:9 + - Bit 0:11 + * - Cb chrominance + - Bit 16:23 + - Bit 16:25 + - Bit 16:27 + * - Cr chrominance + - Bit 32:39 + - Bit 32:41 + - Bit 32:43 + * - Must be zero + - Bit 48:63 + - Bit 48:63 + - Bit 48:63 + ``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)`` If enabled the decoder expects to receive a single slice per buffer, otherwise the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs. +``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY_ENABLE (boolean)`` + If the display delay is enabled then the decoder is forced to return + a CAPTURE buffer (decoded frame) after processing a certain number + of OUTPUT buffers. The delay can be set through + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY``. This + feature can be used for example for generating thumbnails of videos. + Applicable to the decoder. + +``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY (integer)`` + Display delay value for decoder. The decoder is forced to + return a decoded frame after the set 'display delay' number of + frames. If this number is low it may result in frames returned out + of display order, in addition the hardware may still be using the + returned buffer as a reference picture for subsequent frames. + +``V4L2_CID_MPEG_VIDEO_AU_DELIMITER (boolean)`` + If enabled then, AUD (Access Unit Delimiter) NALUs will be generated. + That could be useful to find the start of a frame without having to + fully parse each NALU. Applicable to the H264 and HEVC encoders. + ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)`` Enable writing sample aspect ratio in the Video Usability Information. Applicable to the H264 encoder. @@ -836,7 +926,11 @@ enum v4l2_mpeg_video_h264_profile - The profile information for H264. Applicable to the H264 encoder. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{10.2cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -879,7 +973,9 @@ enum v4l2_mpeg_video_h264_profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_HIGH`` - Constrained High profile +.. raw:: latex + \normalsize .. _v4l2-mpeg-video-mpeg2-profile: @@ -890,7 +986,11 @@ enum v4l2_mpeg_video_mpeg2_profile - The profile information for MPEG2. Applicable to MPEG2 codecs. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{10.2cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -910,6 +1010,9 @@ enum v4l2_mpeg_video_mpeg2_profile - - Multi-view profile (MVP) +.. raw:: latex + + \normalsize .. _v4l2-mpeg-video-mpeg4-profile: @@ -920,7 +1023,11 @@ enum v4l2_mpeg_video_mpeg4_profile - The profile information for MPEG4. Applicable to the MPEG4 encoder. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{11.8cm}|p{5.7cm}| .. flat-table:: :header-rows: 0 @@ -935,9 +1042,11 @@ enum v4l2_mpeg_video_mpeg4_profile - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE_SCALABLE`` - Simple Scalable profile * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY`` - - + - Advanced Coding Efficiency profile +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)`` The maximum number of reference pictures used for encoding. @@ -993,7 +1102,7 @@ enum v4l2_mpeg_video_h264_loop_filter_mode - \small -.. tabularcolumns:: |p{13.6cm}|p{3.9cm}| +.. tabularcolumns:: |p{13.5cm}|p{4.0cm}| .. flat-table:: :header-rows: 0 @@ -1065,7 +1174,46 @@ enum v4l2_mpeg_video_h264_entropy_mode - Cyclic intra macroblock refresh. This is the number of continuous macroblocks refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from - the top of the frame. Applicable to H264, H263 and MPEG4 encoder. + the top of the frame. Setting this control to zero means that + macroblocks will not be refreshed. Note that this control will not + take effect when ``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD`` control + is set to non zero value. + Applicable to H264, H263 and MPEG4 encoder. + +``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD_TYPE (enum)`` + +enum v4l2_mpeg_video_intra_refresh_period_type - + Sets the type of intra refresh. The period to refresh + the whole frame is specified by V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD. + Note that if this control is not present, then it is undefined what + refresh type is used and it is up to the driver to decide. + Applicable to H264 and HEVC encoders. Possible values are: + +.. tabularcolumns:: |p{9.6cm}|p{7.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_INTRA_REFRESH_PERIOD_TYPE_RANDOM`` + - The whole frame is completely refreshed randomly + after the specified period. + * - ``V4L2_MPEG_VIDEO_INTRA_REFRESH_PERIOD_TYPE_CYCLIC`` + - The whole frame MBs are completely refreshed in cyclic order + after the specified period. + +``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD (integer)`` + Intra macroblock refresh period. This sets the period to refresh + the whole frame. In other words, this defines the number of frames + for which the whole frame will be intra-refreshed. An example: + setting period to 1 means that the whole frame will be refreshed, + setting period to 2 means that the half of macroblocks will be + intra-refreshed on frameX and the other half of macroblocks + will be refreshed in frameX + 1 and so on. Setting the period to + zero means no period is specified. + Note that if the client sets this control to non zero value the + ``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB`` control shall be + ignored. Applicable to H264 and HEVC encoders. ``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)`` Frame level rate control enable. If this control is disabled then @@ -1145,6 +1293,18 @@ enum v4l2_mpeg_video_h264_entropy_mode - V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter should be chosen to meet both requirements. +``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the H264 B frame to limit B frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the H264 B frame to limit B frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + ``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)`` Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31. @@ -1163,6 +1323,8 @@ enum v4l2_mpeg_video_h264_entropy_mode - Quantization parameter for an B frame for MPEG4. Valid range: from 1 to 31. +.. _v4l2-mpeg-video-vbv-size: + ``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)`` The Video Buffer Verifier size in kilobytes, it is used as a limitation of frame skip. The VBV is defined in the standard as a @@ -1200,6 +1362,8 @@ enum v4l2_mpeg_video_h264_entropy_mode - Force a key frame for the next queued buffer. Applicable to encoders. This is a general, codec-agnostic keyframe control. +.. _v4l2-mpeg-video-h264-cpb-size: + ``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)`` The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip. The CPB is defined in the H264 standard as @@ -1372,7 +1536,7 @@ enum v4l2_mpeg_video_h264_fmo_change_dir - Specifies a direction of the slice group change for raster and wipe maps. Applicable to the H264 encoder. Possible values are: - +.. tabularcolumns:: |p{9.6cm}|p{7.9cm}| .. flat-table:: :header-rows: 0 @@ -1460,882 +1624,26 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - * - Bit 16:32 - Layer number +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L0_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 0 for H264 encoder. -.. _v4l2-mpeg-h264: - -``V4L2_CID_MPEG_VIDEO_H264_SPS (struct)`` - Specifies the sequence parameter set (as extracted from the - bitstream) for the associated H264 slice data. This includes the - necessary parameters for configuring a stateless hardware decoding - pipeline for H264. The bitstream parameters are defined according - to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data - Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_sps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_sps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``profile_idc`` - - - * - __u8 - - ``constraint_set_flags`` - - See :ref:`Sequence Parameter Set Constraints Set Flags <h264_sps_constraints_set_flags>` - * - __u8 - - ``level_idc`` - - - * - __u8 - - ``seq_parameter_set_id`` - - - * - __u8 - - ``chroma_format_idc`` - - - * - __u8 - - ``bit_depth_luma_minus8`` - - - * - __u8 - - ``bit_depth_chroma_minus8`` - - - * - __u8 - - ``log2_max_frame_num_minus4`` - - - * - __u8 - - ``pic_order_cnt_type`` - - - * - __u8 - - ``log2_max_pic_order_cnt_lsb_minus4`` - - - * - __u8 - - ``max_num_ref_frames`` - - - * - __u8 - - ``num_ref_frames_in_pic_order_cnt_cycle`` - - - * - __s32 - - ``offset_for_ref_frame[255]`` - - - * - __s32 - - ``offset_for_non_ref_pic`` - - - * - __s32 - - ``offset_for_top_to_bottom_field`` - - - * - __u16 - - ``pic_width_in_mbs_minus1`` - - - * - __u16 - - ``pic_height_in_map_units_minus1`` - - - * - __u32 - - ``flags`` - - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` - -.. _h264_sps_constraints_set_flags: - -``Sequence Parameter Set Constraints Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG`` - - 0x00000001 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG`` - - 0x00000002 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG`` - - 0x00000004 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG`` - - 0x00000008 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG`` - - 0x00000010 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG`` - - 0x00000020 - - - -.. _h264_sps_flags: - -``Sequence Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE`` - - 0x00000001 - - - * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS`` - - 0x00000002 - - - * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO`` - - 0x00000004 - - - * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED`` - - 0x00000008 - - - * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY`` - - 0x00000010 - - - * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD`` - - 0x00000020 - - - * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE`` - - 0x00000040 - - - -``V4L2_CID_MPEG_VIDEO_H264_PPS (struct)`` - Specifies the picture parameter set (as extracted from the - bitstream) for the associated H264 slice data. This includes the - necessary parameters for configuring a stateless hardware decoding - pipeline for H264. The bitstream parameters are defined according - to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP - Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_pps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_pps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``pic_parameter_set_id`` - - - * - __u8 - - ``seq_parameter_set_id`` - - - * - __u8 - - ``num_slice_groups_minus1`` - - - * - __u8 - - ``num_ref_idx_l0_default_active_minus1`` - - - * - __u8 - - ``num_ref_idx_l1_default_active_minus1`` - - - * - __u8 - - ``weighted_bipred_idc`` - - - * - __s8 - - ``pic_init_qp_minus26`` - - - * - __s8 - - ``pic_init_qs_minus26`` - - - * - __s8 - - ``chroma_qp_index_offset`` - - - * - __s8 - - ``second_chroma_qp_index_offset`` - - - * - __u16 - - ``flags`` - - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` - -.. _h264_pps_flags: - -``Picture Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` - - 0x00000001 - - - * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` - - 0x00000002 - - - * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` - - 0x00000004 - - - * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` - - 0x00000008 - - - * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` - - 0x00000010 - - - * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` - - 0x00000020 - - - * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` - - 0x00000040 - - - * - ``V4L2_H264_PPS_FLAG_PIC_SCALING_MATRIX_PRESENT`` - - 0x00000080 - - - -``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX (struct)`` - Specifies the scaling matrix (as extracted from the bitstream) for - the associated H264 slice data. The bitstream parameters are - defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling - List Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_scaling_matrix - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``scaling_list_4x4[6][16]`` - - Scaling matrix after applying the inverse scanning process. - Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y, - Inter Cb, Inter Cr. - * - __u8 - - ``scaling_list_8x8[6][64]`` - - Scaling matrix after applying the inverse scanning process. - Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb, - Intra Cr, Inter Cr. - -``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS (struct)`` - Specifies the slice parameters (as extracted from the bitstream) - for the associated H264 slice data. This includes the necessary - parameters for configuring a stateless hardware decoding pipeline - for H264. The bitstream parameters are defined according to - :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further - documentation, refer to the above specification, unless there is - an explicit comment stating otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API - and it is expected to change. - - This structure is expected to be passed as an array, with one - entry for each slice included in the bitstream buffer. - -.. c:type:: v4l2_ctrl_h264_slice_params - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``size`` - - - * - __u32 - - ``start_byte_offset`` - Offset (in bytes) from the beginning of the OUTPUT buffer to the start - of the slice. If the slice starts with a start code, then this is the - offset to such start code. When operating in slice-based decoding mode - (see :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field should - be set to 0. When operating in frame-based decoding mode, this field - should be 0 for the first slice. - * - __u32 - - ``header_bit_size`` - - - * - __u16 - - ``first_mb_in_slice`` - - - * - __u8 - - ``slice_type`` - - - * - __u8 - - ``pic_parameter_set_id`` - - - * - __u8 - - ``colour_plane_id`` - - - * - __u8 - - ``redundant_pic_cnt`` - - - * - __u16 - - ``frame_num`` - - - * - __u16 - - ``idr_pic_id`` - - - * - __u16 - - ``pic_order_cnt_lsb`` - - - * - __s32 - - ``delta_pic_order_cnt_bottom`` - - - * - __s32 - - ``delta_pic_order_cnt0`` - - - * - __s32 - - ``delta_pic_order_cnt1`` - - - * - struct :c:type:`v4l2_h264_pred_weight_table` - - ``pred_weight_table`` - - - * - __u32 - - ``dec_ref_pic_marking_bit_size`` - - Size in bits of the dec_ref_pic_marking() syntax element. - * - __u32 - - ``pic_order_cnt_bit_size`` - - - * - __u8 - - ``cabac_init_idc`` - - - * - __s8 - - ``slice_qp_delta`` - - - * - __s8 - - ``slice_qs_delta`` - - - * - __u8 - - ``disable_deblocking_filter_idc`` - - - * - __s8 - - ``slice_alpha_c0_offset_div2`` - - - * - __s8 - - ``slice_beta_offset_div2`` - - - * - __u8 - - ``num_ref_idx_l0_active_minus1`` - - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l0_default_active_minus1. - * - __u8 - - ``num_ref_idx_l1_active_minus1`` - - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l1_default_active_minus1. - * - __u32 - - ``slice_group_change_cycle`` - - - * - __u8 - - ``ref_pic_list0[32]`` - - Reference picture list after applying the per-slice modifications - * - __u8 - - ``ref_pic_list1[32]`` - - Reference picture list after applying the per-slice modifications - * - __u32 - - ``flags`` - - See :ref:`Slice Parameter Flags <h264_slice_flags>` - -.. _h264_slice_flags: - -``Slice Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SLICE_FLAG_FIELD_PIC`` - - 0x00000001 - - - * - ``V4L2_H264_SLICE_FLAG_BOTTOM_FIELD`` - - 0x00000002 - - - * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED`` - - 0x00000004 - - - * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` - - 0x00000008 - - - -``Prediction Weight Table`` - - The bitstream parameters are defined according to :ref:`h264`, - section 7.4.3.2 "Prediction Weight Table Semantics". For further - documentation, refer to the above specification, unless there is - an explicit comment stating otherwise. +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L1_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 1 for H264 encoder. -.. c:type:: v4l2_h264_pred_weight_table +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L2_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 2 for H264 encoder. -.. cssclass:: longtable +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L3_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 3 for H264 encoder. -.. flat-table:: struct v4l2_h264_pred_weight_table - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``luma_log2_weight_denom`` - - - * - __u16 - - ``chroma_log2_weight_denom`` - - - * - struct :c:type:`v4l2_h264_weight_factors` - - ``weight_factors[2]`` - - The weight factors at index 0 are the weight factors for the reference - list 0, the one at index 1 for the reference list 1. - -.. c:type:: v4l2_h264_weight_factors - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_h264_weight_factors - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s16 - - ``luma_weight[32]`` - - - * - __s16 - - ``luma_offset[32]`` - - - * - __s16 - - ``chroma_weight[32][2]`` - - - * - __s16 - - ``chroma_offset[32][2]`` - - - -``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS (struct)`` - Specifies the decode parameters (as extracted from the bitstream) - for the associated H264 slice data. This includes the necessary - parameters for configuring a stateless hardware decoding pipeline - for H264. The bitstream parameters are defined according to - :ref:`h264`. For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_decode_params - -.. cssclass:: longtable +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L4_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 4 for H264 encoder. -.. flat-table:: struct v4l2_ctrl_h264_decode_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`v4l2_h264_dpb_entry` - - ``dpb[16]`` - - - * - __u16 - - ``num_slices`` - - Number of slices needed to decode the current frame/field. When - operating in slice-based decoding mode (see - :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field - should always be set to one. - * - __u16 - - ``nal_ref_idc`` - - NAL reference ID value coming from the NAL Unit header - * - __s32 - - ``top_field_order_cnt`` - - Picture Order Count for the coded top field - * - __s32 - - ``bottom_field_order_cnt`` - - Picture Order Count for the coded bottom field - * - __u32 - - ``flags`` - - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` - -.. _h264_decode_params_flags: - -``Decode Parameters Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC`` - - 0x00000001 - - That picture is an IDR picture +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L5_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 5 for H264 encoder. -.. c:type:: v4l2_h264_dpb_entry - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_h264_dpb_entry - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``reference_ts`` - - Timestamp of the V4L2 capture buffer to use as reference, used - with B-coded and P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u16 - - ``frame_num`` - - - * - __u16 - - ``pic_num`` - - - * - __s32 - - ``top_field_order_cnt`` - - - * - __s32 - - ``bottom_field_order_cnt`` - - - * - __u32 - - ``flags`` - - See :ref:`DPB Entry Flags <h264_dpb_flags>` - -.. _h264_dpb_flags: - -``DPB Entries Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID`` - - 0x00000001 - - The DPB entry is valid and should be considered - * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` - - 0x00000002 - - The DPB entry is currently being used as a reference frame - * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` - - 0x00000004 - - The DPB entry is a long term reference frame - * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD`` - - 0x00000008 - - The DPB entry is a field reference, which means only one of the field - will be used when decoding the new frame/field. When not set the DPB - entry is a frame reference (both fields will be used). Note that this - flag does not say anything about the number of fields contained in the - reference frame, it just describes the one used to decode the new - field/frame - * - ``V4L2_H264_DPB_ENTRY_FLAG_BOTTOM_FIELD`` - - 0x00000010 - - The DPB entry is a bottom field reference (only the bottom field of the - reference frame is needed to decode the new frame/field). Only valid if - V4L2_H264_DPB_ENTRY_FLAG_FIELD is set. When - V4L2_H264_DPB_ENTRY_FLAG_FIELD is set but - V4L2_H264_DPB_ENTRY_FLAG_BOTTOM_FIELD is not, that means the - DPB entry is a top field reference - -``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE (enum)`` - Specifies the decoding mode to use. Currently exposes slice-based and - frame-based decoding but new modes might be added later on. - This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE - pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE - are required to set this control in order to specify the decoding mode - that is expected for the buffer. - Drivers may expose a single or multiple decoding modes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_h264_decode_mode - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_SLICE_BASED`` - - 0 - - Decoding is done at the slice granularity. - In this mode, ``num_slices`` field in struct - :c:type:`v4l2_ctrl_h264_decode_params` should be set to 1, - and ``start_byte_offset`` in struct - :c:type:`v4l2_ctrl_h264_slice_params` should be set to 0. - The OUTPUT buffer must contain a single slice. - * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_FRAME_BASED`` - - 1 - - Decoding is done at the frame granularity. - In this mode, ``num_slices`` field in struct - :c:type:`v4l2_ctrl_h264_decode_params` should be set to the number - of slices in the frame, and ``start_byte_offset`` in struct - :c:type:`v4l2_ctrl_h264_slice_params` should be set accordingly - for each slice. For the first slice, ``start_byte_offset`` should - be zero. - The OUTPUT buffer must contain all slices needed to decode the - frame. The OUTPUT buffer must also contain both fields. - -``V4L2_CID_MPEG_VIDEO_H264_START_CODE (enum)`` - Specifies the H264 slice start code expected for each slice. - This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE - pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE - are required to set this control in order to specify the start code - that is expected for the buffer. - Drivers may expose a single or multiple start codes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_h264_start_code - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_H264_START_CODE_NONE`` - - 0 - - Selecting this value specifies that H264 slices are passed - to the driver without any start code. - * - ``V4L2_MPEG_VIDEO_H264_START_CODE_ANNEX_B`` - - 1 - - Selecting this value specifies that H264 slices are expected - to be prefixed by Annex B start codes. According to :ref:`h264` - valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. - -.. _v4l2-mpeg-mpeg2: - -``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)`` - Specifies the slice parameters (as extracted from the bitstream) for the - associated MPEG-2 slice data. This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for MPEG-2. - The bitstream parameters are defined according to :ref:`mpeg2part2`. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_mpeg2_slice_params - -.. cssclass:: longtable - -.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| - -.. flat-table:: struct v4l2_ctrl_mpeg2_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``bit_size`` - - Size (in bits) of the current slice data. - * - __u32 - - ``data_bit_offset`` - - Offset (in bits) to the video data in the current slice data. - * - struct :c:type:`v4l2_mpeg2_sequence` - - ``sequence`` - - Structure with MPEG-2 sequence metadata, merging relevant fields from - the sequence header and sequence extension parts of the bitstream. - * - struct :c:type:`v4l2_mpeg2_picture` - - ``picture`` - - Structure with MPEG-2 picture metadata, merging relevant fields from - the picture header and picture coding extension parts of the bitstream. - * - __u64 - - ``backward_ref_ts`` - - Timestamp of the V4L2 capture buffer to use as backward reference, used - with B-coded and P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``forward_ref_ts`` - - Timestamp for the V4L2 capture buffer to use as forward reference, used - with B-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u32 - - ``quantiser_scale_code`` - - Code used to determine the quantization scale to use for the IDCT. - -.. c:type:: v4l2_mpeg2_sequence - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_mpeg2_sequence - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``horizontal_size`` - - The width of the displayable part of the frame's luminance component. - * - __u16 - - ``vertical_size`` - - The height of the displayable part of the frame's luminance component. - * - __u32 - - ``vbv_buffer_size`` - - Used to calculate the required size of the video buffering verifier, - defined (in bits) as: 16 * 1024 * vbv_buffer_size. - * - __u16 - - ``profile_and_level_indication`` - - The current profile and level indication as extracted from the - bitstream. - * - __u8 - - ``progressive_sequence`` - - Indication that all the frames for the sequence are progressive instead - of interlaced. - * - __u8 - - ``chroma_format`` - - The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4). - -.. c:type:: v4l2_mpeg2_picture - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_mpeg2_picture - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``picture_coding_type`` - - Picture coding type for the frame covered by the current slice - (V4L2_MPEG2_PICTURE_CODING_TYPE_I, V4L2_MPEG2_PICTURE_CODING_TYPE_P or - V4L2_MPEG2_PICTURE_CODING_TYPE_B). - * - __u8 - - ``f_code[2][2]`` - - Motion vector codes. - * - __u8 - - ``intra_dc_precision`` - - Precision of Discrete Cosine transform (0: 8 bits precision, - 1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision). - * - __u8 - - ``picture_structure`` - - Picture structure (1: interlaced top field, 2: interlaced bottom field, - 3: progressive frame). - * - __u8 - - ``top_field_first`` - - If set to 1 and interlaced stream, top field is output first. - * - __u8 - - ``frame_pred_frame_dct`` - - If set to 1, only frame-DCT and frame prediction are used. - * - __u8 - - ``concealment_motion_vectors`` - - If set to 1, motion vectors are coded for intra macroblocks. - * - __u8 - - ``q_scale_type`` - - This flag affects the inverse quantization process. - * - __u8 - - ``intra_vlc_format`` - - This flag affects the decoding of transform coefficient data. - * - __u8 - - ``alternate_scan`` - - This flag affects the decoding of transform coefficient data. - * - __u8 - - ``repeat_first_field`` - - This flag affects the decoding process of progressive frames. - * - __u16 - - ``progressive_frame`` - - Indicates whether the current frame is progressive. - -``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION (struct)`` - Specifies quantization matrices (as extracted from the bitstream) for the - associated MPEG-2 slice data. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_mpeg2_quantization - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.2cm}|p{8.0cm}|p{7.4cm}| - -.. raw:: latex - - \small - -.. flat-table:: struct v4l2_ctrl_mpeg2_quantization - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``load_intra_quantiser_matrix`` - - One bit to indicate whether to load the ``intra_quantiser_matrix`` data. - * - __u8 - - ``load_non_intra_quantiser_matrix`` - - One bit to indicate whether to load the ``non_intra_quantiser_matrix`` - data. - * - __u8 - - ``load_chroma_intra_quantiser_matrix`` - - One bit to indicate whether to load the - ``chroma_intra_quantiser_matrix`` data, only relevant for non-4:2:0 YUV - formats. - * - __u8 - - ``load_chroma_non_intra_quantiser_matrix`` - - One bit to indicate whether to load the - ``chroma_non_intra_quantiser_matrix`` data, only relevant for non-4:2:0 - YUV formats. - * - __u8 - - ``intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for intra-coded frames, in zigzag - scanning order. It is relevant for both luma and chroma components, - although it can be superseded by the chroma-specific matrix for - non-4:2:0 YUV formats. - * - __u8 - - ``non_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for non-intra-coded frames, in - zigzag scanning order. It is relevant for both luma and chroma - components, although it can be superseded by the chroma-specific matrix - for non-4:2:0 YUV formats. - * - __u8 - - ``chroma_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for the chominance component of - intra-coded frames, in zigzag scanning order. Only relevant for - non-4:2:0 YUV formats. - * - __u8 - - ``chroma_non_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for the chrominance component of - non-intra-coded frames, in zigzag scanning order. Only relevant for - non-4:2:0 YUV formats. +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L6_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 6 for H264 encoder. ``V4L2_CID_FWHT_I_FRAME_QP (integer)`` Quantization parameter for an I frame for FWHT. Valid range: from 1 @@ -2345,329 +1653,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - Quantization parameter for a P frame for FWHT. Valid range: from 1 to 31. -.. _v4l2-mpeg-vp8: - -``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER (struct)`` - Specifies the frame parameters for the associated VP8 parsed frame data. - This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for VP8. - The bitstream parameters are defined according to :ref:`vp8`. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_vp8_frame_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| - -.. flat-table:: struct v4l2_ctrl_vp8_frame_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`v4l2_vp8_segment_header` - - ``segment_header`` - - Structure with segment-based adjustments metadata. - * - struct :c:type:`v4l2_vp8_loopfilter_header` - - ``loopfilter_header`` - - Structure with loop filter level adjustments metadata. - * - struct :c:type:`v4l2_vp8_quantization_header` - - ``quant_header`` - - Structure with VP8 dequantization indices metadata. - * - struct :c:type:`v4l2_vp8_entropy_header` - - ``entropy_header`` - - Structure with VP8 entropy coder probabilities metadata. - * - struct :c:type:`v4l2_vp8_entropy_coder_state` - - ``coder_state`` - - Structure with VP8 entropy coder state. - * - __u16 - - ``width`` - - The width of the frame. Must be set for all frames. - * - __u16 - - ``height`` - - The height of the frame. Must be set for all frames. - * - __u8 - - ``horizontal_scale`` - - Horizontal scaling factor. - * - __u8 - - ``vertical_scaling factor`` - - Vertical scale. - * - __u8 - - ``version`` - - Bitstream version. - * - __u8 - - ``prob_skip_false`` - - Indicates the probability that the macroblock is not skipped. - * - __u8 - - ``prob_intra`` - - Indicates the probability that a macroblock is intra-predicted. - * - __u8 - - ``prob_last`` - - Indicates the probability that the last reference frame is used - for inter-prediction - * - __u8 - - ``prob_gf`` - - Indicates the probability that the golden reference frame is used - for inter-prediction - * - __u8 - - ``num_dct_parts`` - - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. - * - __u32 - - ``first_part_size`` - - Size of the first partition, i.e. the control partition. - * - __u32 - - ``first_part_header_bits`` - - Size in bits of the first partition header portion. - * - __u32 - - ``dct_part_sizes[8]`` - - DCT coefficients sizes. - * - __u64 - - ``last_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as last reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``golden_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as last reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``alt_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``flags`` - - See :ref:`Frame Header Flags <vp8_frame_header_flags>` - -.. _vp8_frame_header_flags: - -``Frame Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_FRAME_HEADER_FLAG_KEY_FRAME`` - - 0x01 - - Indicates if the frame is a key frame. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_EXPERIMENTAL`` - - 0x02 - - Experimental bitstream. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SHOW_FRAME`` - - 0x04 - - Show frame flag, indicates if the frame is for display. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_MB_NO_SKIP_COEFF`` - - 0x08 - - Enable/disable skipping of macroblocks with no non-zero coefficients. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_GOLDEN`` - - 0x10 - - Sign of motion vectors when the golden frame is referenced. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_ALT`` - - 0x20 - - Sign of motion vectors when the alt frame is referenced. - -.. c:type:: v4l2_vp8_entropy_coder_state - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_entropy_coder_state - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``range`` - - - * - __u8 - - ``value`` - - - * - __u8 - - ``bit_count`` - - - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_vp8_segment_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_segment_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s8 - - ``quant_update[4]`` - - Signed quantizer value update. - * - __s8 - - ``lf_update[4]`` - - Signed loop filter level value update. - * - __u8 - - ``segment_probs[3]`` - - Segment probabilities. - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Segment Header Flags <vp8_segment_header_flags>` - -.. _vp8_segment_header_flags: - -``Segment Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_ENABLED`` - - 0x01 - - Enable/disable segment-based adjustments. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_MAP`` - - 0x02 - - Indicates if the macroblock segmentation map is updated in this frame. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_FEATURE_DATA`` - - 0x04 - - Indicates if the segment feature data is updated in this frame. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_DELTA_VALUE_MODE`` - - 0x08 - - If is set, the segment feature data mode is delta-value. - If cleared, it's absolute-value. - -.. c:type:: v4l2_vp8_loopfilter_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_loopfilter_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s8 - - ``ref_frm_delta[4]`` - - Reference adjustment (signed) delta value. - * - __s8 - - ``mb_mode_delta[4]`` - - Macroblock prediction mode adjustment (signed) delta value. - * - __u8 - - ``sharpness_level`` - - Sharpness level - * - __u8 - - ``level`` - - Filter level - * - __u16 - - ``padding`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Loopfilter Header Flags <vp8_loopfilter_header_flags>` - -.. _vp8_loopfilter_header_flags: - -``Loopfilter Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_LF_HEADER_ADJ_ENABLE`` - - 0x01 - - Enable/disable macroblock-level loop filter adjustment. - * - ``V4L2_VP8_LF_HEADER_DELTA_UPDATE`` - - 0x02 - - Indicates if the delta values used in an adjustment are updated. - * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` - - 0x04 - - If set, indicates the filter type is simple. - If cleared, the filter type is normal. - -.. c:type:: v4l2_vp8_quantization_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_quantization_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``y_ac_qi`` - - Luma AC coefficient table index. - * - __s8 - - ``y_dc_delta`` - - Luma DC delta vaue. - * - __s8 - - ``y2_dc_delta`` - - Y2 block DC delta value. - * - __s8 - - ``y2_ac_delta`` - - Y2 block AC delta value. - * - __s8 - - ``uv_dc_delta`` - - Chroma DC delta value. - * - __s8 - - ``uv_ac_delta`` - - Chroma AC delta value. - * - __u16 - - ``padding`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_vp8_entropy_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_entropy_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``coeff_probs[4][8][3][11]`` - - Coefficient update probabilities. - * - __u8 - - ``y_mode_probs[4]`` - - Luma mode update probabilities. - * - __u8 - - ``uv_mode_probs[3]`` - - Chroma mode update probabilities. - * - __u8 - - ``mv_probs[2][19]`` - - MV decoding update probabilities. - * - __u8 - - ``padding[3]`` - - Applications and drivers must set this to zero. - .. raw:: latex \normalsize @@ -2694,6 +1679,11 @@ MFC 5.1 Control IDs feature can be used for example for generating thumbnails of videos. Applicable to the H264 decoder. + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY_ENABLE`` control instead. + ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)`` Display delay value for H264 decoder. The decoder is forced to return a decoded frame after the set 'display delay' number of @@ -2701,6 +1691,11 @@ MFC 5.1 Control IDs of display order, in addition the hardware may still be using the returned buffer as a reference picture for subsequent frames. + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY`` control instead. + ``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)`` The number of reference pictures used for encoding a P picture. Applicable to the H264 encoder. @@ -2773,6 +1768,11 @@ MFC 5.1 Control IDs ``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE`` (enum) + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_FRAME_SKIP_MODE`` control instead. + enum v4l2_mpeg_mfc51_video_frame_skip_mode - Indicates in what conditions the encoder should skip frames. If encoding a frame would cause the encoded stream to be larger then a @@ -2780,7 +1780,7 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - are: -.. tabularcolumns:: |p{9.2cm}|p{8.3cm}| +.. tabularcolumns:: |p{9.4cm}|p{8.1cm}| .. raw:: latex @@ -2790,12 +1790,12 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - :header-rows: 0 :stub-columns: 0 - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_DISABLED`` - Frame skip mode is disabled. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_LEVEL_LIMIT`` - Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_BUF_LIMIT`` - Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control. @@ -2824,7 +1824,7 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - Force a frame type for the next queued buffer. Applicable to encoders. Possible values are: -.. tabularcolumns:: |p{9.5cm}|p{8.0cm}| +.. tabularcolumns:: |p{9.9cm}|p{7.6cm}| .. flat-table:: :header-rows: 0 @@ -2838,127 +1838,6 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - - Force a non-coded frame. -.. _v4l2-mpeg-fwht: - -``V4L2_CID_MPEG_VIDEO_FWHT_PARAMS (struct)`` - Specifies the fwht parameters (as extracted from the bitstream) for the - associated FWHT data. This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for FWHT. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_fwht_params - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| - -.. flat-table:: struct v4l2_ctrl_fwht_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``backward_ref_ts`` - - Timestamp of the V4L2 capture buffer to use as backward reference, used - with P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u32 - - ``version`` - - The version of the codec - * - __u32 - - ``width`` - - The width of the frame - * - __u32 - - ``height`` - - The height of the frame - * - __u32 - - ``flags`` - - The flags of the frame, see :ref:`fwht-flags`. - * - __u32 - - ``colorspace`` - - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. - * - __u32 - - ``xfer_func`` - - The transfer function, from enum :c:type:`v4l2_xfer_func`. - * - __u32 - - ``ycbcr_enc`` - - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. - * - __u32 - - ``quantization`` - - The quantization range, from enum :c:type:`v4l2_quantization`. - - - -.. _fwht-flags: - -FWHT Flags -============ - -.. cssclass:: longtable - -.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``FWHT_FL_IS_INTERLACED`` - - 0x00000001 - - Set if this is an interlaced format - * - ``FWHT_FL_IS_BOTTOM_FIRST`` - - 0x00000002 - - Set if this is a bottom-first (NTSC) interlaced format - * - ``FWHT_FL_IS_ALTERNATE`` - - 0x00000004 - - Set if each 'frame' contains just one field - * - ``FWHT_FL_IS_BOTTOM_FIELD`` - - 0x00000008 - - If FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the - bottom field, else it is the top field. - * - ``FWHT_FL_LUMA_IS_UNCOMPRESSED`` - - 0x00000010 - - Set if the luma plane is uncompressed - * - ``FWHT_FL_CB_IS_UNCOMPRESSED`` - - 0x00000020 - - Set if the cb plane is uncompressed - * - ``FWHT_FL_CR_IS_UNCOMPRESSED`` - - 0x00000040 - - Set if the cr plane is uncompressed - * - ``FWHT_FL_CHROMA_FULL_HEIGHT`` - - 0x00000080 - - Set if the chroma plane has the same height as the luma plane, - else the chroma plane is half the height of the luma plane - * - ``FWHT_FL_CHROMA_FULL_WIDTH`` - - 0x00000100 - - Set if the chroma plane has the same width as the luma plane, - else the chroma plane is half the width of the luma plane - * - ``FWHT_FL_ALPHA_IS_UNCOMPRESSED`` - - 0x00000200 - - Set if the alpha plane is uncompressed - * - ``FWHT_FL_I_FRAME`` - - 0x00000400 - - Set if this is an I-frame - * - ``FWHT_FL_COMPONENTS_NUM_MSK`` - - 0x00070000 - - A 4-values flag - the number of components - 1 - * - ``FWHT_FL_PIXENC_YUV`` - - 0x00080000 - - Set if the pixel encoding is YUV - * - ``FWHT_FL_PIXENC_RGB`` - - 0x00100000 - - Set if the pixel encoding is RGB - * - ``FWHT_FL_PIXENC_HSV`` - - 0x00180000 - - Set if the pixel encoding is HSV - - CX2341x MPEG Controls ===================== @@ -2981,6 +1860,7 @@ enum v4l2_mpeg_cx2341x_video_spatial_filter_mode - are: +.. tabularcolumns:: |p{11.5cm}|p{6.0cm}| .. flat-table:: :header-rows: 0 @@ -3006,11 +1886,11 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - Select the algorithm to use for the Luma Spatial Filter (default ``1D_HOR``). Possible values: -.. tabularcolumns:: |p{14.5cm}|p{3.0cm}| +.. tabularcolumns:: |p{13.1cm}|p{4.4cm}| .. raw:: latex - \small + \footnotesize .. flat-table:: :header-rows: 0 @@ -3031,8 +1911,6 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - \normalsize - - .. _chroma-spatial-filter-type: ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE`` @@ -3042,8 +1920,11 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - Select the algorithm for the Chroma Spatial Filter (default ``1D_HOR``). Possible values are: +.. raw:: latex + + \footnotesize -.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| +.. tabularcolumns:: |p{11.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 @@ -3054,7 +1935,9 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR`` - One-dimensional horizontal +.. raw:: latex + \normalsize .. _v4l2-mpeg-cx2341x-video-temporal-filter-mode: @@ -3065,7 +1948,9 @@ enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - Sets the Temporal Filter mode (default ``MANUAL``). Possible values are: +.. raw:: latex + \footnotesize .. flat-table:: :header-rows: 0 @@ -3076,7 +1961,9 @@ enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO`` - Choose the filter automatically +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))`` The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default @@ -3091,6 +1978,11 @@ enum v4l2_mpeg_cx2341x_video_median_filter_type - Median Filter Type (default ``OFF``). Possible values are: +.. raw:: latex + + \small + +.. tabularcolumns:: |p{11.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 @@ -3107,7 +1999,9 @@ enum v4l2_mpeg_cx2341x_video_median_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG`` - Diagonal filter +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))`` Threshold above which the luminance median filter is enabled @@ -3184,7 +2078,7 @@ enum v4l2_vp8_num_ref_frames - The number of reference pictures for encoding P frames. Possible values are: -.. tabularcolumns:: |p{7.9cm}|p{9.6cm}| +.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| .. raw:: latex @@ -3239,7 +2133,7 @@ enum v4l2_vp8_golden_frame_sel - \scriptsize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{8.6cm}|p{8.9cm}| .. flat-table:: :header-rows: 0 @@ -3316,6 +2210,49 @@ enum v4l2_mpeg_video_vp9_profile - * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_3`` - Profile 3 +.. _v4l2-mpeg-video-vp9-level: + +``V4L2_CID_MPEG_VIDEO_VP9_LEVEL (enum)`` + +enum v4l2_mpeg_video_vp9_level - + This control allows selecting the level for VP9 encoder. + This is also used to enumerate supported levels by VP9 encoder or decoder. + More information can be found at + `webmproject <https://www.webmproject.org/vp9/levels/>`__. Possible values are: + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_1_0`` + - Level 1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_1_1`` + - Level 1.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_2_0`` + - Level 2 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_2_1`` + - Level 2.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_3_0`` + - Level 3 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_3_1`` + - Level 3.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_4_0`` + - Level 4 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_4_1`` + - Level 4.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_5_0`` + - Level 5 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_5_1`` + - Level 5.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_5_2`` + - Level 5.2 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_6_0`` + - Level 6 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_6_1`` + - Level 6.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_6_2`` + - Level 6.2 + High Efficiency Video Coding (HEVC/H.265) Control Reference =========================================================== @@ -3331,11 +2268,11 @@ HEVC/H.265 Control IDs ``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP (integer)`` Minimum quantization parameter for HEVC. - Valid range: from 0 to 51. + Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP (integer)`` Maximum quantization parameter for HEVC. - Valid range: from 0 to 51. + Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. ``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_QP (integer)`` Quantization parameter for an I frame for HEVC. @@ -3352,6 +2289,42 @@ HEVC/H.265 Control IDs Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC I frame to limit I frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC I frame to limit I frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC P frame to limit P frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC P frame to limit P frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC B frame to limit B frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC B frame to limit B frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_QP (boolean)`` HIERARCHICAL_QP allows the host to specify the quantization parameter values for each temporal layer through HIERARCHICAL_QP_LAYER. This is @@ -3370,7 +2343,7 @@ enum v4l2_mpeg_video_hevc_hier_coding_type - \footnotesize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 @@ -3439,7 +2412,7 @@ enum v4l2_mpeg_video_hevc_profile - \footnotesize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| .. flat-table:: :header-rows: 0 @@ -3465,47 +2438,21 @@ enum v4l2_mpeg_video_hevc_profile - enum v4l2_mpeg_video_hevc_level - Selects the desired level for HEVC encoder. -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` - - Level 1.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` - - Level 2.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` - - Level 2.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` - - Level 3.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` - - Level 3.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` - - Level 4.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` - - Level 4.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` - - Level 5.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` - - Level 5.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` - - Level 5.2 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` - - Level 6.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` - - Level 6.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` - - Level 6.2 - -.. raw:: latex - - \normalsize - +================================== ========= +``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` Level 1.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` Level 2.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` Level 2.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` Level 3.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` Level 3.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` Level 4.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` Level 4.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` Level 5.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` Level 5.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` Level 5.2 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` Level 6.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` Level 6.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` Level 6.2 +================================== ========= ``V4L2_CID_MPEG_VIDEO_HEVC_FRAME_RATE_RESOLUTION (integer)`` Indicates the number of evenly spaced subintervals, called ticks, within @@ -3524,24 +2471,10 @@ enum v4l2_mpeg_video_hevc_tier - this flag to 1 indicates High tier. High tier is for applications requiring high bit rates. -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` - - Main tier. - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` - - High tier. - -.. raw:: latex - - \normalsize +================================== ========== +``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` Main tier. +``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` High tier. +================================== ========== ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)`` @@ -3597,7 +2530,7 @@ enum v4l2_mpeg_video_hevc_hier_refresh_type - \footnotesize -.. tabularcolumns:: |p{8.0cm}|p{9.0cm}| +.. tabularcolumns:: |p{6.2cm}|p{11.3cm}| .. flat-table:: :header-rows: 0 @@ -3677,7 +2610,7 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - \footnotesize -.. tabularcolumns:: |p{6.0cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| .. flat-table:: :header-rows: 0 @@ -3725,550 +2658,3 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - Indicates whether to generate SPS and PPS at every IDR. Setting it to 0 disables generating SPS and PPS at every IDR. Setting it to one enables generating SPS and PPS at every IDR. - -.. _v4l2-mpeg-hevc: - -``V4L2_CID_MPEG_VIDEO_HEVC_SPS (struct)`` - Specifies the Sequence Parameter Set fields (as extracted from the - bitstream) for the associated HEVC slice data. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.3.2 "Sequence parameter set RBSP - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_sps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_sps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``pic_width_in_luma_samples`` - - - * - __u16 - - ``pic_height_in_luma_samples`` - - - * - __u8 - - ``bit_depth_luma_minus8`` - - - * - __u8 - - ``bit_depth_chroma_minus8`` - - - * - __u8 - - ``log2_max_pic_order_cnt_lsb_minus4`` - - - * - __u8 - - ``sps_max_dec_pic_buffering_minus1`` - - - * - __u8 - - ``sps_max_num_reorder_pics`` - - - * - __u8 - - ``sps_max_latency_increase_plus1`` - - - * - __u8 - - ``log2_min_luma_coding_block_size_minus3`` - - - * - __u8 - - ``log2_diff_max_min_luma_coding_block_size`` - - - * - __u8 - - ``log2_min_luma_transform_block_size_minus2`` - - - * - __u8 - - ``log2_diff_max_min_luma_transform_block_size`` - - - * - __u8 - - ``max_transform_hierarchy_depth_inter`` - - - * - __u8 - - ``max_transform_hierarchy_depth_intra`` - - - * - __u8 - - ``pcm_sample_bit_depth_luma_minus1`` - - - * - __u8 - - ``pcm_sample_bit_depth_chroma_minus1`` - - - * - __u8 - - ``log2_min_pcm_luma_coding_block_size_minus3`` - - - * - __u8 - - ``log2_diff_max_min_pcm_luma_coding_block_size`` - - - * - __u8 - - ``num_short_term_ref_pic_sets`` - - - * - __u8 - - ``num_long_term_ref_pics_sps`` - - - * - __u8 - - ``chroma_format_idc`` - - - * - __u64 - - ``flags`` - - See :ref:`Sequence Parameter Set Flags <hevc_sps_flags>` - -.. _hevc_sps_flags: - -``Sequence Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_SPS_FLAG_SEPARATE_COLOUR_PLANE`` - - 0x00000001 - - - * - ``V4L2_HEVC_SPS_FLAG_SCALING_LIST_ENABLED`` - - 0x00000002 - - - * - ``V4L2_HEVC_SPS_FLAG_AMP_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_SPS_FLAG_SAMPLE_ADAPTIVE_OFFSET`` - - 0x00000008 - - - * - ``V4L2_HEVC_SPS_FLAG_PCM_ENABLED`` - - 0x00000010 - - - * - ``V4L2_HEVC_SPS_FLAG_PCM_LOOP_FILTER_DISABLED`` - - 0x00000020 - - - * - ``V4L2_HEVC_SPS_FLAG_LONG_TERM_REF_PICS_PRESENT`` - - 0x00000040 - - - * - ``V4L2_HEVC_SPS_FLAG_SPS_TEMPORAL_MVP_ENABLED`` - - 0x00000080 - - - * - ``V4L2_HEVC_SPS_FLAG_STRONG_INTRA_SMOOTHING_ENABLED`` - - 0x00000100 - - - -``V4L2_CID_MPEG_VIDEO_HEVC_PPS (struct)`` - Specifies the Picture Parameter Set fields (as extracted from the - bitstream) for the associated HEVC slice data. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.3.3 "Picture parameter set RBSP - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_pps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_pps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``num_extra_slice_header_bits`` - - - * - __s8 - - ``init_qp_minus26`` - - - * - __u8 - - ``diff_cu_qp_delta_depth`` - - - * - __s8 - - ``pps_cb_qp_offset`` - - - * - __s8 - - ``pps_cr_qp_offset`` - - - * - __u8 - - ``num_tile_columns_minus1`` - - - * - __u8 - - ``num_tile_rows_minus1`` - - - * - __u8 - - ``column_width_minus1[20]`` - - - * - __u8 - - ``row_height_minus1[22]`` - - - * - __s8 - - ``pps_beta_offset_div2`` - - - * - __s8 - - ``pps_tc_offset_div2`` - - - * - __u8 - - ``log2_parallel_merge_level_minus2`` - - - * - __u8 - - ``padding[4]`` - - Applications and drivers must set this to zero. - * - __u64 - - ``flags`` - - See :ref:`Picture Parameter Set Flags <hevc_pps_flags>` - -.. _hevc_pps_flags: - -``Picture Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_PPS_FLAG_DEPENDENT_SLICE_SEGMENT`` - - 0x00000001 - - - * - ``V4L2_HEVC_PPS_FLAG_OUTPUT_FLAG_PRESENT`` - - 0x00000002 - - - * - ``V4L2_HEVC_PPS_FLAG_SIGN_DATA_HIDING_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_PPS_FLAG_CABAC_INIT_PRESENT`` - - 0x00000008 - - - * - ``V4L2_HEVC_PPS_FLAG_CONSTRAINED_INTRA_PRED`` - - 0x00000010 - - - * - ``V4L2_HEVC_PPS_FLAG_TRANSFORM_SKIP_ENABLED`` - - 0x00000020 - - - * - ``V4L2_HEVC_PPS_FLAG_CU_QP_DELTA_ENABLED`` - - 0x00000040 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT`` - - 0x00000080 - - - * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_PRED`` - - 0x00000100 - - - * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_BIPRED`` - - 0x00000200 - - - * - ``V4L2_HEVC_PPS_FLAG_TRANSQUANT_BYPASS_ENABLED`` - - 0x00000400 - - - * - ``V4L2_HEVC_PPS_FLAG_TILES_ENABLED`` - - 0x00000800 - - - * - ``V4L2_HEVC_PPS_FLAG_ENTROPY_CODING_SYNC_ENABLED`` - - 0x00001000 - - - * - ``V4L2_HEVC_PPS_FLAG_LOOP_FILTER_ACROSS_TILES_ENABLED`` - - 0x00002000 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_LOOP_FILTER_ACROSS_SLICES_ENABLED`` - - 0x00004000 - - - * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_OVERRIDE_ENABLED`` - - 0x00008000 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_DISABLE_DEBLOCKING_FILTER`` - - 0x00010000 - - - * - ``V4L2_HEVC_PPS_FLAG_LISTS_MODIFICATION_PRESENT`` - - 0x00020000 - - - * - ``V4L2_HEVC_PPS_FLAG_SLICE_SEGMENT_HEADER_EXTENSION_PRESENT`` - - 0x00040000 - - - -``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS (struct)`` - Specifies various slice-specific parameters, especially from the NAL unit - header, general slice segment header and weighted prediction parameter - parts of the bitstream. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.7 "General slice segment header - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_slice_params - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``bit_size`` - - Size (in bits) of the current slice data. - * - __u32 - - ``data_bit_offset`` - - Offset (in bits) to the video data in the current slice data. - * - __u8 - - ``nal_unit_type`` - - - * - __u8 - - ``nuh_temporal_id_plus1`` - - - * - __u8 - - ``slice_type`` - - - (V4L2_HEVC_SLICE_TYPE_I, V4L2_HEVC_SLICE_TYPE_P or - V4L2_HEVC_SLICE_TYPE_B). - * - __u8 - - ``colour_plane_id`` - - - * - __u16 - - ``slice_pic_order_cnt`` - - - * - __u8 - - ``num_ref_idx_l0_active_minus1`` - - - * - __u8 - - ``num_ref_idx_l1_active_minus1`` - - - * - __u8 - - ``collocated_ref_idx`` - - - * - __u8 - - ``five_minus_max_num_merge_cand`` - - - * - __s8 - - ``slice_qp_delta`` - - - * - __s8 - - ``slice_cb_qp_offset`` - - - * - __s8 - - ``slice_cr_qp_offset`` - - - * - __s8 - - ``slice_act_y_qp_offset`` - - - * - __s8 - - ``slice_act_cb_qp_offset`` - - - * - __s8 - - ``slice_act_cr_qp_offset`` - - - * - __s8 - - ``slice_beta_offset_div2`` - - - * - __s8 - - ``slice_tc_offset_div2`` - - - * - __u8 - - ``pic_struct`` - - - * - __u8 - - ``num_active_dpb_entries`` - - The number of entries in ``dpb``. - * - __u8 - - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The list of L0 reference elements as indices in the DPB. - * - __u8 - - ``ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The list of L1 reference elements as indices in the DPB. - * - __u8 - - ``num_rps_poc_st_curr_before`` - - The number of reference pictures in the short-term set that come before - the current frame. - * - __u8 - - ``num_rps_poc_st_curr_after`` - - The number of reference pictures in the short-term set that come after - the current frame. - * - __u8 - - ``num_rps_poc_lt_curr`` - - The number of reference pictures in the long-term set. - * - __u8 - - ``padding[7]`` - - Applications and drivers must set this to zero. - * - struct :c:type:`v4l2_hevc_dpb_entry` - - ``dpb[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The decoded picture buffer, for meta-data about reference frames. - * - struct :c:type:`v4l2_hevc_pred_weight_table` - - ``pred_weight_table`` - - The prediction weight coefficients for inter-picture prediction. - * - __u64 - - ``flags`` - - See :ref:`Slice Parameters Flags <hevc_slice_params_flags>` - -.. _hevc_slice_params_flags: - -``Slice Parameters Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_LUMA`` - - 0x00000001 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_CHROMA`` - - 0x00000002 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_TEMPORAL_MVP_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_MVD_L1_ZERO`` - - 0x00000008 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_CABAC_INIT`` - - 0x00000010 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_COLLOCATED_FROM_L0`` - - 0x00000020 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_USE_INTEGER_MV`` - - 0x00000040 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_DEBLOCKING_FILTER_DISABLED`` - - 0x00000080 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_LOOP_FILTER_ACROSS_SLICES_ENABLED`` - - 0x00000100 - - - -.. c:type:: v4l2_hevc_dpb_entry - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_hevc_dpb_entry - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``timestamp`` - - Timestamp of the V4L2 capture buffer to use as reference, used - with B-coded and P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u8 - - ``rps`` - - The reference set for the reference frame - (V4L2_HEVC_DPB_ENTRY_RPS_ST_CURR_BEFORE, - V4L2_HEVC_DPB_ENTRY_RPS_ST_CURR_AFTER or - V4L2_HEVC_DPB_ENTRY_RPS_LT_CURR) - * - __u8 - - ``field_pic`` - - Whether the reference is a field picture or a frame. - * - __u16 - - ``pic_order_cnt[2]`` - - The picture order count of the reference. Only the first element of the - array is used for frame pictures, while the first element identifies the - top field and the second the bottom field in field-coded pictures. - * - __u8 - - ``padding[2]`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_hevc_pred_weight_table - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_hevc_pred_weight_table - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``luma_log2_weight_denom`` - - - * - __s8 - - ``delta_chroma_log2_weight_denom`` - - - * - __s8 - - ``delta_luma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``luma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``delta_chroma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``chroma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``delta_luma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``luma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``delta_chroma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``chroma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __u8 - - ``padding[6]`` - - Applications and drivers must set this to zero. - -``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE (enum)`` - Specifies the decoding mode to use. Currently exposes slice-based and - frame-based decoding but new modes might be added later on. - This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE - pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE - are required to set this control in order to specify the decoding mode - that is expected for the buffer. - Drivers may expose a single or multiple decoding modes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_hevc_decode_mode - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_HEVC_DECODE_MODE_SLICE_BASED`` - - 0 - - Decoding is done at the slice granularity. - The OUTPUT buffer must contain a single slice. - * - ``V4L2_MPEG_VIDEO_HEVC_DECODE_MODE_FRAME_BASED`` - - 1 - - Decoding is done at the frame granularity. - The OUTPUT buffer must contain all slices needed to decode the - frame. The OUTPUT buffer must also contain both fields. - -``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE (enum)`` - Specifies the HEVC slice start code expected for each slice. - This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE - pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE - are required to set this control in order to specify the start code - that is expected for the buffer. - Drivers may expose a single or multiple start codes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_hevc_start_code - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_NONE`` - - 0 - - Selecting this value specifies that HEVC slices are passed - to the driver without any start code. - * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_ANNEX_B`` - - 1 - - Selecting this value specifies that HEVC slices are expected - to be prefixed by Annex B start codes. According to :ref:`hevc` - valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst new file mode 100644 index 000000000000..1e7265155715 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _colorimetry-controls: + +***************************** +Colorimetry Control Reference +***************************** + +The Colorimetry class includes controls for High Dynamic Range +imaging for representing colors in digital images and video. The +controls should be used for video and image encoding and decoding +as well as in HDMI receivers and transmitters. + +Colorimetry Control IDs +----------------------- + +.. _colorimetry-control-id: + +``V4L2_CID_COLORIMETRY_CLASS (class)`` + The Colorimetry class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_COLORIMETRY_HDR10_CLL_INFO (struct)`` + The Content Light Level defines upper bounds for the nominal target + brightness light level of the pictures. + +.. c:type:: v4l2_ctrl_hdr10_cll_info + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hdr10_cll_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``max_content_light_level`` + - The upper bound for the maximum light level among all individual + samples for the pictures of a video sequence, cd/m\ :sup:`2`. + When equal to 0 no such upper bound is present. + * - __u16 + - ``max_pic_average_light_level`` + - The upper bound for the maximum average light level among the + samples for any individual picture of a video sequence, + cd/m\ :sup:`2`. When equal to 0 no such upper bound is present. + +``V4L2_CID_COLORIMETRY_HDR10_MASTERING_DISPLAY (struct)`` + The mastering display defines the color volume (the color primaries, + white point and luminance range) of a display considered to be the + mastering display for the current video content. + +.. c:type:: v4l2_ctrl_hdr10_mastering_display + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hdr10_mastering_display + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``display_primaries_x[3]`` + - Specifies the normalized x chromaticity coordinate of the color + primary component c of the mastering display in increments of 0.00002. + For describing the mastering display that uses Red, Green and Blue + color primaries, index value c equal to 0 corresponds to the Green + primary, c equal to 1 corresponds to Blue primary and c equal to 2 + corresponds to the Red color primary. + * - __u16 + - ``display_primaries_y[3]`` + - Specifies the normalized y chromaticity coordinate of the color + primary component c of the mastering display in increments of 0.00002. + For describing the mastering display that uses Red, Green and Blue + color primaries, index value c equal to 0 corresponds to the Green + primary, c equal to 1 corresponds to Blue primary and c equal to 2 + corresponds to Red color primary. + * - __u16 + - ``white_point_x`` + - Specifies the normalized x chromaticity coordinate of the white + point of the mastering display in increments of 0.00002. + * - __u16 + - ``white_point_y`` + - Specifies the normalized y chromaticity coordinate of the white + point of the mastering display in increments of 0.00002. + * - __u32 + - ``max_luminance`` + - Specifies the nominal maximum display luminance of the mastering + display in units of 0.0001 cd/m\ :sup:`2`. + * - __u32 + - ``min_luminance`` + - specifies the nominal minimum display luminance of the mastering + display in units of 0.0001 cd/m\ :sup:`2`. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst index 77a4992f26bd..312c4fa94dc3 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _detect-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst index c572b65dc772..d2794e03ac6d 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dv-controls: @@ -106,7 +99,7 @@ enum v4l2_dv_it_content_type - or an analog source. The enum v4l2_dv_it_content_type defines the possible content types: -.. tabularcolumns:: |p{7.3cm}|p{10.4cm}| +.. tabularcolumns:: |p{7.3cm}|p{10.2cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst index 5053a380f7de..d22c5efb806a 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _flash-controls: @@ -70,6 +63,7 @@ Flash Control IDs presence of some faults. See V4L2_CID_FLASH_FAULT. +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| .. flat-table:: :header-rows: 0 @@ -80,14 +74,16 @@ Flash Control IDs * - ``V4L2_FLASH_LED_MODE_FLASH`` - Flash mode. * - ``V4L2_FLASH_LED_MODE_TORCH`` - - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. + - Torch mode. + + See V4L2_CID_FLASH_TORCH_INTENSITY. ``V4L2_CID_FLASH_STROBE_SOURCE (menu)`` Defines the source of the flash LED strobe. -.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| +.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst index 69197bbe23dd..b6cfc0e823d2 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _fm-rx-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst index c13ec0a6af3a..04c997c9a4c3 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _fm-tx-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst index bb9d484c25e4..b1c2ab2854af 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _image-process-controls: @@ -27,25 +20,26 @@ Image Process Control IDs ``V4L2_CID_IMAGE_PROC_CLASS (class)`` The IMAGE_PROC class descriptor. +.. _v4l2-cid-link-freq: + ``V4L2_CID_LINK_FREQ (integer menu)`` - Data bus frequency. Together with the media bus pixel code, bus type - (clock cycles per sample), the data bus frequency defines the pixel - rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly - elsewhere, if the device is not an image sensor). The frame rate can - be calculated from the pixel clock, image width and height and - horizontal and vertical blanking. While the pixel rate control may - be defined elsewhere than in the subdev containing the pixel array, - the frame rate cannot be obtained from that information. This is - because only on the pixel array it can be assumed that the vertical - and horizontal blanking information is exact: no other blanking is - allowed in the pixel array. The selection of frame rate is performed - by selecting the desired horizontal and vertical blanking. The unit - of this control is Hz. + The frequency of the data bus (e.g. parallel or CSI-2). + +.. _v4l2-cid-pixel-rate: ``V4L2_CID_PIXEL_RATE (64-bit integer)`` - Pixel rate in the source pads of the subdev. This control is + Pixel sampling rate in the device's pixel array. This control is read-only and its unit is pixels / second. + Some devices use horizontal and vertical balanking to configure the frame + rate. The frame rate can be calculated from the pixel rate, analogue crop + rectangle as well as horizontal and vertical blanking. The pixel rate + control may be present in a different sub-device than the blanking controls + and the analogue crop rectangle configuration. + + The configuration of the frame rate is performed by selecting the desired + horizontal and vertical blanking. The unit of this control is Hz. + ``V4L2_CID_TEST_PATTERN (menu)`` Some capture/display/sensor devices have the capability to generate test pattern images. These hardware specific test patterns can be diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst index 7b75158aca4d..71f23f131f97 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _image-source-controls: @@ -65,3 +58,37 @@ Image Source Control IDs The unit cell consists of the whole area of the pixel, sensitive and non-sensitive. This control is required for automatic calibration of sensors/cameras. + +.. c:type:: v4l2_area + +.. flat-table:: struct v4l2_area + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``width`` + - Width of the area. + * - __u32 + - ``height`` + - Height of the area. + +``V4L2_CID_NOTIFY_GAINS (integer array)`` + The sensor is notified what gains will be applied to the different + colour channels by subsequent processing (such as by an ISP). The + sensor is merely informed of these values in case it performs + processing that requires them, but it does not apply them itself to + the output pixels. + + Currently it is defined only for Bayer sensors, and is an array + control taking 4 gain values, being the gains for each of the + Bayer channels. The gains are always in the order B, Gb, Gr and R, + irrespective of the exact Bayer order of the sensor itself. + + The use of an array allows this control to be extended to sensors + with, for example, non-Bayer CFAs (colour filter arrays). + + The units for the gain values are linear, with the default value + representing a gain of exactly 1.0. For example, if this default value + is reported as being (say) 128, then a value of 192 would represent + a gain of exactly 1.5. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst index 5ea69978f3ea..522095c08469 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _jpeg-controls: @@ -15,7 +8,7 @@ JPEG Control Reference The JPEG class includes controls for common features of JPEG encoders and decoders. Currently it includes features for codecs implementing -progressive baseline DCT compression process with Huffman entrophy +progressive baseline DCT compression process with Huffman entropy coding. @@ -71,13 +64,12 @@ JPEG Control IDs .. _jpeg-quality-control: ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)`` - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off - between image quality and size. It provides simpler method for - applications to control image quality, without a need for direct - reconfiguration of luminance and chrominance quantization tables. In - cases where a driver uses quantization tables configured directly by - an application, using interfaces defined elsewhere, - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by + Determines trade-off between image quality and size. + It provides simpler method for applications to control image quality, + without a need for direct reconfiguration of luminance and chrominance + quantization tables. In cases where a driver uses quantization tables + configured directly by an application, using interfaces defined + elsewhere, ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by driver to 0. The value range of this control is driver-specific. Only positive, diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst index 5277138fce67..8a6f9f0373ff 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _rf-tuner-controls: diff --git a/Documentation/userspace-api/media/v4l/extended-controls.rst b/Documentation/userspace-api/media/v4l/extended-controls.rst index 9aa352ac5ea4..44fcd67f20bf 100644 --- a/Documentation/userspace-api/media/v4l/extended-controls.rst +++ b/Documentation/userspace-api/media/v4l/extended-controls.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _extended-controls: @@ -62,8 +55,8 @@ controls in that array and a control class. Control classes are used to group similar controls into a single class. For example, control class ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` -ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls -relating to MPEG encoding, etc. +ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls +relating to codecs. All controls in the control array must belong to the specified control class. An error is returned if this is not the case. @@ -137,9 +130,9 @@ control class is found: .. code-block:: c - qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; + qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL; while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { - if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) + if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC) break; /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; diff --git a/Documentation/userspace-api/media/v4l/field-order.rst b/Documentation/userspace-api/media/v4l/field-order.rst index 04e9a6932dc5..9a0ed8fc550f 100644 --- a/Documentation/userspace-api/media/v4l/field-order.rst +++ b/Documentation/userspace-api/media/v4l/field-order.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _field-order: @@ -69,7 +62,7 @@ enum v4l2_field .. c:type:: v4l2_field -.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{11.1cm}| +.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{10.9cm}| .. cssclass:: longtable diff --git a/Documentation/userspace-api/media/v4l/fieldseq_bt.svg b/Documentation/userspace-api/media/v4l/fieldseq_bt.svg index b663f6fcb70b..91ac2813b454 100644 --- a/Documentation/userspace-api/media/v4l/fieldseq_bt.svg +++ b/Documentation/userspace-api/media/v4l/fieldseq_bt.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/fieldseq_tb.svg b/Documentation/userspace-api/media/v4l/fieldseq_tb.svg index f8b440a1cb60..7b4f8fb33757 100644 --- a/Documentation/userspace-api/media/v4l/fieldseq_tb.svg +++ b/Documentation/userspace-api/media/v4l/fieldseq_tb.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst index e47fc0505727..35bbb2fea46e 100644 --- a/Documentation/userspace-api/media/v4l/format.rst +++ b/Documentation/userspace-api/media/v4l/format.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _format: @@ -13,7 +7,6 @@ Data Formats ************ - Data Format Negotiation ======================= @@ -60,8 +53,8 @@ image size. When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side effects are implied by the next step, the selection of an I/O method with the :ref:`VIDIOC_REQBUFS` ioctl or implicit -with the first :ref:`read() <func-read>` or -:ref:`write() <func-write>` call. +with the first :c:func:`read()` or +:c:func:`write()` call. Generally only one logical stream can be assigned to a file descriptor, the exception being drivers permitting simultaneous video capturing and @@ -74,7 +67,6 @@ All drivers exchanging data with applications must support the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. - Image Format Enumeration ======================== diff --git a/Documentation/userspace-api/media/v4l/func-close.rst b/Documentation/userspace-api/media/v4l/func-close.rst index 37a64dae56b0..dba3263fd1b9 100644 --- a/Documentation/userspace-api/media/v4l/func-close.rst +++ b/Documentation/userspace-api/media/v4l/func-close.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-close: @@ -18,7 +12,6 @@ Name v4l2-close - Close a V4L2 device - Synopsis ======== @@ -26,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: v4l2-close Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -45,7 +35,6 @@ associated with the file descriptor are freed. However data format parameters, current input or output, control values or other properties remain unchanged. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/func-ioctl.rst b/Documentation/userspace-api/media/v4l/func-ioctl.rst index 4e69f303636b..f3b005094334 100644 --- a/Documentation/userspace-api/media/v4l/func-ioctl.rst +++ b/Documentation/userspace-api/media/v4l/func-ioctl.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-ioctl: @@ -18,7 +12,6 @@ Name v4l2-ioctl - Program a V4L2 device - Synopsis ======== @@ -26,15 +19,13 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: v4l2-ioctl +``int ioctl(int fd, int request, void *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``request`` V4L2 ioctl request code as defined in the ``videodev2.h`` header @@ -43,7 +34,6 @@ Arguments ``argp`` Pointer to a function parameter, usually a structure. - Description =========== @@ -57,7 +47,6 @@ include the version in the kernel sources on the system they compile on. All V4L2 ioctl requests, their respective function and parameters are specified in :ref:`user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/func-mmap.rst b/Documentation/userspace-api/media/v4l/func-mmap.rst index f9c77bdce434..e3e5e64ebe7e 100644 --- a/Documentation/userspace-api/media/v4l/func-mmap.rst +++ b/Documentation/userspace-api/media/v4l/func-mmap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-mmap: @@ -18,7 +12,6 @@ Name v4l2-mmap - Map device memory into application address space - Synopsis ======== @@ -27,9 +20,7 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) - :name: v4l2-mmap Arguments ========= @@ -61,7 +52,7 @@ Arguments #. 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() <func-mmap>` function fails. + :c:func:`mmap()` function fails. #. Device memory accesses (e. g. the memory on a graphics card with video capturing hardware) may incur a performance penalty @@ -77,7 +68,7 @@ Arguments ``MAP_FIXED`` requests that the driver selects no other address than the one specified. If the specified address cannot be used, - :ref:`mmap() <func-mmap>` will fail. If ``MAP_FIXED`` is specified, + :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified, ``start`` must be a multiple of the pagesize. Use of this option is discouraged. @@ -94,7 +85,7 @@ Arguments flags. ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``offset`` Offset of the buffer in device memory. This must be the same value @@ -104,11 +95,10 @@ Arguments in the struct :c:type:`v4l2_plane` ``m`` union ``mem_offset`` field for the multi-planar API. - Description =========== -The :ref:`mmap() <func-mmap>` function asks to map ``length`` bytes starting at +The :c:func:`mmap()` function asks to map ``length`` bytes starting at ``offset`` in the memory of the device specified by ``fd`` into the application address space, preferably at address ``start``. This latter address is a hint only, and is usually specified as 0. @@ -118,13 +108,12 @@ Suitable length and offset parameters are queried with the allocated with the :ref:`VIDIOC_REQBUFS` ioctl before they can be queried. -To unmap buffers the :ref:`munmap() <func-munmap>` function is used. - +To unmap buffers the :c:func:`munmap()` function is used. Return Value ============ -On success :ref:`mmap() <func-mmap>` returns a pointer to the mapped buffer. On +On success :c:func:`mmap()` returns a pointer to the mapped buffer. On error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/v4l/func-munmap.rst b/Documentation/userspace-api/media/v4l/func-munmap.rst index 18a9941b47ab..077d58333904 100644 --- a/Documentation/userspace-api/media/v4l/func-munmap.rst +++ b/Documentation/userspace-api/media/v4l/func-munmap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-munmap: @@ -18,7 +12,6 @@ Name v4l2-munmap - Unmap device memory - Synopsis ======== @@ -27,37 +20,33 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: int munmap( void *start, size_t length ) - :name: v4l2-munmap Arguments ========= ``start`` Address of the mapped buffer as returned by the - :ref:`mmap() <func-mmap>` function. + :c:func:`mmap()` function. ``length`` Length of the mapped buffer. This must be the same value as given to - :ref:`mmap() <func-mmap>` and returned by the driver in the struct + :c:func:`mmap()` and returned by the driver in the struct :c:type:`v4l2_buffer` ``length`` field for the single-planar API and in the struct :c:type:`v4l2_plane` ``length`` field for the multi-planar API. - Description =========== -Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped +Unmaps a previously with the :c:func:`mmap()` function mapped buffer and frees it, if possible. - Return Value ============ -On success :ref:`munmap() <func-munmap>` returns 0, on failure -1 and the +On success :c:func:`munmap()` returns 0, on failure -1 and the ``errno`` variable is set appropriately: EINVAL diff --git a/Documentation/userspace-api/media/v4l/func-open.rst b/Documentation/userspace-api/media/v4l/func-open.rst index 8bcdec8ab387..ba23ff1e45dd 100644 --- a/Documentation/userspace-api/media/v4l/func-open.rst +++ b/Documentation/userspace-api/media/v4l/func-open.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-open: @@ -18,7 +12,6 @@ Name v4l2-open - Open a V4L2 device - Synopsis ======== @@ -26,9 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: v4l2-open Arguments ========= @@ -41,7 +32,7 @@ Arguments technicality, input devices still support only reading and output devices only writing. - When the ``O_NONBLOCK`` flag is given, the :ref:`read() <func-read>` + When the ``O_NONBLOCK`` flag is given, the :c:func:`read()` function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will return the ``EAGAIN`` error code when no data is available or no buffer is in the driver outgoing queue, otherwise these functions @@ -50,22 +41,20 @@ Arguments Other flags have no effect. - Description =========== -To open a V4L2 device applications call :ref:`open() <func-open>` with the +To open a V4L2 device applications call :c:func:`open()` with the desired device name. This function has no side effects; all data format parameters, current input or output, control values or other properties -remain unchanged. At the first :ref:`open() <func-open>` call after loading the +remain unchanged. At the first :c:func:`open()` call after loading the driver they will be reset to default values, drivers are never in an undefined state. - Return Value ============ -On success :ref:`open() <func-open>` returns the new file descriptor. On error +On success :c:func:`open()` returns the new file descriptor. On error -1 is returned, and the ``errno`` variable is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/v4l/func-poll.rst b/Documentation/userspace-api/media/v4l/func-poll.rst index 2c6704c1fab7..cbf4a0a10ae2 100644 --- a/Documentation/userspace-api/media/v4l/func-poll.rst +++ b/Documentation/userspace-api/media/v4l/func-poll.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-poll: @@ -18,7 +12,6 @@ Name v4l2-poll - Wait for some event on a file descriptor - Synopsis ======== @@ -26,19 +19,16 @@ Synopsis #include <sys/poll.h> - .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: v4l2-poll Arguments ========= - Description =========== -With the :ref:`poll() <func-poll>` function applications can suspend execution +With the :c:func:`poll()` function applications can suspend execution until the driver has captured data or is ready to accept data for output. @@ -51,57 +41,56 @@ display. When buffers are already in the outgoing queue of the driver (capture) or the incoming queue isn't full (display) the function returns immediately. -On success :ref:`poll() <func-poll>` returns the number of file descriptors +On success :c:func:`poll()` returns the number of file descriptors that have been selected (that is, file descriptors for which the -``revents`` field of the respective :c:func:`struct pollfd` structure +``revents`` field of the respective ``struct pollfd`` structure is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM`` flags in the ``revents`` field, output devices the ``POLLOUT`` and ``POLLWRNORM`` flags. When the function timed out it returns a value of zero, on failure it returns -1 and the ``errno`` variable is set appropriately. When the application did not call -:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :ref:`poll() <func-poll>` +:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :c:func:`poll()` function succeeds, but sets the ``POLLERR`` flag in the ``revents`` field. When the application has called :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the -:ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in +:c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in the ``revents`` field. For output devices this same situation will cause -:ref:`poll() <func-poll>` to succeed as well, but it sets the ``POLLOUT`` and +:c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and ``POLLWRNORM`` flags in the ``revents`` field. If an event occurred (see :ref:`VIDIOC_DQEVENT`) then ``POLLPRI`` will be set in the ``revents`` field and -:ref:`poll() <func-poll>` will return. +:c:func:`poll()` will return. -When use of the :ref:`read() <func-read>` function has been negotiated and the -driver does not capture yet, the :ref:`poll() <func-poll>` function starts +When use of the :c:func:`read()` function has been negotiated and the +driver does not capture yet, the :c:func:`poll()` function starts capturing. When that fails it returns a ``POLLERR`` as above. Otherwise it waits until data has been captured and can be read. When the driver captures continuously (as opposed to, for example, still images) the function may return immediately. -When use of the :ref:`write() <func-write>` function has been negotiated and the -driver does not stream yet, the :ref:`poll() <func-poll>` function starts +When use of the :c:func:`write()` function has been negotiated and the +driver does not stream yet, the :c:func:`poll()` function starts streaming. When that fails it returns a ``POLLERR`` as above. Otherwise it waits until the driver is ready for a non-blocking -:ref:`write() <func-write>` call. +:c:func:`write()` call. If the caller is only interested in events (just ``POLLPRI`` is set in -the ``events`` field), then :ref:`poll() <func-poll>` will *not* start +the ``events`` field), then :c:func:`poll()` will *not* start streaming if the driver does not stream yet. This makes it possible to just poll for events and not for buffers. -All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` -function or streaming I/O must also support the :ref:`poll() <func-poll>` +All drivers implementing the :c:func:`read()` or :c:func:`write()` +function or streaming I/O must also support the :c:func:`poll()` function. -For more details see the :ref:`poll() <func-poll>` manual page. - +For more details see the :c:func:`poll()` manual page. Return Value ============ -On success, :ref:`poll() <func-poll>` returns the number structures which have +On success, :c:func:`poll()` returns the number structures which have non-zero ``revents`` fields, or zero if the call timed out. On error -1 is returned, and the ``errno`` variable is set appropriately: diff --git a/Documentation/userspace-api/media/v4l/func-read.rst b/Documentation/userspace-api/media/v4l/func-read.rst index 1728aa5d8313..e6f6ac4bed77 100644 --- a/Documentation/userspace-api/media/v4l/func-read.rst +++ b/Documentation/userspace-api/media/v4l/func-read.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-read: @@ -18,7 +12,6 @@ Name v4l2-read - Read from a V4L2 device - Synopsis ======== @@ -26,15 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t read( int fd, void *buf, size_t count ) - :name: v4l2-read Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``buf`` Buffer to be filled @@ -45,48 +36,48 @@ Arguments Description =========== -:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file +:c:func:`read()` attempts to read up to ``count`` bytes from file descriptor ``fd`` into the buffer starting at ``buf``. The layout of the data in the buffer is discussed in the respective device interface -section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero +section, see ##. If ``count`` is zero, :c:func:`read()` returns zero and has no other results. If ``count`` is greater than ``SSIZE_MAX``, the result is unspecified. Regardless of the ``count`` value each -:ref:`read() <func-read>` call will provide at most one frame (two fields) +:c:func:`read()` call will provide at most one frame (two fields) worth of data. -By default :ref:`read() <func-read>` blocks until data becomes available. When -the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` +By default :c:func:`read()` blocks until data becomes available. When +the ``O_NONBLOCK`` flag was given to the :c:func:`open()` function it returns immediately with an ``EAGAIN`` error code when no data -is available. The :ref:`select() <func-select>` or -:ref:`poll() <func-poll>` functions can always be used to suspend +is available. The :c:func:`select()` or +:c:func:`poll()` functions can always be used to suspend execution until data becomes available. All drivers supporting the -:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and -:ref:`poll() <func-poll>`. +:c:func:`read()` function must also support :c:func:`select()` and +:c:func:`poll()`. Drivers can implement read functionality in different ways, using a single or multiple buffers and discarding the oldest or newest frames once the internal buffers are filled. -:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled. +:c:func:`read()` never returns a "snapshot" of a buffer being filled. Using a single buffer the driver will stop capturing when the application starts reading the buffer until the read is finished. Thus only the period of the vertical blanking interval is available for reading, or the capture rate must fall below the nominal frame rate of the video standard. -The behavior of :ref:`read() <func-read>` when called during the active picture +The behavior of :c:func:`read()` when called during the active picture period or the vertical blanking separating the top and bottom field depends on the discarding policy. A driver discarding the oldest frames keeps capturing into an internal buffer, continuously overwriting the previously, not read frame, and returns the frame being received at the -time of the :ref:`read() <func-read>` call as soon as it is complete. +time of the :c:func:`read()` call as soon as it is complete. A driver discarding the newest frames stops capturing until the next -:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>` +:c:func:`read()` call. The frame being received at :c:func:`read()` time is discarded, returning the following frame instead. Again this implies a reduction of the capture rate to one half or less of the nominal frame rate. An example of this model is the video read mode of -the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>` +the bttv driver, initiating a DMA to user memory when :c:func:`read()` is called and returning when the DMA finished. In the multiple buffer model drivers maintain a ring of internal @@ -101,14 +92,13 @@ the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and however. The discarding policy is not reported and cannot be changed. For minimum requirements see :ref:`devices`. - Return Value ============ On success, the number of bytes read is returned. It is not an error if this number is smaller than the number of bytes requested, or the amount of data required for one frame. This may happen for example because -:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is +:c:func:`read()` was interrupted by a signal. On error, -1 is returned, and the ``errno`` variable is set appropriately. In this case the next read will start at the beginning of a new frame. Possible error codes are: @@ -136,5 +126,5 @@ EIO communicate with a remote device (USB camera etc.). EINVAL - The :ref:`read() <func-read>` function is not supported by this driver, not + The :c:func:`read()` function is not supported by this driver, not on this device, or generally not on this type of device. diff --git a/Documentation/userspace-api/media/v4l/func-select.rst b/Documentation/userspace-api/media/v4l/func-select.rst index 6aca8a290c1f..ba1879c728f0 100644 --- a/Documentation/userspace-api/media/v4l/func-select.rst +++ b/Documentation/userspace-api/media/v4l/func-select.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-select: @@ -18,7 +12,6 @@ Name v4l2-select - Synchronous I/O multiplexing - Synopsis ======== @@ -28,9 +21,7 @@ Synopsis #include <sys/types.h> #include <unistd.h> - .. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout ) - :name: v4l2-select Arguments ========= @@ -50,11 +41,10 @@ Arguments ``timeout`` Maximum time to wait. - Description =========== -With the :ref:`select() <func-select>` function applications can suspend +With the :c:func:`select()` function applications can suspend execution until the driver has captured data or is ready to accept data for output. @@ -63,40 +53,39 @@ buffer has been filled or displayed and can be dequeued with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in the outgoing queue of the driver the function returns immediately. -On success :ref:`select() <func-select>` returns the total number of bits set in -:c:func:`struct fd_set`. When the function timed out it returns +On success :c:func:`select()` returns the total number of bits set in +``fd_set``. When the function timed out it returns a value of zero. On failure it returns -1 and the ``errno`` variable is set appropriately. When the application did not call :ref:`VIDIOC_QBUF` or -:ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>` +:ref:`VIDIOC_STREAMON` yet the :c:func:`select()` function succeeds, setting the bit of the file descriptor in ``readfds`` or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` calls will fail. [#f1]_ -When use of the :ref:`read() <func-read>` function has been negotiated and the -driver does not capture yet, the :ref:`select() <func-select>` function starts -capturing. When that fails, :ref:`select() <func-select>` returns successful and -a subsequent :ref:`read() <func-read>` call, which also attempts to start +When use of the :c:func:`read()` function has been negotiated and the +driver does not capture yet, the :c:func:`select()` function starts +capturing. When that fails, :c:func:`select()` returns successful and +a subsequent :c:func:`read()` call, which also attempts to start capturing, will return an appropriate error code. When the driver captures continuously (as opposed to, for example, still images) and -data is already available the :ref:`select() <func-select>` function returns +data is already available the :c:func:`select()` function returns immediately. -When use of the :ref:`write() <func-write>` function has been negotiated the -:ref:`select() <func-select>` function just waits until the driver is ready for a -non-blocking :ref:`write() <func-write>` call. +When use of the :c:func:`write()` function has been negotiated the +:c:func:`select()` function just waits until the driver is ready for a +non-blocking :c:func:`write()` call. -All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` -function or streaming I/O must also support the :ref:`select() <func-select>` +All drivers implementing the :c:func:`read()` or :c:func:`write()` +function or streaming I/O must also support the :c:func:`select()` function. -For more details see the :ref:`select() <func-select>` manual page. - +For more details see the :c:func:`select()` manual page. Return Value ============ -On success, :ref:`select() <func-select>` returns the number of descriptors +On success, :c:func:`select()` returns the number of descriptors contained in the three returned descriptor sets, which will be zero if the timeout expired. On error -1 is returned, and the ``errno`` variable is set appropriately; the sets and ``timeout`` are undefined. Possible @@ -122,6 +111,6 @@ EINVAL ``FD_SETSIZE``. .. [#f1] - The Linux kernel implements :ref:`select() <func-select>` like the - :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot + The Linux kernel implements :c:func:`select()` like the + :c:func:`poll()` function, but :c:func:`select()` cannot return a ``POLLERR``. diff --git a/Documentation/userspace-api/media/v4l/func-write.rst b/Documentation/userspace-api/media/v4l/func-write.rst index fb1955f70f0f..49f5a0f4275f 100644 --- a/Documentation/userspace-api/media/v4l/func-write.rst +++ b/Documentation/userspace-api/media/v4l/func-write.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-write: @@ -18,7 +12,6 @@ Name v4l2-write - Write to a V4L2 device - Synopsis ======== @@ -26,15 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t write( int fd, void *buf, size_t count ) - :name: v4l2-write Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``buf`` Buffer with data to be written @@ -45,10 +36,10 @@ Arguments Description =========== -:ref:`write() <func-write>` writes up to ``count`` bytes to the device +:c:func:`write()` writes up to ``count`` bytes to the device referenced by the file descriptor ``fd`` from the buffer starting at ``buf``. When the hardware outputs are not active yet, this function -enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0 +enables them. When ``count`` is zero, :c:func:`write()` returns 0 without any other effect. When the application does not provide more data in time, the previous @@ -56,7 +47,6 @@ video frame, raw VBI image, sliced VPS or WSS data is displayed again. Sliced Teletext or Closed Caption data is not repeated, the driver inserts a blank line instead. - Return Value ============ @@ -87,5 +77,5 @@ EIO I/O error. This indicates some hardware problem. EINVAL - The :ref:`write() <func-write>` function is not supported by this driver, + The :c:func:`write()` function is not supported by this driver, not on this device, or generally not on this type of device. diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst index 7913d017cd33..cdc11e9a0f32 100644 --- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _hist-v4l2: @@ -21,18 +15,17 @@ not just an extension but a replacement for the V4L API. However it took another four years and two stable kernel releases until the new API was finally accepted for inclusion into the kernel in its present form. - Early Versions ============== 1998-08-20: First version. -1998-08-27: The :ref:`select() <func-select>` function was introduced. +1998-08-27: The :c:func:`select()` function was introduced. 1998-09-10: New video standard interface. 1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise -meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the +meaningless ``O_TRUNC`` :c:func:`open()` flag, and the aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set this flag if they intend to access controls only, as opposed to capture applications which need exclusive access. The ``VIDEO_STD_XXX`` @@ -43,7 +36,7 @@ transmission arguments. 1998-09-28: Revamped video standard. Made video controls individually enumerable. -1998-10-02: The ``id`` field was removed from struct +1998-10-02: The ``id`` field was removed from struct ``video_standard`` and the color subcarrier fields were renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was renamed to :ref:`VIDIOC_ENUMSTD`, @@ -52,9 +45,9 @@ renamed to :ref:`VIDIOC_ENUMSTD`, Codec API was released. 1998-11-08: Many minor changes. Most symbols have been renamed. Some -material changes to struct :c:type:`v4l2_capability`. +material changes to struct v4l2_capability. -1998-11-12: The read/write directon of some ioctls was misdefined. +1998-11-12: The read/write direction of some ioctls was misdefined. 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio @@ -72,7 +65,6 @@ output devices were added. 1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed. - V4L2 Version 0.16 1999-01-31 ============================ @@ -80,7 +72,6 @@ V4L2 Version 0.16 1999-01-31 are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added digital zoom (cropping) controls. - V4L2 Version 0.18 1999-03-16 ============================ @@ -88,7 +79,6 @@ Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver writers, this changes how you implement your ioctl handler. See the Driver Writer's Guide. Added some more control id codes. - V4L2 Version 0.19 1999-06-05 ============================ @@ -114,7 +104,6 @@ malfunction of this ioctl. 1999-06-05: Changed the value of V4L2_CID_WHITENESS. - V4L2 Version 0.20 (1999-09-10) ============================== @@ -123,9 +112,8 @@ compatible* with 0.19 and earlier versions. Purpose of these changes was to simplify the API, while making it more extensible and following common Linux driver API conventions. -1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct - :c:type:`v4l2_clip` was changed for compatibility with - v4l. (1999-08-30) +1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct v4l2_clip + was changed for compatibility with v4l. (1999-08-30) 2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05) @@ -136,14 +124,12 @@ common Linux driver API conventions. VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example - .. code-block:: c err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); becomes - .. code-block:: c int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); @@ -158,16 +144,14 @@ common Linux driver API conventions. This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``, ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``, ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format - structure struct :c:type:`v4l2_format` was renamed to struct - :c:type:`v4l2_pix_format`, while struct - :c:type:`v4l2_format` is now the envelopping structure + struct v4l2_format was renamed to struct v4l2_pix_format, while + struct v4l2_format is now the enveloping structure for all format negotiations. 5. Similar to the changes above, the ``VIDIOC_G_PARM`` and ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and - ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct - :c:type:`v4l2_streamparm` selects the respective - union member. + ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct v4l2_streamparm + selects the respective union member. This change obsoletes the ``VIDIOC_G_OUTPARM`` and ``VIDIOC_S_OUTPARM`` ioctls. @@ -185,7 +169,7 @@ common Linux driver API conventions. categories might have a greater separation, or may even appear in separate windows. -7. The struct :c:type:`v4l2_buffer` ``timestamp`` was +7. The struct v4l2_buffer ``timestamp`` was changed to a 64 bit integer, containing the sampling or output time of the frame in nanoseconds. Additionally timestamps will be in absolute system time, not starting from zero at the beginning of a @@ -208,16 +192,14 @@ common Linux driver API conventions. v4l2_masterclock_gettime() function (used only by drivers) to return a 64-bit integer. -8. A ``sequence`` field was added to struct - :c:type:`v4l2_buffer`. The ``sequence`` field counts - captured frames, it is ignored by output devices. When a capture - driver drops a frame, the sequence number of that frame is skipped. - +8. A ``sequence`` field was added to struct v4l2_buffer. The ``sequence`` + field counts captured frames, it is ignored by output devices. When a + capture driver drops a frame, the sequence number of that frame is skipped. V4L2 Version 0.20 incremental changes ===================================== -1999-12-23: In struct :c:type:`v4l2_vbi_format` the +1999-12-23: In struct v4l2_vbi_format the ``reserved1`` field became ``offset``. Previously drivers were required to clear the ``reserved1`` field. @@ -260,12 +242,11 @@ multiple tuners into account.) 2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and -:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct ``v4l2_fmt`` ``type`` field does not contain -``V4L2_BUF_TYPE_VBI``. In the documentation of the struct -:c:type:`v4l2_vbi_format` ``offset`` field the -ambiguous phrase "rising edge" was changed to "leading edge". - +``V4L2_BUF_TYPE_VBI``. In the documentation of the struct v4l2_vbi_format`, +the ``offset`` field the ambiguous phrase "rising edge" was changed to +"leading edge". V4L2 Version 0.20 2000-11-23 ============================ @@ -302,13 +283,11 @@ A number of changes were made to the raw VBI interface. were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the latter was missing in the ``videodev.h`` file. - V4L2 Version 0.20 2002-07-25 ============================ Added sliced VBI interface proposal. - V4L2 in Linux 2.5.46, 2002-10 ============================= @@ -319,7 +298,7 @@ This unnamed version was finally merged into Linux 2.5.46. 1. As specified in :ref:`related`, drivers must make related device functions available under all minor device numbers. -2. The :ref:`open() <func-open>` function requires access mode +2. The :c:func:`open()` function requires access mode ``O_RDWR`` regardless of the device type. All V4L2 drivers exchanging data with applications must support the ``O_NONBLOCK`` flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the @@ -328,7 +307,7 @@ This unnamed version was finally merged into Linux 2.5.46. until the application attempts to initiate a data exchange, see :ref:`open`. -3. The struct :c:type:`v4l2_capability` changed +3. The struct v4l2_capability changed dramatically. Note that also the size of the structure changed, which is encoded in the ioctl request code, thus older V4L2 devices will respond with an ``EINVAL`` error code to the new @@ -337,7 +316,7 @@ This unnamed version was finally merged into Linux 2.5.46. There are new fields to identify the driver, a new RDS device function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag indicates if the device has any audio connectors, another I/O - capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these + capability V4L2_CAP_ASYNCIO can be flagged. In response to these changes the ``type`` field became a bit set and was merged into the ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced @@ -361,7 +340,7 @@ This unnamed version was finally merged into Linux 2.5.46. ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is available as described in :ref:`format`. -4. In struct :c:type:`v4l2_input` the ``assoc_audio`` +4. In struct v4l2_input the ``assoc_audio`` field and the ``capability`` field and its only flag ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field. Instead of linking one video input to one audio input this field @@ -370,11 +349,11 @@ This unnamed version was finally merged into Linux 2.5.46. New fields are ``tuner`` (reversing the former link from tuners to video inputs), ``std`` and ``status``. - Accordingly struct :c:type:`v4l2_output` lost its + Accordingly struct v4l2_output lost its ``capability`` and ``assoc_audio`` fields. ``audioset``, ``modulator`` and ``std`` where added instead. -5. The struct :c:type:`v4l2_audio` field ``audio`` was +5. The struct v4l2_audio field ``audio`` was renamed to ``index``, for consistency with other structures. A new capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the audio input in question supports stereo sound. @@ -382,21 +361,20 @@ This unnamed version was finally merged into Linux 2.5.46. where removed. This can be easily implemented using controls. (However the same applies to AVL which is still there.) - Again for consistency the struct - :c:type:`v4l2_audioout` field ``audio`` was renamed + Again for consistency the struct v4l2_audioout field ``audio`` was renamed to ``index``. -6. The struct :c:type:`v4l2_tuner` ``input`` field was +6. The struct v4l2_tuner ``input`` field was replaced by an ``index`` field, permitting devices with multiple tuners. The link between video inputs and tuners is now reversed, inputs point to their tuner. The ``std`` substructure became a - simple set (more about this below) and moved into struct - :c:type:`v4l2_input`. A ``type`` field was added. + simple set (more about this below) and moved into struct v4l2_input. + A ``type`` field was added. - Accordingly in struct :c:type:`v4l2_modulator` the + Accordingly in struct v4l2_modulator the ``output`` was replaced by an ``index`` field. - In struct :c:type:`v4l2_frequency` the ``port`` + In struct v4l2_frequency the ``port`` field was replaced by a ``tuner`` field containing the respective tuner or modulator index number. A tuner ``type`` field was added and the ``reserved`` field became larger for future extensions @@ -412,7 +390,7 @@ This unnamed version was finally merged into Linux 2.5.46. :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this type as argument. :ref:`VIDIOC_QUERYSTD` was added to autodetect the received standard, if the hardware has this - capability. In struct :c:type:`v4l2_standard` an + capability. In struct v4l2_standard an ``index`` field was added for :ref:`VIDIOC_ENUMSTD`. A :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as @@ -424,10 +402,10 @@ This unnamed version was finally merged into Linux 2.5.46. Struct ``v4l2_enumstd`` ceased to be. :ref:`VIDIOC_ENUMSTD` now takes a pointer to a - struct :c:type:`v4l2_standard` directly. The + struct v4l2_standard directly. The information which standards are supported by a particular video - input or output moved into struct :c:type:`v4l2_input` - and struct :c:type:`v4l2_output` fields named ``std``, + input or output moved into struct v4l2_input + and struct v4l2_output fields named ``std``, respectively. 8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields @@ -439,15 +417,13 @@ This unnamed version was finally merged into Linux 2.5.46. :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of programming the hardware and regardless of I/O in progress. - In struct :c:type:`v4l2_format` the ``fmt`` union was - extended to contain struct :c:type:`v4l2_window`. All + In struct v4l2_format the ``fmt`` union was + extended to contain struct v4l2_window. All image format negotiations are now possible with ``VIDIOC_G_FMT``, ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN`` and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were - removed. The ``type`` field changed to type enum - :c:type:`v4l2_buf_type` and the buffer type names - changed as follows. - + removed. The ``type`` field changed to type enum v4l2_buf_type and + the buffer type names changed as follows. .. flat-table:: @@ -455,7 +431,7 @@ This unnamed version was finally merged into Linux 2.5.46. :stub-columns: 0 * - Old defines - - enum :c:type:`v4l2_buf_type` + - enum v4l2_buf_type * - ``V4L2_BUF_TYPE_CAPTURE`` - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` * - ``V4L2_BUF_TYPE_CODECIN`` @@ -483,16 +459,12 @@ This unnamed version was finally merged into Linux 2.5.46. * - ``V4L2_BUF_TYPE_PRIVATE_BASE`` - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated) +10. In struct v4l2_fmtdesc a enum v4l2_buf_type field named ``type`` was + added as in struct v4l2_format. The ``VIDIOC_ENUM_FBUFFMT`` ioctl is no + longer needed and was removed. These calls can be replaced by + :ref:`VIDIOC_ENUM_FMT` with type ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. -10. In struct :c:type:`v4l2_fmtdesc` a enum - :c:type:`v4l2_buf_type` field named ``type`` was - added as in struct :c:type:`v4l2_format`. The - ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed. - These calls can be replaced by - :ref:`VIDIOC_ENUM_FMT` with type - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. - -11. In struct :c:type:`v4l2_pix_format` the ``depth`` +11. In struct v4l2_pix_format the ``depth`` field was removed, assuming applications which recognize the format by its four-character-code already know the color depth, and others do not care about it. The same rationale lead to the removal of the @@ -505,18 +477,15 @@ This unnamed version was finally merged into Linux 2.5.46. Since the remaining flags were replaced as well, the ``flags`` field itself was removed. - The interlace flags were replaced by a enum - :c:type:`v4l2_field` value in a newly added ``field`` - field. - - + The interlace flags were replaced by a enum v4l2_field value in a + newly added ``field`` field. .. flat-table:: :header-rows: 1 :stub-columns: 0 * - Old flag - - enum :c:type:`v4l2_field` + - enum v4l2_field * - ``V4L2_FMT_FLAG_NOT_INTERLACED`` - ? * - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED`` @@ -532,33 +501,31 @@ This unnamed version was finally merged into Linux 2.5.46. * - ``-`` - ``V4L2_FIELD_ALTERNATE`` - - The color space flags were replaced by a enum - :c:type:`v4l2_colorspace` value in a newly added - ``colorspace`` field, where one of ``V4L2_COLORSPACE_SMPTE170M``, - ``V4L2_COLORSPACE_BT878``, ``V4L2_COLORSPACE_470_SYSTEM_M`` or + The color space flags were replaced by a enum v4l2_colorspace value in + a newly added ``colorspace`` field, where one of + ``V4L2_COLORSPACE_SMPTE170M``, ``V4L2_COLORSPACE_BT878``, + ``V4L2_COLORSPACE_470_SYSTEM_M`` or ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``. -12. In struct :c:type:`v4l2_requestbuffers` the - ``type`` field was properly defined as enum - :c:type:`v4l2_buf_type`. Buffer types changed as - mentioned above. A new ``memory`` field of type enum - :c:type:`v4l2_memory` was added to distinguish between +12. In struct v4l2_requestbuffers the + ``type`` field was properly defined as enum v4l2_buf_type. Buffer types + changed as mentioned above. A new ``memory`` field of type + enum v4l2_memory was added to distinguish between I/O methods using buffers allocated by the driver or the application. See :ref:`io` for details. -13. In struct :c:type:`v4l2_buffer` the ``type`` field was - properly defined as enum :c:type:`v4l2_buf_type`. +13. In struct v4l2_buffer the ``type`` field was + properly defined as enum v4l2_buf_type. Buffer types changed as mentioned above. A ``field`` field of type - enum :c:type:`v4l2_field` was added to indicate if a + enum v4l2_field was added to indicate if a buffer contains a top or bottom field. The old field flags were removed. Since no unadjusted system time clock was added to the kernel as planned, the ``timestamp`` field changed back from type stamp_t, an unsigned 64 bit integer expressing the sample time in - nanoseconds, to struct :c:type:`timeval`. With the addition + nanoseconds, to struct timeval. With the addition of a second memory mapping method the ``offset`` field moved into - union ``m``, and a new ``memory`` field of type enum - :c:type:`v4l2_memory` was added to distinguish between + union ``m``, and a new ``memory`` field of type enum v4l2_memory + was added to distinguish between I/O methods. See :ref:`io` for details. The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility @@ -567,7 +534,7 @@ This unnamed version was finally merged into Linux 2.5.46. indeed allocated in device memory rather than DMA-able system memory. It was barely useful and so was removed. -14. In struct :c:type:`v4l2_framebuffer` the +14. In struct v4l2_framebuffer the ``base[3]`` array anticipating double- and triple-buffering in off-screen video memory, however without defining a synchronization mechanism, was replaced by a single pointer. The @@ -578,40 +545,38 @@ This unnamed version was finally merged into Linux 2.5.46. ``V4L2_FBUF_CAP_LIST_CLIPPING`` and ``V4L2_FBUF_CAP_BITMAP_CLIPPING``. -15. In struct :c:type:`v4l2_clip` the ``x``, ``y``, +15. In struct v4l2_clip the ``x``, ``y``, ``width`` and ``height`` field moved into a ``c`` substructure of - type struct :c:type:`v4l2_rect`. The ``x`` and ``y`` + type struct v4l2_rect. The ``x`` and ``y`` fields were renamed to ``left`` and ``top``, i. e. offsets to a context dependent origin. -16. In struct :c:type:`v4l2_window` the ``x``, ``y``, +16. In struct v4l2_window the ``x``, ``y``, ``width`` and ``height`` field moved into a ``w`` substructure as - above. A ``field`` field of type :c:type:`v4l2_field` was added to + above. A ``field`` field of type enum v4l2_field was added to distinguish between field and frame (interlaced) overlay. -17. The digital zoom interface, including struct - struct ``v4l2_zoomcap``, struct +17. The digital zoom interface, including struct ``v4l2_zoomcap``, struct ``v4l2_zoom``, ``V4L2_ZOOM_NONCAP`` and ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and - scaling interface. The previously unused struct - struct :c:type:`v4l2_cropcap` and struct :c:type:`v4l2_crop` + scaling interface. The previously unused + struct v4l2_cropcap and struct v4l2_crop where redefined for this purpose. See :ref:`crop` for details. -18. In struct :c:type:`v4l2_vbi_format` the +18. In struct v4l2_vbi_format the ``SAMPLE_FORMAT`` field now contains a four-character-code as used to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was extended. -19. In struct :c:type:`v4l2_captureparm` the type of - the ``timeperframe`` field changed from unsigned long to struct - :c:type:`v4l2_fract`. This allows the accurate +19. In struct v4l2_captureparm the type of + the ``timeperframe`` field changed from unsigned long to + struct v4l2_fract. This allows the accurate expression of multiples of the NTSC-M frame rate 30000 / 1001. A new field ``readbuffers`` was added to control the driver behaviour in read I/O mode. - Similar changes were made to struct - :c:type:`v4l2_outputparm`. + Similar changes were made to struct v4l2_outputparm. 20. The struct ``v4l2_performance`` and ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the @@ -622,7 +587,6 @@ This unnamed version was finally merged into Linux 2.5.46. V4L2 documentation was inaccurate, this has been corrected in :ref:`pixfmt`. - V4L2 2003-06-19 =============== @@ -673,7 +637,6 @@ V4L2 2003-06-19 Kernel 2.6.39. Drivers and applications assuming a constant parameter need an update. - V4L2 2003-11-05 =============== @@ -682,7 +645,6 @@ V4L2 2003-11-05 refer to bytes in memory, in ascending address order. - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -703,7 +665,6 @@ V4L2 2003-11-05 - R, G, B, X - B, G, R, X - The ``V4L2_PIX_FMT_BGR24`` example was always correct. In :ref:`v4l-image-properties` the mapping of the V4L @@ -714,7 +675,6 @@ V4L2 2003-11-05 RGB pixel formats differently. These issues have yet to be addressed, for details see :ref:`pixfmt-rgb`. - V4L2 in Linux 2.6.6, 2004-05-09 =============================== @@ -723,18 +683,16 @@ V4L2 in Linux 2.6.6, 2004-05-09 ioctl, while the read-only version was renamed to ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39. - V4L2 in Linux 2.6.8 =================== 1. A new field ``input`` (former ``reserved[0]``) was added to the - struct :c:type:`v4l2_buffer` structure. Purpose of this + struct v4l2_buffer. Purpose of this field is to alternate between video inputs (e. g. cameras) in step with the video capturing process. This function must be enabled with the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no longer read-only. - V4L2 spec erratum 2004-08-01 ============================ @@ -748,11 +706,10 @@ V4L2 spec erratum 2004-08-01 4. The documentation of the :ref:`VIDIOC_QBUF` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the - struct :c:type:`v4l2_buffer` ``memory`` field. It was + struct v4l2_buffer ``memory`` field. It was also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO`` error code was not documented. - V4L2 in Linux 2.6.14 ==================== @@ -760,7 +717,6 @@ V4L2 in Linux 2.6.14 :ref:`sliced` and replaces the interface first proposed in V4L2 specification 0.8. - V4L2 in Linux 2.6.15 ==================== @@ -780,7 +736,6 @@ V4L2 in Linux 2.6.15 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed in Linux 2.6.25.) - V4L2 spec erratum 2005-11-27 ============================ @@ -790,37 +745,31 @@ cropping is supported. In the video standard selection example in :ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used the wrong argument type. - V4L2 spec erratum 2006-01-10 ============================ -1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct - :c:type:`v4l2_input` not only indicates if the color - killer is enabled, but also if it is active. (The color killer - disables color decoding when it detects no color in the video signal - to improve the image quality.) +1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct v4l2_input not only + indicates if the color killer is enabled, but also if it is active. + (The color killer disables color decoding when it detects no color + in the video signal to improve the image quality.) 2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not write-only as stated on its reference page. The ioctl changed in 2003 as noted above. - V4L2 spec erratum 2006-02-03 ============================ -1. In struct :c:type:`v4l2_captureparm` and struct - :c:type:`v4l2_outputparm` the ``timeperframe`` +1. In struct v4l2_captureparm and struct v4l2_outputparm the ``timeperframe`` field gives the time in seconds, not microseconds. - V4L2 spec erratum 2006-02-04 ============================ -1. The ``clips`` field in struct :c:type:`v4l2_window` - must point to an array of struct :c:type:`v4l2_clip`, not - a linked list, because drivers ignore the struct - struct :c:type:`v4l2_clip`. ``next`` pointer. - +1. The ``clips`` field in struct v4l2_window + must point to an array of struct v4l2_clip, not + a linked list, because drivers ignore the + struct v4l2_clip. ``next`` pointer. V4L2 in Linux 2.6.17 ==================== @@ -836,7 +785,6 @@ V4L2 in Linux 2.6.17 ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details. - V4L2 spec erratum 2006-09-23 (Draft 0.15) ========================================= @@ -844,19 +792,18 @@ V4L2 spec erratum 2006-09-23 (Draft 0.15) ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were not mentioned along with other buffer types. -2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the struct - :c:type:`v4l2_audio` ``mode`` field is a flags field. +2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the + struct v4l2_audio ``mode`` field is a flags field. 3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio capability flags. -4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that applications - must initialize the tuner ``type`` field of struct - :c:type:`v4l2_frequency` before calling +4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that + applications must initialize the tuner ``type`` field of + struct v4l2_frequency before calling :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. -5. The ``reserved`` array in struct - :c:type:`v4l2_requestbuffers` has 2 elements, +5. The ``reserved`` array in struct v4l2_requestbuffers has 2 elements, not 32. 6. In :ref:`output` and :ref:`raw-vbi` the device file names @@ -866,7 +813,6 @@ V4L2 spec erratum 2006-09-23 (Draft 0.15) extended from 224-239 to 224-255. Accordingly device file names ``/dev/vbi0`` to ``/dev/vbi31`` are possible now. - V4L2 in Linux 2.6.18 ==================== @@ -876,16 +822,15 @@ V4L2 in Linux 2.6.18 flag to skip unsupported controls with :ref:`VIDIOC_QUERYCTRL`, new control types ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS`` - (:c:type:`v4l2_ctrl_type`), and new control flags + (enum v4l2_ctrl_type), and new control flags ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``, ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER`` (:ref:`control-flags`). See :ref:`extended-controls` for details. - V4L2 in Linux 2.6.19 ==================== -1. In struct :c:type:`v4l2_sliced_vbi_cap` a +1. In struct v4l2_sliced_vbi_cap a buffer type field was added replacing a reserved field. Note on architectures where the size of enum types differs from int types the size of the structure changed. The @@ -903,14 +848,12 @@ V4L2 in Linux 2.6.19 3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was added. - V4L2 spec erratum 2006-10-12 (Draft 0.17) ========================================= 1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not 4:2:2 format. - V4L2 in Linux 2.6.21 ==================== @@ -918,12 +861,11 @@ V4L2 in Linux 2.6.21 General Public License version two or later, and under a 3-clause BSD-style license. - V4L2 in Linux 2.6.22 ==================== 1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and - ``V4L2_FIELD_INTERLACED_BT`` were added. See :c:type:`v4l2_field` for + ``V4L2_FIELD_INTERLACED_BT`` were added. See enum v4l2_field for details. 2. Three new clipping/blending methods with a global or straight or @@ -931,20 +873,17 @@ V4L2 in Linux 2.6.22 See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details. - A new ``global_alpha`` field was added to - :c:type:`v4l2_window`, extending the structure. This - may *break compatibility* with applications using a struct - struct :c:type:`v4l2_window` directly. However the + A new ``global_alpha`` field was added to struct v4l2_window, + extending the structure. This may **break compatibility** with + applications using a struct v4l2_window directly. However the :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a - pointer to a :c:type:`v4l2_format` parent structure + pointer to a struct v4l2_format parent structure with padding bytes at the end, are not affected. -3. The format of the ``chromakey`` field in struct - :c:type:`v4l2_window` changed from "host order RGB32" - to a pixel value in the same format as the framebuffer. This may - *break compatibility* with existing applications. Drivers supporting - the "host order RGB32" format are not known. - +3. The format of the ``chromakey`` field in struct v4l2_window changed from + "host order RGB32" to a pixel value in the same format as the framebuffer. + This may **break compatibility** with existing applications. Drivers + supporting the "host order RGB32" format are not known. V4L2 in Linux 2.6.24 ==================== @@ -953,7 +892,6 @@ V4L2 in Linux 2.6.24 ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and ``V4L2_PIX_FMT_YUV32`` were added. - V4L2 in Linux 2.6.25 ==================== @@ -980,7 +918,6 @@ V4L2 in Linux 2.6.25 interface in Linux 2.6.18, where finally removed from the ``videodev2.h`` header file. - V4L2 in Linux 2.6.26 ==================== @@ -990,7 +927,6 @@ V4L2 in Linux 2.6.26 2. Added user controls ``V4L2_CID_CHROMA_AGC`` and ``V4L2_CID_COLOR_KILLER``. - V4L2 in Linux 2.6.27 ==================== @@ -1002,7 +938,6 @@ V4L2 in Linux 2.6.27 ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``, ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added. - V4L2 in Linux 2.6.28 ==================== @@ -1014,14 +949,12 @@ V4L2 in Linux 2.6.28 3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added. - V4L2 in Linux 2.6.29 ==================== 1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was - introduced in its place. The old struct - struct ``v4l2_chip_ident`` was renamed to + introduced in its place. The old struct ``v4l2_chip_ident`` was renamed to struct ``v4l2_chip_ident_old``. 2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and @@ -1031,7 +964,6 @@ V4L2 in Linux 2.6.29 ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and ``V4L2_CID_PRIVACY``. - V4L2 in Linux 2.6.30 ==================== @@ -1039,7 +971,6 @@ V4L2 in Linux 2.6.30 2. New control ``V4L2_CID_COLORFX`` was added. - V4L2 in Linux 2.6.32 ==================== @@ -1066,21 +997,18 @@ V4L2 in Linux 2.6.32 9. Added Remote Controller chapter, describing the default Remote Controller mapping for media devices. - V4L2 in Linux 2.6.33 ==================== 1. Added support for Digital Video timings in order to support HDTV receivers and transmitters. - V4L2 in Linux 2.6.34 ==================== 1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE`` controls to the :ref:`Camera controls class <camera-controls>`. - V4L2 in Linux 2.6.37 ==================== @@ -1089,7 +1017,6 @@ V4L2 in Linux 2.6.37 applications found that used it. It was originally scheduled for removal in 2.6.35. - V4L2 in Linux 2.6.39 ==================== @@ -1099,7 +1026,6 @@ V4L2 in Linux 2.6.39 drivers and applications. See :ref:`multi-planar API <planar-apis>` for details. - V4L2 in Linux 3.1 ================= @@ -1110,7 +1036,6 @@ V4L2 in Linux 3.1 Added V4L2_CTRL_TYPE_BITMASK. - V4L2 in Linux 3.2 ================= @@ -1121,7 +1046,6 @@ V4L2 in Linux 3.2 Does not affect the compatibility of current drivers and applications. See :ref:`selection API <selection-api>` for details. - V4L2 in Linux 3.3 ================= @@ -1131,7 +1055,6 @@ V4L2 in Linux 3.3 2. Added the device_caps field to struct v4l2_capabilities and added the new V4L2_CAP_DEVICE_CAPS capability. - V4L2 in Linux 3.4 ================= @@ -1142,7 +1065,6 @@ V4L2 in Linux 3.4 :ref:`VIDIOC_QUERY_DV_TIMINGS` and :ref:`VIDIOC_DV_TIMINGS_CAP`. - V4L2 in Linux 3.5 ================= @@ -1169,11 +1091,10 @@ V4L2 in Linux 3.5 ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``, ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``. - V4L2 in Linux 3.6 ================= -1. Replaced ``input`` in struct :c:type:`v4l2_buffer` by +1. Replaced ``input`` in struct v4l2_buffer by ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``. 2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE @@ -1182,17 +1103,15 @@ V4L2 in Linux 3.6 3. Added support for frequency band enumerations: :ref:`VIDIOC_ENUM_FREQ_BANDS`. - V4L2 in Linux 3.9 ================= 1. Added timestamp types to ``flags`` field in - struct :c:type:`v4l2_buffer`. See :ref:`buffer-flags`. + struct v4l2_buffer. See :ref:`buffer-flags`. 2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See :ref:`ctrl-changes-flags`. - V4L2 in Linux 3.10 ================== @@ -1204,59 +1123,48 @@ V4L2 in Linux 3.10 2. Added new debugging ioctl :ref:`VIDIOC_DBG_G_CHIP_INFO`. - V4L2 in Linux 3.11 ================== 1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl. - V4L2 in Linux 3.14 ================== -1. In struct :c:type:`v4l2_rect`, the type of ``width`` and +1. In struct v4l2_rect, the type of ``width`` and ``height`` fields changed from _s32 to _u32. - V4L2 in Linux 3.15 ================== 1. Added Software Defined Radio (SDR) Interface. - V4L2 in Linux 3.16 ================== 1. Added event V4L2_EVENT_SOURCE_CHANGE. - V4L2 in Linux 3.17 ================== -1. Extended struct :c:type:`v4l2_pix_format`. Added +1. Extended struct v4l2_pix_format. Added format flags. 2. Added compound control types and :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. - V4L2 in Linux 3.18 ================== 1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera controls. - V4L2 in Linux 3.19 ================== -1. Rewrote Colorspace chapter, added new enum - :c:type:`v4l2_ycbcr_encoding` and enum - :c:type:`v4l2_quantization` fields to struct - :c:type:`v4l2_pix_format`, struct - :c:type:`v4l2_pix_format_mplane` and - struct :c:type:`v4l2_mbus_framefmt`. - +1. Rewrote Colorspace chapter, added new enum v4l2_ycbcr_encoding + and enum v4l2_quantization fields to struct v4l2_pix_format, + struct v4l2_pix_format_mplane and struct v4l2_mbus_framefmt. V4L2 in Linux 4.4 ================= @@ -1268,13 +1176,11 @@ V4L2 in Linux 4.4 3. Added transmitter support for Software Defined Radio (SDR) Interface. - .. _other: Relation of V4L2 to other Linux multimedia APIs =============================================== - .. _xvideo: X Video Extension @@ -1320,7 +1226,6 @@ YUV to RGB conversion and scaling for faster video playback, and added an interface to MPEG-2 decoding hardware. This API is useful to display images captured with V4L2 devices. - Digital Video ------------- @@ -1330,13 +1235,11 @@ homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux DVB API has no connection to the V4L2 API except that drivers for hybrid hardware may support both. - Audio Interfaces ---------------- [to do - OSS/ALSA] - .. _experimental: Experimental API Elements @@ -1350,7 +1253,6 @@ change in the future. - :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. - .. _obsolete: Obsolete API Elements diff --git a/Documentation/userspace-api/media/v4l/hsv-formats.rst b/Documentation/userspace-api/media/v4l/hsv-formats.rst index 4906f7e0d80d..d810c914b673 100644 --- a/Documentation/userspace-api/media/v4l/hsv-formats.rst +++ b/Documentation/userspace-api/media/v4l/hsv-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _hsv-formats: diff --git a/Documentation/userspace-api/media/v4l/io.rst b/Documentation/userspace-api/media/v4l/io.rst index de0e2f529268..4b1964df9d73 100644 --- a/Documentation/userspace-api/media/v4l/io.rst +++ b/Documentation/userspace-api/media/v4l/io.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _io: @@ -16,15 +10,14 @@ The V4L2 API defines several different methods to read from or write to a device. All drivers exchanging data with applications must support at least one of them. -The classic I/O method using the :ref:`read() <func-read>` and -:ref:`write() <func-write>` function is automatically selected after opening a +The classic I/O method using the :c:func:`read()` and +:c:func:`write()` function is automatically selected after opening a V4L2 device. When the driver does not support this method attempts to read or write will fail at any time. Other methods must be negotiated. To select the streaming I/O method with memory mapped or user buffers applications call the -:ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O -method is not defined yet. +:ref:`VIDIOC_REQBUFS` ioctl. Video overlay can be considered another I/O method, although the application does not directly receive the image data. It is selected by @@ -45,7 +38,6 @@ closing and reopening the device. The following sections describe the various I/O methods in more detail. - .. toctree:: :maxdepth: 1 @@ -53,6 +45,5 @@ The following sections describe the various I/O methods in more detail. mmap userp dmabuf - async buffer field-order diff --git a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst index 95f3127b4749..7c8bf160e1c6 100644 --- a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst +++ b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _libv4l-introduction: @@ -24,7 +18,6 @@ An example of using libv4l is provided by libv4l consists of 3 different libraries: - libv4lconvert ============= @@ -33,7 +26,7 @@ found in V4L2 drivers into a few common RGB and YUY formats. It currently accepts the following V4L2 driver formats: :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`, -:ref:`V4L2_PIX_FMT_HM12 <V4L2-PIX-FMT-HM12>`, +:ref:`V4L2_PIX_FMT_NV12_16L16 <V4L2-PIX-FMT-NV12-16L16>`, :ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`, :ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`, :ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`, @@ -72,7 +65,6 @@ libv4lconvert/processing. These controls are stored application wide libv4lconvert/processing offers the actual video processing functionality. - libv4l1 ======= @@ -85,7 +77,6 @@ just pass calls through. Since those functions are emulations of the old V4L1 API, it shouldn't be used for new applications. - libv4l2 ======= @@ -112,7 +103,6 @@ available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>` keeps enumerating the hardware supported formats, plus the emulated formats offered by libv4l at the end. - .. _libv4l-ops: Libv4l device control functions @@ -122,17 +112,17 @@ The common file operation methods are provided by libv4l. Those functions operate just like the gcc function ``dup()`` and V4L2 functions -:c:func:`open() <v4l2-open>`, :c:func:`close() <v4l2-close>`, -:c:func:`ioctl() <v4l2-ioctl>`, :c:func:`read() <v4l2-read>`, -:c:func:`mmap() <v4l2-mmap>` and :c:func:`munmap() <v4l2-munmap>`: +:c:func:`open()`, :c:func:`close()`, +:c:func:`ioctl()`, :c:func:`read()`, +:c:func:`mmap()` and :c:func:`munmap()`: .. c:function:: int v4l2_open(const char *file, int oflag, ...) - operates like the :c:func:`open() <v4l2-open>` function. + operates like the :c:func:`open()` function. .. c:function:: int v4l2_close(int fd) - operates like the :c:func:`close() <v4l2-close>` function. + operates like the :c:func:`close()` function. .. c:function:: int v4l2_dup(int fd) @@ -140,19 +130,19 @@ V4L2 functions .. c:function:: int v4l2_ioctl (int fd, unsigned long int request, ...) - operates like the :c:func:`ioctl() <v4l2-ioctl>` function. + operates like the :c:func:`ioctl()` function. .. c:function:: int v4l2_read (int fd, void* buffer, size_t n) - operates like the :c:func:`read() <v4l2-read>` function. + operates like the :c:func:`read()` function. -.. c:function:: void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); +.. c:function:: void *v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - operates like the :c:func:`munmap() <v4l2-munmap>` function. + operates like the :c:func:`mmap()` function. .. c:function:: int v4l2_munmap(void *_start, size_t length); - operates like the :c:func:`munmap() <v4l2-munmap>` function. + operates like the :c:func:`munmap()` function. Those functions provide additional control: @@ -175,14 +165,13 @@ Those functions provide additional control: of the given v4l control id. when the cid does not exist, could not be accessed for some reason, or some error occurred 0 is returned. - v4l1compat.so wrapper library ============================= This library intercepts calls to -:c:func:`open() <v4l2-open>`, :c:func:`close() <v4l2-close>`, -:c:func:`ioctl() <v4l2-ioctl>`, :c:func:`mmap() <v4l2-mmap>` and -:c:func:`munmap() <v4l2-munmap>` +:c:func:`open()`, :c:func:`close()`, +:c:func:`ioctl()`, :c:func:`mmap()` and +:c:func:`munmap()` operations and redirects them to the libv4l counterparts, by using ``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also emulates V4L1 calls via V4L2 API. diff --git a/Documentation/userspace-api/media/v4l/libv4l.rst b/Documentation/userspace-api/media/v4l/libv4l.rst index 5ea2016cac65..f446dd2d01ac 100644 --- a/Documentation/userspace-api/media/v4l/libv4l.rst +++ b/Documentation/userspace-api/media/v4l/libv4l.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _libv4l: diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst index 7dcc4bacbb0c..0bb61fc5bc00 100644 --- a/Documentation/userspace-api/media/v4l/meta-formats.rst +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _meta-formats: @@ -19,9 +12,10 @@ These formats are used for the :ref:`metadata` interface only. .. toctree:: :maxdepth: 1 - pixfmt-meta-d4xx - pixfmt-meta-intel-ipu3 - pixfmt-meta-uvc - pixfmt-meta-vsp1-hgo - pixfmt-meta-vsp1-hgt - pixfmt-meta-vivid + metafmt-d4xx + metafmt-intel-ipu3 + metafmt-rkisp1 + metafmt-uvc + metafmt-vsp1-hgo + metafmt-vsp1-hgt + metafmt-vivid diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst index 4eaf2f9086a9..0686413b16b2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-d4xx: @@ -19,7 +12,7 @@ Intel D4xx UVC Cameras Metadata Description =========== -Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC +Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC payload headers, following the Microsoft(R) UVC extension proposal [1_]. That means, that the private D4XX metadata, following the standard UVC header, is organised in blocks. D4XX cameras implement several standard block types, @@ -33,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary payload header data. D4xx cameras use bulk transfers and only send one payload per frame, therefore their headers cannot be larger than 255 bytes. +This document implements Intel Configuration version 3 [9_]. + Below are proprietary Microsoft style metadata types, used by D4xx cameras, where all fields are in little endian order: @@ -50,10 +45,10 @@ where all fields are in little endian order: * - __u32 ID - 0x80000000 * - __u32 Size - - Size in bytes (currently 56) + - Size in bytes, include ID (all protocol versions: 60) * - __u32 Version - - Version of this structure. The documentation herein corresponds to - version xxx. The version number will be incremented when new fields are + - Version of this structure. The documentation herein covers versions 1, + 2 and 3. The version number will be incremented when new fields are added. * - __u32 Flags - A bitmask of flags: see [2_] below @@ -79,13 +74,17 @@ where all fields are in little endian order: - Bottom border of the AE Region of Interest * - __u32 Preset - Preset selector value, default: 0, unless changed by the user - * - __u32 Laser mode - - 0: off, 1: on + * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_] + - 0: off, 1: on, same as __u32 Laser mode for v1 + * - __u8 RFU byte (v3 only) + - Spare byte for future use + * - __u16 LED Power (v3 only) + - Led power value 0-360 (F416 SKU) * - :cspan:`1` *Capture Timing* * - __u32 ID - 0x80000001 * - __u32 Size - - Size in bytes (currently 40) + - Size in bytes, include ID (all protocol versions: 40) * - __u32 Version - Version of this structure. The documentation herein corresponds to version xxx. The version number will be incremented when new fields are @@ -108,7 +107,7 @@ where all fields are in little endian order: * - __u32 ID - 0x80000002 * - __u32 Size - - Size in bytes (currently 40) + - Size in bytes, include ID (v1:36, v3:40) * - __u32 Version - Version of this structure. The documentation herein corresponds to version xxx. The version number will be incremented when new fields are @@ -131,6 +130,14 @@ where all fields are in little endian order: - Requested frame rate per second * - __u16 Trigger - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger + * - __u16 Calibration count (v3 only) + - Calibration counter, see [4_] below + * - __u8 GPIO input data (v3 only) + - GPIO readout, see [4_] below (Supported from FW 5.12.7.0) + * - __u32 Sub-preset info (v3 only) + - Sub-preset choice information, see [4_] below + * - __u8 reserved (v3 only) + - RFU byte. .. _1: @@ -147,6 +154,8 @@ where all fields are in little endian order: 0x00000010 Exposure priority 0x00000020 AE ROI 0x00000040 Preset + 0x00000080 Emitter mode + 0x00000100 LED Power .. _3: @@ -172,6 +181,8 @@ where all fields are in little endian order: 0x00000040 Framerate 0x00000080 Trigger 0x00000100 Cal count + 0x00000200 GPIO Input Data + 0x00000400 Sub-preset Info .. _5: @@ -218,3 +229,24 @@ Left sensor: :: Fish Eye sensor: :: 1 RAW8 + +.. _8: + +[8] The "Laser mode" has been replaced in version 3 by three different fields. +"Laser" has been renamed to "Emitter" as there are multiple technologies for +camera projectors. As we have another field for "Laser Power" we introduced +"LED Power" for extra emitter. + +The "Laser mode" __u32 fields has been split into: :: + 1 __u8 Emitter mode + 2 __u8 RFU byte + 3 __u16 LED Power + +This is a change between versions 1 and 3. All versions 1, 2 and 3 are backward +compatible with the same data format and they are supported. See [2_] for which +attributes are valid. + +.. _9: + +[9] LibRealSense SDK metadata source: +https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-intel-ipu3.rst b/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst index 97a9a2925671..84d81dd7a7b5 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-intel-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst @@ -1,27 +1,4 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License version -.. 2.0 as published by the Free Software Foundation. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License version 2.0 for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-params: .. _v4l2-meta-fmt-stat-3a: @@ -101,4 +78,4 @@ hardware and algorithm details. Intel IPU3 ImgU uAPI data types =============================== -.. kernel-doc:: drivers/staging/media/ipu3/include/intel-ipu3.h +.. kernel-doc:: drivers/staging/media/ipu3/include/uapi/intel-ipu3.h diff --git a/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst b/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst new file mode 100644 index 000000000000..fa04f00bcd2e --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _v4l2-meta-fmt-rk-isp1-params: + +.. _v4l2-meta-fmt-rk-isp1-stat-3a: + +***************************************************************************** +V4L2_META_FMT_RK_ISP1_PARAMS ('rk1p'), V4L2_META_FMT_RK_ISP1_STAT_3A ('rk1s') +***************************************************************************** + +Configuration parameters +======================== + +The configuration parameters are passed to the +:ref:`rkisp1_params <rkisp1_params>` metadata output video node, using +the :c:type:`v4l2_meta_format` interface. The buffer contains +a single instance of the C structure :c:type:`rkisp1_params_cfg` defined in +``rkisp1-config.h``. So the structure can be obtained from the buffer by: + +.. code-block:: c + + struct rkisp1_params_cfg *params = (struct rkisp1_params_cfg*) buffer; + +.. rkisp1_stat_buffer + +3A and histogram statistics +=========================== + +The ISP1 device collects different statistics over an input Bayer frame. +Those statistics are obtained from the :ref:`rkisp1_stats <rkisp1_stats>` +metadata capture video node, +using the :c:type:`v4l2_meta_format` interface. The buffer contains a single +instance of the C structure :c:type:`rkisp1_stat_buffer` defined in +``rkisp1-config.h``. So the structure can be obtained from the buffer by: + +.. code-block:: c + + struct rkisp1_stat_buffer *stats = (struct rkisp1_stat_buffer*) buffer; + +The statistics collected are Exposure, AWB (Auto-white balance), Histogram and +AF (Auto-focus). See :c:type:`rkisp1_stat_buffer` for details of the statistics. + +The 3A statistics and configuration parameters described here are usually +consumed and produced by dedicated user space libraries that comprise the +important tuning tools using software control loop. + +rkisp1 uAPI data types +====================== + +.. kernel-doc:: include/uapi/linux/rkisp1-config.h diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-uvc.rst b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst index debc50285a25..784346d14bbd 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-uvc.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-uvc: diff --git a/Documentation/userspace-api/media/v4l/metafmt-vivid.rst b/Documentation/userspace-api/media/v4l/metafmt-vivid.rst new file mode 100644 index 000000000000..7173e2c3e245 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-vivid.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _v4l2-meta-fmt-vivid: + +******************************* +V4L2_META_FMT_VIVID ('VIVD') +******************************* + +VIVID Metadata Format + + +Description +=========== + +This describes metadata format used by the vivid driver. + +It sets Brightness, Saturation, Contrast and Hue, each of which maps to +corresponding controls of the vivid driver with respect to the range and default values. + +It contains the following fields: + +.. flat-table:: VIVID Metadata + :widths: 1 4 + :header-rows: 1 + :stub-columns: 0 + + * - Field + - Description + * - u16 brightness; + - Image brightness, the value is in the range 0 to 255, with the default value as 128. + * - u16 contrast; + - Image contrast, the value is in the range 0 to 255, with the default value as 128. + * - u16 saturation; + - Image color saturation, the value is in the range 0 to 255, with the default value as 128. + * - s16 hue; + - Image color balance, the value is in the range -128 to 128, with the default value as 0. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgo.rst b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst index b780e447dd4b..8d886feb180c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgo.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-vsp1-hgo: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgt.rst b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst index e165320cc1ff..d8830ff605de 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgt.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-vsp1-hgt: diff --git a/Documentation/userspace-api/media/v4l/mmap.rst b/Documentation/userspace-api/media/v4l/mmap.rst index 9c44d05ebc3f..a5672573dd6f 100644 --- a/Documentation/userspace-api/media/v4l/mmap.rst +++ b/Documentation/userspace-api/media/v4l/mmap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _mmap: @@ -42,22 +36,22 @@ This ioctl can also be used to change the number of buffers or to free the allocated memory, provided none of the buffers are still mapped. Before applications can access the buffers they must map them into their -address space with the :ref:`mmap() <func-mmap>` function. The +address space with the :c:func:`mmap()` function. The location of the buffers in device memory can be determined with the :ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar API case, the ``m.offset`` and ``length`` returned in a struct :c:type:`v4l2_buffer` are passed as sixth and second -parameter to the :ref:`mmap() <func-mmap>` function. When using the +parameter to the :c:func:`mmap()` function. When using the multi-planar API, struct :c:type:`v4l2_buffer` contains an array of struct :c:type:`v4l2_plane` structures, each containing its own ``m.offset`` and ``length``. When using the multi-planar API, every plane of every buffer has to be mapped -separately, so the number of calls to :ref:`mmap() <func-mmap>` should +separately, so the number of calls to :c:func:`mmap()` should be equal to number of buffers times number of planes in each buffer. The offset and length values must not be modified. Remember, the buffers are allocated in physical memory, as opposed to virtual memory, which can be swapped out to disk. Applications should free the buffers as soon as -possible with the :ref:`munmap() <func-munmap>` function. +possible with the :c:func:`munmap()` function. Example: Mapping buffers in the single-planar API ================================================= @@ -129,7 +123,6 @@ Example: Mapping buffers in the single-planar API for (i = 0; i < reqbuf.count; i++) munmap(buffers[i].start, buffers[i].length); - Example: Mapping buffers in the multi-planar API ================================================ @@ -239,16 +232,16 @@ In the write loop, when the application runs out of free buffers, it must wait until an empty buffer can be dequeued and reused. To enqueue and dequeue a buffer applications use the -:ref:`VIVIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer being mapped, enqueued, full or empty can be determined at any time using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` -flag was given to the :ref:`open() <func-open>` function, +flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` -error code when no buffer is available. The :ref:`select() <func-select>` -or :ref:`poll() <func-poll>` functions are always available. +error code when no buffer is available. The :c:func:`select()` +or :c:func:`poll()` functions are always available. To start and stop capturing or output applications call the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF @@ -266,15 +259,15 @@ Drivers implementing memory mapping I/O must support the <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap() -<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select() -<func-select>` and :ref:`poll() <func-poll>` function. [#f3]_ +<func-mmap>`, :c:func:`munmap()`, :ref:`select() +<func-select>` and :c:func:`poll()` function. [#f3]_ [capture example] .. [#f1] One could use one file descriptor and set the buffer type field accordingly when calling :ref:`VIDIOC_QBUF` etc., - but it makes the :ref:`select() <func-select>` function ambiguous. We also + but it makes the :c:func:`select()` function ambiguous. We also like the clean approach of one file descriptor per logical stream. Video overlay for example is also a logical stream, although the CPU is not needed for continuous operation. @@ -287,6 +280,6 @@ and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap() scatter-gather lists and the like. .. [#f3] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. The rest should be evident. diff --git a/Documentation/userspace-api/media/v4l/nv12mt.svg b/Documentation/userspace-api/media/v4l/nv12mt.svg index d4bb4eb83f6a..30a15b5470be 100644 --- a/Documentation/userspace-api/media/v4l/nv12mt.svg +++ b/Documentation/userspace-api/media/v4l/nv12mt.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/nv12mt_example.svg b/Documentation/userspace-api/media/v4l/nv12mt_example.svg index e5075af9f45a..d1e2023f4973 100644 --- a/Documentation/userspace-api/media/v4l/nv12mt_example.svg +++ b/Documentation/userspace-api/media/v4l/nv12mt_example.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst index 38046ef20141..18bfb9b8137d 100644 --- a/Documentation/userspace-api/media/v4l/open.rst +++ b/Documentation/userspace-api/media/v4l/open.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _open: @@ -13,22 +7,105 @@ Opening and Closing Devices *************************** +.. _v4l2_hardware_control: -Device Naming -============= +Controlling a hardware peripheral via V4L2 +========================================== + +Hardware that is supported using the V4L2 uAPI often consists of multiple +devices or peripherals, each of which have their own driver. + +The bridge driver exposes one or more V4L2 device nodes +(see :ref:`v4l2_device_naming`). + +There are other drivers providing support for other components of +the hardware, which may also expose device nodes, called V4L2 sub-devices. + +When such V4L2 sub-devices are exposed, they allow controlling those +other hardware components - usually connected via a serial bus (like +I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices +can be controlled indirectly via the bridge driver or explicitly via +the :ref:`Media Controller <media_controller>` and via the +:ref:`V4L2 sub-devices <subdev>`. + +The devices that require the use of the +:ref:`Media Controller <media_controller>` are called **MC-centric** +devices. The devices that are fully controlled via V4L2 device nodes +are called **video-node-centric**. + +Userspace can check if a V4L2 hardware peripheral is MC-centric by +calling :ref:`VIDIOC_QUERYCAP` and checking the +:ref:`device_caps field <device-capabilities>`. + +If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``, +then it is MC-centric, otherwise, it is video-node-centric. + +It is required for MC-centric drivers to identify the V4L2 +sub-devices and to configure the pipelines via the +:ref:`media controller API <media_controller>` before using the peripheral. +Also, the sub-devices' configuration shall be controlled via the +:ref:`sub-device API <subdev>`. + +.. note:: + + A video-node-centric may still provide media-controller and + sub-device interfaces as well. + + However, in that case the media-controller and the sub-device + interfaces are read-only and just provide information about the + device. The actual configuration is done via the video nodes. + +.. _v4l2_device_naming: + +V4L2 Device Node Naming +======================= V4L2 drivers are implemented as kernel modules, loaded manually by the system administrator or automatically when a device is first discovered. -The driver modules plug into the "videodev" kernel module. It provides +The driver modules plug into the ``videodev`` kernel module. It provides helper functions and a common application interface specified in this document. Each driver thus loaded registers one or more device nodes with major -number 81 and a minor number between 0 and 255. Minor numbers are -allocated dynamically unless the kernel is compiled with the kernel -option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers -are allocated in ranges depending on the device node type (video, radio, -etc.). +number 81. Minor numbers are allocated dynamically unless the kernel +is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES. +In that case minor numbers are allocated in ranges depending on the +device node type. + +The device nodes supported by the Video4Linux subsystem are: + +======================== ==================================================== +Default device node name Usage +======================== ==================================================== +``/dev/videoX`` Video and metadata for capture/output devices +``/dev/vbiX`` Vertical blank data (i.e. closed captions, teletext) +``/dev/radioX`` Radio tuners and modulators +``/dev/swradioX`` Software Defined Radio tuners and modulators +``/dev/v4l-touchX`` Touch sensors +``/dev/v4l-subdevX`` Video sub-devices (used by sensors and other + components of the hardware peripheral)\ [#]_ +======================== ==================================================== + +Where ``X`` is a non-negative integer. + +.. note:: + + 1. The actual device node name is system-dependent, as udev rules may apply. + 2. There is no guarantee that ``X`` will remain the same for the same + device, as the number depends on the device driver's probe order. + If you need an unique name, udev default rules produce + ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing + links that can be used uniquely to identify a V4L2 device node:: + + $ tree /dev/v4l + /dev/v4l + ├── by-id + │ └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 + └── by-path + └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0 + +.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different + set of system calls, as covered at :ref:`subdev`. Many drivers support "video_nr", "radio_nr" or "vbi_nr" module options to select specific video/radio/vbi node numbers. This allows the @@ -64,7 +141,6 @@ means applications cannot *reliably* scan for loaded or installed drivers. The user must enter a device name, or the application can try the conventional device names. - .. _related: Related Devices @@ -73,7 +149,7 @@ Related Devices Devices can support several functions. For example video capturing, VBI capturing and radio support. -The V4L2 API creates different nodes for each of these functions. +The V4L2 API creates different V4L2 device nodes for each of these functions. The V4L2 API was designed with the idea that one device node could support all functions. However, in practice this never worked: this @@ -81,19 +157,19 @@ support all functions. However, in practice this never worked: this support it and if they did it was certainly never tested. In addition, switching a device node between different functions only works when using the streaming I/O API, not with the -:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API. +:c:func:`read()`/\ :c:func:`write()` API. -Today each device node supports just one function. +Today each V4L2 device node supports just one function. Besides video input or output the hardware may also support audio sampling or playback. If so, these functions are implemented as ALSA PCM devices with optional ALSA audio mixer devices. One problem with all these devices is that the V4L2 API makes no -provisions to find these related devices. Some really complex devices -use the Media Controller (see :ref:`media_controller`) which can be -used for this purpose. But most drivers do not use it, and while some -code exists that uses sysfs to discover related devices (see +provisions to find these related V4L2 device nodes. Some really complex +hardware use the Media Controller (see :ref:`media_controller`) which can +be used for this purpose. But several drivers do not use it, and while some +code exists that uses sysfs to discover related V4L2 device nodes (see libmedia_dev in the `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git repository), there is no library yet that can provide a single API @@ -102,7 +178,6 @@ the Media Controller. If you want to work on this please write to the linux-media mailing list: `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. - Multiple Opens ============== @@ -116,8 +191,8 @@ device should not change the state of the device. [#f2]_ Once an application has allocated the memory buffers needed for streaming data (by calling the :ref:`VIDIOC_REQBUFS` or :ref:`VIDIOC_CREATE_BUFS` ioctls, or -implicitly by calling the :ref:`read() <func-read>` or -:ref:`write() <func-write>` functions) that application (filehandle) +implicitly by calling the :c:func:`read()` or +:c:func:`write()` functions) that application (filehandle) becomes the owner of the device. It is no longer allowed to make changes that would affect the buffer sizes (e.g. by calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are @@ -130,7 +205,6 @@ requested type of data, and to change related properties, to this file descriptor. Applications can request additional access privileges using the priority mechanism described in :ref:`app-pri`. - Shared Data Streams =================== @@ -139,12 +213,11 @@ the same data stream on a device by copying buffers, time multiplexing or similar means. This is better handled by a proxy application in user space. - Functions ========= To open and close V4L2 devices applications use the -:ref:`open() <func-open>` and :ref:`close() <func-close>` function, +:c:func:`open()` and :c:func:`close()` function, respectively. Devices are programmed using the :ref:`ioctl() <func-ioctl>` function as explained in the following sections. @@ -152,7 +225,7 @@ sections. .. [#f1] There are still some old and obscure drivers that have not been updated to allow for multiple opens. This implies that for such - drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code + drivers :c:func:`open()` can return an ``EBUSY`` error code when the device is already in use. .. [#f2] diff --git a/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst b/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst index be9a8385ebc1..2500413e5f43 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt-bayer: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index 3828bb79225d..806ed73ac474 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ****************** Compressed Formats @@ -14,7 +7,13 @@ Compressed Formats .. _compressed-formats: -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.8cm}|p{1.2cm}|p{10.3cm}| + +.. cssclass:: longtable .. flat-table:: Compressed Image Formats :header-rows: 1 @@ -64,18 +63,18 @@ Compressed Formats - H264 parsed slice data, including slice headers, either with or without the start code, as extracted from the H264 bitstream. This format is adapted for stateless video decoders that implement an - H264 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + H264 pipeline with the :ref:`stateless_decoder`. This pixelformat has two modifiers that must be set at least once - through the ``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE`` - and ``V4L2_CID_MPEG_VIDEO_H264_START_CODE`` controls. + through the ``V4L2_CID_STATELESS_H264_DECODE_MODE`` + and ``V4L2_CID_STATELESS_H264_START_CODE`` controls. In addition, metadata associated with the frame to decode are - required to be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``, - ``V4L2_CID_MPEG_VIDEO_H264_PPS``, - ``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX``, - ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` and - ``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS`` controls. See the - :ref:`associated Codec Control IDs <v4l2-mpeg-h264>`. Exactly - one output and one capture buffer must be provided for use + required to be passed through the ``V4L2_CID_STATELESS_H264_SPS``, + ``V4L2_CID_STATELESS_H264_PPS``, + ``V4L2_CID_STATELESS_H264_SCALING_MATRIX``, + ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` and + ``V4L2_CID_STATELESS_H264_DECODE_PARAMS`` controls. See the + :ref:`associated Codec Control IDs <v4l2-codec-stateless-h264>`. + Exactly one output and one capture buffer must be provided for use with this pixel format. The output buffer must contain the appropriate number of macroblocks to decode a full corresponding frame to the matching capture buffer. @@ -84,16 +83,16 @@ Compressed Formats 7.3.2.8 "Slice layer without partitioning RBSP syntax" and the following sections. - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. - * .. _V4L2-PIX-FMT-H263: - ``V4L2_PIX_FMT_H263`` - 'H263' - H263 video elementary stream. + * .. _V4L2-PIX-FMT-SPK: + + - ``V4L2_PIX_FMT_SPK`` + - 'SPK0' + - Sorenson Spark is an implementation of H.263 for use in Flash Video and Adobe Flash files * .. _V4L2-PIX-FMT-MPEG1: - ``V4L2_PIX_FMT_MPEG1`` @@ -118,12 +117,13 @@ Compressed Formats - 'MG2S' - MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream. This format is adapted for stateless video decoders that implement a - MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + MPEG-2 pipeline with the :ref:`stateless_decoder`. Metadata associated with the frame to decode is required to be passed - through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and - quantization matrices can optionally be specified through the - ``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION`` control. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-mpeg2>`. + through the ``V4L2_CID_STATELESS_MPEG2_SEQUENCE`` and + ``V4L2_CID_STATELESS_MPEG2_PICTURE`` controls. + Quantisation matrices can optionally be specified through the + ``V4L2_CID_STATELESS_MPEG2_QUANTISATION`` control. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-mpeg2>`. Exactly one output and one capture buffer must be provided for use with this pixel format. The output buffer must contain the appropriate number of macroblocks to decode a full corresponding frame to the matching @@ -159,22 +159,17 @@ Compressed Formats - ``V4L2_PIX_FMT_VP8_FRAME`` - 'VP8F' - - VP8 parsed frame, as extracted from the container. - This format is adapted for stateless video decoders that implement a - VP8 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + - VP8 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement an + VP8 pipeline with the :ref:`stateless_decoder`. Metadata associated with the frame to decode is required to be passed - through the ``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER`` control. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-vp8>`. + through the ``V4L2_CID_STATELESS_VP8_FRAME`` control. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-vp8>`. Exactly one output and one capture buffer must be provided for use with this pixel format. The output buffer must contain the appropriate number of macroblocks to decode a full corresponding frame to the matching capture buffer. - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. - * .. _V4L2-PIX-FMT-VP9: - ``V4L2_PIX_FMT_VP9`` @@ -182,6 +177,21 @@ Compressed Formats - VP9 compressed video frame. The encoder generates one compressed frame per buffer, and the decoder requires one compressed frame per buffer. + * .. _V4L2-PIX-FMT-VP9-FRAME: + + - ``V4L2_PIX_FMT_VP9_FRAME`` + - 'VP9F' + - VP9 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement a + VP9 pipeline with the :ref:`stateless_decoder`. + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_STATELESS_VP9_FRAME`` and + the ``V4L2_CID_STATELESS_VP9_COMPRESSED_HDR`` controls. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-vp9>`. + Exactly one output and one capture buffer must be provided for use with + this pixel format. The output buffer must contain the appropriate number + of macroblocks to decode a full corresponding frame to the matching + capture buffer. * .. _V4L2-PIX-FMT-HEVC: - ``V4L2_PIX_FMT_HEVC`` @@ -203,18 +213,13 @@ Compressed Formats through the ``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE`` and ``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE`` controls. Metadata associated with the frame to decode is required to be passed - through the following controls : - * ``V4L2_CID_MPEG_VIDEO_HEVC_SPS`` - * ``V4L2_CID_MPEG_VIDEO_HEVC_PPS`` - * ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS`` - See the :ref:`associated Codec Control IDs <v4l2-mpeg-hevc>`. + through the following controls: + ``V4L2_CID_MPEG_VIDEO_HEVC_SPS``, + ``V4L2_CID_MPEG_VIDEO_HEVC_PPS``, and + ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS``. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-hevc>`. Buffers associated with this pixel format must contain the appropriate number of macroblocks to decode a full corresponding frame. - - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. * .. _V4L2-PIX-FMT-FWHT: - ``V4L2_PIX_FMT_FWHT`` @@ -229,4 +234,46 @@ Compressed Formats - ``V4L2_PIX_FMT_FWHT_STATELESS`` - 'SFWH' - Same format as V4L2_PIX_FMT_FWHT but requires stateless codec implementation. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-fwht>`. + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_STATELESS_FWHT_PARAMS`` control. + See the :ref:`associated Codec Control ID <codec-stateless-fwht>`. + * .. _V4L2-PIX-FMT-RV30: + + - ``V4L2_PIX_FMT_RV30`` + - 'RV30' + - RealVideo, or also spelled as Real Video, is a suite of + proprietary video compression formats developed by + RealNetworks - the specific format changes with the version. + RealVideo codecs are identified by four-character codes. + RV30 corresponds to RealVideo 8, suspected to be based + largely on an early draft of H.264 + * .. _V4L2-PIX-FMT-RV40: + + - ``V4L2_PIX_FMT_RV40`` + - 'RV40' + - RV40 represents RealVideo 9 and RealVideo 10. + RealVideo 9, suspected to be based on H.264. + RealVideo 10, aka RV9 EHQ, This refers to an improved encoder + for the RV9 format that is fully backwards compatible with + RV9 players - the format and decoder did not change, only + the encoder did. As a result, it uses the same FourCC. + + * .. _V4L2-PIX-FMT-AV1-FRAME: + + - ``V4L2_PIX_FMT_AV1_FRAME`` + - 'AV1F' + - AV1 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement a AV1 + pipeline with the :ref:`stateless_decoder`. Metadata associated with the + frame to decode is required to be passed through the + ``V4L2_CID_STATELESS_AV1_SEQUENCE``, ``V4L2_CID_STATELESS_AV1_FRAME``, + and ``V4L2_CID_STATELESS_AV1_TILE_GROUP_ENTRY`` controls. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-av1>`. + Exactly one output and one capture buffer must be provided for use with + this pixel format. The output buffer must contain the appropriate number + of macroblocks to decode a full corresponding frame to the matching + capture buffer. + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst b/Documentation/userspace-api/media/v4l/pixfmt-grey.rst deleted file mode 100644 index 7b03db3393be..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-GREY: - -************************** -V4L2_PIX_FMT_GREY ('GREY') -************************** - -Grey-scale image - - -Description -=========== - -This is a grey-scale image. It is really a degenerate Y'CbCr format -which simply contains no Cb or Cr data. - -**Byte Order.** -Each cell is one byte. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst b/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst index d0d46ed27260..5bd4a47c5854 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt-indexed: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-intro.rst b/Documentation/userspace-api/media/v4l/pixfmt-intro.rst index af870895f653..14239ee826bf 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-intro.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ********************** Standard Image Formats diff --git a/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst b/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst index f85cccb71741..3115c8f6a842 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-INZI: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst index 5180bbe16c6e..c01a949e7c11 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-M420: @@ -74,60 +67,5 @@ Each cell is one byte. **Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally and vertically. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst b/Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst deleted file mode 100644 index 34a2382ef91c..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _v4l2-meta-fmt-vivid: - -******************************* -V4L2_META_FMT_VIVID ('VIVD') -******************************* - -VIVID Metadata Format - - -Description -=========== - -This describes metadata format used by the vivid driver. - -It sets Brightness, Saturation, Contrast and Hue, each of which maps to -corresponding controls of the vivid driver with respect to the range and default values. - -It contains the following fields: - -.. flat-table:: VIVID Metadata - :widths: 1 4 - :header-rows: 1 - :stub-columns: 0 - - * - Field - - Description - * - u16 brightness; - - Image brightness, the value is in the range 0 to 255, with the default value as 128. - * - u16 contrast; - - Image contrast, the value is in the range 0 to 255, with the default value as 128. - * - u16 saturation; - - Image color saturation, the value is in the range 0 to 255, with the default value as 128. - * - s16 hue; - - Image color balance, the value is in the range -128 to 128, with the default value as 0. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst deleted file mode 100644 index 19d47b38e02a..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV12: -.. _V4L2-PIX-FMT-NV21: - -****************************************************** -V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21') -****************************************************** - - -V4L2_PIX_FMT_NV21 -Formats with ½ horizontal and vertical chroma resolution, also known as -YUV 4:2:0. One luminance and one chrominance plane with alternating -chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:2:0 format. The three -components are separated into two sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a -combined CbCr plane immediately follows the Y plane in memory. The CbCr -plane is the same width, in bytes, as the Y plane (and of the image), -but is half as tall in pixels. Each CbCr pair belongs to four pixels. -For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is -the same except the Cb and Cr bytes are swapped, the CrCb plane starts -with a Cr byte. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start + 20: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst deleted file mode 100644 index 115ea603c13f..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV12M: -.. _v4l2-pix-fmt-nv12mt-16x16: -.. _V4L2-PIX-FMT-NV21M: - -*********************************************************************************** -V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16 -*********************************************************************************** - - -V4L2_PIX_FMT_NV21M -V4L2_PIX_FMT_NV12MT_16X16 -Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes -non contiguous in memory. - - -Description -=========== - -This is a multi-planar, two-plane version of the YUV 4:2:0 format. The -three components are separated into two sub-images or planes. -``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the -two planes are non-contiguous in memory, i.e. the chroma plane do not -necessarily immediately follows the luma plane. The luminance data -occupies the first plane. The Y plane has one byte per pixel. In the -second plane there is a chrominance data with alternating chroma -samples. The CbCr plane is the same width, in bytes, as the Y plane (and -of the image), but is half as tall in pixels. Each CbCr pair belongs to -four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to -Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. -``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of -``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are -arranged in 16x16 2D tiles and tiles are arranged in linear order in -memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M`` -except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr -byte. - -``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and -applications that support the multi-planar API, described in -:ref:`planar-apis`. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start1 + 4: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst deleted file mode 100644 index daac1c16d4f2..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV12MT: - -**************************** -V4L2_PIX_FMT_NV12MT ('TM12') -**************************** - -Formats with ½ horizontal and vertical chroma resolution. This format -has two planes - one for luminance and one for chrominance. Chroma -samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the -memory layout. Pixels are grouped in macroblocks of 64x32 size. The -order of macroblocks in memory is also not standard. - - -Description -=========== - -This is the two-plane versions of the YUV 4:2:0 format where data is -grouped into 64x32 macroblocks. The three components are separated into -two sub-images or planes. The Y plane has one byte per pixel and pixels -are grouped into 64x32 macroblocks. The CbCr plane has the same width, -in bytes, as the Y plane (and the image), but is half as tall in pixels. -The chroma plane is also grouped into 64x32 macroblocks. - -Width of the buffer has to be aligned to the multiple of 128, and height -alignment is 32. Every four adjacent buffers - two horizontally and two -vertically are grouped together and are located in memory in Z or -flipped Z order. - -Layout of macroblocks in memory is presented in the following figure. - - -.. _nv12mt: - -.. kernel-figure:: nv12mt.svg - :alt: nv12mt.svg - :align: center - - V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout - -The requirement that width is multiple of 128 is implemented because, -the Z shape cannot be cut in half horizontally. In case the vertical -resolution of macroblocks is odd then the last row of macroblocks is -arranged in a linear order. - -In case of chroma the layout is identical. Cb and Cr samples are -interleaved. Height of the buffer is aligned to 32. - - -.. _nv12mt_ex: - -.. kernel-figure:: nv12mt_example.svg - :alt: nv12mt_example.svg - :align: center - - Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks - -Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most -extreme case. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst deleted file mode 100644 index 977636fc98d6..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV16: -.. _V4L2-PIX-FMT-NV61: - -****************************************************** -V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61') -****************************************************** - -V4L2_PIX_FMT_NV61 -Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2. -One luminance and one chrominance plane with alternating chroma samples -as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:2:2 format. The three -components are separated into two sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a -combined CbCr plane immediately follows the Y plane in memory. The CbCr -plane is the same width and height, in bytes, as the Y plane (and of the -image). Each CbCr pair belongs to two pixels. For example, -Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. -``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are -swapped, the CrCb plane starts with a Cr byte. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start + 20: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - * - start + 24: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`21` - - Cr\ :sub:`21` - * - start + 28: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`31` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst deleted file mode 100644 index cf33942d942d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV16M: -.. _v4l2-pix-fmt-nv61m: - -******************************************************** -V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61') -******************************************************** - -V4L2_PIX_FMT_NV61M -Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes -non contiguous in memory. - - -Description -=========== - -This is a multi-planar, two-plane version of the YUV 4:2:2 format. The -three components are separated into two sub-images or planes. -``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the -two planes are non-contiguous in memory, i.e. the chroma plane does not -necessarily immediately follow the luma plane. The luminance data -occupies the first plane. The Y plane has one byte per pixel. In the -second plane there is chrominance data with alternating chroma samples. -The CbCr plane is the same width and height, in bytes, as the Y plane. -Each CbCr pair belongs to two pixels. For example, -Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. -``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the -Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte. - -``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`02` - - Cr\ :sub:`02` - * - start1 + 4: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`12` - - Cr\ :sub:`12` - * - start1 + 8: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`22` - - Cr\ :sub:`22` - * - start1 + 12: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`32` - - Cr\ :sub:`32` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst deleted file mode 100644 index c6fb97bd0472..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV24: -.. _V4L2-PIX-FMT-NV42: - -****************************************************** -V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42') -****************************************************** - -V4L2_PIX_FMT_NV42 -Formats with full horizontal and vertical chroma resolutions, also known -as YUV 4:4:4. One luminance and one chrominance plane with alternating -chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:4:4 format. The three -components are separated into two sub-images or planes. The Y plane is -first, with each Y sample stored in one byte per pixel. For -``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y -plane in memory. The CbCr plane has the same width and height, in -pixels, as the Y plane (and the image). Each line contains one CbCr pair -per pixel, with each Cb and Cr sample stored in one byte. -``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are -swapped, the CrCb plane starts with a Cr sample. - -If the Y plane has pad bytes after each row, then the CbCr plane has -twice as many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - - Cb\ :sub:`02` - - Cr\ :sub:`02` - - Cb\ :sub:`03` - - Cr\ :sub:`03` - * - start + 24: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - Cb\ :sub:`12` - - Cr\ :sub:`12` - - Cb\ :sub:`13` - - Cr\ :sub:`13` - * - start + 32: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`21` - - Cr\ :sub:`21` - - Cb\ :sub:`22` - - Cr\ :sub:`22` - - Cb\ :sub:`23` - - Cr\ :sub:`23` - * - start + 40: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`31` - - Cr\ :sub:`31` - - Cb\ :sub:`32` - - Cr\ :sub:`32` - - Cb\ :sub:`33` - - Cr\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst index b8c9b0225eea..dd89860f50e0 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _packed-hsv: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index bbd4bd094deb..9f111ed594d2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _packed-yuv: @@ -13,24 +6,42 @@ Packed YUV formats ****************** -Description -=========== +Similarly to the packed RGB formats, the packed YUV formats store the Y, Cb and +Cr components consecutively in memory. They may apply subsampling to the chroma +components and thus differ in how they interlave the three components. -Similar to the packed RGB formats these formats store the Y, Cb and Cr -component of each pixel in one 16 or 32 bit word. +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - 'Y', 'Cb' and 'Cr' denote bits of the luma, blue chroma (also known as + 'U') and red chroma (also known as 'V') components respectively. 'A' + denotes bits of the alpha component (if supported by the format), and 'X' + denotes padding bits. + + +4:4:4 Subsampling +================= + +These formats do not subsample the chroma components and store each pixels as a +full triplet of Y, Cb and Cr values. +The next table lists the packed YUV 4:4:4 formats with less than 8 bits per +component. They are named based on the order of the Y, Cb and Cr components as +seen in a 16-bit word, which is then stored in memory in little endian byte +order, and on the number of bits for each component. For instance the YUV565 +format stores a pixel in a 16-bit word [15:0] laid out at as [Y'\ :sub:`4-0` +Cb\ :sub:`5-0` Cr\ :sub:`4-0`], and stored in memory in two bytes, +[Cb\ :sub:`2-0` Cr\ :sub:`4-0`] followed by [Y'\ :sub:`4-0` Cb\ :sub:`5-3`]. .. raw:: latex \begingroup - \tiny + \scriptsize \setlength{\tabcolsep}{2pt} -.. _packed-yuv-formats: +.. tabularcolumns:: |p{3.5cm}|p{0.96cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}| -.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| - -.. flat-table:: Packed YUV Image Formats +.. flat-table:: Packed YUV 4:4:4 Image Formats (less than 8bpc) :header-rows: 2 :stub-columns: 0 @@ -41,10 +52,6 @@ component of each pixel in one 16 or 32 bit word. - :cspan:`7` Byte 1 - - :cspan:`7` Byte 2 - - - :cspan:`7` Byte 3 - * - - - 7 @@ -65,24 +72,6 @@ component of each pixel in one 16 or 32 bit word. - 1 - 0 - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - * .. _V4L2-PIX-FMT-YUV444: - ``V4L2_PIX_FMT_YUV444`` @@ -106,8 +95,6 @@ component of each pixel in one 16 or 32 bit word. - Y'\ :sub:`1` - Y'\ :sub:`0` - - :cspan:`15` - * .. _V4L2-PIX-FMT-YUV555: - ``V4L2_PIX_FMT_YUV555`` @@ -131,7 +118,6 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`4` - Cb\ :sub:`3` - - :cspan:`15` * .. _V4L2-PIX-FMT-YUV565: - ``V4L2_PIX_FMT_YUV565`` @@ -155,226 +141,342 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`4` - Cb\ :sub:`3` - - :cspan:`15` +.. raw:: latex - * .. _V4L2-PIX-FMT-YUV32: + \endgroup - - ``V4L2_PIX_FMT_YUV32`` - - 'YUV4' +.. note:: - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` + For the YUV444 and YUV555 formats, the value of alpha bits is undefined + when reading from the driver, ignored when writing to the driver, except + when alpha blending has been negotiated for a :ref:`Video Overlay + <overlay>` or :ref:`Video Output Overlay <osd>`. - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` +The next table lists the packed YUV 4:4:4 formats with 8 bits per component. +They are named based on the order of the Y, Cb and Cr components as stored in +memory, and on the total number of bits per pixel. For instance, the VUYX32 +format stores a pixel with Cr\ :sub:`7-0` in the first byte, Cb\ :sub:`7-0` in +the second byte and Y'\ :sub:`7-0` in the third byte. - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` +.. flat-table:: Packed YUV Image Formats (8bpc) + :header-rows: 1 + :stub-columns: 0 - * .. _V4L2-PIX-FMT-AYUV32: + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 - - ``V4L2_PIX_FMT_AYUV32`` - - 'AYUV' + * .. _V4L2-PIX-FMT-YUV32: - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` + - ``V4L2_PIX_FMT_YUV32`` + - 'YUV4' - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` + - A\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` + * .. _V4L2-PIX-FMT-AYUV32: - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - ``V4L2_PIX_FMT_AYUV32`` + - 'AYUV' + + - A\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` * .. _V4L2-PIX-FMT-XYUV32: - ``V4L2_PIX_FMT_XYUV32`` - 'XYUV' - - - - - - - - - - - - - - - - - - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` - - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - X\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` * .. _V4L2-PIX-FMT-VUYA32: - ``V4L2_PIX_FMT_VUYA32`` - 'VUYA' - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` - - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` - - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` + - Cr\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Y'\ :sub:`7-0` + - A\ :sub:`7-0` * .. _V4L2-PIX-FMT-VUYX32: - ``V4L2_PIX_FMT_VUYX32`` - 'VUYX' - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - Cr\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Y'\ :sub:`7-0` + - X\ :sub:`7-0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` + * .. _V4L2-PIX-FMT-YUVA32: + + - ``V4L2_PIX_FMT_YUVA32`` + - 'YUVA' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - A\ :sub:`7-0` + + * .. _V4L2-PIX-FMT-YUVX32: + + - ``V4L2_PIX_FMT_YUVX32`` + - 'YUVX' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - X\ :sub:`7-0` + + * .. _V4L2-PIX-FMT-YUV24: + + - ``V4L2_PIX_FMT_YUV24`` + - 'YUV3' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - -\ + +.. note:: + + - The alpha component is expected to contain a meaningful value that can be + used by drivers and applications. + - The padding bits contain undefined values that must be ignored by all + applications and drivers. + +The next table lists the packed YUV 4:4:4 formats with 12 bits per component. +Expand the bits per component to 16 bits, data in the high bits, zeros in the low bits, +arranged in little endian order, storing 1 pixel in 6 bytes. + +.. flat-table:: Packed YUV 4:4:4 Image Formats (12bpc) + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 1-0 + - Byte 3-2 + - Byte 5-4 + - Byte 7-6 + - Byte 9-8 + - Byte 11-10 + + * .. _V4L2-PIX-FMT-YUV48-12: + + - ``V4L2_PIX_FMT_YUV48_12`` + - 'Y312' + + - Y'\ :sub:`0` - Cb\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`1` + - Cr\ :sub:`1` - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` +4:2:2 Subsampling +================= + +These formats, commonly referred to as YUYV or YUY2, subsample the chroma +components horizontally by 2, storing 2 pixels in a container. The container +is 32-bits for 8-bit formats, and 64-bits for 10+-bit formats. + +The packed YUYV formats with more than 8 bits per component are stored as four +16-bit little-endian words. Each word's most significant bits contain one +component, and the least significant bits are zero padding. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + +.. flat-table:: Packed YUV 4:2:2 Formats in 32-bit container + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + - Byte 7 + * .. _V4L2-PIX-FMT-UYVY: + + - ``V4L2_PIX_FMT_UYVY`` + - 'UYVY' + + - Cb\ :sub:`0` + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`2` + - Y'\ :sub:`2` + - Cr\ :sub:`2` - Y'\ :sub:`3` + * .. _V4L2-PIX-FMT-VYUY: + + - ``V4L2_PIX_FMT_VYUY`` + - 'VYUY' + + - Cr\ :sub:`0` + - Y'\ :sub:`0` + - Cb\ :sub:`0` + - Y'\ :sub:`1` + - Cr\ :sub:`2` - Y'\ :sub:`2` + - Cb\ :sub:`2` + - Y'\ :sub:`3` + * .. _V4L2-PIX-FMT-YUYV: + + - ``V4L2_PIX_FMT_YUYV`` + - 'YUYV' + + - Y'\ :sub:`0` + - Cb\ :sub:`0` - Y'\ :sub:`1` + - Cr\ :sub:`0` + - Y'\ :sub:`2` + - Cb\ :sub:`2` + - Y'\ :sub:`3` + - Cr\ :sub:`2` + * .. _V4L2-PIX-FMT-YVYU: + + - ``V4L2_PIX_FMT_YVYU`` + - 'YVYU' + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`0` + - Y'\ :sub:`2` + - Cr\ :sub:`2` + - Y'\ :sub:`3` + - Cb\ :sub:`2` - - - - - - - - - - - - - - - - +.. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + +.. flat-table:: Packed YUV 4:2:2 Formats in 64-bit container + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Word 0 + - Word 1 + - Word 2 + - Word 3 + * .. _V4L2-PIX-FMT-Y210: + + - ``V4L2_PIX_FMT_Y210`` + - 'Y210' + + - Y'\ :sub:`0` (bits 15-6) + - Cb\ :sub:`0` (bits 15-6) + - Y'\ :sub:`1` (bits 15-6) + - Cr\ :sub:`0` (bits 15-6) + * .. _V4L2-PIX-FMT-Y212: + + - ``V4L2_PIX_FMT_Y212`` + - 'Y212' + + - Y'\ :sub:`0` (bits 15-4) + - Cb\ :sub:`0` (bits 15-4) + - Y'\ :sub:`1` (bits 15-4) + - Cr\ :sub:`0` (bits 15-4) + * .. _V4L2-PIX-FMT-Y216: + + - ``V4L2_PIX_FMT_Y216`` + - 'Y216' + + - Y'\ :sub:`0` (bits 15-0) + - Cb\ :sub:`0` (bits 15-0) + - Y'\ :sub:`1` (bits 15-0) + - Cr\ :sub:`0` (bits 15-0) .. raw:: latex - \endgroup + \normalsize + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + + +4:1:1 Subsampling +================= + +This format subsamples the chroma components horizontally by 4, storing 8 +pixels in 12 bytes. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{2.9cm}|p{0.8cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}| + +.. flat-table:: Packed YUV 4:1:1 Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + - Byte 7 + - Byte 8 + - Byte 9 + - Byte 10 + - Byte 11 + * .. _V4L2-PIX-FMT-Y41P: + + - ``V4L2_PIX_FMT_Y41P`` + - 'Y41P' + + - Cb\ :sub:`0` + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`4` + - Y'\ :sub:`2` + - Cr\ :sub:`4` + - Y'\ :sub:`3` + - Y'\ :sub:`4` + - Y'\ :sub:`5` + - Y'\ :sub:`6` + - Y'\ :sub:`7` + +.. raw:: latex + + \normalsize .. note:: - #) Bit 7 is the most significant bit; + Do not confuse ``V4L2_PIX_FMT_Y41P`` with + :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived from + "YUV 4:1:1 **packed**", while YUV411P stands for "YUV 4:1:1 **planar**". - #) The value of a = alpha bits is undefined when reading from the driver, - ignored when writing to the driver, except when alpha blending has - been negotiated for a :ref:`Video Overlay <overlay>` or - :ref:`Video Output Overlay <osd>` for the formats Y444, YUV555 and - YUV4. However, for formats AYUV32 and VUYA32, the alpha component is - expected to contain a meaningful value that can be used by drivers - and applications. And, the formats XYUV32 and VUYX32 contain undefined - alpha values that must be ignored by all applications and drivers. +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index 59b9e7238f90..886ba7b08d6b 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt-reserved: @@ -24,7 +17,11 @@ you think your format should be listed in a standard format section please make a proposal on the linux-media mailing list. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. raw:: latex + + \small .. _reserved-formats: @@ -51,14 +48,6 @@ please make a proposal on the linux-media mailing list. - ``V4L2_PIX_FMT_HI240`` - 'HI24' - 8 bit RGB format used by the BTTV driver. - * .. _V4L2-PIX-FMT-HM12: - - - ``V4L2_PIX_FMT_HM12`` - - 'HM12' - - YUV 4:2:0 format used by the IVTV driver. - - The format is documented in the kernel sources in the file - ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst`` * .. _V4L2-PIX-FMT-CPIA1: - ``V4L2_PIX_FMT_CPIA1`` @@ -244,39 +233,68 @@ please make a proposal on the linux-media mailing list. - ``V4L2_PIX_FMT_MT21C`` - 'MT21' - - Compressed two-planar YVU420 format used by Mediatek MT8173. - The compression is lossless. - It is an opaque intermediate format and the MDP hardware must be + - Compressed two-planar YVU420 format used by Mediatek MT8173, MT8192, + MT8195 and more. The compression is lossless. This format have + similitude with ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. + It remains an opaque intermediate format and the MDP hardware must be used to convert ``V4L2_PIX_FMT_MT21C`` to ``V4L2_PIX_FMT_NV12M``, ``V4L2_PIX_FMT_YUV420M`` or ``V4L2_PIX_FMT_YVU420``. - * .. _V4L2-PIX-FMT-SUNXI-TILED-NV12: - - - ``V4L2_PIX_FMT_SUNXI_TILED_NV12`` - - 'ST12' - - Two-planar NV12-based format used by the video engine found on Allwinner - (codenamed sunxi) platforms, with 32x32 tiles for the luminance plane - and 32x64 tiles for the chrominance plane. The data in each tile is - stored in linear order, within the tile bounds. Each tile follows the - previous one linearly in memory (from left to right, top to bottom). - - The associated buffer dimensions are aligned to match an integer number - of tiles, resulting in 32-aligned resolutions for the luminance plane - and 16-aligned resolutions for the chrominance plane (with 2x2 - subsampling). - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _format-flags: - -.. flat-table:: Format Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA`` - - 0x00000001 - - The color values are premultiplied by the alpha channel value. For - example, if a light blue pixel with 50% transparency was described - by RGBA values (128, 192, 255, 128), the same pixel described with - premultiplied colors would be described by RGBA values (64, 96, - 128, 128) + * .. _V4L2-PIX-FMT-QC08C: + + - ``V4L2_PIX_FMT_QC08C`` + - 'QC08C' + - Compressed Macro-tile 8-Bit YUV420 format used by Qualcomm platforms. + It is an opaque intermediate format. The used compression is lossless + and it is used by various multimedia hardware blocks like GPU, display + controllers, ISP and video accelerators. + It contains four planes for progressive video and eight planes for + interlaced video. + * .. _V4L2-PIX-FMT-QC10C: + + - ``V4L2_PIX_FMT_QC10C`` + - 'QC10C' + - Compressed Macro-tile 10-Bit YUV420 format used by Qualcomm platforms. + It is an opaque intermediate format. The used compression is lossless + and it is used by various multimedia hardware blocks like GPU, display + controllers, ISP and video accelerators. + It contains four planes for progressive video. + * .. _V4L2-PIX-FMT-AJPG: + + - ``V4L2_PIX_FMT_AJPG`` + - 'AJPG' + - ASPEED JPEG format used by the aspeed-video driver on Aspeed platforms, + which is generally adapted for remote KVM. + On each frame compression, I will compare the new frame with previous + one to decide which macroblock's data is changed, and only the changed + macroblocks will be compressed. + + The implementation is based on AST2600 A3 datasheet, revision 0.9, which + is not publicly available. Or you can reference Video stream data format + – ASPEED mode compression of SDK_User_Guide which available on + `github <https://github.com/AspeedTech-BMC/openbmc/releases/>`__. + + Decoder's implementation can be found here, + `aspeed_codec <https://github.com/AspeedTech-BMC/aspeed_codec/>`__ + * .. _V4L2-PIX-FMT-MT2110T: + + - ``V4L2_PIX_FMT_MT2110T`` + - 'MT2110T' + - This format is two-planar 10-Bit tile mode and having similitude with + ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. Used for VP9, AV1 + and HEVC. + * .. _V4L2-PIX-FMT-MT2110R: + + - ``V4L2_PIX_FMT_MT2110R`` + - 'MT2110R' + - This format is two-planar 10-Bit raster mode and having similitude with + ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. Used for AVC. + * .. _V4L2-PIX-FMT-HEXTILE: + + - ``V4L2_PIX_FMT_HEXTILE`` + - 'HXTL' + - Compressed format used by Nuvoton NPCM video driver. This format is + defined in Remote Framebuffer Protocol (RFC 6143, chapter 7.7.4 Hextile + Encoding). +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 89cc2a37b285..b71b80d634d6 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt-rgb: @@ -13,13 +6,62 @@ RGB Formats *********** -Description -=========== - -These formats are designed to match the pixel formats of typical PC -graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel. -These are all packed-pixel formats, meaning all the data for a pixel lie -next to each other in memory. +These formats encode each pixel as a triplet of RGB values. They are packed +formats, meaning that the RGB values for one pixel are stored consecutively in +memory and each pixel consumes an integer number of bytes. When the number of +bits required to store a pixel is not aligned to a byte boundary, the data is +padded with additional bits to fill the remaining byte. + +The formats differ by the number of bits per RGB component (typically but not +always the same for all components), the order of components in memory, and the +presence of an alpha component or additional padding bits. + +The usage and value of the alpha bits in formats that support them (named ARGB +or a permutation thereof, collectively referred to as alpha formats) depend on +the device type and hardware operation. :ref:`Capture <capture>` devices +(including capture queues of mem-to-mem devices) fill the alpha component in +memory. When the device captures an alpha channel the alpha component will have +a meaningful value. Otherwise, when the device doesn't capture an alpha channel +but can set the alpha bit to a user-configurable value, the +:ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control is used to +specify that alpha value, and the alpha component of all pixels will be set to +the value specified by that control. Otherwise a corresponding format without +an alpha component (XRGB or XBGR) must be used instead of an alpha format. + +:ref:`Output <output>` devices (including output queues of mem-to-mem devices +and :ref:`video output overlay <osd>` devices) read the alpha component from +memory. When the device processes the alpha channel the alpha component must be +filled with meaningful values by applications. Otherwise a corresponding format +without an alpha component (XRGB or XBGR) must be used instead of an alpha +format. + +Formats that contain padding bits are named XRGB (or a permutation thereof). +The padding bits contain undefined values and must be ignored by applications, +devices and drivers, for both :ref:`capture` and :ref:`output` devices. + +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - 'r', 'g' and 'b' denote bits of the red, green and blue components + respectively. 'a' denotes bits of the alpha component (if supported by the + format), and 'x' denotes padding bits. + + +Less Than 8 Bits Per Component +============================== + +These formats store an RGB triplet in one, two or four bytes. They are named +based on the order of the RGB components as seen in a 8-, 16- or 32-bit word, +which is then stored in memory in little endian byte order (unless otherwise +noted by the presence of bit 31 in the 4CC value), and on the number of bits +for each component. For instance, the RGB565 format stores a pixel in a 16-bit +word [15:0] laid out at as [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2` G\ :sub:`1` +G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`], and +stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2` +G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` +B\ :sub:`0`]. .. raw:: latex @@ -30,7 +72,7 @@ next to each other in memory. .. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| -.. flat-table:: RGB Image Formats +.. flat-table:: RGB Formats With Less Than 8 Bits Per Component :header-rows: 2 :stub-columns: 0 @@ -128,10 +170,10 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - r\ :sub:`3` - r\ :sub:`2` - r\ :sub:`1` @@ -169,10 +211,10 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - r\ :sub:`3` - r\ :sub:`2` @@ -220,10 +262,10 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` @@ -261,10 +303,10 @@ next to each other in memory. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - b\ :sub:`3` - b\ :sub:`2` @@ -312,7 +354,7 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` @@ -356,7 +398,7 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` @@ -404,7 +446,7 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - - `-` + - x - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` @@ -448,7 +490,7 @@ next to each other in memory. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - - `-` + - x - b\ :sub:`4` - b\ :sub:`3` @@ -510,7 +552,7 @@ next to each other in memory. - ``V4L2_PIX_FMT_XRGB555X`` - 'XR15' | (1 << 31) - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` @@ -551,332 +593,325 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - * .. _V4L2-PIX-FMT-BGR24: + * .. _V4L2-PIX-FMT-BGR666: - - ``V4L2_PIX_FMT_BGR24`` - - 'BGR3' + - ``V4L2_PIX_FMT_BGR666`` + - 'BGRH' - - b\ :sub:`7` - - b\ :sub:`6` - b\ :sub:`5` - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` + - g\ :sub:`3` - g\ :sub:`2` - g\ :sub:`1` - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` + - r\ :sub:`1` - r\ :sub:`0` + - x + - x + - x + - x + - x + - x + + - x + - x + - x + - x + - x + - x + - x + - x + +.. raw:: latex + + \endgroup + + +8 Bits Per Component +==================== + +These formats store an RGB triplet in three or four bytes. They are named based +on the order of the RGB components as stored in memory, and on the total number +of bits per pixel. For instance, RGB24 format stores a pixel with [R\ :sub:`7` +R\ :sub:`6` R\ :sub:`5` R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0`] in the first byte, [G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` +G\ :sub:`3` G\ :sub:`2` G\ :sub:`1` G\ :sub:`0`] in the second byte and +[B\ :sub:`7` B\ :sub:`6` B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` +B\ :sub:`1` B\ :sub:`0`] in the third byte. This differs from the DRM format +nomenclature that instead use the order of components as seen in a 24- or +32-bit little endian word. + +.. raw:: latex + + \small + +.. flat-table:: RGB Formats With 8 Bits Per Component + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 in memory + - Byte 1 + - Byte 2 + - Byte 3 + * .. _V4L2-PIX-FMT-BGR24: + + - ``V4L2_PIX_FMT_BGR24`` + - 'BGR3' + + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` - * .. _V4L2-PIX-FMT-RGB24: - ``V4L2_PIX_FMT_RGB24`` - 'RGB3' - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - + * .. _V4L2-PIX-FMT-ABGR32: - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + - ``V4L2_PIX_FMT_ABGR32`` + - 'AR24' - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGR666: + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + - A\ :sub:`7-0` + * .. _V4L2-PIX-FMT-XBGR32: - - ``V4L2_PIX_FMT_BGR666`` - - 'BGRH' + - ``V4L2_PIX_FMT_XBGR32`` + - 'XR24' - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + - X\ :sub:`7-0` + * .. _V4L2-PIX-FMT-BGRA32: - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` + - ``V4L2_PIX_FMT_BGRA32`` + - 'RA24' - - r\ :sub:`1` - - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - * .. _V4L2-PIX-FMT-ABGR32: + - A\ :sub:`7-0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + * .. _V4L2-PIX-FMT-BGRX32: - - ``V4L2_PIX_FMT_ABGR32`` - - 'AR24' + - ``V4L2_PIX_FMT_BGRX32`` + - 'RX24' - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` + - X\ :sub:`7-0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + * .. _V4L2-PIX-FMT-RGBA32: - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + - ``V4L2_PIX_FMT_RGBA32`` + - 'AB24' - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - A\ :sub:`7-0` + * .. _V4L2-PIX-FMT-RGBX32: - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-XBGR32: + - ``V4L2_PIX_FMT_RGBX32`` + - 'XB24' - - ``V4L2_PIX_FMT_XBGR32`` - - 'XR24' + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - X\ :sub:`7-0` + * .. _V4L2-PIX-FMT-ARGB32: + + - ``V4L2_PIX_FMT_ARGB32`` + - 'BA24' + + - A\ :sub:`7-0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + * .. _V4L2-PIX-FMT-XRGB32: + + - ``V4L2_PIX_FMT_XRGB32`` + - 'BX24' + + - X\ :sub:`7-0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + +.. raw:: latex + + \normalsize + + +10 Bits Per Component +===================== + +These formats store a 30-bit RGB triplet with an optional 2 bit alpha in four +bytes. They are named based on the order of the RGB components as seen in a +32-bit word, which is then stored in memory in little endian byte order +(unless otherwise noted by the presence of bit 31 in the 4CC value), and on the +number of bits for each component. + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{3.2cm}|p{0.8cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + + +.. flat-table:: RGB Formats 10 Bits Per Color Component + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - :cspan:`7` Byte 0 in memory + - :cspan:`7` Byte 1 + - :cspan:`7` Byte 2 + - :cspan:`7` Byte 3 + * - + - + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _V4L2-PIX-FMT-RGBX1010102: + + - ``V4L2_PIX_FMT_RGBX1010102`` + - 'RX30' - - b\ :sub:`7` - - b\ :sub:`6` - b\ :sub:`5` - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + - x + - x - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - g\ :sub:`3` - g\ :sub:`2` - g\ :sub:`1` - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - * .. _V4L2-PIX-FMT-BGRA32: - - - ``V4L2_PIX_FMT_BGRA32`` - - 'RA24' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - + - b\ :sub:`9` + - b\ :sub:`8` - b\ :sub:`7` - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + - r\ :sub:`9` + - r\ :sub:`8` - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - * .. _V4L2-PIX-FMT-BGRX32: + * .. _V4L2-PIX-FMT-RGBA1010102: - - ``V4L2_PIX_FMT_BGRX32`` - - 'RX24' - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` + - ``V4L2_PIX_FMT_RGBA1010102`` + - 'RA30' - - b\ :sub:`7` - - b\ :sub:`6` - b\ :sub:`5` - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + - a\ :sub:`1` + - a\ :sub:`0` - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - g\ :sub:`3` - g\ :sub:`2` - g\ :sub:`1` - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - * .. _V4L2-PIX-FMT-RGBA32: - - - ``V4L2_PIX_FMT_RGBA32`` - - 'AB24' - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - + - g\ :sub:`9` + - g\ :sub:`8` - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-RGBX32: - - - ``V4L2_PIX_FMT_RGBX32`` - - 'XB24' + - r\ :sub:`9` + - r\ :sub:`8` - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` + * .. _V4L2-PIX-FMT-ARGB2101010: - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + - ``V4L2_PIX_FMT_ARGB2101010`` + - 'AR30' - b\ :sub:`7` - b\ :sub:`6` @@ -887,202 +922,87 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - * .. _V4L2-PIX-FMT-ARGB32: - - - ``V4L2_PIX_FMT_ARGB32`` - - 'BA24' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` - g\ :sub:`3` - g\ :sub:`2` - g\ :sub:`1` - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - * .. _V4L2-PIX-FMT-XRGB32: - - - ``V4L2_PIX_FMT_XRGB32`` - - 'BX24' - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - + - g\ :sub:`9` + - g\ :sub:`8` - g\ :sub:`7` - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` + - a\ :sub:`1` + - a\ :sub:`0` + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` .. raw:: latex \endgroup -.. note:: Bit 7 is the most significant bit. - -The usage and value of the alpha bits (a) in the ARGB and ABGR formats -(collectively referred to as alpha formats) depend on the device type -and hardware operation. :ref:`Capture <capture>` devices (including -capture queues of mem-to-mem devices) fill the alpha component in -memory. When the device outputs an alpha channel the alpha component -will have a meaningful value. Otherwise, when the device doesn't output -an alpha channel but can set the alpha bit to a user-configurable value, -the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control -is used to specify that alpha value, and the alpha component of all -pixels will be set to the value specified by that control. Otherwise a -corresponding format without an alpha component (XRGB or XBGR) must be -used instead of an alpha format. - -:ref:`Output <output>` devices (including output queues of mem-to-mem -devices and :ref:`video output overlay <osd>` devices) read the alpha -component from memory. When the device processes the alpha channel the -alpha component must be filled with meaningful values by applications. -Otherwise a corresponding format without an alpha component (XRGB or -XBGR) must be used instead of an alpha format. - -The XRGB and XBGR formats contain undefined bits (-). Applications, -devices and drivers must ignore those bits, for both -:ref:`capture` and :ref:`output` devices. - -**Byte Order.** -Each cell is one byte. +12 Bits Per Component +============================== +These formats store an RGB triplet in six or eight bytes, with 12 bits per component. +Expand the bits per component to 16 bits, data in the high bits, zeros in the low bits, +arranged in little endian order. .. raw:: latex \small -.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| +.. flat-table:: RGB Formats With 12 Bits Per Component + :header-rows: 1 -.. flat-table:: RGB byte order - :header-rows: 0 - :stub-columns: 0 - :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3 - - * - start + 0: - - B\ :sub:`00` - - G\ :sub:`00` - - R\ :sub:`00` - - B\ :sub:`01` - - G\ :sub:`01` - - R\ :sub:`01` - - B\ :sub:`02` - - G\ :sub:`02` - - R\ :sub:`02` - - B\ :sub:`03` - - G\ :sub:`03` - - R\ :sub:`03` - * - start + 12: - - B\ :sub:`10` - - G\ :sub:`10` - - R\ :sub:`10` - - B\ :sub:`11` - - G\ :sub:`11` - - R\ :sub:`11` - - B\ :sub:`12` - - G\ :sub:`12` - - R\ :sub:`12` - - B\ :sub:`13` - - G\ :sub:`13` - - R\ :sub:`13` - * - start + 24: - - B\ :sub:`20` - - G\ :sub:`20` - - R\ :sub:`20` - - B\ :sub:`21` - - G\ :sub:`21` - - R\ :sub:`21` - - B\ :sub:`22` - - G\ :sub:`22` - - R\ :sub:`22` - - B\ :sub:`23` - - G\ :sub:`23` - - R\ :sub:`23` - * - start + 36: - - B\ :sub:`30` - - G\ :sub:`30` - - R\ :sub:`30` - - B\ :sub:`31` - - G\ :sub:`31` - - R\ :sub:`31` - - B\ :sub:`32` - - G\ :sub:`32` - - R\ :sub:`32` - - B\ :sub:`33` - - G\ :sub:`33` - - R\ :sub:`33` + * - Identifier + - Code + - Byte 1-0 + - Byte 3-2 + - Byte 5-4 + - Byte 7-6 + * .. _V4L2-PIX-FMT-BGR48-12: + + - ``V4L2_PIX_FMT_BGR48_12`` + - 'B312' + + - B\ :sub:`15-4` + - G\ :sub:`15-4` + - R\ :sub:`15-4` + - + * .. _V4L2-PIX-FMT-ABGR64-12: + + - ``V4L2_PIX_FMT_ABGR64_12`` + - 'B412' + + - B\ :sub:`15-4` + - G\ :sub:`15-4` + - R\ :sub:`15-4` + - A\ :sub:`15-4` .. raw:: latex \normalsize -Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and -must not be used by new drivers. They are documented here for reference. -The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in -either the corresponding ARGB or XRGB format, depending on the driver. +Deprecated RGB Formats +====================== +Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and must not be +used by new drivers. They are documented here for reference. The meaning of +their alpha bits ``(a)`` is ill-defined and they are interpreted as in either +the corresponding ARGB or XRGB format, depending on the driver. .. raw:: latex diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst index 13f3908d162a..bd6ee6111de4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-sdr-fmt-cs8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst index 41e5b990d499..ea21b288d357 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-CS14LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst index 1085b5ad8eb7..45fce09d85ff 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-sdr-fmt-cu8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst index 9772b30bda95..7f4242f8da6f 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-CU16LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst index 53a0a862f33a..a4d4b70ece63 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-PCU16BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst index 7f2d2545fb04..3db690bd683a 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-PCU18BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst index 9f3d67b4e94c..485343cdf150 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-PCU20BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst index c9cde8d425f7..2ad4706bfc7a 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-RU12LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst index 5afa02a66698..3322b0600f1d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-pix-fmt-ipu3-sbggr10: .. _v4l2-pix-fmt-ipu3-sgbrg10: @@ -16,7 +9,9 @@ V4L2_PIX_FMT_IPU3_SBGGR10 ('ip3b'), V4L2_PIX_FMT_IPU3_SGBRG10 ('ip3g'), V4L2_PIX_FMT_IPU3_SGRBG10 ('ip3G'), V4L2_PIX_FMT_IPU3_SRGGB10 ('ip3r') ********************************************************************************************************************************************** +==================== 10-bit Bayer formats +==================== Description =========== @@ -32,7 +27,11 @@ Below is an example of a small image in V4L2_PIX_FMT_IPU3_SBGGR10 format. **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{0.8cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| .. flat-table:: @@ -340,3 +339,7 @@ Each cell is one byte. - R\ :sub:`0323high` - G\ :sub:`0324low` - G\ :sub:`0324high`\ (bits 1--0) + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst index 37cc1bb8241f..a66414ab4291 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB10: .. _v4l2-pix-fmt-sbggr10: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst index f1b8627f0141..a5ae1f099e68 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SBGGR10ALAW8: .. _v4l2-pix-fmt-sgbrg10alaw8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst index 9814c4ffac68..f0544c6f4580 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SBGGR10DPCM8: .. _v4l2-pix-fmt-sgbrg10dpcm8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst index 76a4d278e640..fd5feb415531 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB10P: .. _v4l2-pix-fmt-sbggr10p: @@ -40,7 +33,7 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| +.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst index 98ae80b968ae..15c34e1e4835 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB12: .. _v4l2-pix-fmt-sbggr12: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst index 7309dd7fa60f..7c3810ff783c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB12P: .. _v4l2-pix-fmt-sbggr12p: @@ -38,7 +31,7 @@ Below is an example of a small V4L2_PIX_FMT_SBGGR12P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}| +.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| .. flat-table:: @@ -67,7 +60,7 @@ Each cell is one byte. G\ :sub:`10low`\ (bits 3--0) - G\ :sub:`12high` - R\ :sub:`13high` - - R\ :sub:`13low`\ (bits 3--2) + - R\ :sub:`13low`\ (bits 7--4) G\ :sub:`12low`\ (bits 3--0) - - start + 12: @@ -89,6 +82,6 @@ Each cell is one byte. G\ :sub:`30low`\ (bits 3--0) - G\ :sub:`32high` - R\ :sub:`33high` - - R\ :sub:`33low`\ (bits 3--2) + - R\ :sub:`33low`\ (bits 7--4) G\ :sub:`32low`\ (bits 3--0) diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst index a4c7a392fe7f..4f5120a6c678 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB14: .. _v4l2-pix-fmt-sbggr14: @@ -18,7 +11,9 @@ V4L2_PIX_FMT_SRGGB14 ('RG14'), V4L2_PIX_FMT_SGRBG14 ('GR14'), V4L2_PIX_FMT_SGBRG *************************************************************************************************************************** +======================================== 14-bit Bayer formats expanded to 16 bits +======================================== Description diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst index ec1239ada316..3572e42adb22 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB14P: .. _v4l2-pix-fmt-sbggr14p: @@ -43,9 +36,11 @@ Each cell is one byte. .. raw:: latex + \begingroup \footnotesize + \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{1.8cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.1cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| +.. tabularcolumns:: |p{1.6cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{3.5cm}|p{3.5cm}|p{3.5cm}| .. flat-table:: :header-rows: 0 @@ -69,37 +64,37 @@ Each cell is one byte. B\ :sub:`00low bits 5--0`\ (bits 5--0) - - R\ :sub:`02low bits 3--0`\ (bits 7--4) + - B\ :sub:`02low bits 3--0`\ (bits 7--4) G\ :sub:`01low bits 5--2`\ (bits 3--0) - G\ :sub:`03low bits 5--0`\ (bits 7--2) - R\ :sub:`02low bits 5--4`\ (bits 1--0) + B\ :sub:`02low bits 5--4`\ (bits 1--0) - .. row 2 - start + 7 - - G\ :sub:`00high` + - G\ :sub:`10high` - - R\ :sub:`01high` + - R\ :sub:`11high` - - G\ :sub:`02high` + - G\ :sub:`12high` - - R\ :sub:`03high` + - R\ :sub:`13high` - - R\ :sub:`01low bits 1--0`\ (bits 7--6) + - R\ :sub:`11low bits 1--0`\ (bits 7--6) - G\ :sub:`00low bits 5--0`\ (bits 5--0) + G\ :sub:`10low bits 5--0`\ (bits 5--0) - - G\ :sub:`02low bits 3--0`\ (bits 7--4) + - G\ :sub:`12low bits 3--0`\ (bits 7--4) - R\ :sub:`01low bits 5--2`\ (bits 3--0) + R\ :sub:`11low bits 5--2`\ (bits 3--0) - - R\ :sub:`03low bits 5--0`\ (bits 7--2) + - R\ :sub:`13low bits 5--0`\ (bits 7--2) - G\ :sub:`02low bits 5--4`\ (bits 1--0) + G\ :sub:`12low bits 5--4`\ (bits 1--0) - .. row 3 @@ -117,13 +112,13 @@ Each cell is one byte. B\ :sub:`20low bits 5--0`\ (bits 5--0) - - R\ :sub:`22low bits 3--0`\ (bits 7--4) + - B\ :sub:`22low bits 3--0`\ (bits 7--4) G\ :sub:`21low bits 5--2`\ (bits 3--0) - G\ :sub:`23low bits 5--0`\ (bits 7--2) - R\ :sub:`22low bits 5--4`\ (bits 1--0) + B\ :sub:`22low bits 5--4`\ (bits 1--0) - .. row 4 @@ -148,5 +143,5 @@ Each cell is one byte. .. raw:: latex - \normalsize + \endgroup diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst index 885f0d1f331d..2f2f1ef430d9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB16: .. _v4l2-pix-fmt-sbggr16: @@ -18,7 +11,9 @@ V4L2_PIX_FMT_SRGGB16 ('RG16'), V4L2_PIX_FMT_SGRBG16 ('GR16'), V4L2_PIX_FMT_SGBRG *************************************************************************************************************************** +==================== 16-bit Bayer formats +==================== Description diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst index c275e6ef09f9..02061c5a9778 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB8: .. _v4l2-pix-fmt-sbggr8: @@ -17,8 +10,9 @@ V4L2_PIX_FMT_SRGGB8 ('RGGB'), V4L2_PIX_FMT_SGRBG8 ('GRBG'), V4L2_PIX_FMT_SGBRG8 *************************************************************************************************************************** +=================== 8-bit Bayer formats - +=================== Description =========== diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst index 165c9be2bfc5..ec89f43c60ec 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-TCH-FMT-DELTA-TD08: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst index 6dca01182175..7b59a6424243 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-TCH-FMT-DELTA-TD16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst index f1380b72977f..63c5264b8668 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-TCH-FMT-TU08: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst index 2b9e1b15abcf..ade618a037a8 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-TCH-FMT-TU16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst b/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst index a36c1a4d64a4..ff1d73ef5dba 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-UV8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst b/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst deleted file mode 100644 index 776cb37f76f1..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-UYVY: - -************************** -V4L2_PIX_FMT_UYVY ('UYVY') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cb\ :sub:`00` - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`01` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - * - start + 8: - - Cb\ :sub:`10` - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`11` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - * - start + 16: - - Cb\ :sub:`20` - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`21` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - * - start + 24: - - Cb\ :sub:`30` - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`31` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst index 444b4082684c..ad4da988c3a3 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ****************************** Multi-planar format structures @@ -20,7 +13,7 @@ describing all planes of that format. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.4cm}|p{4.0cm}|p{11.9cm}| .. c:type:: v4l2_plane_pix_format @@ -59,7 +52,7 @@ describing all planes of that format. \small -.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}| +.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.3cm}| .. c:type:: v4l2_pix_format_mplane @@ -105,29 +98,21 @@ describing all planes of that format. * - __u8 - ``ycbcr_enc`` - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. - This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + See struct :c:type:`v4l2_pix_format`. * - __u8 - ``hsv_enc`` - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`. - This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + See struct :c:type:`v4l2_pix_format`. * - } - * - __u8 - ``quantization`` - Quantization range, from enum :c:type:`v4l2_quantization`. - This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + See struct :c:type:`v4l2_pix_format`. * - __u8 - ``xfer_func`` - Transfer function, from enum :c:type:`v4l2_xfer_func`. - This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + See struct :c:type:`v4l2_pix_format`. * - __u8 - ``reserved[7]`` - Reserved for future extensions. Should be zeroed by drivers and diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst index 759420a872d6..9c423ffe02f9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst @@ -1,17 +1,10 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ****************************** Single-planar format structure ****************************** -.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}| +.. tabularcolumns:: |p{4.0cm}|p{2.6cm}|p{10.7cm}| .. c:type:: v4l2_pix_format @@ -44,6 +37,11 @@ Single-planar format structure inside the stream, when fed to a stateful mem2mem decoder, the fields may be zero to rely on the decoder to detect the right values. For more details see :ref:`decoder` and format descriptions. + + For compressed formats on the CAPTURE side of a stateful mem2mem + encoder, the fields must be zero, since the coded size is expected to + be calculated internally by the encoder itself, based on the OUTPUT + side. For more details see :ref:`encoder` and format descriptions. * - __u32 - ``pixelformat`` - The pixel format or type of compression, set by the application. @@ -111,7 +109,14 @@ Single-planar format structure - Image colorspace, from enum :c:type:`v4l2_colorspace`. This information supplements the ``pixelformat`` and must be set by the driver for capture streams and by the application for - output streams, see :ref:`colorspaces`. + output streams, see :ref:`colorspaces`. If the application sets the + flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set + this field for a capture stream to request a specific colorspace + for the captured image data. If the driver cannot handle requested + conversion, it will return another supported colorspace. + The driver indicates that colorspace conversion is supported by setting + the flag V4L2_FMT_FLAG_CSC_COLORSPACE in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. * - __u32 - ``priv`` - This field indicates whether the remaining fields of the @@ -148,13 +153,29 @@ Single-planar format structure - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + streams, see :ref:`colorspaces`. If the application sets the + flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set + this field for a capture stream to request a specific Y'CbCr encoding + for the captured image data. If the driver cannot handle requested + conversion, it will return another supported encoding. + This field is ignored for HSV pixelformats. The driver indicates that + ycbcr_enc conversion is supported by setting the flag + V4L2_FMT_FLAG_CSC_YCBCR_ENC in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. * - __u32 - ``hsv_enc`` - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + streams, see :ref:`colorspaces`. If the application sets the flag + ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set this + field for a capture stream to request a specific HSV encoding for the + captured image data. If the driver cannot handle requested + conversion, it will return another supported encoding. + This field is ignored for non-HSV pixelformats. The driver indicates + that hsv_enc conversion is supported by setting the flag + V4L2_FMT_FLAG_CSC_HSV_ENC in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. * - } - * - __u32 @@ -162,10 +183,58 @@ Single-planar format structure - Quantization range, from enum :c:type:`v4l2_quantization`. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + streams, see :ref:`colorspaces`. If the application sets the flag + ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set + this field for a capture stream to request a specific quantization + range for the captured image data. If the driver cannot handle requested + conversion, it will return another supported quantization. + The driver indicates that quantization conversion is supported by setting + the flag V4L2_FMT_FLAG_CSC_QUANTIZATION in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. * - __u32 - ``xfer_func`` - Transfer function, from enum :c:type:`v4l2_xfer_func`. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + streams, see :ref:`colorspaces`. If the application sets the flag + ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set + this field for a capture stream to request a specific transfer function + for the captured image data. If the driver cannot handle requested + conversion, it will return another supported transfer function. + The driver indicates that xfer_func conversion is supported by setting + the flag V4L2_FMT_FLAG_CSC_XFER_FUNC in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. + +.. tabularcolumns:: |p{6.8cm}|p{2.3cm}|p{8.2cm}| + +.. _format-flags: + +.. flat-table:: Format Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA`` + - 0x00000001 + - The color values are premultiplied by the alpha channel value. For + example, if a light blue pixel with 50% transparency was described + by RGBA values (128, 192, 255, 128), the same pixel described with + premultiplied colors would be described by RGBA values (64, 96, + 128, 128) + * .. _`v4l2-pix-fmt-flag-set-csc`: + + - ``V4L2_PIX_FMT_FLAG_SET_CSC`` + - 0x00000002 + - Set by the application. It is only used for capture and is + ignored for output streams. If set, then request the device to do + colorspace conversion from the received colorspace to the requested + colorspace values. If the colorimetry field (``colorspace``, ``xfer_func``, + ``ycbcr_enc``, ``hsv_enc`` or ``quantization``) is set to ``*_DEFAULT``, + then that colorimetry setting will remain unchanged from what was received. + So in order to change the quantization, only the ``quantization`` field shall + be set to non default value (``V4L2_QUANTIZATION_FULL_RANGE`` or + ``V4L2_QUANTIZATION_LIM_RANGE``) and all other colorimetry fields shall + be set to ``*_DEFAULT``. + + To check which conversions are supported by the hardware for the current + pixel format, see :ref:`fmtdesc-flags`. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst b/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst deleted file mode 100644 index 6cd574e78e4c..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-VYUY: - -************************** -V4L2_PIX_FMT_VYUY ('VYUY') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cr\ :sub:`00` - - Y'\ :sub:`00` - - Cb\ :sub:`00` - - Y'\ :sub:`01` - - Cr\ :sub:`01` - - Y'\ :sub:`02` - - Cb\ :sub:`01` - - Y'\ :sub:`03` - * - start + 8: - - Cr\ :sub:`10` - - Y'\ :sub:`10` - - Cb\ :sub:`10` - - Y'\ :sub:`11` - - Cr\ :sub:`11` - - Y'\ :sub:`12` - - Cb\ :sub:`11` - - Y'\ :sub:`13` - * - start + 16: - - Cr\ :sub:`20` - - Y'\ :sub:`20` - - Cb\ :sub:`20` - - Y'\ :sub:`21` - - Cr\ :sub:`21` - - Y'\ :sub:`22` - - Cb\ :sub:`21` - - Y'\ :sub:`23` - * - start + 24: - - Cr\ :sub:`30` - - Y'\ :sub:`30` - - Cb\ :sub:`30` - - Y'\ :sub:`31` - - Cr\ :sub:`31` - - Y'\ :sub:`32` - - Cb\ :sub:`31` - - Y'\ :sub:`33` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10.rst deleted file mode 100644 index dfb352ae6784..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y10: - -************************* -V4L2_PIX_FMT_Y10 ('Y10 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 10 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst deleted file mode 100644 index b5d89d6d5c52..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y10BPACK: - -****************************** -V4L2_PIX_FMT_Y10BPACK ('Y10B') -****************************** - -Grey-scale image as a bit-packed array - - -Description -=========== - -This is a packed grey-scale image format with a depth of 10 bits per -pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel, -with no padding between them and with the most significant bits coming -first from the left. - -**Bit-packed representation.** - -pixels cross the byte boundary and have a ratio of 5 bytes for each 4 -pixels. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - Y'\ :sub:`00[9:2]` - - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]` - - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]` - - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]` - - Y'\ :sub:`03[7:0]` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst deleted file mode 100644 index ffb6e1631b78..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y10P: - -****************************** -V4L2_PIX_FMT_Y10P ('Y10P') -****************************** - -Grey-scale image as a MIPI RAW10 packed array - - -Description -=========== - -This is a packed grey-scale image format with a depth of 10 bits per -pixel. Every four consecutive pixels are packed into 5 bytes. Each of -the first 4 bytes contain the 8 high order bits of the pixels, and -the 5th byte contains the 2 least significants bits of each pixel, -in the same order. - -**Bit-packed representation.** - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{1.2cm}||p{1.2cm}||p{1.2cm}||p{1.2cm}|p{3.2cm}|p{3.2cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 8 8 8 8 64 - - * - Y'\ :sub:`00[9:2]` - - Y'\ :sub:`01[9:2]` - - Y'\ :sub:`02[9:2]` - - Y'\ :sub:`03[9:2]` - - Y'\ :sub:`03[1:0]`\ (bits 7--6) Y'\ :sub:`02[1:0]`\ (bits 5--4) - Y'\ :sub:`01[1:0]`\ (bits 3--2) Y'\ :sub:`00[1:0]`\ (bits 1--0) - -.. raw:: latex - - \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst b/Documentation/userspace-api/media/v4l/pixfmt-y12.rst deleted file mode 100644 index 4226c49232de..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y12: - -************************* -V4L2_PIX_FMT_Y12 ('Y12 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 12 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst b/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst index b4752754337b..d9b539381d74 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-Y12I: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst b/Documentation/userspace-api/media/v4l/pixfmt-y14.rst deleted file mode 100644 index d702b6549160..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y14: - -************************* -V4L2_PIX_FMT_Y14 ('Y14 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 14 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst deleted file mode 100644 index f4eda7b95b51..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y16-BE: - -**************************************** -V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31)) -**************************************** - - -Grey-scale image - - -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. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00high` - - Y'\ :sub:`00low` - - Y'\ :sub:`01high` - - Y'\ :sub:`01low` - - Y'\ :sub:`02high` - - Y'\ :sub:`02low` - - Y'\ :sub:`03high` - - Y'\ :sub:`03low` - * - start + 8: - - Y'\ :sub:`10high` - - Y'\ :sub:`10low` - - Y'\ :sub:`11high` - - Y'\ :sub:`11low` - - Y'\ :sub:`12high` - - Y'\ :sub:`12low` - - Y'\ :sub:`13high` - - Y'\ :sub:`13low` - * - start + 16: - - Y'\ :sub:`20high` - - Y'\ :sub:`20low` - - Y'\ :sub:`21high` - - Y'\ :sub:`21low` - - Y'\ :sub:`22high` - - Y'\ :sub:`22low` - - Y'\ :sub:`23high` - - Y'\ :sub:`23low` - * - start + 24: - - Y'\ :sub:`30high` - - Y'\ :sub:`30low` - - Y'\ :sub:`31high` - - Y'\ :sub:`31low` - - Y'\ :sub:`32high` - - Y'\ :sub:`32low` - - Y'\ :sub:`33high` - - Y'\ :sub:`33low` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16.rst deleted file mode 100644 index a092b0a5ff12..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y16: - -************************* -V4L2_PIX_FMT_Y16 ('Y16 ') -************************* - - -Grey-scale image - - -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. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst deleted file mode 100644 index 211afd7593cc..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y41P: - -************************** -V4L2_PIX_FMT_Y41P ('Y41P') -************************** - - -Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1 - - -Description -=========== - -In this format each 12 bytes is eight pixels. In the twelve bytes are -two CbCr pairs and eight Y's. The first CbCr pair goes with the first -four Y's, and the second CbCr pair goes with the other four Y's. The Cb -and Cr components have one fourth the horizontal resolution of the Y -component. - -Do not confuse this format with -:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived -from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 -*planar*". - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cb\ :sub:`00` - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`01` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - - Y'\ :sub:`04` - - Y'\ :sub:`05` - - Y'\ :sub:`06` - - Y'\ :sub:`07` - * - start + 12: - - Cb\ :sub:`10` - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`11` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - - Y'\ :sub:`14` - - Y'\ :sub:`15` - - Y'\ :sub:`16` - - Y'\ :sub:`17` - * - start + 24: - - Cb\ :sub:`20` - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`21` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - - Y'\ :sub:`24` - - Y'\ :sub:`25` - - Y'\ :sub:`26` - - Y'\ :sub:`27` - * - start + 36: - - Cb\ :sub:`30` - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`31` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - Y'\ :sub:`34` - - Y'\ :sub:`35` - - Y'\ :sub:`36` - - Y'\ :sub:`37` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - - - 2 - - 3 - - 4 - - 5 - - - - 6 - - 7 - * - 0 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 1 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 2 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 3 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst b/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst index 4248c6f735b7..770ed4749c14 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-Y8I: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst new file mode 100644 index 000000000000..cf8e4dfbfbd4 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -0,0 +1,163 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _yuv-luma-only: + +***************** +Luma-Only Formats +***************** + +This family of formats only store the luma component of a Y'CbCr image. They +are often referred to as greyscale formats. + +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - Formats are described with the minimum number of pixels needed to create a + byte-aligned repeating pattern. `...` indicates repetition of the pattern. + - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at column + `x`. + - `0` denotes padding bits set to 0. + + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{3.6cm}|p{3.0cm}|p{1.3cm}|p{2.6cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}| + +.. flat-table:: Luma-Only Image Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + + * .. _V4L2-PIX-FMT-GREY: + + - ``V4L2_PIX_FMT_GREY`` + - 'GREY' + + - Y'\ :sub:`0`\ [7:0] + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-IPU3-Y10: + + - ``V4L2_PIX_FMT_IPU3_Y10`` + - 'ip3y' + + - Y'\ :sub:`0`\ [7:0] + - Y'\ :sub:`1`\ [5:0] Y'\ :sub:`0`\ [9:8] + - Y'\ :sub:`2`\ [3:0] Y'\ :sub:`1`\ [9:6] + - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [9:4] + - Y'\ :sub:`3`\ [9:2] + + * .. _V4L2-PIX-FMT-Y10: + + - ``V4L2_PIX_FMT_Y10`` + - 'Y10 ' + + - Y'\ :sub:`0`\ [7:0] + - `000000` Y'\ :sub:`0`\ [9:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y10BPACK: + + - ``V4L2_PIX_FMT_Y10BPACK`` + - 'Y10B' + + - Y'\ :sub:`0`\ [9:2] + - Y'\ :sub:`0`\ [1:0] Y'\ :sub:`1`\ [9:4] + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`2`\ [9:6] + - Y'\ :sub:`2`\ [5:0] Y'\ :sub:`3`\ [9:8] + - Y'\ :sub:`3`\ [7:0] + + * .. _V4L2-PIX-FMT-Y10P: + + - ``V4L2_PIX_FMT_Y10P`` + - 'Y10P' + + - Y'\ :sub:`0`\ [9:2] + - Y'\ :sub:`1`\ [9:2] + - Y'\ :sub:`2`\ [9:2] + - Y'\ :sub:`3`\ [9:2] + - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0] + + * .. _V4L2-PIX-FMT-Y12: + + - ``V4L2_PIX_FMT_Y12`` + - 'Y12 ' + + - Y'\ :sub:`0`\ [7:0] + - `0000` Y'\ :sub:`0`\ [11:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y012: + + - ``V4L2_PIX_FMT_Y012`` + - 'Y012' + + - Y'\ :sub:`0`\ [3:0] `0000` + - Y'\ :sub:`0`\ [11:4] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y14: + + - ``V4L2_PIX_FMT_Y14`` + - 'Y14 ' + + - Y'\ :sub:`0`\ [7:0] + - `00` Y'\ :sub:`0`\ [13:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y16: + + - ``V4L2_PIX_FMT_Y16`` + - 'Y16 ' + + - Y'\ :sub:`0`\ [7:0] + - Y'\ :sub:`0`\ [15:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y16-BE: + + - ``V4L2_PIX_FMT_Y16_BE`` + - 'Y16 ' | (1U << 31) + + - Y'\ :sub:`0`\ [15:8] + - Y'\ :sub:`0`\ [7:0] + - ... + - ... + - ... + +.. raw:: latex + + \normalsize + +.. note:: + + For the Y16 and Y16_BE formats, the actual sampling precision may be lower + than 16 bits. For example, 10 bits per pixel uses values in the range 0 to + 1023. For the IPU3_Y10 format 25 pixels are packed into 32 bytes, which + leaves the 6 most significant bits of the last byte padded with 0. + + For Y012 and Y12 formats, Y012 places its data in the 12 high bits, with + padding zeros in the 4 low bits, in contrast to the Y12 format, which has + its padding located in the most significant bits of the 16 bit word. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst new file mode 100644 index 000000000000..1840224faa41 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -0,0 +1,1196 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. planar-yuv: + +****************** +Planar YUV formats +****************** + +Planar formats split luma and chroma data in separate memory regions. They +exist in two variants: + +- Semi-planar formats use two planes. The first plane is the luma plane and + stores the Y components. The second plane is the chroma plane and stores the + Cb and Cr components interleaved. + +- Fully planar formats use three planes to store the Y, Cb and Cr components + separately. + +Within a plane, components are stored in pixel order, which may be linear or +tiled. Padding may be supported at the end of the lines, and the line stride of +the chroma planes may be constrained by the line stride of the luma plane. + +Some planar formats allow planes to be placed in independent memory locations. +They are identified by an 'M' suffix in their name (such as in +``V4L2_PIX_FMT_NV12M``). Those formats are intended to be used only in drivers +and applications that support the multi-planar API, described in +:ref:`planar-apis`. Unless explicitly documented as supporting non-contiguous +planes, formats require the planes to follow each other immediately in memory. + + +Semi-Planar YUV Formats +======================= + +These formats are commonly referred to as NV formats (NV12, NV16, ...). They +use two planes, and store the luma components in the first plane and the chroma +components in the second plane. The Cb and Cr components are interleaved in the +chroma plane, with Cb and Cr always stored in pairs. The chroma order is +exposed as different formats. + +For memory contiguous formats, the number of padding pixels at the end of the +chroma lines is identical to the padding of the luma lines. Without horizontal +subsampling, the chroma line stride (in bytes) is thus equal to twice the luma +line stride. With horizontal subsampling by 2, the chroma line stride is equal +to the luma line stride. Vertical subsampling doesn't affect the line stride. + +For non-contiguous formats, no constraints are enforced by the format on the +relationship between the luma and chroma line padding and stride. + +All components are stored with the same number of bits per component. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{5.2cm}|p{1.0cm}|p{1.5cm}|p{1.9cm}|p{1.2cm}|p{1.8cm}|p{2.7cm}| + +.. flat-table:: Overview of Semi-Planar YUV Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Bits per component + - Subsampling + - Chroma order [1]_ + - Contiguous [2]_ + - Tiling [3]_ + * - V4L2_PIX_FMT_NV12 + - 'NV12' + - 8 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV21 + - 'NV21' + - 8 + - 4:2:0 + - Cr, Cb + - Yes + - Linear + * - V4L2_PIX_FMT_NV12M + - 'NM12' + - 8 + - 4:2:0 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV21M + - 'NM21' + - 8 + - 4:2:0 + - Cr, Cb + - No + - Linear + * - V4L2_PIX_FMT_NV12MT + - 'TM12' + - 8 + - 4:2:0 + - Cb, Cr + - No + - 64x32 tiles + + Horizontal Z order + * - V4L2_PIX_FMT_NV12MT_16X16 + - 'VM12' + - 8 + - 4:2:2 + - Cb, Cr + - No + - 16x16 tiles + * - V4L2_PIX_FMT_P010 + - 'P010' + - 10 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_P010_4L4 + - 'T010' + - 10 + - 4:2:0 + - Cb, Cr + - Yes + - 4x4 tiles + * - V4L2_PIX_FMT_P012 + - 'P012' + - 12 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_P012M + - 'PM12' + - 12 + - 4:2:0 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV15_4L4 + - 'VT15' + - 15 + - 4:2:0 + - Cb, Cr + - Yes + - 4x4 tiles + * - V4L2_PIX_FMT_NV16 + - 'NV16' + - 8 + - 4:2:2 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV61 + - 'NV61' + - 8 + - 4:2:2 + - Cr, Cb + - Yes + - Linear + * - V4L2_PIX_FMT_NV16M + - 'NM16' + - 8 + - 4:2:2 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV61M + - 'NM61' + - 8 + - 4:2:2 + - Cr, Cb + - No + - Linear + * - V4L2_PIX_FMT_NV24 + - 'NV24' + - 8 + - 4:4:4 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV42 + - 'NV42' + - 8 + - 4:4:4 + - Cr, Cb + - Yes + - Linear + +.. raw:: latex + + \normalsize + +.. [1] Order of chroma samples in the second plane +.. [2] Indicates if planes have to be contiguous in memory or can be + disjoint +.. [3] Macroblock size in pixels + + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + + +.. _V4L2-PIX-FMT-NV12: +.. _V4L2-PIX-FMT-NV21: +.. _V4L2-PIX-FMT-NV12M: +.. _V4L2-PIX-FMT-NV21M: +.. _V4L2-PIX-FMT-P010: + +NV12, NV21, NV12M and NV21M +--------------------------- + +Semi-planar YUV 4:2:0 formats. The chroma plane is subsampled by 2 in each +direction. Chroma lines contain half the number of pixels and the same number +of bytes as luma lines, and the chroma plane contains half the number of lines +of the luma plane. + +.. flat-table:: Sample 4x4 NV12 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 20: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. flat-table:: Sample 4x4 NV12M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start1 + 4: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + + +.. _V4L2-PIX-FMT-NV12MT: +.. _V4L2-PIX-FMT-NV12MT-16X16: +.. _V4L2-PIX-FMT-NV12-4L4: +.. _V4L2-PIX-FMT-NV12-16L16: +.. _V4L2-PIX-FMT-NV12-32L32: +.. _V4L2-PIX-FMT-NV12M-8L128: +.. _V4L2-PIX-FMT-NV12-8L128: +.. _V4L2-PIX-FMT-NV12M-10BE-8L128: +.. _V4L2-PIX-FMT-NV12-10BE-8L128: +.. _V4L2-PIX-FMT-MM21: + +Tiled NV12 +---------- + +Semi-planar YUV 4:2:0 formats, using macroblock tiling. The chroma plane is +subsampled by 2 in each direction. Chroma lines contain half the number of +pixels and the same number of bytes as luma lines, and the chroma plane +contains half the number of lines of the luma plane. Each tile follows the +previous one linearly in memory (from left to right, top to bottom). + +``V4L2_PIX_FMT_NV12MT_16X16`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores +pixels in 2D 16x16 tiles, and stores tiles linearly in memory. +The line stride and image height must be aligned to a multiple of 16. +The layouts of the luma and chroma planes are identical. + +``V4L2_PIX_FMT_NV12MT`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores +pixels in 2D 64x32 tiles, and stores 2x2 groups of tiles in +Z-order in memory, alternating Z and mirrored Z shapes horizontally. +The line stride must be a multiple of 128 pixels to ensure an +integer number of Z shapes. The image height must be a multiple of 32 pixels. +If the vertical resolution is an odd number of tiles, the last row of +tiles is stored in linear order. The layouts of the luma and chroma +planes are identical. + +``V4L2_PIX_FMT_NV12_4L4`` stores pixels in 4x4 tiles, and stores +tiles linearly in memory. The line stride and image height must be +aligned to a multiple of 4. The layouts of the luma and chroma planes are +identical. + +``V4L2_PIX_FMT_NV12_16L16`` stores pixels in 16x16 tiles, and stores +tiles linearly in memory. The line stride and image height must be +aligned to a multiple of 16. The layouts of the luma and chroma planes are +identical. + +``V4L2_PIX_FMT_NV12_32L32`` stores pixels in 32x32 tiles, and stores +tiles linearly in memory. The line stride and image height must be +aligned to a multiple of 32. The layouts of the luma and chroma planes are +identical. + +``V4L2_PIX_FMT_NV12M_8L128`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores +pixels in 2D 8x128 tiles, and stores tiles linearly in memory. +The image height must be aligned to a multiple of 128. +The layouts of the luma and chroma planes are identical. + +``V4L2_PIX_FMT_NV12_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_8L128`` but stores +two planes in one memory. + +``V4L2_PIX_FMT_NV12M_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores +10 bits pixels in 2D 8x128 tiles, and stores tiles linearly in memory. +the data is arranged in big endian order. +The image height must be aligned to a multiple of 128. +The layouts of the luma and chroma planes are identical. +Note the tile size is 8bytes multiplied by 128 bytes, +it means that the low bits and high bits of one pixel may be in different tiles. +The 10 bit pixels are packed, so 5 bytes contain 4 10-bit pixels layout like +this (for luma): +byte 0: Y0(bits 9-2) +byte 1: Y0(bits 1-0) Y1(bits 9-4) +byte 2: Y1(bits 3-0) Y2(bits 9-6) +byte 3: Y2(bits 5-0) Y3(bits 9-8) +byte 4: Y3(bits 7-0) + +``V4L2_PIX_FMT_NV12_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_10BE_8L128`` but stores +two planes in one memory. + +``V4L2_PIX_FMT_MM21`` store luma pixel in 16x32 tiles, and chroma pixels +in 16x16 tiles. The line stride must be aligned to a multiple of 16 and the +image height must be aligned to a multiple of 32. The number of luma and chroma +tiles are identical, even though the tile size differ. The image is formed of +two non-contiguous planes. + +.. _nv12mt: + +.. kernel-figure:: nv12mt.svg + :alt: nv12mt.svg + :align: center + + V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout + +.. _nv12mt_ex: + +.. kernel-figure:: nv12mt_example.svg + :alt: nv12mt_example.svg + :align: center + + Example V4L2_PIX_FMT_NV12MT memory layout of tiles + +.. _V4L2-PIX-FMT-NV15-4L4: + +Tiled NV15 +---------- + +Semi-planar 10-bit YUV 4:2:0 formats, using 4x4 tiling. +All components are packed without any padding between each other. +As a side-effect, each group of 4 components are stored over 5 bytes +(YYYY or UVUV = 4 * 10 bits = 40 bits = 5 bytes). + +.. _V4L2-PIX-FMT-NV16: +.. _V4L2-PIX-FMT-NV61: +.. _V4L2-PIX-FMT-NV16M: +.. _V4L2-PIX-FMT-NV61M: + +NV16, NV61, NV16M and NV61M +--------------------------- + +Semi-planar YUV 4:2:2 formats. The chroma plane is subsampled by 2 in the +horizontal direction. Chroma lines contain half the number of pixels and the +same number of bytes as luma lines, and the chroma plane contains the same +number of lines as the luma plane. + +.. flat-table:: Sample 4x4 NV16 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 20: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + * - start + 24: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`21` + - Cr\ :sub:`21` + * - start + 28: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`31` + - Cr\ :sub:`31` + +.. flat-table:: Sample 4x4 NV16M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`02` + - Cr\ :sub:`02` + * - start1 + 4: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`12` + - Cr\ :sub:`12` + * - start1 + 8: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`22` + - Cr\ :sub:`22` + * - start1 + 12: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`32` + - Cr\ :sub:`32` + + +.. _V4L2-PIX-FMT-NV24: +.. _V4L2-PIX-FMT-NV42: + +NV24 and NV42 +------------- + +Semi-planar YUV 4:4:4 formats. The chroma plane is not subsampled. +Chroma lines contain the same number of pixels and twice the +number of bytes as luma lines, and the chroma plane contains the same +number of lines as the luma plane. + +.. flat-table:: Sample 4x4 NV24 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + - Cb\ :sub:`02` + - Cr\ :sub:`02` + - Cb\ :sub:`03` + - Cr\ :sub:`03` + * - start + 24: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + - Cb\ :sub:`12` + - Cr\ :sub:`12` + - Cb\ :sub:`13` + - Cr\ :sub:`13` + * - start + 32: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`21` + - Cr\ :sub:`21` + - Cb\ :sub:`22` + - Cr\ :sub:`22` + - Cb\ :sub:`23` + - Cr\ :sub:`23` + * - start + 40: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`31` + - Cr\ :sub:`31` + - Cb\ :sub:`32` + - Cr\ :sub:`32` + - Cb\ :sub:`33` + - Cr\ :sub:`33` + +.. _V4L2_PIX_FMT_P010: +.. _V4L2-PIX-FMT-P010-4L4: + +P010 and tiled P010 +------------------- + +P010 is like NV12 with 10 bits per component, expanded to 16 bits. +Data in the 10 high bits, zeros in the 6 low bits, arranged in little endian order. + +.. flat-table:: Sample 4x4 P010 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 8: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 16: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 24: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 32: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 40: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. _V4L2-PIX-FMT-P012: +.. _V4L2-PIX-FMT-P012M: + +P012 and P012M +-------------- + +P012 is like NV12 with 12 bits per component, expanded to 16 bits. +Data in the 12 high bits, zeros in the 4 low bits, arranged in little endian order. + +.. flat-table:: Sample 4x4 P012 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 8: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 16: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 24: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 32: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 40: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. flat-table:: Sample 4x4 P012M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 8: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 16: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 24: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start1 + 8: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + + +Fully Planar YUV Formats +======================== + +These formats store the Y, Cb and Cr components in three separate planes. The +luma plane comes first, and the order of the two chroma planes varies between +formats. The two chroma planes always use the same subsampling. + +For memory contiguous formats, the number of padding pixels at the end of the +chroma lines is identical to the padding of the luma lines. The chroma line +stride (in bytes) is thus equal to the luma line stride divided by the +horizontal subsampling factor. Vertical subsampling doesn't affect the line +stride. + +For non-contiguous formats, no constraints are enforced by the format on the +relationship between the luma and chroma line padding and stride. + +All components are stored with the same number of bits per component. + +``V4L2_PIX_FMT_P010_4L4`` stores pixels in 4x4 tiles, and stores tiles linearly +in memory. The line stride must be aligned to multiple of 8 and image height to +a multiple of 4. The layouts of the luma and chroma planes are identical. + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.0cm}|p{1.1cm}|p{1.5cm}|p{2.2cm}|p{1.2cm}|p{3.7cm}| + +.. flat-table:: Overview of Fully Planar YUV Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Bits per component + - Subsampling + - Planes order [4]_ + - Contiguous [5]_ + + * - V4L2_PIX_FMT_YUV410 + - 'YUV9' + - 8 + - 4:1:0 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YVU410 + - 'YVU9' + - 8 + - 4:1:0 + - Y, Cr, Cb + - Yes + * - V4L2_PIX_FMT_YUV411P + - '411P' + - 8 + - 4:1:1 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YUV420M + - 'YM12' + - 8 + - 4:2:0 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU420M + - 'YM21' + - 8 + - 4:2:0 + - Y, Cr, Cb + - No + * - V4L2_PIX_FMT_YUV420 + - 'YU12' + - 8 + - 4:2:0 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YVU420 + - 'YV12' + - 8 + - 4:2:0 + - Y, Cr, Cb + - Yes + * - V4L2_PIX_FMT_YUV422P + - '422P' + - 8 + - 4:2:2 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YUV422M + - 'YM16' + - 8 + - 4:2:2 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU422M + - 'YM61' + - 8 + - 4:2:2 + - Y, Cr, Cb + - No + * - V4L2_PIX_FMT_YUV444M + - 'YM24' + - 8 + - 4:4:4 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU444M + - 'YM42' + - 8 + - 4:4:4 + - Y, Cr, Cb + - No + +.. raw:: latex + + \normalsize + +.. [4] Order of luma and chroma planes +.. [5] Indicates if planes have to be contiguous in memory or can be + disjoint + + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + +.. _V4L2-PIX-FMT-YUV410: +.. _V4L2-PIX-FMT-YVU410: + +YUV410 and YVU410 +----------------- + +Planar YUV 4:1:0 formats. The chroma planes are subsampled by 4 in each +direction. Chroma lines contain a quarter of the number of pixels and bytes of +the luma lines, and the chroma planes contain a quarter of the number of lines +of the luma plane. + +.. flat-table:: Sample 4x4 YUV410 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cr\ :sub:`00` + * - start + 17: + - Cb\ :sub:`00` + + +.. _V4L2-PIX-FMT-YUV411P: + +YUV411P +------- + +Planar YUV 4:1:1 formats. The chroma planes are subsampled by 4 in the +horizontal direction. Chroma lines contain a quarter of the number of pixels +and bytes of the luma lines, and the chroma planes contain the same number of +lines as the luma plane. + +.. flat-table:: Sample 4x4 YUV411P Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + * - start + 17: + - Cb\ :sub:`10` + * - start + 18: + - Cb\ :sub:`20` + * - start + 19: + - Cb\ :sub:`30` + * - start + 20: + - Cr\ :sub:`00` + * - start + 21: + - Cr\ :sub:`10` + * - start + 22: + - Cr\ :sub:`20` + * - start + 23: + - Cr\ :sub:`30` + + +.. _V4L2-PIX-FMT-YUV420: +.. _V4L2-PIX-FMT-YVU420: +.. _V4L2-PIX-FMT-YUV420M: +.. _V4L2-PIX-FMT-YVU420M: + +YUV420, YVU420, YUV420M and YVU420M +----------------------------------- + +Planar YUV 4:2:0 formats. The chroma planes are subsampled by 2 in each +direction. Chroma lines contain half of the number of pixels and bytes of the +luma lines, and the chroma planes contain half of the number of lines of the +luma plane. + +.. flat-table:: Sample 4x4 YUV420 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start + 18: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start + 20: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start + 22: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + +.. flat-table:: Sample 4x4 YUV420M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start1 + 2: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start2 + 2: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + + +.. _V4L2-PIX-FMT-YUV422P: +.. _V4L2-PIX-FMT-YUV422M: +.. _V4L2-PIX-FMT-YVU422M: + +YUV422P, YUV422M and YVU422M +---------------------------- + +Planar YUV 4:2:2 formats. The chroma planes are subsampled by 2 in the +horizontal direction. Chroma lines contain half of the number of pixels and +bytes of the luma lines, and the chroma planes contain the same number of lines +as the luma plane. + +.. flat-table:: Sample 4x4 YUV422P Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start + 18: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - start + 20: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + * - start + 22: + - Cb\ :sub:`30` + - Cb\ :sub:`31` + * - start + 24: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start + 26: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start + 28: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + * - start + 30: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + +.. flat-table:: Sample 4x4 YUV422M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start1 + 2: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - start1 + 4: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + * - start1 + 6: + - Cb\ :sub:`30` + - Cb\ :sub:`31` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start2 + 2: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start2 + 4: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + * - start2 + 6: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + + +.. _V4L2-PIX-FMT-YUV444M: +.. _V4L2-PIX-FMT-YVU444M: + +YUV444M and YVU444M +------------------- + +Planar YUV 4:4:4 formats. The chroma planes are no subsampled. Chroma lines +contain the same number of pixels and bytes of the luma lines, and the chroma +planes contain the same number of lines as the luma plane. + +.. flat-table:: Sample 4x4 YUV444M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + - Cb\ :sub:`02` + - Cb\ :sub:`03` + * - start1 + 4: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + - Cb\ :sub:`12` + - Cb\ :sub:`13` + * - start1 + 8: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + - Cb\ :sub:`22` + - Cb\ :sub:`23` + * - start1 + 12: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + - Cb\ :sub:`32` + - Cb\ :sub:`33` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + - Cr\ :sub:`02` + - Cr\ :sub:`03` + * - start2 + 4: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + - Cr\ :sub:`12` + - Cr\ :sub:`13` + * - start2 + 8: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + - Cr\ :sub:`22` + - Cr\ :sub:`23` + * - start2 + 12: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + - Cr\ :sub:`32` + - Cr\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst deleted file mode 100644 index 1d20115f2b1d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst +++ /dev/null @@ -1,134 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YVU410: -.. _v4l2-pix-fmt-yuv410: - -********************************************************** -V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9') -********************************************************** - - -V4L2_PIX_FMT_YUV410 -Planar formats with ¼ horizontal and vertical chroma resolution, also -known as YUV 4:1:0 - - -Description -=========== - -These are planar formats, as opposed to a packed format. The three -components are separated into three sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``, -the Cr plane immediately follows the Y plane in memory. The Cr plane is -¼ the width and ¼ the height of the Y plane (and of the image). Each Cr -belongs to 16 pixels, a four-by-four square of the image. Following the -Cr plane is the Cb plane, just like the Cr plane. -``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first, -then the Cr plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have ¼ as many pad bytes after their rows. In other words, four Cx rows -(including padding) are exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cr\ :sub:`00` - * - start + 17: - - Cb\ :sub:`00` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - - - - - C - - - - - - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst deleted file mode 100644 index 967ba7ce41a2..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV411P: - -***************************** -V4L2_PIX_FMT_YUV411P ('411P') -***************************** - - -Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1. -Planar layout as opposed to ``V4L2_PIX_FMT_Y41P`` - - -Description -=========== - -This format is not commonly used. This is a planar format similar to the -4:2:2 planar format except with half as many chroma. The three -components are separated into three sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. The Cb plane immediately -follows the Y plane in memory. The Cb plane is ¼ the width of the Y -plane (and of the image). Each Cb belongs to 4 pixels all on the same -row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, -Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane, -just like the Cb plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have ¼ as many pad bytes after their rows. In other words, four C x rows -(including padding) is exactly as long as one Y row (including padding). - -**Byte Order.** -Each cell is one byte. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - * - start + 17: - - Cb\ :sub:`10` - * - start + 18: - - Cb\ :sub:`20` - * - start + 19: - - Cb\ :sub:`30` - * - start + 20: - - Cr\ :sub:`00` - * - start + 21: - - Cr\ :sub:`10` - * - start + 22: - - Cr\ :sub:`20` - * - start + 23: - - Cr\ :sub:`30` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - - - 2 - - 3 - * - 0 - - Y - - Y - - C - - Y - - Y - * - 1 - - Y - - Y - - C - - Y - - Y - * - 2 - - Y - - Y - - C - - Y - - Y - * - 3 - - Y - - Y - - C - - Y - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst deleted file mode 100644 index 7cb685cc8289..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst +++ /dev/null @@ -1,150 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YVU420: -.. _V4L2-PIX-FMT-YUV420: - -********************************************************** -V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12') -********************************************************** - - -V4L2_PIX_FMT_YUV420 -Planar formats with ½ horizontal and vertical chroma resolution, also -known as YUV 4:2:0 - - -Description -=========== - -These are planar formats, as opposed to a packed format. The three -components are separated into three sub- images or planes. The Y plane -is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in -memory. The Cr plane is half the width and half the height of the Y -plane (and of the image). Each Cr belongs to four pixels, a two-by-two -square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane -is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the -same except the Cb plane comes first, then the Cr plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start + 18: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start + 20: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start + 22: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst deleted file mode 100644 index 80c14d4f5acb..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst +++ /dev/null @@ -1,159 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV420M: -.. _v4l2-pix-fmt-yvu420m: - -************************************************************ -V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21') -************************************************************ - - -V4L2_PIX_FMT_YVU420M -Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with -planes non contiguous in memory. - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which -is half the width and half the height of the Y plane (and of the image). -Each Cb belongs to four pixels, a two-by-two square of the image. For -example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, -Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane, -is in the third plane. - -``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start1 + 2: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start2 + 2: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst deleted file mode 100644 index 29b78480ccad..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV422M: -.. _v4l2-pix-fmt-yvu422m: - -************************************************************ -V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61') -************************************************************ - - -V4L2_PIX_FMT_YVU422M -Planar formats with ½ horizontal resolution, also known as YUV and YVU -4:2:2 - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which -is half the width of the Y plane (and of the image). Each Cb belongs to -two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third -plane. - -``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start1 + 2: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - start1 + 4: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - * - start1 + 6: - - Cb\ :sub:`30` - - Cb\ :sub:`31` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start2 + 2: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start2 + 4: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - * - start2 + 6: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst deleted file mode 100644 index 73fde222d820..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV422P: - -***************************** -V4L2_PIX_FMT_YUV422P ('422P') -***************************** - - -Format with ½ horizontal chroma resolution, also known as YUV 4:2:2. -Planar layout as opposed to ``V4L2_PIX_FMT_YUYV`` - - -Description -=========== - -This format is not commonly used. This is a planar version of the YUYV -format. The three components are separated into three sub-images or -planes. The Y plane is first. The Y plane has one byte per pixel. The Cb -plane immediately follows the Y plane in memory. The Cb plane is half -the width of the Y plane (and of the image). Each Cb belongs to two -pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb -plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start + 18: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - start + 20: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - * - start + 22: - - Cb\ :sub:`30` - - Cb\ :sub:`31` - * - start + 24: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start + 26: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start + 28: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - * - start + 30: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst deleted file mode 100644 index 7073ac7f842d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV444M: -.. _v4l2-pix-fmt-yvu444m: - -************************************************************ -V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42') -************************************************************ - - -V4L2_PIX_FMT_YVU444M -Planar formats with full horizontal resolution, also known as YUV and -YVU 4:4:4 - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which -is the same width and height as the Y plane (and as the image). The Cr -data, just like the Cb plane, is in the third plane. - -``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have the same number of pad bytes after their rows. - -``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - - Cb\ :sub:`02` - - Cb\ :sub:`03` - * - start1 + 4: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - - Cb\ :sub:`12` - - Cb\ :sub:`13` - * - start1 + 8: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - - Cb\ :sub:`22` - - Cb\ :sub:`23` - * - start1 + 12: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - - Cb\ :sub:`32` - - Cb\ :sub:`33` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - - Cr\ :sub:`02` - - Cr\ :sub:`03` - * - start2 + 4: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - - Cr\ :sub:`12` - - Cr\ :sub:`13` - * - start2 + 8: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - - Cr\ :sub:`22` - - Cr\ :sub:`23` - * - start2 + 12: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - Cr\ :sub:`32` - - Cr\ :sub:`33` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - 2 - - 3 - * - 0 - - YC - - YC - - YC - - YC - * - 1 - - YC - - YC - - YC - - YC - * - 2 - - YC - - YC - - YC - - YC - * - 3 - - YC - - YC - - YC - - YC diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst deleted file mode 100644 index fe70e007787d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUYV: - -************************** -V4L2_PIX_FMT_YUYV ('YUYV') -************************** - - -Packed format with ½ horizontal chroma resolution, also known as YUV -4:2:2 - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV`` -is known in the Windows environment as YUY2. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Cb\ :sub:`00` - - Y'\ :sub:`01` - - Cr\ :sub:`00` - - Y'\ :sub:`02` - - Cb\ :sub:`01` - - Y'\ :sub:`03` - - Cr\ :sub:`01` - * - start + 8: - - Y'\ :sub:`10` - - Cb\ :sub:`10` - - Y'\ :sub:`11` - - Cr\ :sub:`10` - - Y'\ :sub:`12` - - Cb\ :sub:`11` - - Y'\ :sub:`13` - - Cr\ :sub:`11` - * - start + 16: - - Y'\ :sub:`20` - - Cb\ :sub:`20` - - Y'\ :sub:`21` - - Cr\ :sub:`20` - - Y'\ :sub:`22` - - Cb\ :sub:`21` - - Y'\ :sub:`23` - - Cr\ :sub:`21` - * - start + 24: - - Y'\ :sub:`30` - - Cb\ :sub:`30` - - Y'\ :sub:`31` - - Cr\ :sub:`30` - - Y'\ :sub:`32` - - Cb\ :sub:`31` - - Y'\ :sub:`33` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst b/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst deleted file mode 100644 index 96c1b537d5a0..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YVYU: - -************************** -V4L2_PIX_FMT_YVYU ('YVYU') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`00` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - - Cb\ :sub:`01` - * - start + 8: - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`10` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - - Cb\ :sub:`11` - * - start + 16: - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`20` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - - Cb\ :sub:`21` - * - start + 24: - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`30` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - Cb\ :sub:`31` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-z16.rst b/Documentation/userspace-api/media/v4l/pixfmt-z16.rst index fe2fb21edeea..54a8cd723d1a 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-z16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-z16.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-Z16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt.rst b/Documentation/userspace-api/media/v4l/pixfmt.rst index 70ca3a5c2cf1..11dab4a90630 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt: diff --git a/Documentation/userspace-api/media/v4l/planar-apis.rst b/Documentation/userspace-api/media/v4l/planar-apis.rst index 6247b0c4ab4d..9207ce4283df 100644 --- a/Documentation/userspace-api/media/v4l/planar-apis.rst +++ b/Documentation/userspace-api/media/v4l/planar-apis.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _planar-apis: diff --git a/Documentation/userspace-api/media/v4l/querycap.rst b/Documentation/userspace-api/media/v4l/querycap.rst index 35fba2a9e09b..15a90271af45 100644 --- a/Documentation/userspace-api/media/v4l/querycap.rst +++ b/Documentation/userspace-api/media/v4l/querycap.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _querycap: diff --git a/Documentation/userspace-api/media/v4l/rw.rst b/Documentation/userspace-api/media/v4l/rw.rst index ce2768c994d0..64b85fb2a328 100644 --- a/Documentation/userspace-api/media/v4l/rw.rst +++ b/Documentation/userspace-api/media/v4l/rw.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _rw: @@ -13,8 +7,8 @@ Read/Write ********** -Input and output devices support the :ref:`read() <func-read>` and -:ref:`write() <func-write>` function, respectively, when the +Input and output devices support the :c:func:`read()` and +:c:func:`write()` function, respectively, when the ``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl is set. @@ -29,18 +23,17 @@ However this is also the simplest I/O method, requiring little or no setup to exchange data. It permits command line stunts like this (the vidctrl tool is fictitious): - .. code-block:: none $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288 $ dd if=/dev/video of=myimage.422 bs=202752 count=1 -To read from the device applications use the :ref:`read() <func-read>` -function, to write the :ref:`write() <func-write>` function. Drivers +To read from the device applications use the :c:func:`read()` +function, to write the :c:func:`write()` function. Drivers must implement one I/O method if they exchange data with applications, but it need not be this. [#f1]_ When reading or writing is supported, the -driver must also support the :ref:`select() <func-select>` and -:ref:`poll() <func-poll>` function. [#f2]_ +driver must also support the :c:func:`select()` and +:c:func:`poll()` function. [#f2]_ .. [#f1] It would be desirable if applications could depend on drivers @@ -50,5 +43,5 @@ driver must also support the :ref:`select() <func-select>` and capturing still images. .. [#f2] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. diff --git a/Documentation/userspace-api/media/v4l/sdr-formats.rst b/Documentation/userspace-api/media/v4l/sdr-formats.rst index b7a1be75251f..d8bdfdb56911 100644 --- a/Documentation/userspace-api/media/v4l/sdr-formats.rst +++ b/Documentation/userspace-api/media/v4l/sdr-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _sdr-formats: diff --git a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst index 67ff67fd734e..fee49bf1a1c0 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ************* Configuration @@ -101,7 +94,7 @@ specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given -by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the +by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in the same coordinate system as the bounds rectangle. The active cropping area must lie completely inside the crop boundaries and the driver may further adjust the requested size and/or position according to hardware diff --git a/Documentation/userspace-api/media/v4l/selection-api-examples.rst b/Documentation/userspace-api/media/v4l/selection-api-examples.rst index 2f4027211129..5f8e8a1f59d7 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-examples.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-examples.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ******** Examples diff --git a/Documentation/userspace-api/media/v4l/selection-api-intro.rst b/Documentation/userspace-api/media/v4l/selection-api-intro.rst index 0994ca25be5e..6534854ae9f7 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-intro.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ************ Introduction diff --git a/Documentation/userspace-api/media/v4l/selection-api-targets.rst b/Documentation/userspace-api/media/v4l/selection-api-targets.rst index 56eab969c9d8..50fdadd5b307 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-targets.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-targets.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ***************** Selection targets diff --git a/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst b/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst index a9360a000022..f57b9180012c 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _selection-vs-crop: diff --git a/Documentation/userspace-api/media/v4l/selection-api.rst b/Documentation/userspace-api/media/v4l/selection-api.rst index b86e387721df..0360743746dc 100644 --- a/Documentation/userspace-api/media/v4l/selection-api.rst +++ b/Documentation/userspace-api/media/v4l/selection-api.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _selection-api: diff --git a/Documentation/userspace-api/media/v4l/selection.svg b/Documentation/userspace-api/media/v4l/selection.svg index c0e00ab2ae6b..6305b53b8e54 100644 --- a/Documentation/userspace-api/media/v4l/selection.svg +++ b/Documentation/userspace-api/media/v4l/selection.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg enable-background="new" version="1" viewBox="0 0 4226.3 1686.8" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> <defs> <pattern id="ig" xlink:href="#ka" patternTransform="matrix(5.4432 0 0 10.1 1722.4 161.06)"/> diff --git a/Documentation/userspace-api/media/v4l/selections-common.rst b/Documentation/userspace-api/media/v4l/selections-common.rst index d5ea05869a61..322b39cf0eba 100644 --- a/Documentation/userspace-api/media/v4l/selections-common.rst +++ b/Documentation/userspace-api/media/v4l/selections-common.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-selections-common: diff --git a/Documentation/userspace-api/media/v4l/standard.rst b/Documentation/userspace-api/media/v4l/standard.rst index 61c341508eb3..1f6678325da9 100644 --- a/Documentation/userspace-api/media/v4l/standard.rst +++ b/Documentation/userspace-api/media/v4l/standard.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _standard: diff --git a/Documentation/userspace-api/media/v4l/streaming-par.rst b/Documentation/userspace-api/media/v4l/streaming-par.rst index 6d1a1b93ac8b..806cbfdad0f1 100644 --- a/Documentation/userspace-api/media/v4l/streaming-par.rst +++ b/Documentation/userspace-api/media/v4l/streaming-par.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _streaming-par: @@ -21,13 +15,13 @@ The current video standard determines a nominal number of frames per second. If less than this number of frames is to be captured or output, applications can request frame skipping or duplicating on the driver side. This is especially useful when using the -:ref:`read() <func-read>` or :ref:`write() <func-write>`, which are +:c:func:`read()` or :c:func:`write()`, which are not augmented by timestamps or sequence counters, and to avoid unnecessary data copying. Finally these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For implications see the -section discussing the :ref:`read() <func-read>` function. +section discussing the :c:func:`read()` function. To get and set the streaming parameters applications call the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index 9a4d61b0d76f..eb3cd20b0cf2 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -1,21 +1,16 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-mbus-format: Media Bus Formats ================= -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_mbus_framefmt +.. tabularcolumns:: |p{2.0cm}|p{4.0cm}|p{11.3cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_mbus_framefmt :header-rows: 0 :stub-columns: 0 @@ -41,32 +36,109 @@ Media Bus Formats :ref:`field-order` for details. * - __u32 - ``colorspace`` - - Image colorspace, from enum - :c:type:`v4l2_colorspace`. See - :ref:`colorspaces` for details. + - Image colorspace, from enum :c:type:`v4l2_colorspace`. + Must be set by the driver for subdevices. If the application sets the + flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set this + field on the source pad to request a specific colorspace for the media + bus data. If the driver cannot handle the requested conversion, it will + return another supported colorspace. The driver indicates that colorspace + conversion is supported by setting the flag + V4L2_SUBDEV_MBUS_CODE_CSC_COLORSPACE in the corresponding struct + :c:type:`v4l2_subdev_mbus_code_enum` during enumeration. + See :ref:`v4l2-subdev-mbus-code-flags`. + * - union { + - (anonymous) * - __u16 - ``ycbcr_enc`` - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + the driver for subdevices, see :ref:`colorspaces`. If the application + sets the flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set + this field on a source pad to request a specific Y'CbCr encoding + for the media bus data. If the driver cannot handle the requested + conversion, it will return another supported encoding. + This field is ignored for HSV media bus formats. The driver indicates + that ycbcr_enc conversion is supported by setting the flag + V4L2_SUBDEV_MBUS_CODE_CSC_YCBCR_ENC in the corresponding struct + :c:type:`v4l2_subdev_mbus_code_enum` during enumeration. + See :ref:`v4l2-subdev-mbus-code-flags`. + * - __u16 + - ``hsv_enc`` + - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`. + This information supplements the ``colorspace`` and must be set by + the driver for subdevices, see :ref:`colorspaces`. If the application + sets the flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set + this field on a source pad to request a specific HSV encoding + for the media bus data. If the driver cannot handle the requested + conversion, it will return another supported encoding. + This field is ignored for Y'CbCr media bus formats. The driver indicates + that hsv_enc conversion is supported by setting the flag + V4L2_SUBDEV_MBUS_CODE_CSC_HSV_ENC in the corresponding struct + :c:type:`v4l2_subdev_mbus_code_enum` during enumeration. + See :ref:`v4l2-subdev-mbus-code-flags` + * - } + - * - __u16 - ``quantization`` - Quantization range, from enum :c:type:`v4l2_quantization`. This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + the driver for subdevices, see :ref:`colorspaces`. If the application + sets the flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set + this field on a source pad to request a specific quantization + for the media bus data. If the driver cannot handle the requested + conversion, it will return another supported quantization. + The driver indicates that quantization conversion is supported by + setting the flag V4L2_SUBDEV_MBUS_CODE_CSC_QUANTIZATION in the + corresponding struct :c:type:`v4l2_subdev_mbus_code_enum` + during enumeration. See :ref:`v4l2-subdev-mbus-code-flags`. + * - __u16 - ``xfer_func`` - Transfer function, from enum :c:type:`v4l2_xfer_func`. This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + the driver for subdevices, see :ref:`colorspaces`. If the application + sets the flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set + this field on a source pad to request a specific transfer + function for the media bus data. If the driver cannot handle the requested + conversion, it will return another supported transfer function. + The driver indicates that the transfer function conversion is supported by + setting the flag V4L2_SUBDEV_MBUS_CODE_CSC_XFER_FUNC in the + corresponding struct :c:type:`v4l2_subdev_mbus_code_enum` + during enumeration. See :ref:`v4l2-subdev-mbus-code-flags`. * - __u16 - - ``reserved``\ [11] + - ``flags`` + - flags See: :ref:v4l2-mbus-framefmt-flags + * - __u16 + - ``reserved``\ [10] - Reserved for future extensions. Applications and drivers must set the array to zero. +.. _v4l2-mbus-framefmt-flags: + +.. tabularcolumns:: |p{6.5cm}|p{1.6cm}|p{9.2cm}| + +.. flat-table:: v4l2_mbus_framefmt Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`mbus-framefmt-set-csc`: + + - ``V4L2_MBUS_FRAMEFMT_SET_CSC`` + - 0x0001 + - Set by the application. It is only used for source pads and is + ignored for sink pads. If set, then request the subdevice to do + colorspace conversion from the received colorspace to the requested + colorspace values. If the colorimetry field (``colorspace``, ``xfer_func``, + ``ycbcr_enc``, ``hsv_enc`` or ``quantization``) is set to ``*_DEFAULT``, + then that colorimetry setting will remain unchanged from what was received. + So in order to change the quantization, only the ``quantization`` field shall + be set to non default value (``V4L2_QUANTIZATION_FULL_RANGE`` or + ``V4L2_QUANTIZATION_LIM_RANGE``) and all other colorimetry fields shall + be set to ``*_DEFAULT``. + + To check which conversions are supported by the hardware for the current + media bus frame format, see :ref:`v4l2-subdev-mbus-code-flags`. .. _v4l2-mbus-pixelcode: @@ -136,7 +208,7 @@ The following tables list existing packed RGB formats. .. it switches to long table, and there's no way to override it. -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-rgb: @@ -877,6 +949,115 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB666-2X9-BE: + + - MEDIA_BUS_FMT_RGB666_2X9_BE + - 0x1025 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR666-1X18: + + - MEDIA_BUS_FMT_BGR666_1X18 + - 0x1023 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` * .. _MEDIA-BUS-FMT-RBG888-1X24: - MEDIA_BUS_FMT_RBG888_1X24 @@ -951,6 +1132,80 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR666-1X24_CPADHI: + + - MEDIA_BUS_FMT_BGR666_1X24_CPADHI + - 0x1024 + - + - + - + - + - + - + - + - + - + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB565-1X24_CPADHI: + + - MEDIA_BUS_FMT_RGB565_1X24_CPADHI + - 0x1022 + - + - + - + - + - + - + - + - + - + - 0 + - 0 + - 0 + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` * .. _MEDIA-BUS-FMT-BGR888-1X24: - MEDIA_BUS_FMT_BGR888_1X24 @@ -1420,6 +1675,80 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB666-1X30-CPADLO: + + - MEDIA_BUS_FMT_RGB666_1X30-CPADLO + - 0x101e + - + - + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + * .. _MEDIA-BUS-FMT-RGB888-1X30-CPADLO: + + - MEDIA_BUS_FMT_RGB888_1X30-CPADLO + - 0x101f + - + - + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 * .. _MEDIA-BUS-FMT-ARGB888-1X32: - MEDIA_BUS_FMT_ARGB888_1X32 @@ -1499,8 +1828,8 @@ The following tables list existing packed RGB formats. - MEDIA_BUS_FMT_RGB101010_1X30 - 0x1018 - - - 0 - - 0 + - + - - r\ :sub:`9` - r\ :sub:`8` - r\ :sub:`7` @@ -1597,6 +1926,88 @@ The following table list existing packed 36bit wide RGB formats. - 2 - 1 - 0 + * .. _MEDIA-BUS-FMT-RGB666-1X36-CPADLO: + + - MEDIA_BUS_FMT_RGB666_1X36_CPADLO + - 0x1020 + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + * .. _MEDIA-BUS-FMT-RGB888-1X36-CPADLO: + + - MEDIA_BUS_FMT_RGB888_1X36_CPADLO + - 0x1021 + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 * .. _MEDIA-BUS-FMT-RGB121212-1X36: - MEDIA_BUS_FMT_RGB121212_1X36 @@ -1822,7 +2233,7 @@ JEIDA defined bit mapping will be named .. raw:: latex - \tiny + \small .. _v4l2-mbus-pixelcode-rgb-lvds: @@ -2084,7 +2495,7 @@ organization is given as an example for the first pixel only. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{6.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-bayer: @@ -2937,7 +3348,7 @@ the following codes. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8: @@ -5829,6 +6240,43 @@ the following codes. - y\ :sub:`2` - y\ :sub:`1` - y\ :sub:`0` + * .. _MEDIA-BUS-FMT-Y16-1X16: + + - MEDIA_BUS_FMT_Y16_1X16 + - 0x202e + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` * .. _MEDIA-BUS-FMT-UYVY8-1X16: - MEDIA_BUS_FMT_UYVY8_1X16 @@ -7142,7 +7590,7 @@ The following table list existing packed 36bit wide YUV formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{4.1cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8-36bit: @@ -7330,7 +7778,7 @@ The following table list existing packed 48bit wide YUV formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8-48bit: @@ -7761,7 +8209,7 @@ The following table lists existing HSV/HSL formats. .. raw:: latex - \normalsize + \endgroup JPEG Compressed Formats @@ -7783,7 +8231,7 @@ The following table lists existing JPEG compressed formats. .. _v4l2-mbus-pixelcode-jpeg: -.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{10.1cm}| +.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{9.9cm}| .. flat-table:: JPEG Formats :header-rows: 1 @@ -7816,7 +8264,7 @@ formats. .. _v4l2-mbus-pixelcode-vendor-specific: -.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.9cm}| .. flat-table:: Vendor and device specific formats :header-rows: 1 @@ -7831,3 +8279,30 @@ formats. - 0x5001 - Interleaved raw UYVY and JPEG image format with embedded meta-data used by Samsung S3C73MX camera sensors. + +.. _v4l2-mbus-metadata-fmts: + +Metadata Formats +^^^^^^^^^^^^^^^^ + +This section lists all metadata formats. + +The following table lists the existing metadata formats. + +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.9cm}| + +.. flat-table:: Metadata formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Comments + * .. _MEDIA-BUS-FMT-METADATA-FIXED: + + - MEDIA_BUS_FMT_METADATA_FIXED + - 0x7001 + - This format should be used when the same driver handles + both sides of the link and the bus format is a fixed + metadata format that is not configurable from userspace. + Width and height will be set to 0 for this format. diff --git a/Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg b/Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg index 109bbcebd3b4..d92311281e01 100644 --- a/Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg +++ b/Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg b/Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg index cfdb7532d5b6..864a594ff8d0 100644 --- a/Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg +++ b/Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg b/Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg index f7f1379d30a6..b75755d31f15 100644 --- a/Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg +++ b/Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/tch-formats.rst b/Documentation/userspace-api/media/v4l/tch-formats.rst index f83aec85fd76..8c941ff9e200 100644 --- a/Documentation/userspace-api/media/v4l/tch-formats.rst +++ b/Documentation/userspace-api/media/v4l/tch-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _tch-formats: diff --git a/Documentation/userspace-api/media/v4l/tuner.rst b/Documentation/userspace-api/media/v4l/tuner.rst index 02a396eb6613..e2c53c3abdc6 100644 --- a/Documentation/userspace-api/media/v4l/tuner.rst +++ b/Documentation/userspace-api/media/v4l/tuner.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _tuner: diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst index bf77c842718e..15ff0bf7bbe6 100644 --- a/Documentation/userspace-api/media/v4l/user-func.rst +++ b/Documentation/userspace-api/media/v4l/user-func.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _user-func: @@ -77,7 +70,9 @@ Function Reference vidioc-subdev-g-crop vidioc-subdev-g-fmt vidioc-subdev-g-frame-interval + vidioc-subdev-g-routing vidioc-subdev-g-selection + vidioc-subdev-g-client-cap vidioc-subdev-querycap vidioc-subscribe-event func-mmap diff --git a/Documentation/userspace-api/media/v4l/userp.rst b/Documentation/userspace-api/media/v4l/userp.rst index 2d0fa7353066..db224f9b611e 100644 --- a/Documentation/userspace-api/media/v4l/userp.rst +++ b/Documentation/userspace-api/media/v4l/userp.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _userp: @@ -85,10 +79,10 @@ buffers it must wait until an empty buffer can be dequeued and reused. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the -``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, +``O_NONBLOCK`` flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` error code when no buffer is available. The :ref:`select() -<func-select>` or :ref:`poll() <func-poll>` function are always +<func-select>` or :c:func:`poll()` function are always available. To start and stop capturing or output applications call the @@ -108,7 +102,7 @@ Drivers implementing user pointer I/O must support the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [#f2]_ +:c:func:`select()` and :c:func:`poll()` function. [#f2]_ .. [#f1] We expect that frequently used buffers are typically not swapped out. @@ -123,6 +117,6 @@ and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the because an application may share them with other processes. .. [#f2] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. The rest should be evident. diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst index 5c6f351b2443..1cb1531c1e52 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-selection-flags: @@ -13,10 +6,16 @@ Selection flags *************** -.. tabularcolumns:: |p{5.2cm}|p{2.0cm}|p{6.5cm}|p{1.2cm}|p{1.6cm}| - .. _v4l2-selection-flags-table: +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.6cm}|p{2.0cm}|p{6.5cm}|p{1.2cm}|p{1.2cm}| + +.. cssclass:: longtable + .. flat-table:: Selection flag definitions :header-rows: 1 :stub-columns: 0 @@ -49,3 +48,7 @@ Selection flags inside the subdevice to all further processing steps. - No - Yes + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst index 69f500093aa2..b46bae984f35 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-selection-targets: @@ -19,7 +12,13 @@ of the two interfaces they are used. .. _v4l2-selection-targets-table: -.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{7.4cm}|p{1.2cm}|p{1.4cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{6.2cm}|p{1.4cm}|p{7.3cm}|p{1.2cm}|p{0.8cm}| + +.. cssclass:: longtable .. flat-table:: Selection target definitions :header-rows: 1 @@ -76,3 +75,7 @@ of the two interfaces they are used. modified by hardware. - Yes - No + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst index ab7c97c39b97..cf8ae56a008c 100644 --- a/Documentation/userspace-api/media/v4l/v4l2.rst +++ b/Documentation/userspace-api/media/v4l/v4l2.rst @@ -1,13 +1,6 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. include:: <isonum.txt> + .. _v4l2spec: ############################ @@ -18,13 +11,8 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification. **Revision 4.5** -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :numbered: :maxdepth: 5 @@ -63,6 +51,7 @@ Authors, in alphabetical order: - Figa, Tomasz <tfiga@chromium.org> - Documented the memory-to-memory decoder interface. + - Documented the memory-to-memory encoder interface. - H Schimek, Michael <mschimek@gmx.at> @@ -75,6 +64,7 @@ Authors, in alphabetical order: - Osciak, Pawel <posciak@chromium.org> - Documented the memory-to-memory decoder interface. + - Documented the memory-to-memory encoder interface. - Osciak, Pawel <pawel@osciak.com> diff --git a/Documentation/userspace-api/media/v4l/v4l2grab-example.rst b/Documentation/userspace-api/media/v4l/v4l2grab-example.rst index 270738876f72..b323be42c580 100644 --- a/Documentation/userspace-api/media/v4l/v4l2grab-example.rst +++ b/Documentation/userspace-api/media/v4l/v4l2grab-example.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2grab-example: diff --git a/Documentation/userspace-api/media/v4l/v4l2grab.c.rst b/Documentation/userspace-api/media/v4l/v4l2grab.c.rst index a21ff357a830..1a55e3617ea8 100644 --- a/Documentation/userspace-api/media/v4l/v4l2grab.c.rst +++ b/Documentation/userspace-api/media/v4l/v4l2grab.c.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later file: media/v4l/v4l2grab.c ========================== @@ -53,7 +46,7 @@ file: media/v4l/v4l2grab.c } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN))); if (r == -1) { - fprintf(stderr, "error %d, %s\\n", errno, strerror(errno)); + fprintf(stderr, "error %d, %s\n", errno, strerror(errno)); exit(EXIT_FAILURE); } } @@ -87,11 +80,11 @@ file: media/v4l/v4l2grab.c fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; xioctl(fd, VIDIOC_S_FMT, &fmt); if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) { - printf("Libv4l didn't accept RGB24 format. Can't proceed.\\n"); + printf("Libv4l didn't accept RGB24 format. Can't proceed.\n"); exit(EXIT_FAILURE); } if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480)) - printf("Warning: driver is sending image at %dx%d\\n", + printf("Warning: driver is sending image at %dx%d\n", fmt.fmt.pix.width, fmt.fmt.pix.height); CLEAR(req); @@ -141,7 +134,7 @@ file: media/v4l/v4l2grab.c tv.tv_usec = 0; r = select(fd + 1, &fds, NULL, NULL, &tv); - } while ((r == -1 && (errno = EINTR))); + } while ((r == -1 && (errno == EINTR))); if (r == -1) { perror("select"); return errno; @@ -158,7 +151,7 @@ file: media/v4l/v4l2grab.c perror("Cannot open image"); exit(EXIT_FAILURE); } - fprintf(fout, "P6\\n%d %d 255\\n", + fprintf(fout, "P6\n%d %d 255\n", fmt.fmt.pix.width, fmt.fmt.pix.height); fwrite(buffers[buf.index].start, buf.bytesused, 1, fout); fclose(fout); diff --git a/Documentation/userspace-api/media/v4l/vbi_525.svg b/Documentation/userspace-api/media/v4l/vbi_525.svg index b7d09057617e..1951de29a111 100644 --- a/Documentation/userspace-api/media/v4l/vbi_525.svg +++ b/Documentation/userspace-api/media/v4l/vbi_525.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -23,7 +14,7 @@ xml:space="preserve" width="208.73068mm" height="51.395489mm" - viewBox="0 0 739.59691 182.11" + viewBox="0 0 788.90338 194.25067" sodipodi:docname="vbi_525.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -34,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" fit-margin-top="0" diff --git a/Documentation/userspace-api/media/v4l/vbi_625.svg b/Documentation/userspace-api/media/v4l/vbi_625.svg index e1f5e8552c37..21f524de3aed 100644 --- a/Documentation/userspace-api/media/v4l/vbi_625.svg +++ b/Documentation/userspace-api/media/v4l/vbi_625.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -23,7 +14,7 @@ xml:space="preserve" width="209.46608mm" height="51.576824mm" - viewBox="0 0 742.20265 182.75252" + viewBox="0 0 791.6828 194.93604" sodipodi:docname="vbi_625.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -34,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" fit-margin-top="0" diff --git a/Documentation/userspace-api/media/v4l/vbi_hsync.svg b/Documentation/userspace-api/media/v4l/vbi_hsync.svg index 77606a7b00a4..d360251e5f20 100644 --- a/Documentation/userspace-api/media/v4l/vbi_hsync.svg +++ b/Documentation/userspace-api/media/v4l/vbi_hsync.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -23,7 +14,7 @@ xml:space="preserve" width="192.39857mm" height="146.83536mm" - viewBox="0 0 681.72724 520.28277" + viewBox="0 0 727.17572 554.96826" sodipodi:docname="vbi_hsync.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -34,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" inkscape:zoom="1.5350601" diff --git a/Documentation/userspace-api/media/v4l/video.rst b/Documentation/userspace-api/media/v4l/video.rst index 9b73dba0eb8d..f8f69a57602c 100644 --- a/Documentation/userspace-api/media/v4l/video.rst +++ b/Documentation/userspace-api/media/v4l/video.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _video: diff --git a/Documentation/userspace-api/media/v4l/videodev.rst b/Documentation/userspace-api/media/v4l/videodev.rst index c8244b895802..c866fec417eb 100644 --- a/Documentation/userspace-api/media/v4l/videodev.rst +++ b/Documentation/userspace-api/media/v4l/videodev.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _videodev: diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst index e1afc5b504c2..49232c9006c2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_CREATE_BUFS: @@ -18,24 +12,22 @@ Name VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp ) - :name: VIDIOC_CREATE_BUFS +.. c:macro:: VIDIOC_CREATE_BUFS +``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_create_buffers`. - Description =========== @@ -78,10 +70,9 @@ the actual number allocated and the starting index in the ``count`` and the ``index`` fields respectively. On return ``count`` can be smaller than the number requested. - .. c:type:: v4l2_create_buffers -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_create_buffers :header-rows: 0 @@ -120,12 +111,21 @@ than the number requested. If you want to just query the capabilities without making any other changes, then set ``count`` to 0, ``memory`` to ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type. + * - __u32 - - ``reserved``\ [7] + - ``flags`` + - Specifies additional buffer management attributes. + See :ref:`memory-flags`. + * - __u32 + - ``max_num_buffers`` + - If the V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS capability flag is set + this field indicates the maximum possible number of buffers + for this queue. + * - __u32 + - ``reserved``\ [5] - A place holder for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst index 035ed9d577ae..7f10f0bbcfd3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_CROPCAP: @@ -18,24 +12,22 @@ Name VIDIOC_CROPCAP - Information about the video cropping and scaling abilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp ) - :name: VIDIOC_CROPCAP +.. c:macro:: VIDIOC_CROPCAP +``int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_cropcap`. - Description =========== @@ -53,7 +45,7 @@ overlay devices. .. c:type:: v4l2_cropcap -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_cropcap :header-rows: 0 @@ -79,7 +71,7 @@ overlay devices. - Default cropping rectangle, it shall cover the "whole picture". Assuming pixel aspect 1/1 this could be for example a 640 × 480 rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM - centered over the active picture area. The same co-ordinate system + centered over the active picture area. The same coordinate system as for ``bounds`` is used. * - struct :c:type:`v4l2_fract` - ``pixelaspect`` @@ -102,10 +94,9 @@ overlay devices. Starting with kernel 4.13 both variations are allowed. - .. _v4l2-rect-crop: -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_rect :header-rows: 0 @@ -127,7 +118,6 @@ overlay devices. - ``height`` - Height of the rectangle, in pixels. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst index 16078a2d3e3d..1a1e093936f1 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DBG_G_CHIP_INFO: @@ -18,24 +12,22 @@ Name VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp ) - :name: VIDIOC_DBG_G_CHIP_INFO +.. c:macro:: VIDIOC_DBG_G_CHIP_INFO +``int ioctl(int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dbg_chip_info`. - Description =========== @@ -83,8 +75,7 @@ is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. _name-v4l2-dbg-match: @@ -110,8 +101,7 @@ instructions. - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_dbg_chip_info @@ -137,8 +127,7 @@ instructions. - Reserved fields, both application and driver must set these to 0. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _name-chip-match-types: @@ -155,7 +144,6 @@ instructions. - 4 - Match the nth sub-device. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst index 6311a63278a5..53f10c7319b2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DBG_G_REGISTER: @@ -18,27 +12,26 @@ Name VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp ) - :name: VIDIOC_DBG_G_REGISTER +.. c:macro:: VIDIOC_DBG_G_REGISTER + +``int ioctl(int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp ) - :name: VIDIOC_DBG_S_REGISTER +.. c:macro:: VIDIOC_DBG_S_REGISTER +``int ioctl(int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dbg_register`. - Description =========== @@ -92,8 +85,7 @@ It is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_dbg_match @@ -119,7 +111,6 @@ instructions. - - .. c:type:: v4l2_dbg_register .. flat-table:: struct v4l2_dbg_register @@ -140,8 +131,7 @@ instructions. - The value read from, or to be written into the register. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _chip-match-types: @@ -158,7 +148,6 @@ instructions. - 4 - Match the nth sub-device. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst index 7986a248bff9..7ccae3b91616 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DECODER_CMD: @@ -18,28 +12,26 @@ Name VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp ) - :name: VIDIOC_DECODER_CMD +.. c:macro:: VIDIOC_DECODER_CMD +``int ioctl(int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp ) - :name: VIDIOC_TRY_DECODER_CMD +.. c:macro:: VIDIOC_TRY_DECODER_CMD +``int ioctl(int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` pointer to struct :c:type:`v4l2_decoder_cmd`. - Description =========== @@ -54,11 +46,11 @@ this structure. The ``cmd`` field must contain the command code. Some commands use the ``flags`` field for additional information. -A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON` +A :c:func:`write()` or :ref:`VIDIOC_STREAMON` call sends an implicit START command to the decoder if it has not been started yet. Applies to both queues of mem2mem decoders. -A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP command to the decoder, and all buffered data is discarded. Applies to both queues of mem2mem decoders. @@ -67,8 +59,7 @@ In principle, these ioctls are optional, not all drivers may support them. They introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders (as further documented in :ref:`decoder`). - -.. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}| +.. tabularcolumns:: |p{2.0cm}|p{1.1cm}|p{2.2cm}|p{11.8cm}| .. c:type:: v4l2_decoder_cmd @@ -138,8 +129,9 @@ introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decod - +.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.1cm}| -.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.3cm}| +.. cssclass:: longtable .. _decoder-cmds: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst index a9a176d5256d..8db103760930 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DQEVENT: @@ -18,24 +12,22 @@ Name VIDIOC_DQEVENT - Dequeue event - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp ) - :name: VIDIOC_DQEVENT +.. c:macro:: VIDIOC_DQEVENT +``int ioctl(int fd, VIDIOC_DQEVENT, struct v4l2_event *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_event`. - Description =========== @@ -45,12 +37,10 @@ structure are filled by the driver. The file handle will also receive exceptions which the application may get by e.g. using the select system call. - -.. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}| - .. c:type:: v4l2_event -.. cssclass: longtable +.. tabularcolumns:: |p{3.0cm}|p{3.4cm}|p{10.9cm}| + .. flat-table:: struct v4l2_event :header-rows: 0 @@ -107,8 +97,7 @@ call. zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.2cm}|p{2.6cm}|p{8.5cm}| .. cssclass:: longtable @@ -198,8 +187,7 @@ call. - Base event number for driver-private events. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_vsync @@ -213,8 +201,7 @@ call. - The upcoming field. See enum :c:type:`v4l2_field`. - -.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{10.8cm}| .. c:type:: v4l2_event_ctrl @@ -260,12 +247,11 @@ call. :ref:`v4l2_queryctrl <v4l2-queryctrl>`. * - __s32 - ``default_value`` - - The default value value of the control. See struct + - The default value of the control. See struct :ref:`v4l2_queryctrl <v4l2-queryctrl>`. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_frame_sync @@ -279,8 +265,7 @@ call. - The sequence number of the frame being received. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_src_change @@ -295,8 +280,7 @@ call. :ref:`src-changes-flags`. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_motion_det @@ -325,8 +309,7 @@ call. automatically assigned to the default region 0. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _ctrl-changes-flags: @@ -349,10 +332,14 @@ call. - 0x0004 - This control event was triggered because the minimum, maximum, step or the default value of the control changed. + * - ``V4L2_EVENT_CTRL_CH_DIMENSIONS`` + - 0x0008 + - This control event was triggered because the dimensions of the + control changed. Note that the number of dimensions remains the + same. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _src-changes-flags: @@ -382,7 +369,6 @@ call. loss of signal and so restarting streaming I/O is required in order for the hardware to synchronize to the video signal. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst index 60730c32bfe4..8ced100bb156 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DV_TIMINGS_CAP: @@ -18,27 +12,26 @@ Name VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp ) - :name: VIDIOC_DV_TIMINGS_CAP +.. c:macro:: VIDIOC_DV_TIMINGS_CAP + +``int ioctl(int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp ) - :name: VIDIOC_SUBDEV_DV_TIMINGS_CAP +.. c:macro:: VIDIOC_SUBDEV_DV_TIMINGS_CAP +``int ioctl(int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings_cap`. - Description =========== @@ -62,8 +55,7 @@ the desired pad number in the struct zero the ``reserved`` array. Attempts to query capabilities on a pad that doesn't support them will return an ``EINVAL`` error code. - -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.2cm}|p{12.9cm}| .. c:type:: v4l2_bt_timings_cap @@ -104,8 +96,7 @@ that doesn't support them will return an ``EINVAL`` error code. Drivers must set the array to zero. - -.. tabularcolumns:: |p{1.0cm}|p{4.0cm}|p{3.5cm}|p{9.2cm}| +.. tabularcolumns:: |p{4.4cm}|p{3.6cm}|p{9.3cm}| .. c:type:: v4l2_dv_timings_cap @@ -137,7 +128,7 @@ that doesn't support them will return an ``EINVAL`` error code. * - } - -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| .. _dv-bt-cap-capabilities: @@ -160,7 +151,6 @@ that doesn't support them will return an ``EINVAL`` error code. - Can support non-standard timings, i.e. timings not belonging to the standards set in the ``standards`` field. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst index 16269b3b1715..2b5867a68b31 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENCODER_CMD: @@ -18,22 +12,22 @@ Name VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) - :name: VIDIOC_ENCODER_CMD +.. c:macro:: VIDIOC_ENCODER_CMD + +``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) - :name: VIDIOC_TRY_ENCODER_CMD +.. c:macro:: VIDIOC_TRY_ENCODER_CMD +``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_encoder_cmd`. @@ -51,28 +45,28 @@ To send a command applications must initialize all fields of a struct ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to this structure. -The ``cmd`` field must contain the command code. The ``flags`` field is -currently only used by the STOP command and contains one bit: If the -``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue -until the end of the current *Group Of Pictures*, otherwise it will stop -immediately. +The ``cmd`` field must contain the command code. Some commands use the +``flags`` field for additional information. -A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` -call sends an implicit START command to the encoder if it has not been -started yet. After a STOP command, :ref:`read() <func-read>` calls will read +After a STOP command, :c:func:`read()` calls will read the remaining data buffered by the driver. When the buffer is empty, -:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>` +:c:func:`read()` will return zero and the next :c:func:`read()` call will restart the encoder. -A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` +call sends an implicit START command to the encoder if it has not been +started yet. Applies to both queues of mem2mem encoders. + +A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP to -the encoder, and all buffered data is discarded. +the encoder, and all buffered data is discarded. Applies to both queues of +mem2mem encoders. These ioctls are optional, not all drivers may support them. They were -introduced in Linux 2.6.21. - +introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem +encoders (as further documented in :ref:`encoder`). -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_encoder_cmd @@ -95,8 +89,7 @@ introduced in Linux 2.6.21. the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _encoder-cmds: @@ -109,21 +102,24 @@ introduced in Linux 2.6.21. - 0 - Start the encoder. When the encoder is already running or paused, this command does nothing. No flags are defined for this command. + + For a device implementing the :ref:`encoder`, once the drain sequence + is initiated with the ``V4L2_ENC_CMD_STOP`` command, it must be driven + to completion before this command can be invoked. Any attempt to + invoke the command while the drain sequence is in progress will trigger + an ``EBUSY`` error code. See :ref:`encoder` for more details. * - ``V4L2_ENC_CMD_STOP`` - 1 - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue until the end of the current *Group Of Pictures*, otherwise encoding will stop immediately. When the - encoder is already stopped, this command does nothing. mem2mem - encoders will send a ``V4L2_EVENT_EOS`` event when the last frame - has been encoded and all frames are ready to be dequeued and will - set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of - the capture queue to indicate there will be no new buffers - produced to dequeue. This buffer may be empty, indicated by the - driver setting the ``bytesused`` field to 0. Once the - ``V4L2_BUF_FLAG_LAST`` flag was set, the - :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, - but return an ``EPIPE`` error code. + encoder is already stopped, this command does nothing. + + For a device implementing the :ref:`encoder`, the command will initiate + the drain sequence as documented in :ref:`encoder`. No flags or other + arguments are accepted in this case. Any attempt to invoke the command + again before the sequence completes will trigger an ``EBUSY`` error + code. * - ``V4L2_ENC_CMD_PAUSE`` - 2 - Pause the encoder. When the encoder has not been started yet, the @@ -137,8 +133,7 @@ introduced in Linux 2.6.21. the encoder is already running, this command does nothing. No flags are defined for this command. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _encoder-flags: @@ -152,6 +147,7 @@ introduced in Linux 2.6.21. - Stop encoding at the end of the current *Group Of Pictures*, rather than immediately. + Does not apply to :ref:`encoder`. Return Value ============ @@ -160,6 +156,11 @@ On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. +EBUSY + A drain sequence of a device implementing the :ref:`encoder` is still in + progress. It is not allowed to issue another encoder command until it + completes. + EINVAL The ``cmd`` field is invalid. diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst index 89d6b860193a..a91c1a3f0e32 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_DV_TIMINGS: @@ -18,27 +12,26 @@ Name VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp ) - :name: VIDIOC_ENUM_DV_TIMINGS +.. c:macro:: VIDIOC_ENUM_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp ) - :name: VIDIOC_SUBDEV_ENUM_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_ENUM_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_enum_dv_timings`. - Description =========== @@ -72,10 +65,9 @@ pad number in the struct Attempts to enumerate timings on a pad that doesn't support them will return an ``EINVAL`` error code. - .. c:type:: v4l2_enum_dv_timings -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_enum_dv_timings :header-rows: 0 @@ -98,7 +90,6 @@ return an ``EINVAL`` error code. - ``timings`` - The timings. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst index a53dd3d7f7e2..000c154b0f98 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FMT: @@ -18,24 +12,22 @@ Name VIDIOC_ENUM_FMT - Enumerate image formats - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp ) - :name: VIDIOC_ENUM_FMT +.. c:macro:: VIDIOC_ENUM_FMT +``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_fmtdesc`. - Description =========== @@ -79,10 +71,11 @@ the ``mbus_code`` field is handled differently: formats shall not depend on the active configuration of the video device or device pipeline. +.. c:type:: v4l2_fmtdesc -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. cssclass:: longtable -.. c:type:: v4l2_fmtdesc +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_fmtdesc :header-rows: 0 @@ -144,8 +137,9 @@ the ``mbus_code`` field is handled differently: zero. +.. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}| -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. cssclass:: longtable .. _fmtdesc-flags: @@ -167,18 +161,72 @@ the ``mbus_code`` field is handled differently: - The hardware decoder for this compressed bytestream format (aka coded format) is capable of parsing a continuous bytestream. Applications do not need to parse the bytestream themselves to find the boundaries - between frames/fields. This flag can only be used in combination with - the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed + between frames/fields. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed formats only. This flag is valid for stateful decoders only. * - ``V4L2_FMT_FLAG_DYN_RESOLUTION`` - 0x0008 - Dynamic resolution switching is supported by the device for this compressed bytestream format (aka coded format). It will notify the user via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video - parameters are detected. This flag can only be used in combination - with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to - compressed formats only. It is also only applies to stateful codecs. - + parameters are detected. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to + compressed formats only. This flag is valid for stateful codecs only. + * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL`` + - 0x0010 + - The hardware encoder supports setting the ``CAPTURE`` coded frame + interval separately from the ``OUTPUT`` raw frame interval. + Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` + also sets the ``CAPTURE`` coded frame interval to the same value. + If this flag is set, then the ``CAPTURE`` coded frame interval can be + set to a different value afterwards. This is typically used for + offline encoding where the ``OUTPUT`` raw frame interval is used as + a hint for reserving hardware encoder resources and the ``CAPTURE`` coded + frame interval is the actual frame rate embedded in the encoded video + stream. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to + compressed formats only. This flag is valid for stateful encoders only. + * - ``V4L2_FMT_FLAG_CSC_COLORSPACE`` + - 0x0020 + - The driver allows the application to try to change the default + colorspace. This flag is relevant only for capture devices. + The application can ask to configure the colorspace of the capture device + when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_CSC_XFER_FUNC`` + - 0x0040 + - The driver allows the application to try to change the default + transfer function. This flag is relevant only for capture devices. + The application can ask to configure the transfer function of the capture + device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_CSC_YCBCR_ENC`` + - 0x0080 + - The driver allows the application to try to change the default + Y'CbCr encoding. This flag is relevant only for capture devices. + The application can ask to configure the Y'CbCr encoding of the capture device + when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_CSC_HSV_ENC`` + - 0x0080 + - The driver allows the application to try to change the default + HSV encoding. This flag is relevant only for capture devices. + The application can ask to configure the HSV encoding of the capture device + when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_CSC_QUANTIZATION`` + - 0x0100 + - The driver allows the application to try to change the default + quantization. This flag is relevant only for capture devices. + The application can ask to configure the quantization of the capture + device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst index 0e3db737371f..34cd39feaeaa 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FRAMEINTERVALS: @@ -18,25 +12,23 @@ Name VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp ) - :name: VIDIOC_ENUM_FRAMEINTERVALS +.. c:macro:: VIDIOC_ENUM_FRAMEINTERVALS +``int ioctl(int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frmivalenum` that contains a pixel format and size and receives a frame interval. - Description =========== @@ -98,7 +90,6 @@ other ioctl calls while it runs the frame interval enumeration. frame_rate = 1 / frame_interval - Structs ======= @@ -106,11 +97,8 @@ In the structs below, *IN* denotes a value that has to be filled in by the application, *OUT* denotes values that the driver fills in. The application should zero out all members except for the *IN* fields. - .. c:type:: v4l2_frmival_stepwise -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmival_stepwise :header-rows: 0 :stub-columns: 0 @@ -127,10 +115,9 @@ application should zero out all members except for the *IN* fields. - Frame interval step size [s]. - .. c:type:: v4l2_frmivalenum -.. tabularcolumns:: |p{1.8cm}|p{4.4cm}|p{2.4cm}|p{8.9cm}| +.. tabularcolumns:: |p{4.9cm}|p{3.3cm}|p{9.1cm}| .. flat-table:: struct v4l2_frmivalenum :header-rows: 0 @@ -165,19 +152,16 @@ application should zero out all members except for the *IN* fields. - * - __u32 - ``reserved[2]`` - - - Reserved space for future use. Must be zeroed by drivers and applications. - Enums ===== - .. c:type:: v4l2_frmivaltypes -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_frmivaltypes :header-rows: 0 @@ -194,7 +178,6 @@ Enums - 3 - Step-wise defined frame interval. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst index 1934d7da9743..7271fe37ce3f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FRAMESIZES: @@ -18,26 +12,24 @@ Name VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp ) - :name: VIDIOC_ENUM_FRAMESIZES +.. c:macro:: VIDIOC_ENUM_FRAMESIZES +``int ioctl(int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frmsizeenum` that contains an index and pixel format and receives a frame width and height. - Description =========== @@ -88,7 +80,6 @@ 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 size enumeration. - Structs ======= @@ -96,11 +87,8 @@ In the structs below, *IN* denotes a value that has to be filled in by the application, *OUT* denotes values that the driver fills in. The application should zero out all members except for the *IN* fields. - .. c:type:: v4l2_frmsize_discrete -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmsize_discrete :header-rows: 0 :stub-columns: 0 @@ -114,11 +102,8 @@ application should zero out all members except for the *IN* fields. - Height of the frame [pixel]. - .. c:type:: v4l2_frmsize_stepwise -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmsize_stepwise :header-rows: 0 :stub-columns: 0 @@ -144,10 +129,9 @@ application should zero out all members except for the *IN* fields. - Frame height step size [pixel]. - .. c:type:: v4l2_frmsizeenum -.. tabularcolumns:: |p{1.4cm}|p{5.9cm}|p{2.3cm}|p{8.0cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.8cm}|p{8.1cm}| .. flat-table:: struct v4l2_frmsizeenum :header-rows: 0 @@ -180,14 +164,12 @@ application should zero out all members except for the *IN* fields. applications. - Enums ===== - .. c:type:: v4l2_frmsizetypes -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_frmsizetypes :header-rows: 0 @@ -204,7 +186,6 @@ Enums - 3 - Step-wise defined frame size. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst index ee3ba67601fa..e385929bed62 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FREQ_BANDS: @@ -18,24 +12,22 @@ Name VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp ) - :name: VIDIOC_ENUM_FREQ_BANDS +.. c:macro:: VIDIOC_ENUM_FREQ_BANDS +``int ioctl(int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frequency_band`. - Description =========== @@ -48,8 +40,7 @@ fields, and zero out the ``reserved`` array of a struct This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability of the corresponding tuner/modulator is set. - -.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}| .. c:type:: v4l2_frequency_band @@ -117,8 +108,7 @@ of the corresponding tuner/modulator is set. Applications and drivers must set the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _band-modulation: @@ -137,7 +127,6 @@ of the corresponding tuner/modulator is set. - 0x08 - Amplitude Modulation, commonly used for analog radio. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst b/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst index afe4821e5863..7873e5434d3e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMAUDIO: @@ -18,24 +12,22 @@ Name VIDIOC_ENUMAUDIO - Enumerate audio inputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMAUDIO, struct v4l2_audio *argp ) - :name: VIDIOC_ENUMAUDIO +.. c:macro:: VIDIOC_ENUMAUDIO +``int ioctl(int fd, VIDIOC_ENUMAUDIO, struct v4l2_audio *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audio`. - Description =========== @@ -50,7 +42,6 @@ zero, incrementing by one until the driver returns ``EINVAL``. See :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` for a description of struct :c:type:`v4l2_audio`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst b/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst index 31c2ae460e2d..d4c3ba320834 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMAUDOUT: @@ -18,24 +12,22 @@ Name VIDIOC_ENUMAUDOUT - Enumerate audio outputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMAUDOUT, struct v4l2_audioout *argp ) - :name: VIDIOC_ENUMAUDOUT +.. c:macro:: VIDIOC_ENUMAUDOUT +``int ioctl(int fd, VIDIOC_ENUMAUDOUT, struct v4l2_audioout *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audioout`. - Description =========== @@ -55,7 +47,6 @@ zero, incrementing by one until the driver returns ``EINVAL``. See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct :c:type:`v4l2_audioout`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst index 510670bff3de..d5f0535bd866 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMINPUT: @@ -18,24 +12,22 @@ Name VIDIOC_ENUMINPUT - Enumerate video inputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp ) - :name: VIDIOC_ENUMINPUT +.. c:macro:: VIDIOC_ENUMINPUT +``int ioctl(int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_input`. - Description =========== @@ -46,8 +38,7 @@ fill the rest of the structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all inputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{3.0cm}|p{3.5cm}|p{10.8cm}| .. c:type:: v4l2_input @@ -110,8 +101,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{1.0cm}|p{9.7cm}| .. _input-type: @@ -133,8 +123,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - This input is a touch device for capturing raw touch data. - -.. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}| +.. tabularcolumns:: |p{5.6cm}|p{2.6cm}|p{9.1cm}| .. _input-status: @@ -205,8 +194,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - VTR time constant. [?] - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.4cm}|p{8.3cm}| .. _input-capabilities: @@ -229,7 +217,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see :ref:`v4l2-selections-common`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst index 591a99cf8000..06ee8386ae86 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMOUTPUT: @@ -18,24 +12,22 @@ Name VIDIOC_ENUMOUTPUT - Enumerate video outputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp ) - :name: VIDIOC_ENUMOUTPUT +.. c:macro:: VIDIOC_ENUMOUTPUT +``int ioctl(int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_output`. - Description =========== @@ -47,8 +39,7 @@ when the index is out of bounds. To enumerate all outputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_output @@ -105,8 +96,7 @@ shall begin at index zero, incrementing by one until the driver returns zero. - -.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.5cm}|p{0.6cm}|p{9.2cm}| .. _output-type: @@ -128,8 +118,7 @@ shall begin at index zero, incrementing by one until the driver returns - The video output will be copied to a :ref:`video overlay <overlay>`. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.4cm}|p{8.5cm}| .. _output-capabilities: @@ -152,7 +141,6 @@ shall begin at index zero, incrementing by one until the driver returns ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see :ref:`v4l2-selections-common`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst index 8a0508536c13..6af71b74d42e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMSTD: @@ -18,27 +12,26 @@ Name VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp ) - :name: VIDIOC_ENUMSTD +.. c:macro:: VIDIOC_ENUMSTD + +``int ioctl(int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp ) - :name: VIDIOC_SUBDEV_ENUMSTD +.. c:macro:: VIDIOC_SUBDEV_ENUMSTD +``int ioctl(int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_standard`. - Description =========== @@ -52,10 +45,9 @@ zero, incrementing by one until the driver returns ``EINVAL``. Drivers may enumerate a different set of standards after switching the video input or output. [#f1]_ - .. c:type:: v4l2_standard -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_standard :header-rows: 0 @@ -92,10 +84,9 @@ or output. [#f1]_ zero. - .. c:type:: v4l2_fract -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_fract :header-rows: 0 @@ -109,8 +100,7 @@ or output. [#f1]_ - ``denominator`` - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. _v4l2-std-id: @@ -127,7 +117,6 @@ or output. [#f1]_ standards. - .. code-block:: c #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) @@ -149,7 +138,6 @@ rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some PAL video recorders can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic PAL TV. - .. code-block:: c #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) @@ -159,7 +147,6 @@ a 50/60 Hz agnostic PAL TV. ``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC color modulation with a 4.43 MHz color subcarrier. - .. code-block:: c #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) @@ -182,7 +169,6 @@ terrestrial digital TV standards. Presently the V4L2 API does not support digital TV. See also the Linux DVB API at `https://linuxtv.org <https://linuxtv.org>`__. - .. code-block:: c #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B | @@ -235,7 +221,6 @@ support digital TV. See also the Linux DVB API at #define V4L2_STD_ALL (V4L2_STD_525_60 | V4L2_STD_625_50) - .. raw:: latex \begingroup @@ -310,7 +295,6 @@ support digital TV. See also the Linux DVB API at \endgroup - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst index 384a9be9eba0..982e8bcd9c47 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_EXPBUF: @@ -18,24 +12,22 @@ Name VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor. - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp ) - :name: VIDIOC_EXPBUF +.. c:macro:: VIDIOC_EXPBUF +``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_exportbuffer`. - Description =========== @@ -70,11 +62,9 @@ for details about importing DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it is no longer used to allow the associated memory to be reclaimed. - Examples ======== - .. code-block:: c int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd) @@ -94,7 +84,6 @@ Examples return 0; } - .. code-block:: c int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index, @@ -121,10 +110,9 @@ Examples return 0; } - .. c:type:: v4l2_exportbuffer -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_exportbuffer :header-rows: 0 @@ -162,7 +150,6 @@ Examples - Reserved field for future use. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst index 68531bcb62ab..bf61db04d12e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_AUDIO: @@ -18,27 +12,26 @@ Name VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp ) - :name: VIDIOC_G_AUDIO +.. c:macro:: VIDIOC_G_AUDIO + +``int ioctl(int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp ) - :name: VIDIOC_S_AUDIO +.. c:macro:: VIDIOC_S_AUDIO +``int ioctl(int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audio`. - Description =========== @@ -56,8 +49,7 @@ ioctl. Drivers may switch to a different audio mode if the request cannot be satisfied. However, this is a write-only ioctl, it does not return the actual new audio mode. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_audio @@ -87,8 +79,7 @@ return the actual new audio mode. the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _audio-capability: @@ -108,8 +99,7 @@ return the actual new audio mode. - Automatic Volume Level mode is supported. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _audio-mode: @@ -122,7 +112,6 @@ return the actual new audio mode. - 0x00001 - AVL mode is on. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst index e13b74bf5ce3..9ab15add2911 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_AUDOUT: @@ -18,27 +12,26 @@ Name VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp ) - :name: VIDIOC_G_AUDOUT +.. c:macro:: VIDIOC_G_AUDOUT + +``int ioctl(int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp ) - :name: VIDIOC_S_AUDOUT +.. c:macro:: VIDIOC_S_AUDOUT +``int ioctl(int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audioout`. - Description =========== @@ -63,10 +56,9 @@ as ``VIDIOC_G_AUDOUT`` does. Connectors on a TV card to loop back the received audio signal to a sound card are not audio outputs in this sense. - .. c:type:: v4l2_audioout -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_audioout :header-rows: 0 @@ -94,7 +86,6 @@ as ``VIDIOC_G_AUDOUT`` does. - Reserved for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst index 10e086be55d5..570d98308dc4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_CROP: @@ -18,27 +12,26 @@ Name VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_CROP, struct v4l2_crop *argp ) - :name: VIDIOC_G_CROP +.. c:macro:: VIDIOC_G_CROP + +``int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp ) - :name: VIDIOC_S_CROP +.. c:macro:: VIDIOC_S_CROP +``int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_crop`. - Description =========== @@ -76,10 +69,9 @@ been negotiated. When cropping is not supported then no parameters are changed and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code. - .. c:type:: v4l2_crop -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_crop :header-rows: 0 @@ -107,7 +99,6 @@ When cropping is not supported then no parameters are changed and Starting with kernel 4.13 both variations are allowed. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst index 9831b7514028..fd09677f64f8 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_CTRL: @@ -18,27 +12,26 @@ Name VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_CTRL, struct v4l2_control *argp ) - :name: VIDIOC_G_CTRL +.. c:macro:: VIDIOC_G_CTRL + +``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_CTRL, struct v4l2_control *argp ) - :name: VIDIOC_S_CTRL +.. c:macro:: VIDIOC_S_CTRL +``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_control`. - Description =========== @@ -62,10 +55,9 @@ These ioctls work only with user controls. For other control classes the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used. - .. c:type:: v4l2_control -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_control :header-rows: 0 @@ -79,7 +71,6 @@ These ioctls work only with user controls. For other control classes the - ``value`` - New value or current value. - Return Value ============ @@ -104,3 +95,6 @@ EBUSY EACCES Attempt to set a read-only control or to get a write-only control. + + Or if there is an attempt to set an inactive control and the driver is + not capable of caching the new value until the control is active again. diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst index 9a035a4ea0f0..6518d857c131 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_DV_TIMINGS: @@ -18,33 +12,34 @@ Name VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_G_DV_TIMINGS +.. c:macro:: VIDIOC_G_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp)`` + +.. c:macro:: VIDIOC_S_DV_TIMINGS -.. c:function:: int ioctl( int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_S_DV_TIMINGS +``int ioctl(int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_G_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_G_DV_TIMINGS -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_S_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp)`` +.. c:macro:: VIDIOC_SUBDEV_S_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings`. - Description =========== @@ -67,7 +62,6 @@ the current input or output does not support DV timings (e.g. if :ref:`VIDIOC_ENUMINPUT` does not set the ``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned. - Return Value ============ @@ -88,10 +82,12 @@ EBUSY EPERM ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_bt_timings +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_bt_timings :header-rows: 0 :stub-columns: 0 @@ -177,8 +173,7 @@ EPERM - Reserved for future extensions. Drivers and applications must set the array to zero. - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.1cm}| .. c:type:: v4l2_dv_timings @@ -201,7 +196,7 @@ EPERM * - } - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. _dv-timing-types: @@ -220,7 +215,9 @@ EPERM - 0 - BT.656/1120 timings -.. tabularcolumns:: |p{4.5cm}|p{12.8cm}| +.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| + +.. cssclass:: longtable .. _dv-bt-standards: @@ -243,7 +240,9 @@ EPERM There are no horizontal syncs/porches at all in this format. Total blanking timings must be set in hsync or vsync fields only. -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| + +.. cssclass:: longtable .. _dv-bt-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst index 0620f4cbbcbd..fc5535c50d61 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_EDID: @@ -18,34 +12,34 @@ Name VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_G_EDID +.. c:macro:: VIDIOC_G_EDID + +``int ioctl(int fd, VIDIOC_G_EDID, struct v4l2_edid *argp)`` + +.. c:macro:: VIDIOC_S_EDID -.. c:function:: int ioctl( int fd, VIDIOC_S_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_S_EDID +``int ioctl(int fd, VIDIOC_S_EDID, struct v4l2_edid *argp)`` +.. c:macro:: VIDIOC_SUBDEV_G_EDID -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_SUBDEV_G_EDID +``int ioctl(int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_SUBDEV_S_EDID +.. c:macro:: VIDIOC_SUBDEV_S_EDID +``int ioctl(int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_edid`. - Description =========== @@ -104,10 +98,9 @@ this will drive the hotplug pin low and/or block the source from reading the EDID data in some way. In any case, the end result is the same: the EDID is no longer available. - .. c:type:: v4l2_edid -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_edid :header-rows: 0 @@ -139,7 +132,6 @@ EDID is no longer available. - Pointer to memory that contains the EDID. The minimum size is ``blocks`` * 128. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst index 8aad30a7c6c3..c6792bbe3d04 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_ENC_INDEX: @@ -18,24 +12,22 @@ Name VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp ) - :name: VIDIOC_G_ENC_INDEX +.. c:macro:: VIDIOC_G_ENC_INDEX +``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_enc_idx`. - Description =========== @@ -62,8 +54,7 @@ will be zero. Currently this ioctl is only defined for MPEG-2 program streams and video elementary streams. - -.. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}| +.. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}| .. c:type:: v4l2_enc_idx @@ -90,8 +81,7 @@ video elementary streams. their ``offset``. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_enc_idx_entry @@ -123,8 +113,7 @@ video elementary streams. - Reserved for future extensions. Drivers must set the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _enc-idx-flags: @@ -147,7 +136,6 @@ video elementary streams. - *AND* the flags field with this mask to obtain the picture coding type. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index add17c9204cb..4d56c0528ad7 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_EXT_CTRLS: @@ -18,32 +12,30 @@ Name VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_G_EXT_CTRLS +.. c:macro:: VIDIOC_G_EXT_CTRLS +``int ioctl(int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_S_EXT_CTRLS +.. c:macro:: VIDIOC_S_EXT_CTRLS +``int ioctl(int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_TRY_EXT_CTRLS +.. c:macro:: VIDIOC_TRY_EXT_CTRLS +``int ioctl(int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_ext_controls`. - Description =========== @@ -61,7 +53,7 @@ by the ``controls`` fields. To get the current value of a set of controls applications initialize the ``id``, ``size`` and ``reserved2`` fields of each struct :c:type:`v4l2_ext_control` and call the -:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls must also set the ``string`` field. Controls of compound types (``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field. @@ -126,12 +118,15 @@ correct. This prevents the situation where only some of the controls were set/get. Only low-level errors (e. g. a failed i2c command) can still cause this situation. - -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{1.5cm}|p{11.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{4.0cm}|p{6.5cm}| .. c:type:: v4l2_ext_control -.. cssclass: longtable +.. raw:: latex + + \footnotesize + +.. cssclass:: longtable .. flat-table:: struct v4l2_ext_control :header-rows: 0 @@ -143,11 +138,12 @@ still cause this situation. - Identifies the control, set by the application. * - __u32 - ``size`` - - The total size in bytes of the payload of this control. This is - normally 0, but for pointer controls this should be set to the - size of the memory containing the payload, or that will receive - the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is - less than is required to store the payload result, then it is set + - The total size in bytes of the payload of this control. + * - :cspan:`2` The ``size`` field is normally 0, but for pointer + controls this should be set to the size of the memory that contains + the payload or that will receive the payload. + If :ref:`VIDIOC_G_EXT_CTRLS <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. @@ -189,10 +185,124 @@ still cause this situation. - ``p_u32`` - A pointer to a matrix control of unsigned 32-bit values. Valid if this control is of type ``V4L2_CTRL_TYPE_U32``. - * - :c:type:`v4l2_area` * + * - __s32 * + - ``p_s32`` + - A pointer to a matrix control of signed 32-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_INTEGER`` and + ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set. + * - __s64 * + - ``p_s64`` + - A pointer to a matrix control of signed 64-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_INTEGER64`` and + ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set. + * - struct :c:type:`v4l2_area` * - ``p_area`` - A pointer to a struct :c:type:`v4l2_area`. Valid if this control is of type ``V4L2_CTRL_TYPE_AREA``. + * - struct :c:type:`v4l2_ctrl_h264_sps` * + - ``p_h264_sps`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_sps`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SPS``. + * - struct :c:type:`v4l2_ctrl_h264_pps` * + - ``p_h264_pps`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_pps`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_PPS``. + * - struct :c:type:`v4l2_ctrl_h264_scaling_matrix` * + - ``p_h264_scaling_matrix`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_scaling_matrix`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``. + * - struct :c:type:`v4l2_ctrl_h264_pred_weights` * + - ``p_h264_pred_weights`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_pred_weights`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_PRED_WEIGHTS``. + * - struct :c:type:`v4l2_ctrl_h264_slice_params` * + - ``p_h264_slice_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_slice_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_h264_decode_params` * + - ``p_h264_decode_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_decode_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_fwht_params` * + - ``p_fwht_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_fwht_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_FWHT_PARAMS``. + * - struct :c:type:`v4l2_ctrl_vp8_frame` * + - ``p_vp8_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp8_frame`. Valid if this control is + of type ``V4L2_CTRL_TYPE_VP8_FRAME``. + * - struct :c:type:`v4l2_ctrl_mpeg2_sequence` * + - ``p_mpeg2_sequence`` + - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_sequence`. Valid if this control is + of type ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``. + * - struct :c:type:`v4l2_ctrl_mpeg2_picture` * + - ``p_mpeg2_picture`` + - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_picture`. Valid if this control is + of type ``V4L2_CTRL_TYPE_MPEG2_PICTURE``. + * - struct :c:type:`v4l2_ctrl_mpeg2_quantisation` * + - ``p_mpeg2_quantisation`` + - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_quantisation`. Valid if this control is + of type ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``. + * - struct :c:type:`v4l2_ctrl_vp9_compressed_hdr` * + - ``p_vp9_compressed_hdr_probs`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`. Valid if this + control is of type ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``. + * - struct :c:type:`v4l2_ctrl_vp9_frame` * + - ``p_vp9_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp9_frame`. Valid if this + control is of type ``V4L2_CTRL_TYPE_VP9_FRAME``. + * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` * + - ``p_hdr10_cll`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``. + * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` * + - ``p_hdr10_mastering`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``. + * - struct :c:type:`v4l2_ctrl_hevc_sps` * + - ``p_hevc_sps`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_sps`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SPS``. + * - struct :c:type:`v4l2_ctrl_hevc_pps` * + - ``p_hevc_pps`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_pps`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_PPS``. + * - struct :c:type:`v4l2_ctrl_hevc_slice_params` * + - ``p_hevc_slice_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_slice_params`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_hevc_scaling_matrix` * + - ``p_hevc_scaling_matrix`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``. + * - struct :c:type:`v4l2_ctrl_hevc_decode_params` * + - ``p_hevc_decode_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_decode_params`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_av1_sequence` * + - ``p_av1_sequence`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_sequence`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_SEQUENCE``. + * - struct :c:type:`v4l2_ctrl_av1_tile_group_entry` * + - ``p_av1_tile_group_entry`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_tile_group_entry`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY``. + * - struct :c:type:`v4l2_ctrl_av1_frame` * + - ``p_av1_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_frame`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_FRAME``. + * - struct :c:type:`v4l2_ctrl_av1_film_grain` * + - ``p_av1_film_grain`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_film_grain`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN``. + * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` * + - ``p_hdr10_cll_info`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``. + * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` * + - ``p_hdr10_mastering_display`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``. * - void * - ``ptr`` - A pointer to a compound type which can be an N-dimensional array @@ -202,8 +312,11 @@ still cause this situation. * - } - +.. raw:: latex -.. tabularcolumns:: |p{4.0cm}|p{2.2cm}|p{2.1cm}|p{8.2cm}| + \normalsize + +.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{10.8cm}| .. c:type:: v4l2_ext_controls @@ -217,29 +330,18 @@ still cause this situation. * - union { - (anonymous) * - __u32 - - ``ctrl_class`` - - The control class to which all controls belong, see - :ref:`ctrl-class`. Drivers that use a kernel framework for - handling controls will also accept a value of 0 here, meaning that - the controls can belong to any control class. Whether drivers - support this can be tested by setting ``ctrl_class`` to 0 and - calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that - succeeds, then the driver supports this feature. - * - __u32 - ``which`` - Which value of the control to get/set/try. - ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the - control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default + * - :cspan:`2` ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of + the control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default value of the control and ``V4L2_CTRL_WHICH_REQUEST_VAL`` indicates that these controls have to be retrieved from a request or tried/set for a request. In the latter case the ``request_fd`` field contains the file descriptor of the request that should be used. If the device does not support requests, then ``EACCES`` will be returned. - .. note:: - - When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware that you can only - get the default value of the control, you cannot set or try it. + When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware that 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 @@ -247,9 +349,12 @@ still cause this situation. just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and that require a control class here. You can test for such drivers - by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling - VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the - driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + by setting ``which`` to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling + :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a count of 0. + If that fails, then the driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + * - __u32 + - ``ctrl_class`` + - Deprecated name kept for backwards compatibility. Use ``which`` instead. * - } - * - __u32 @@ -257,7 +362,8 @@ still cause this situation. - The number of controls in the controls array. May also be zero. * - __u32 - ``error_idx`` - - Set by the driver in case of an error. If the error is associated + - Index of the failing control. Set by the driver in case of an error. + * - :cspan:`2` If the error is associated with a particular control, then ``error_idx`` is set to the index of that control. If the error is not related to a specific control, or the validation step failed (see below), then @@ -316,8 +422,9 @@ still cause this situation. Ignored if ``count`` equals zero. +.. tabularcolumns:: |p{7.3cm}|p{2.0cm}|p{8.0cm}| -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. cssclass:: longtable .. _ctrl-class: @@ -333,10 +440,10 @@ still cause this situation. :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this class. - * - ``V4L2_CTRL_CLASS_MPEG`` + * - ``V4L2_CTRL_CLASS_CODEC`` - 0x990000 - - The class containing MPEG compression controls. These controls are - described in :ref:`mpeg-controls`. + - The class containing stateful codec controls. These controls are + described in :ref:`codec-controls`. * - ``V4L2_CTRL_CLASS_CAMERA`` - 0x9a0000 - The class containing camera controls. These controls are described @@ -369,7 +476,18 @@ still cause this situation. - 0xa20000 - The class containing RF tuner controls. These controls are described in :ref:`rf-tuner-controls`. - + * - ``V4L2_CTRL_CLASS_DETECT`` + - 0xa30000 + - The class containing motion or object detection controls. These controls + are described in :ref:`detect-controls`. + * - ``V4L2_CTRL_CLASS_CODEC_STATELESS`` + - 0xa40000 + - The class containing stateless codec controls. These controls are + described in :ref:`codec-stateless-controls`. + * - ``V4L2_CTRL_CLASS_COLORIMETRY`` + - 0xa50000 + - The class containing colorimetry controls. These controls are + described in :ref:`colorimetry-controls`. Return Value ============ @@ -414,3 +532,6 @@ EACCES Or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL`` but the device does not support requests. + + Or if there is an attempt to set an inactive control and the driver is + not capable of caching the new value until the control is active again. diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst index 0124444419ae..b651e53643dd 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FBUF: @@ -18,27 +12,26 @@ Name VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp ) - :name: VIDIOC_G_FBUF +.. c:macro:: VIDIOC_G_FBUF + +``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp ) - :name: VIDIOC_S_FBUF +.. c:macro:: VIDIOC_S_FBUF +``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_framebuffer`. - Description =========== @@ -56,6 +49,9 @@ of a graphics card. A non-destructive overlay blends video images into a VGA signal or graphics into a video signal. *Video Output Overlays* are always non-destructive. +Destructive overlay support has been removed: with modern GPUs and CPUs +this is no longer needed, and it was always a very dangerous feature. + To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl with a pointer to a struct :c:type:`v4l2_framebuffer` structure. The driver fills all fields of the structure or returns an @@ -70,20 +66,13 @@ this structure, the driver prepares for the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error code. -To set the parameters for a *non-destructive Video Overlay*, +To set the parameters for a *Video Capture Overlay* applications must initialize the ``flags`` field, the ``fmt`` substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error code. -For a *destructive Video Overlay* applications must additionally provide -a ``base`` address. Setting up a DMA to a random memory location can -jeopardize the system security, its stability or even damage the -hardware, therefore only the superuser can set the parameters for a -destructive video overlay. - - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_framebuffer @@ -108,17 +97,14 @@ destructive video overlay. - ``base`` - - Physical base address of the framebuffer, that is the address of - the pixel in the top left corner of the framebuffer. [#f1]_ - * - - - - - - - This field is irrelevant to *non-destructive Video Overlays*. For - *destructive Video Overlays* applications must provide a base - address. The driver may accept only base addresses which are a - multiple of two, four or eight bytes. For *Video Output Overlays* - the driver must return a valid base address, so applications can + the pixel in the top left corner of the framebuffer. + For :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` this field is no longer supported + and the kernel will always set this to NULL. + For *Video Output Overlays* + the driver will return a valid base address, so applications can find the corresponding Linux framebuffer device (see - :ref:`osd`). + :ref:`osd`). For *Video Capture Overlays* this field will always be + NULL. * - struct - ``fmt`` - @@ -144,8 +130,7 @@ destructive video overlay. * - - - - - For *destructive Video Overlays* applications must initialize this - field. For *Video Output Overlays* the driver must return a valid + - For *Video Output Overlays* the driver must return a valid format. * - - @@ -173,13 +158,6 @@ destructive video overlay. This field is irrelevant to *non-destructive Video Overlays*. - For *destructive Video Overlays* both applications and drivers can - set this field to request padding bytes at the end of each line. - Drivers however may ignore the requested value, returning - ``width`` times bytes-per-pixel or a larger value required by the - hardware. That implies applications can just set this field to - zero to get a reasonable default. - For *Video Output Overlays* the driver must return a valid value. Video hardware may access padding bytes, therefore they must @@ -198,9 +176,8 @@ destructive video overlay. * - - __u32 - ``sizeimage`` - - This field is irrelevant to *non-destructive Video Overlays*. For - *destructive Video Overlays* applications must initialize this - field. For *Video Output Overlays* the driver must return a valid + - This field is irrelevant to *non-destructive Video Overlays*. + For *Video Output Overlays* the driver must return a valid format. Together with ``base`` it defines the framebuffer memory @@ -215,8 +192,7 @@ destructive video overlay. - ``priv`` - Reserved. Drivers and applications must set this field to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}| .. _framebuffer-cap: @@ -241,9 +217,11 @@ destructive video overlay. * - ``V4L2_FBUF_CAP_LIST_CLIPPING`` - 0x0004 - The device supports clipping using a list of clip rectangles. + Note that this is no longer supported. * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` - 0x0008 - The device supports clipping using a bit mask. + Note that this is no longer supported. * - ``V4L2_FBUF_CAP_LOCAL_ALPHA`` - 0x0010 - The device supports clipping/blending using the alpha channel of @@ -264,8 +242,7 @@ destructive video overlay. chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY`` - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}| .. _framebuffer-flags: @@ -339,7 +316,6 @@ destructive video overlay. other, so same ``chromakey`` field of struct :c:type:`v4l2_window` is being used. - Return Value ============ @@ -353,10 +329,3 @@ EPERM EINVAL The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable. - -.. [#f1] - A physical base address may not suit all platforms. GK notes in - theory we should pass something like PCI device + memory region + - offset instead. If you encounter problems please discuss on the - linux-media mailing list: - `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst index 88bb69ec07e2..675c385e5aca 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FMT: @@ -18,29 +12,30 @@ Name VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FMT, struct v4l2_format *argp ) - :name: VIDIOC_G_FMT +.. c:macro:: VIDIOC_G_FMT + +``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)`` + +.. c:macro:: VIDIOC_S_FMT + +``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FMT, struct v4l2_format *argp ) - :name: VIDIOC_S_FMT +.. c:macro:: VIDIOC_TRY_FMT -.. c:function:: int ioctl( int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp ) - :name: VIDIOC_TRY_FMT +``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_format`. - Description =========== @@ -92,10 +87,9 @@ recommended drivers are not required to implement this ioctl. The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output. - .. c:type:: v4l2_format -.. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}| +.. tabularcolumns:: |p{7.4cm}|p{4.4cm}|p{5.5cm}| .. flat-table:: struct v4l2_format :header-rows: 0 @@ -142,7 +136,6 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical * - } - - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst index 26300e0258a3..0d037665a89e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FREQUENCY: @@ -18,27 +12,26 @@ Name VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp ) - :name: VIDIOC_G_FREQUENCY +.. c:macro:: VIDIOC_G_FREQUENCY + +``int ioctl(int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp ) - :name: VIDIOC_S_FREQUENCY +.. c:macro:: VIDIOC_S_FREQUENCY +``int ioctl(int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frequency`. - Description =========== @@ -58,8 +51,7 @@ structure. When the requested frequency is not possible the driver assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a write-only ioctl, it does not return the actual new frequency. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_frequency @@ -96,7 +88,6 @@ write-only ioctl, it does not return the actual new frequency. - Reserved for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-input.rst b/Documentation/userspace-api/media/v4l/vidioc-g-input.rst index 294e346678c1..eee9ce51c797 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-input.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-input.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_INPUT: @@ -18,27 +12,26 @@ Name VIDIOC_G_INPUT - VIDIOC_S_INPUT - Query or select the current video input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_INPUT, int *argp ) - :name: VIDIOC_G_INPUT +.. c:macro:: VIDIOC_G_INPUT + +``int ioctl(int fd, VIDIOC_G_INPUT, int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_INPUT, int *argp ) - :name: VIDIOC_S_INPUT +.. c:macro:: VIDIOC_S_INPUT +``int ioctl(int fd, VIDIOC_S_INPUT, int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer an integer with input index. - Description =========== @@ -59,7 +52,6 @@ other parameters. Information about video inputs is available using the :ref:`VIDIOC_ENUMINPUT` ioctl. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst index 3b9981dcb8e0..d4565d2cc1f5 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_JPEGCOMP: @@ -18,27 +12,26 @@ Name VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp ) - :name: VIDIOC_G_JPEGCOMP +.. c:macro:: VIDIOC_G_JPEGCOMP + +``int ioctl(int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp ) - :name: VIDIOC_S_JPEGCOMP +.. c:macro:: VIDIOC_S_JPEGCOMP +``int ioctl(int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_jpegcompression`. - Description =========== @@ -61,8 +54,7 @@ stored in the JPEG-encoded fields. These define how the JPEG field is encoded. If you omit them, applications assume you've used standard encoding. You usually do want to add them. - -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| .. c:type:: v4l2_jpegcompression @@ -99,8 +91,7 @@ encoding. You usually do want to add them. control is exposed by a driver applications should use it instead and ignore this field. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _jpeg-markers: @@ -125,7 +116,6 @@ encoding. You usually do want to add them. - (1<<7) - App segment, driver will always use APP0 - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst index c2072f6e8756..6bdf925f9a4a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_MODULATOR: @@ -18,27 +12,26 @@ Name VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp ) - :name: VIDIOC_G_MODULATOR +.. c:macro:: VIDIOC_G_MODULATOR + +``int ioctl(int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp ) - :name: VIDIOC_S_MODULATOR +.. c:macro:: VIDIOC_S_MODULATOR +``int ioctl(int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_modulator`. - Description =========== @@ -67,8 +60,7 @@ context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. - -.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}| .. c:type:: v4l2_modulator @@ -127,9 +119,9 @@ To change the radio frequency the Drivers and applications must set the array to zero. +.. tabularcolumns:: |p{6.0cm}|p{2.0cm}|p{9.3cm}| - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. cssclass:: longtable .. _modulator-txsubchans: @@ -189,7 +181,6 @@ To change the radio frequency the - 0x0010 - Enable the RDS encoder for a radio FM transmitter. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst index cad477420fd7..dbcdd51dd2a8 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_OUTPUT: @@ -18,27 +12,26 @@ Name VIDIOC_G_OUTPUT - VIDIOC_S_OUTPUT - Query or select the current video output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_OUTPUT, int *argp ) - :name: VIDIOC_G_OUTPUT +.. c:macro:: VIDIOC_G_OUTPUT + +``int ioctl(int fd, VIDIOC_G_OUTPUT, int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_OUTPUT, int *argp ) - :name: VIDIOC_S_OUTPUT +.. c:macro:: VIDIOC_S_OUTPUT +``int ioctl(int fd, VIDIOC_S_OUTPUT, int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer with output index. - Description =========== @@ -53,14 +46,13 @@ To select a video output applications store the number of the desired output in an integer and call the :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a pointer to this integer. Side effects are possible. For example outputs may support different video standards, so the driver may implicitly -switch the current standard. standard. Because of these possible side +switch the current standard. Because of these possible side effects applications must select an output before querying or negotiating any other parameters. Information about video outputs is available using the :ref:`VIDIOC_ENUMOUTPUT` ioctl. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst index 42e9f6ee7a59..8b5600fbf013 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_PARM: @@ -18,51 +12,51 @@ Name VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_PARM, v4l2_streamparm *argp ) - :name: VIDIOC_G_PARM +.. c:macro:: VIDIOC_G_PARM + +``int ioctl(int fd, VIDIOC_G_PARM, v4l2_streamparm *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_PARM, v4l2_streamparm *argp ) - :name: VIDIOC_S_PARM +.. c:macro:: VIDIOC_S_PARM +``int ioctl(int fd, VIDIOC_S_PARM, v4l2_streamparm *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_streamparm`. - Description =========== -The current video standard determines a nominal number of frames per -second. If less than this number of frames is to be captured or output, -applications can request frame skipping or duplicating on the driver -side. This is especially useful when using the :ref:`read() <func-read>` or -:ref:`write() <func-write>`, which are not augmented by timestamps or sequence -counters, and to avoid unnecessary data copying. +Applications can request a different frame interval. The capture or +output device will be reconfigured to support the requested frame +interval if possible. Optionally drivers may choose to skip or +repeat frames to achieve the requested frame interval. + +For stateful encoders (see :ref:`encoder`) this represents the +frame interval that is typically embedded in the encoded video stream. Changing the frame interval shall never change the format. Changing the format, on the other hand, may change the frame interval. Further these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For implications see the -section discussing the :ref:`read() <func-read>` function. +section discussing the :c:func:`read()` function. To get and set the streaming parameters applications call the -:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a +:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and +:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a pointer to a struct :c:type:`v4l2_streamparm` which contains a union holding separate parameters for input and output devices. - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.7cm}|p{3.5cm}|p{10.1cm}| .. c:type:: v4l2_streamparm @@ -91,11 +85,9 @@ union holding separate parameters for input and output devices. - ``raw_data``\ [200] - A place holder for future extensions. * - } - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_captureparm @@ -113,14 +105,21 @@ union holding separate parameters for input and output devices. * - struct :c:type:`v4l2_fract` - ``timeperframe`` - This is the desired period between successive frames captured by - the driver, in seconds. The field is intended to skip frames on - the driver side, saving I/O bandwidth. + the driver, in seconds. + * - :cspan:`2` + + This will configure the speed at which the video source (e.g. a sensor) + generates video frames. If the speed is fixed, then the driver may + choose to skip or repeat frames in order to achieve the requested + frame rate. + + For stateful encoders (see :ref:`encoder`) this represents the + frame interval that is typically embedded in the encoded video stream. Applications store here the desired frame period, drivers return - the actual frame period, which must be greater or equal to the - nominal frame period determined by the current video standard - (struct :c:type:`v4l2_standard` ``frameperiod`` - field). Changing the video standard (also implicitly by switching + the actual frame period. + + Changing the video standard (also implicitly by switching the video input) may reset this parameter to the nominal frame period. To reset manually applications can just set this field to zero. @@ -136,7 +135,7 @@ union holding separate parameters for input and output devices. * - __u32 - ``readbuffers`` - Applications set this field to the desired number of buffers used - internally by the driver in :ref:`read() <func-read>` mode. + internally by the driver in :c:func:`read()` mode. Drivers return the actual number of buffers. When an application requests zero buffers, drivers should just return the current setting rather than the minimum or an error code. For details see @@ -147,8 +146,7 @@ union holding separate parameters for input and output devices. the array to zero. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_outputparm @@ -170,14 +168,18 @@ union holding separate parameters for input and output devices. * - :cspan:`2` The field is intended to repeat frames on the driver side in - :ref:`write() <func-write>` mode (in streaming mode timestamps + :c:func:`write()` mode (in streaming mode timestamps can be used to throttle the output), saving I/O bandwidth. + For stateful encoders (see :ref:`encoder`) this represents the + frame interval that is typically embedded in the encoded video stream + and it provides a hint to the encoder of the speed at which raw + frames are queued up to the encoder. + Applications store here the desired frame period, drivers return - the actual frame period, which must be greater or equal to the - nominal frame period determined by the current video standard - (struct :c:type:`v4l2_standard` ``frameperiod`` - field). Changing the video standard (also implicitly by switching + the actual frame period. + + Changing the video standard (also implicitly by switching the video output) may reset this parameter to the nominal frame period. To reset manually applications can just set this field to zero. @@ -193,7 +195,7 @@ union holding separate parameters for input and output devices. * - __u32 - ``writebuffers`` - Applications set this field to the desired number of buffers used - internally by the driver in :ref:`write() <func-write>` mode. Drivers + internally by the driver in :c:func:`write()` mode. Drivers return the actual number of buffers. When an application requests zero buffers, drivers should just return the current setting rather than the minimum or an error code. For details see @@ -204,8 +206,7 @@ union holding separate parameters for input and output devices. the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _parm-caps: @@ -216,12 +217,11 @@ union holding separate parameters for input and output devices. * - ``V4L2_CAP_TIMEPERFRAME`` - 0x1000 - - The frame skipping/repeating controlled by the ``timeperframe`` - field is supported. + - The frame period can be modified by setting the ``timeperframe`` + field. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _parm-flags: @@ -259,8 +259,7 @@ union holding separate parameters for input and output devices. - Moving objects in the image might have excessive motion blur. - - Capture might only work through the :ref:`read() <func-read>` call. - + - Capture might only work through the :c:func:`read()` call. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst index c8add130c7a4..3031256159c3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_PRIORITY: @@ -18,27 +12,26 @@ Name VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp ) - :name: VIDIOC_G_PRIORITY +.. c:macro:: VIDIOC_G_PRIORITY + +``int ioctl(int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp ) - :name: VIDIOC_S_PRIORITY +.. c:macro:: VIDIOC_S_PRIORITY +``int ioctl(int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an enum :c:type:`v4l2_priority` type. - Description =========== @@ -50,10 +43,9 @@ To request an access priority applications store the desired priority in an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to this variable. - .. c:type:: v4l2_priority -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_priority :header-rows: 0 @@ -85,7 +77,6 @@ with a pointer to this variable. it blocks any other fd from changing device properties. Usually applications which must not be interrupted, like video recording. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst index faab0454b1e4..2b5b27260741 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_SELECTION: @@ -18,23 +12,22 @@ Name VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp ) - :name: VIDIOC_G_SELECTION +.. c:macro:: VIDIOC_G_SELECTION +``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp ) - :name: VIDIOC_S_SELECTION +.. c:macro:: VIDIOC_S_SELECTION +``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_selection`. @@ -122,7 +115,6 @@ constraints. Selection targets and flags are documented in :ref:`v4l2-selections-common`. - .. _sel-const-adjust: .. kernel-figure:: constraints.svg @@ -135,10 +127,9 @@ Selection targets and flags are documented in - .. c:type:: v4l2_selection -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_selection :header-rows: 0 @@ -175,7 +166,6 @@ Selection targets and flags are documented in Starting with kernel 4.13 both variations are allowed. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst index 7a62c4f4e37f..90d40f6af57b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_SLICED_VBI_CAP: @@ -18,24 +12,22 @@ Name VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp ) - :name: VIDIOC_G_SLICED_VBI_CAP +.. c:macro:: VIDIOC_G_SLICED_VBI_CAP +``int ioctl(int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_sliced_vbi_cap`. - Description =========== @@ -51,10 +43,9 @@ the sliced VBI API is unsupported or ``type`` is invalid. The ``type`` field was added, and the ioctl changed from read-only to write-read, in Linux 2.6.19. - .. c:type:: v4l2_sliced_vbi_cap -.. tabularcolumns:: |p{1.2cm}|p{4.2cm}|p{4.1cm}|p{4.0cm}|p{4.0cm}| +.. tabularcolumns:: |p{1.4cm}|p{4.4cm}|p{4.5cm}|p{3.6cm}|p{3.6cm}| .. flat-table:: struct v4l2_sliced_vbi_cap :header-rows: 0 @@ -127,12 +118,11 @@ the sliced VBI API is unsupported or ``type`` is invalid. See also :ref:`vbi-525` and :ref:`vbi-625`. - .. raw:: latex \scriptsize -.. tabularcolumns:: |p{3.5cm}|p{1.0cm}|p{2.0cm}|p{2.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{3.9cm}|p{1.0cm}|p{2.0cm}|p{3.0cm}|p{7.0cm}| .. _vbi-services: @@ -172,13 +162,7 @@ the sliced VBI API is unsupported or ``type`` is invalid. :ref:`itu1119` - PAL/SECAM line 23 - - - - :: - - Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + - See :ref:`v4l2-sliced-vbi-cap-wss-625-payload` below. * - ``V4L2_SLICED_VBI_525`` - 0x1000 - :cspan:`2` Set of services applicable to 525 line systems. @@ -186,10 +170,26 @@ the sliced VBI API is unsupported or ``type`` is invalid. - 0x4401 - :cspan:`2` Set of services applicable to 625 line systems. + .. raw:: latex \normalsize +.. _v4l2-sliced-vbi-cap-wss-625-payload: + +V4L2_SLICED_VBI_CAP WSS_625 payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The payload for ``V4L2_SLICED_WSS_625`` is: + + +-----+------------------+-----------------------+ + |Byte | 0 | 1 | + +-----+--------+---------+-----------+-----------+ + | | msb | lsb | msb | lsb | + | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 | + +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-std.rst b/Documentation/userspace-api/media/v4l/vidioc-g-std.rst index 6d8cb7f29ac6..da91fe07d9e0 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-std.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-std.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_STD: @@ -18,33 +12,34 @@ Name VIDIOC_G_STD - VIDIOC_S_STD - VIDIOC_SUBDEV_G_STD - VIDIOC_SUBDEV_S_STD - Query or select the video standard of the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_STD, v4l2_std_id *argp ) - :name: VIDIOC_G_STD +.. c:macro:: VIDIOC_G_STD + +``int ioctl(int fd, VIDIOC_G_STD, v4l2_std_id *argp)`` + +.. c:macro:: VIDIOC_S_STD -.. c:function:: int ioctl( int fd, VIDIOC_S_STD, const v4l2_std_id *argp ) - :name: VIDIOC_S_STD +``int ioctl(int fd, VIDIOC_S_STD, const v4l2_std_id *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_G_STD +.. c:macro:: VIDIOC_SUBDEV_G_STD -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_S_STD +``int ioctl(int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp)`` +.. c:macro:: VIDIOC_SUBDEV_S_STD + +``int ioctl(int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to :c:type:`v4l2_std_id`. - Description =========== diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst index 40bff6f0a88d..b0522f1ff7a4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_TUNER: @@ -18,27 +12,26 @@ Name VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp ) - :name: VIDIOC_G_TUNER +.. c:macro:: VIDIOC_G_TUNER + +``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp ) - :name: VIDIOC_S_TUNER +.. c:macro:: VIDIOC_S_TUNER +``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_tuner`. - Description =========== @@ -66,8 +59,7 @@ to zero. The term 'tuner' means SDR receiver in this context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. - - .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{6.6cm}|p{6.6cm}| + .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}| .. c:type:: v4l2_tuner @@ -190,8 +182,7 @@ To change the radio frequency the Drivers and applications must set the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. c:type:: v4l2_tuner_type @@ -214,8 +205,7 @@ To change the radio frequency the - 5 - Tuner controls the RF part of a Software Digital Radio (SDR) - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm}| .. _tuner-capability: @@ -306,8 +296,7 @@ To change the radio frequency the instead of 62.5 kHz. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _tuner-rxsubchans: @@ -345,8 +334,7 @@ To change the radio frequency the - The tuner receives an RDS channel. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _tuner-audmode: diff --git a/Documentation/userspace-api/media/v4l/vidioc-log-status.rst b/Documentation/userspace-api/media/v4l/vidioc-log-status.rst index 64c06fa72b9c..c218747be762 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-log-status.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-log-status.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_LOG_STATUS: @@ -18,20 +12,18 @@ Name VIDIOC_LOG_STATUS - Log driver status information - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_LOG_STATUS) - :name: VIDIOC_LOG_STATUS +.. c:macro:: VIDIOC_LOG_STATUS +``int ioctl(int fd, VIDIOC_LOG_STATUS)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -47,7 +39,6 @@ Mismatches may give an indication where the problem is. This ioctl is optional and not all drivers support it. It was introduced in Linux 2.6.15. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-overlay.rst b/Documentation/userspace-api/media/v4l/vidioc-overlay.rst index 74310ff486ba..f2efaaba24c0 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-overlay.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-overlay.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_OVERLAY: @@ -18,24 +12,22 @@ Name VIDIOC_OVERLAY - Start or stop video overlay - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_OVERLAY, const int *argp ) - :name: VIDIOC_OVERLAY +.. c:macro:: VIDIOC_OVERLAY +``int ioctl(int fd, VIDIOC_OVERLAY, const int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer. - Description =========== @@ -48,7 +40,6 @@ Drivers do not support :ref:`VIDIOC_STREAMON` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst index b6c09d5b128f..45bb1eab2c2d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_PREPARE_BUF: @@ -18,24 +12,22 @@ Name VIDIOC_PREPARE_BUF - Prepare a buffer for I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp ) - :name: VIDIOC_PREPARE_BUF +.. c:macro:: VIDIOC_PREPARE_BUF +``int ioctl(int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -48,7 +40,6 @@ in advance saves time during the actual I/O. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst index ec0a54fbeb43..e4b3d9beb9ab 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QBUF: @@ -18,27 +12,26 @@ Name VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_QBUF +.. c:macro:: VIDIOC_QBUF + +``int ioctl(int fd, VIDIOC_QBUF, struct v4l2_buffer *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_DQBUF +.. c:macro:: VIDIOC_DQBUF +``int ioctl(int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -132,7 +125,7 @@ Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled queue. They just set the ``type``, ``memory`` and ``reserved`` fields of a struct :c:type:`v4l2_buffer` as above, when ``VIDIOC_DQBUF`` is called with a pointer to this structure the driver -fills the remaining fields or returns an error code. The driver may also +fills all remaining fields or returns an error code. The driver may also set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a non-critical (recoverable) streaming error. In such case the application may continue as normal, but should be aware that data in the dequeued @@ -149,13 +142,12 @@ API is used the ``m.fd`` fields of the passed array of struct By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the -:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns +:c:func:`open()` function, ``VIDIOC_DQBUF`` returns immediately with an ``EAGAIN`` error code when no buffer is available. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ @@ -171,7 +163,7 @@ EINVAL The buffer ``type`` is not supported, or the ``index`` is out of bounds, or no buffers have been allocated yet, or the ``userptr`` or ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was - set but the the given ``request_fd`` was invalid, or ``m.fd`` was + set but the given ``request_fd`` was invalid, or ``m.fd`` was an invalid DMABUF file descriptor. EIO diff --git a/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst index ab86408446f3..5afdc4b4dc2d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERY_DV_TIMINGS: @@ -18,27 +12,26 @@ Name VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_QUERY_DV_TIMINGS +.. c:macro:: VIDIOC_QUERY_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_QUERY_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings`. - Description =========== @@ -72,7 +65,6 @@ and returns ``ERANGE``. In that case the application can call found timings with the hardware's capabilities in order to give more precise feedback to the user. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst index 646f91140ccf..6c615e893866 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYBUF: @@ -18,24 +12,22 @@ Name VIDIOC_QUERYBUF - Query the status of a buffer - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_QUERYBUF +.. c:macro:: VIDIOC_QUERYBUF +``int ioctl(int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -74,7 +66,6 @@ flags, they are meaningless in this context. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst index 666ac4d42051..6c57b8428356 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYCAP: @@ -18,24 +12,22 @@ Name VIDIOC_QUERYCAP - Query device capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp ) - :name: VIDIOC_QUERYCAP +.. c:macro:: VIDIOC_QUERYCAP +``int ioctl(int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_capability`. - Description =========== @@ -46,10 +38,11 @@ pointer to a struct :c:type:`v4l2_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns an ``EINVAL`` error code. +.. c:type:: v4l2_capability -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| -.. c:type:: v4l2_capability +.. cssclass:: longtable .. flat-table:: struct v4l2_capability :header-rows: 0 @@ -139,8 +132,7 @@ specification the ioctl returns an ``EINVAL`` error code. zero. - -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{2.6cm}|p{7.7cm}| .. _device-capabilities: @@ -168,11 +160,11 @@ specification the ioctl returns an ``EINVAL`` error code. - The device supports the :ref:`multi-planar API <planar-apis>` through the :ref:`Video Output <output>` interface. * - ``V4L2_CAP_VIDEO_M2M`` - - 0x00004000 + - 0x00008000 - The device supports the single-planar API through the Video Memory-To-Memory interface. * - ``V4L2_CAP_VIDEO_M2M_MPLANE`` - - 0x00008000 + - 0x00004000 - The device supports the :ref:`multi-planar API <planar-apis>` through the Video Memory-To-Memory interface. * - ``V4L2_CAP_VIDEO_OVERLAY`` @@ -250,11 +242,8 @@ specification the ioctl returns an ``EINVAL`` error code. - The device supports the :ref:`metadata` capture interface. * - ``V4L2_CAP_READWRITE`` - 0x01000000 - - The device supports the :ref:`read() <rw>` and/or - :ref:`write() <rw>` I/O methods. - * - ``V4L2_CAP_ASYNCIO`` - - 0x02000000 - - The device supports the :ref:`asynchronous <async>` I/O methods. + - The device supports the :c:func:`read()` and/or + :c:func:`write()` I/O methods. * - ``V4L2_CAP_STREAMING`` - 0x04000000 - The device supports the :ref:`streaming <mmap>` I/O method. @@ -276,7 +265,6 @@ specification the ioctl returns an ``EINVAL`` error code. only appear in the ``capabilities`` field and never in the ``device_caps`` field. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index fbb0038d86bf..4d38acafe8e1 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYCTRL: @@ -18,31 +12,29 @@ Name VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items - Synopsis ======== -.. c:function:: int ioctl( int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp ) - :name: VIDIOC_QUERYCTRL +``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)`` + +.. c:macro:: VIDIOC_QUERY_EXT_CTRL -.. c:function:: int ioctl( int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp ) - :name: VIDIOC_QUERY_EXT_CTRL +``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp ) - :name: VIDIOC_QUERYMENU +.. c:macro:: VIDIOC_QUERYMENU +``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl` or :c:type:`v4l2_querymenu` (depending on the ioctl). - Description =========== @@ -102,8 +94,7 @@ inclusive. See also the examples in :ref:`control`. - -.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}| .. _v4l2-queryctrl: @@ -181,8 +172,7 @@ See also the examples in :ref:`control`. zero. - -.. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}| .. _v4l2-query-ext-ctrl: @@ -282,8 +272,7 @@ See also the examples in :ref:`control`. the array to zero. - -.. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| .. _v4l2-querymenu: @@ -317,11 +306,13 @@ See also the examples in :ref:`control`. - Reserved for future extensions. Drivers must set the array to zero. +.. c:type:: v4l2_ctrl_type +.. raw:: latex -.. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}| + \footnotesize -.. c:type:: v4l2_ctrl_type +.. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm}|p{1.5cm}|p{6.8cm}| .. cssclass:: longtable @@ -426,18 +417,24 @@ See also the examples in :ref:`control`. - any - An unsigned 32-bit valued control ranging from minimum to maximum inclusive. The step value indicates the increment between values. - * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS`` + * - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION`` - n/a - n/a - n/a - - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2 - slice parameters for stateless video decoders. - * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION`` + - A struct :c:type:`v4l2_ctrl_mpeg2_quantisation`, containing MPEG-2 + quantisation matrices for stateless video decoders. + * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_mpeg2_sequence`, containing MPEG-2 + sequence parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE`` - n/a - n/a - n/a - - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2 - quantization matrices for stateless video decoders. + - A struct :c:type:`v4l2_ctrl_mpeg2_picture`, containing MPEG-2 + picture parameters for stateless video decoders. * - ``V4L2_CTRL_TYPE_AREA`` - n/a - n/a @@ -474,6 +471,12 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 decode parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_FWHT_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT + parameters for stateless video decoders. * - ``V4L2_CTRL_TYPE_HEVC_SPS`` - n/a - n/a @@ -492,13 +495,71 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC slice parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`, containing HEVC + scaling matrix for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP8_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8 + frame parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_decode_params`, containing HEVC + decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`, containing VP9 + probabilities updates for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP9_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9 + frame decode parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_SEQUENCE`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_sequence`, containing AV1 Sequence OBU + decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_tile_group_entry`, containing AV1 Tile Group + OBU decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_frame`, containing AV1 Frame/Frame + Header OBU decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_film_grain`, containing AV1 Film Grain + parameters for stateless video decoders. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. raw:: latex -.. _control-flags: + \normalsize + +.. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}| .. cssclass:: longtable +.. _control-flags: + .. flat-table:: Control Flags :header-rows: 0 :stub-columns: 0 @@ -588,7 +649,14 @@ See also the examples in :ref:`control`. ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or streaming is in progress since most drivers do not support changing the format in that case. - + * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY`` + - 0x0800 + - This control is a dynamically sized 1-dimensional array. It + behaves the same as a regular array, except that the number + of elements as reported by the ``elems`` field is between 1 and + ``dims[0]``. So setting the control with a differently sized + array will change the ``elems`` field when the control is + queried afterwards. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querystd.rst b/Documentation/userspace-api/media/v4l/vidioc-querystd.rst index 899f0ef6eefe..4a88287d8f61 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querystd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querystd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYSTD: @@ -18,27 +12,26 @@ Name VIDIOC_QUERYSTD - VIDIOC_SUBDEV_QUERYSTD - Sense the video standard received by the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp ) - :name: VIDIOC_QUERYSTD +.. c:macro:: VIDIOC_QUERYSTD + +``int ioctl(int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_QUERYSTD +.. c:macro:: VIDIOC_SUBDEV_QUERYSTD +``int ioctl(int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to :c:type:`v4l2_std_id`. - Description =========== @@ -65,7 +58,6 @@ or output. 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/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst index b6d52083707b..0b3a41a45d05 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_REQBUFS: @@ -18,19 +12,18 @@ Name VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp ) - :name: VIDIOC_REQBUFS +.. c:macro:: VIDIOC_REQBUFS +``int ioctl(int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_requestbuffers`. @@ -76,10 +69,9 @@ fds are closed. A ``count`` value of zero frees or orphans all buffers, after aborting or finishing any DMA in progress, an implicit :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`. - .. c:type:: v4l2_requestbuffers -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_requestbuffers :header-rows: 0 @@ -112,12 +104,13 @@ aborting or finishing any DMA in progress, an implicit ``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will free any previously allocated buffers, so this is typically something that will be done at the start of the application. - * - __u32 - - ``reserved``\ [1] - - A place holder for future extensions. Drivers and applications - must set the array to zero. - -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| + * - __u8 + - ``flags`` + - Specifies additional buffer management attributes. + See :ref:`memory-flags`. + * - __u8 + - ``reserved``\ [3] + - Reserved for future extensions. .. _v4l2-buf-capabilities: .. _V4L2-BUF-CAP-SUPPORTS-MMAP: @@ -126,6 +119,14 @@ aborting or finishing any DMA in progress, an implicit .. _V4L2-BUF-CAP-SUPPORTS-REQUESTS: .. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS: .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF: +.. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS: +.. _V4L2-BUF-CAP-SUPPORTS-MAX-NUM-BUFFERS: + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.1cm}|p{2.2cm}|p{7.0cm}| .. cssclass:: longtable @@ -156,6 +157,18 @@ aborting or finishing any DMA in progress, an implicit - Only valid for stateless decoders. If set, then userspace can set the ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag to hold off on returning the capture buffer until the OUTPUT timestamp changes. + * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS`` + - 0x00000040 + - This capability is set by the driver to indicate that the queue supports + cache and memory management hints. However, it's only valid when the + queue is used for :ref:`memory mapping <mmap>` streaming I/O. See + :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>`, + :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>` and + :ref:`V4L2_MEMORY_FLAG_NON_COHERENT <V4L2-MEMORY-FLAG-NON-COHERENT>`. + +.. raw:: latex + + \normalsize Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst index 4c16e7e89cfa..ed10f380579a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_S_HW_FREQ_SEEK: @@ -18,24 +12,22 @@ Name VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp ) - :name: VIDIOC_S_HW_FREQ_SEEK +.. c:macro:: VIDIOC_S_HW_FREQ_SEEK +``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_hw_freq_seek`. - Description =========== @@ -66,8 +58,7 @@ set. If this ioctl is called from a non-blocking filehandle, then ``EAGAIN`` error code is returned and no seek takes place. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_hw_freq_seek @@ -123,7 +114,6 @@ error code is returned and no seek takes place. - Reserved for future extensions. Applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-streamon.rst b/Documentation/userspace-api/media/v4l/vidioc-streamon.rst index 13e0136d5c25..1a79313a29fa 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-streamon.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-streamon.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_STREAMON: @@ -18,22 +12,22 @@ Name VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_STREAMON, const int *argp ) - :name: VIDIOC_STREAMON +.. c:macro:: VIDIOC_STREAMON + +``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_STREAMOFF, const int *argp ) - :name: VIDIOC_STREAMOFF +.. c:macro:: VIDIOC_STREAMOFF +``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer. @@ -49,8 +43,7 @@ the capture or output process during streaming Capture hardware is disabled and no input buffers are filled (if there are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON`` has been called. Output hardware is disabled and no video signal is -produced until ``VIDIOC_STREAMON`` has been called. The ioctl will -succeed when at least one output buffer is in the incoming queue. +produced until ``VIDIOC_STREAMON`` has been called. Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has been called for both the capture and output stream types. @@ -91,7 +84,6 @@ state as mentioned above. no notion of starting or stopping "now". Buffer timestamps can be used to synchronize with other events. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst index 3527745935c7..c935bacc3bc2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL: @@ -18,24 +12,22 @@ Name VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_interval_enum`. - Description =========== @@ -69,7 +61,7 @@ multiple pads of the same sub-device is not defined. .. c:type:: v4l2_subdev_frame_interval_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_interval_enum :header-rows: 0 @@ -100,11 +92,13 @@ multiple pads of the same sub-device is not defined. - Frame intervals to be enumerated, from enum :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -113,8 +107,7 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_frame_interval_enum` - ``pad`` references a non-existing pad, one of the ``code``, - ``width`` or ``height`` fields are invalid for the given pad or the - ``index`` field is out of bounds. + The struct :c:type:`v4l2_subdev_frame_interval_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, one of the + ``code``, ``width`` or ``height`` fields are invalid for the given pad, or + the ``index`` field is out of bounds. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst index eb7401991d02..65f0cfeca973 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE: @@ -18,39 +12,49 @@ Name VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_FRAME_SIZE +.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_SIZE +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_size_enum`. - Description =========== -This ioctl allows applications to enumerate all frame sizes supported by -a sub-device on the given pad for the given media bus format. Supported -formats can be retrieved with the +This ioctl allows applications to access the enumeration of frame sizes +supported by a sub-device on the specified pad +for the specified media bus format. +Supported formats can be retrieved with the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl. -To enumerate frame sizes applications initialize the ``pad``, ``which`` -, ``code`` and ``index`` fields of the struct -:c:type:`v4l2_subdev_mbus_code_enum` and -call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the -structure. Drivers fill the minimum and maximum frame sizes or return an -EINVAL error code if one of the input parameters is invalid. +The enumerations are defined by the driver, and indexed using the ``index`` field +of the struct :c:type:`v4l2_subdev_frame_size_enum`. +Each pair of ``pad`` and ``code`` correspond to a separate enumeration. +Each enumeration starts with the ``index`` of 0, and +the lowest invalid index marks the end of the enumeration. + +Therefore, to enumerate frame sizes allowed on the specified pad +and using the specified mbus format, initialize the +``pad``, ``which``, and ``code`` fields to desired values, +and set ``index`` to 0. +Then call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the +structure. + +A successful call will return with minimum and maximum frame sizes filled in. +Repeat with increasing ``index`` until ``EINVAL`` is received. +``EINVAL`` means that either no more entries are available in the enumeration, +or that an input parameter was invalid. Sub-devices that only support discrete frame sizes (such as most sensors) will return one or more frame sizes with identical minimum and @@ -69,10 +73,9 @@ current values of V4L2 controls. See :ref:`VIDIOC_SUBDEV_G_FMT` for more information about try formats. - .. c:type:: v4l2_subdev_frame_size_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_size_enum :header-rows: 0 @@ -81,36 +84,40 @@ information about try formats. * - __u32 - ``index`` - - Number of the format in the enumeration, set by the application. + - Index of the frame size in the enumeration belonging to the given pad + and format. Filled in by the application. * - __u32 - ``pad`` - Pad number as reported by the media controller API. + Filled in by the application. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the application. * - __u32 - ``min_width`` - - Minimum frame width, in pixels. + - Minimum frame width, in pixels. Filled in by the driver. * - __u32 - ``max_width`` - - Maximum frame width, in pixels. + - Maximum frame width, in pixels. Filled in by the driver. * - __u32 - ``min_height`` - - Minimum frame height, in pixels. + - Minimum frame height, in pixels. Filled in by the driver. * - __u32 - ``max_height`` - - Maximum frame height, in pixels. + - Maximum frame height, in pixels. Filled in by the driver. * - __u32 - ``which`` - Frame sizes to be enumerated, from enum :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -119,7 +126,6 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_frame_size_enum` - ``pad`` references a non-existing pad, the ``code`` is invalid for - the given pad or the ``index`` field is out of bounds. + The struct :c:type:`v4l2_subdev_frame_size_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, the ``code`` + is invalid for the given pad, or the ``index`` field is out of bounds. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst index 35b8607203a4..3050966b199f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_MBUS_CODE: @@ -18,46 +12,56 @@ Name VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_MBUS_CODE +.. c:macro:: VIDIOC_SUBDEV_ENUM_MBUS_CODE +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_mbus_code_enum`. - Description =========== -To enumerate media bus formats available at a given sub-device pad -applications initialize the ``pad``, ``which`` and ``index`` fields of -struct -:c:type:`v4l2_subdev_mbus_code_enum` and -call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an ``EINVAL`` -error code if either the ``pad`` or ``index`` are invalid. All media bus -formats are enumerable by beginning at index zero and incrementing by -one until ``EINVAL`` is returned. +This call is used by the application to access the enumeration +of media bus formats for the selected pad. + +The enumerations are defined by the driver, and indexed using the ``index`` field +of struct :c:type:`v4l2_subdev_mbus_code_enum`. +Each enumeration starts with the ``index`` of 0, and +the lowest invalid index marks the end of enumeration. + +Therefore, to enumerate media bus formats available at a given sub-device pad, +initialize the ``pad``, and ``which`` fields to desired values, +and set ``index`` to 0. +Then call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl +with a pointer to this structure. + +A successful call will return with the ``code`` field filled in +with a mbus code value. +Repeat with increasing ``index`` until ``EINVAL`` is received. +``EINVAL`` means that either ``pad`` is invalid, +or that there are no more codes available at this pad. + +The driver must not return the same value of ``code`` for different indices +at the same pad. Available media bus formats may depend on the current 'try' formats at other pads of the sub-device, as well as on the current active links. See :ref:`VIDIOC_SUBDEV_G_FMT` for more information about the try formats. - .. c:type:: v4l2_subdev_mbus_code_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_mbus_code_enum :header-rows: 0 @@ -66,24 +70,86 @@ information about the try formats. * - __u32 - ``pad`` - - Pad number as reported by the media controller API. + - Pad number as reported by the media controller API. Filled in by the + application. * - __u32 - ``index`` - - Number of the format in the enumeration, set by the application. + - Index of the mbus code in the enumeration belonging to the given pad. + Filled in by the application. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the driver. * - __u32 - ``which`` - Media bus format codes to be enumerated, from enum :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. * - __u32 - - ``reserved``\ [8] + - ``flags`` + - See :ref:`v4l2-subdev-mbus-code-flags` + * - __u32 + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [6] - Reserved for future extensions. Applications and drivers must set the array to zero. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.8cm}|p{2.2cm}|p{6.3cm}| + +.. _v4l2-subdev-mbus-code-flags: + +.. flat-table:: Subdev Media Bus Code Enumerate Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - V4L2_SUBDEV_MBUS_CODE_CSC_COLORSPACE + - 0x00000001 + - The driver allows the application to try to change the default colorspace + encoding. The application can ask to configure the colorspace of the + subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + * - V4L2_SUBDEV_MBUS_CODE_CSC_XFER_FUNC + - 0x00000002 + - The driver allows the application to try to change the default transform function. + The application can ask to configure the transform function of + the subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + * - V4L2_SUBDEV_MBUS_CODE_CSC_YCBCR_ENC + - 0x00000004 + - The driver allows the application to try to change the default Y'CbCr + encoding. The application can ask to configure the Y'CbCr encoding of the + subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + * - V4L2_SUBDEV_MBUS_CODE_CSC_HSV_ENC + - 0x00000004 + - The driver allows the application to try to change the default HSV + encoding. The application can ask to configure the HSV encoding of the + subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + * - V4L2_SUBDEV_MBUS_CODE_CSC_QUANTIZATION + - 0x00000008 + - The driver allows the application to try to change the default + quantization. The application can ask to configure the quantization of + the subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + +.. raw:: latex + + \normalsize + Return Value ============ @@ -92,7 +158,6 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_mbus_code_enum` - ``pad`` references a non-existing pad, or the ``index`` field is out - of bounds. + The struct :c:type:`v4l2_subdev_mbus_code_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the + ``index`` field is out of bounds. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst new file mode 100644 index 000000000000..da4a358ce762 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _VIDIOC_SUBDEV_G_CLIENT_CAP: + +************************************************************ +ioctl VIDIOC_SUBDEV_G_CLIENT_CAP, VIDIOC_SUBDEV_S_CLIENT_CAP +************************************************************ + +Name +==== + +VIDIOC_SUBDEV_G_CLIENT_CAP - VIDIOC_SUBDEV_S_CLIENT_CAP - Get or set client +capabilities. + +Synopsis +======== + +.. c:macro:: VIDIOC_SUBDEV_G_CLIENT_CAP + +``int ioctl(int fd, VIDIOC_SUBDEV_G_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)`` + +.. c:macro:: VIDIOC_SUBDEV_S_CLIENT_CAP + +``int ioctl(int fd, VIDIOC_SUBDEV_S_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``argp`` + Pointer to struct :c:type:`v4l2_subdev_client_capability`. + +Description +=========== + +These ioctls are used to get and set the client (the application using the +subdevice ioctls) capabilities. The client capabilities are stored in the file +handle of the opened subdev device node, and the client must set the +capabilities for each opened subdev separately. + +By default no client capabilities are set when a subdev device node is opened. + +The purpose of the client capabilities are to inform the kernel of the behavior +of the client, mainly related to maintaining compatibility with different +kernel and userspace versions. + +The ``VIDIOC_SUBDEV_G_CLIENT_CAP`` ioctl returns the current client capabilities +associated with the file handle ``fd``. + +The ``VIDIOC_SUBDEV_S_CLIENT_CAP`` ioctl sets client capabilities for the file +handle ``fd``. The new capabilities fully replace the current capabilities, the +ioctl can therefore also be used to remove capabilities that have previously +been set. + +``VIDIOC_SUBDEV_S_CLIENT_CAP`` modifies the struct +:c:type:`v4l2_subdev_client_capability` to reflect the capabilities that have +been accepted. A common case for the kernel not accepting a capability is that +the kernel is older than the headers the userspace uses, and thus the capability +is unknown to the kernel. + +.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}| + +.. c:type:: v4l2_subdev_client_capability + +.. flat-table:: struct v4l2_subdev_client_capability + :header-rows: 0 + :stub-columns: 0 + :widths: 3 4 20 + + * - __u64 + - ``capabilities`` + - Sub-device client capabilities of the opened device. + +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}| + +.. flat-table:: Client Capabilities + :header-rows: 1 + + * - Capability + - Description + * - ``V4L2_SUBDEV_CLIENT_CAP_STREAMS`` + - The client is aware of streams. Setting this flag enables the use + of 'stream' fields (referring to the stream number) with various + ioctls. If this is not set (which is the default), the 'stream' fields + will be forced to 0 by the kernel. + * - ``V4L2_SUBDEV_CLIENT_CAP_INTERVAL_USES_WHICH`` + - The client is aware of the :c:type:`v4l2_subdev_frame_interval` + ``which`` field. If this is not set (which is the default), the + ``which`` field is forced to ``V4L2_SUBDEV_FORMAT_ACTIVE`` by the + kernel. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +ENOIOCTLCMD + The kernel does not support this ioctl. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst index 615e3efdf935..92d933631fda 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_CROP: @@ -18,27 +12,26 @@ Name VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp ) - :name: VIDIOC_SUBDEV_G_CROP +.. c:macro:: VIDIOC_SUBDEV_G_CROP + +``int ioctl(int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp ) - :name: VIDIOC_SUBDEV_S_CROP +.. c:macro:: VIDIOC_SUBDEV_S_CROP +``int ioctl(int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_crop`. - Description =========== @@ -83,10 +76,9 @@ rectangle doesn't match the device capabilities. They must instead modify the rectangle to match what the hardware can provide. The modified format should be as close as possible to the original request. - .. c:type:: v4l2_subdev_crop -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_crop :header-rows: 0 @@ -104,11 +96,13 @@ modified format should be as close as possible to the original request. - ``rect`` - Crop rectangle boundaries, in pixels. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -124,10 +118,9 @@ EBUSY ``VIDIOC_SUBDEV_S_CROP`` EINVAL - The struct :c:type:`v4l2_subdev_crop` ``pad`` - references a non-existing pad, the ``which`` field references a - non-existing format, or cropping is not supported on the given - subdev pad. + The struct :c:type:`v4l2_subdev_crop` ``pad`` references a non-existing pad, + the ``which`` field has an unsupported value, or cropping is not supported + on the given subdev pad. EPERM The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst index 909ee9f90867..4a2b4e4f0152 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_FMT: @@ -18,27 +12,26 @@ Name VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp ) - :name: VIDIOC_SUBDEV_G_FMT +.. c:macro:: VIDIOC_SUBDEV_G_FMT + +``int ioctl(int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp ) - :name: VIDIOC_SUBDEV_S_FMT +.. c:macro:: VIDIOC_SUBDEV_S_FMT +``int ioctl(int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_format`. - Description =========== @@ -88,8 +81,7 @@ doesn't match the device capabilities. They must instead modify the format to match what the hardware can provide. The modified format should be as close as possible to the original request. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_subdev_format @@ -110,13 +102,15 @@ should be as close as possible to the original request. - Definition of an image format, see :c:type:`v4l2_mbus_framefmt` for details. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _v4l2-subdev-format-whence: @@ -132,7 +126,6 @@ should be as close as possible to the original request. - 1 - Active formats, applied to the hardware. - Return Value ============ @@ -147,9 +140,8 @@ EBUSY fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT`` EINVAL - The struct :c:type:`v4l2_subdev_format` - ``pad`` references a non-existing pad, or the ``which`` field - references a non-existing format. + The struct :c:type:`v4l2_subdev_format` ``pad`` references a non-existing + pad, or the ``which`` field has an unsupported value. EPERM The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst index 51e1bff797f0..c8022809ac35 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_FRAME_INTERVAL: @@ -18,27 +12,26 @@ Name VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp ) - :name: VIDIOC_SUBDEV_G_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_G_FRAME_INTERVAL + +``int ioctl(int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp ) - :name: VIDIOC_SUBDEV_S_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_S_FRAME_INTERVAL +``int ioctl(int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_interval`. - Description =========== @@ -65,8 +58,9 @@ struct contains the current frame interval as would be returned by a ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call. -Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been -registered in read-only mode is not allowed. An error is returned and the errno +If the subdev device node has been registered in read-only mode, calls to +``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` are only valid if the ``which`` field is set +to ``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno variable is set to ``-EPERM``. Drivers must not return an error solely because the requested interval @@ -81,10 +75,9 @@ Sub-devices that support the frame interval ioctls should implement them on a single pad only. Their behaviour when supported on multiple pads of the same sub-device is not defined. - .. c:type:: v4l2_subdev_frame_interval -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_interval :header-rows: 0 @@ -98,11 +91,17 @@ the same sub-device is not defined. - ``interval`` - Period, in seconds, between consecutive video frames. * - __u32 - - ``reserved``\ [9] + - ``stream`` + - Stream identifier. + * - __u32 + - ``which`` + - Active or try frame interval, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -118,11 +117,10 @@ EBUSY ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` EINVAL - The struct - :c:type:`v4l2_subdev_frame_interval` - ``pad`` references a non-existing pad, or the pad doesn't support - frame intervals. + The struct :c:type:`v4l2_subdev_frame_interval` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the pad + doesn't support frame intervals. EPERM The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only - subdevice. + subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst new file mode 100644 index 000000000000..26b5004bfe6d --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst @@ -0,0 +1,149 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _VIDIOC_SUBDEV_G_ROUTING: + +****************************************************** +ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING +****************************************************** + +Name +==== + +VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity. + + +Synopsis +======== + +.. c:macro:: VIDIOC_SUBDEV_G_ROUTING + +``int ioctl(int fd, VIDIOC_SUBDEV_G_ROUTING, struct v4l2_subdev_routing *argp)`` + +.. c:macro:: VIDIOC_SUBDEV_S_ROUTING + +``int ioctl(int fd, VIDIOC_SUBDEV_S_ROUTING, struct v4l2_subdev_routing *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``argp`` + Pointer to struct :c:type:`v4l2_subdev_routing`. + + +Description +=========== + +These ioctls are used to get and set the routing in a media entity. +The routing configuration determines the flows of data inside an entity. + +Drivers report their current routing tables using the +``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes +with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and +setting or clearing flags of the ``flags`` field of a +struct :c:type:`v4l2_subdev_route`. + +All stream configurations are reset when ``VIDIOC_SUBDEV_S_ROUTING`` is called. This +means that the userspace must reconfigure all streams after calling the ioctl +with e.g. ``VIDIOC_SUBDEV_S_FMT``. + +Only subdevices which have both sink and source pads can support routing. + +When inspecting routes through ``VIDIOC_SUBDEV_G_ROUTING`` and the application +provided ``num_routes`` is not big enough to contain all the available routes +the subdevice exposes, drivers return the ENOSPC error code and adjust the +value of the ``num_routes`` field. Application should then reserve enough memory +for all the route entries and call ``VIDIOC_SUBDEV_G_ROUTING`` again. + +On a successful ``VIDIOC_SUBDEV_G_ROUTING`` call the driver updates the +``num_routes`` field to reflect the actual number of routes returned. + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_subdev_routing + +.. flat-table:: struct v4l2_subdev_routing + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``which`` + - Routing table to be accessed, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + * - struct :c:type:`v4l2_subdev_route` + - ``routes[]`` + - Array of struct :c:type:`v4l2_subdev_route` entries + * - __u32 + - ``num_routes`` + - Number of entries of the routes array + * - __u32 + - ``reserved``\ [5] + - Reserved for future extensions. Applications and drivers must set + the array to zero. + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_subdev_route + +.. flat-table:: struct v4l2_subdev_route + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``sink_pad`` + - Sink pad number. + * - __u32 + - ``sink_stream`` + - Sink pad stream number. + * - __u32 + - ``source_pad`` + - Source pad number. + * - __u32 + - ``source_stream`` + - Source pad stream number. + * - __u32 + - ``flags`` + - Route enable/disable flags + :ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`. + * - __u32 + - ``reserved``\ [5] + - Reserved for future extensions. Applications and drivers must set + the array to zero. + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. _v4l2-subdev-routing-flags: + +.. flat-table:: enum v4l2_subdev_routing_flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - 0x0001 + - The route is enabled. Set by applications. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +ENOSPC + The application provided ``num_routes`` is not big enough to contain + all the available routes the subdevice exposes. + +EINVAL + The sink or source pad identifiers reference a non-existing pad or reference + pads of different types (ie. the sink_pad identifiers refers to a source + pad), or the ``which`` field has an unsupported value. + +E2BIG + The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is + larger than the number of routes the driver can handle. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst index 06c9553ac48f..19e6c3e9c06d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_SELECTION: @@ -18,27 +12,26 @@ Name VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp ) - :name: VIDIOC_SUBDEV_G_SELECTION +.. c:macro:: VIDIOC_SUBDEV_G_SELECTION + +``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp ) - :name: VIDIOC_SUBDEV_S_SELECTION +.. c:macro:: VIDIOC_SUBDEV_S_SELECTION +``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_selection`. - Description =========== @@ -65,7 +58,6 @@ There are two types of selection targets: actual and bounds. The actual targets are the targets which configure the hardware. The BOUNDS target will return a rectangle that contain all possible actual rectangles. - Discovering supported features ------------------------------ @@ -76,10 +68,9 @@ return ``EINVAL``. Selection targets and flags are documented in :ref:`v4l2-selections-common`. - .. c:type:: v4l2_subdev_selection -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_selection :header-rows: 0 @@ -103,11 +94,13 @@ Selection targets and flags are documented in - ``r`` - Selection rectangle, in pixels. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -123,10 +116,9 @@ EBUSY ``VIDIOC_SUBDEV_S_SELECTION`` EINVAL - The struct :c:type:`v4l2_subdev_selection` - ``pad`` references a non-existing pad, the ``which`` field - references a non-existing format, or the selection target is not - supported on the given subdev pad. + The struct :c:type:`v4l2_subdev_selection` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the + selection target is not supported on the given subdev pad. EPERM The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst index 0371a76321af..9b8d8644ec0f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_QUERYCAP: @@ -18,24 +12,22 @@ Name VIDIOC_SUBDEV_QUERYCAP - Query sub-device capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp ) - :name: VIDIOC_SUBDEV_QUERYCAP +.. c:macro:: VIDIOC_SUBDEV_QUERYCAP +``int ioctl(int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_capability`. - Description =========== @@ -46,7 +38,7 @@ a struct :c:type:`v4l2_subdev_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns ``ENOTTY`` error code. -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| +.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}| .. c:type:: v4l2_subdev_capability @@ -83,7 +75,7 @@ the driver is not compatible with this specification the ioctl returns - ``reserved``\ [14] - Reserved for future extensions. Set to 0 by the V4L2 core. -.. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}| .. _subdevice-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst index ae3ed73c0a9e..a6fc3c5fe99d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBSCRIBE_EVENT: .. _VIDIOC_UNSUBSCRIBE_EVENT: @@ -19,35 +13,33 @@ Name VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp ) - :name: VIDIOC_SUBSCRIBE_EVENT +.. c:macro:: VIDIOC_SUBSCRIBE_EVENT + +``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp ) - :name: VIDIOC_UNSUBSCRIBE_EVENT +.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT +``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_event_subscription`. - Description =========== Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by using the :ref:`VIDIOC_DQEVENT` ioctl. - -.. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}| .. c:type:: v4l2_event_subscription @@ -79,8 +71,7 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. the array to zero. - -.. tabularcolumns:: |p{6.8cm}|p{2.2cm}|p{8.5cm}| +.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}| .. _event-flags: @@ -114,7 +105,6 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. Think carefully when you set this flag so you won't get into situations like that. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst index 8ee92d0cd769..24b34cdfa6fe 100644 --- a/Documentation/userspace-api/media/v4l/yuv-formats.rst +++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _yuv-formats: @@ -21,44 +14,260 @@ reconstructed by subtracting from the brightness component. See :ref:`colorspaces` for conversion examples. YUV was chosen because early television would only transmit brightness information. To add color in a way compatible with existing receivers a new signal carrier -was added to transmit the color difference signals. Secondary in the YUV -format the U and V components usually have lower resolution than the Y -component. This is an analog video compression technique taking -advantage of a property of the human visual system, being more sensitive -to brightness information. +was added to transmit the color difference signals. + + +Subsampling +=========== + +YUV formats commonly encode images with a lower resolution for the chroma +components than for the luma component. This compression technique, taking +advantage of the human eye being more sensitive to luminance than color +differences, is called chroma subsampling. + +While many combinations of subsampling factors in the horizontal and vertical +direction are possible, common factors are 1 (no subsampling), 2 and 4, with +horizontal subsampling always larger than or equal to vertical subsampling. +Common combinations are named as follows. + +- `4:4:4`: No subsampling +- `4:2:2`: Horizontal subsampling by 2, no vertical subsampling +- `4:2:0`: Horizontal subsampling by 2, vertical subsampling by 2 +- `4:1:1`: Horizontal subsampling by 4, no vertical subsampling +- `4:1:0`: Horizontal subsampling by 4, vertical subsampling by 4 + +Subsampling the chroma component effectively creates chroma values that can be +located in different spatial locations: + +- .. _yuv-chroma-centered: + + The subsampled chroma value may be calculated by simply averaging the chroma + value of two consecutive pixels. It effectively models the chroma of a pixel + sited between the two original pixels. This is referred to as centered or + interstitially sited chroma. + +- .. _yuv-chroma-cosited: + + The other option is to subsample chroma values in a way that place them in + the same spatial sites as the pixels. This may be performed by skipping every + other chroma sample (creating aliasing artifacts), or with filters using an + odd number of taps. This is referred to as co-sited chroma. + +The following examples show different combination of chroma siting in a 4x4 +image. + +.. flat-table:: 4:2:2 subsampling, interstitially sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - C + - Y + - + - Y + - C + - Y + * - 1 + - Y + - C + - Y + - + - Y + - C + - Y + * - 2 + - Y + - C + - Y + - + - Y + - C + - Y + * - 3 + - Y + - C + - Y + - + - Y + - C + - Y + +.. flat-table:: 4:2:2 subsampling, co-sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 1 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 2 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 3 + - Y/C + - + - Y + - + - Y/C + - + - Y + +.. flat-table:: 4:2:0 subsampling, horizontally interstitially sited, vertically co-sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - C + - Y + - + - Y + - C + - Y + * - 1 + - Y + - + - Y + - + - Y + - + - Y + * - 2 + - Y + - C + - Y + - + - Y + - C + - Y + * - 3 + - Y + - + - Y + - + - Y + - + - Y + +.. flat-table:: 4:1:0 subsampling, horizontally and vertically interstitially sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - + - + - + - + * - 1 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - C + - + - + - + * - 2 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - + - + - + - + * - 3 + - Y + - + - Y + - + - Y + - + - Y .. toctree:: :maxdepth: 1 pixfmt-packed-yuv - pixfmt-grey - pixfmt-y10 - pixfmt-y12 - pixfmt-y14 - pixfmt-y10b - pixfmt-y10p - pixfmt-y16 - pixfmt-y16-be + pixfmt-yuv-planar + pixfmt-yuv-luma pixfmt-y8i pixfmt-y12i pixfmt-uv8 - pixfmt-yuyv - pixfmt-uyvy - pixfmt-yvyu - pixfmt-vyuy - pixfmt-y41p - pixfmt-yuv420 - pixfmt-yuv420m - pixfmt-yuv422m - pixfmt-yuv444m - pixfmt-yuv410 - pixfmt-yuv422p - pixfmt-yuv411p - pixfmt-nv12 - pixfmt-nv12m - pixfmt-nv12mt - pixfmt-nv16 - pixfmt-nv16m - pixfmt-nv24 pixfmt-m420 diff --git a/Documentation/userspace-api/media/video.h.rst.exceptions b/Documentation/userspace-api/media/video.h.rst.exceptions deleted file mode 100644 index ea9de59ad8b7..000000000000 --- a/Documentation/userspace-api/media/video.h.rst.exceptions +++ /dev/null @@ -1,39 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _UAPI_DVBVIDEO_H_ - -# This is a deprecated obscure API. Just ignore things we don't know -ignore define VIDEO_CMD_PLAY -ignore define VIDEO_CMD_STOP -ignore define VIDEO_CMD_FREEZE -ignore define VIDEO_CMD_CONTINUE -ignore define VIDEO_CMD_FREEZE_TO_BLACK -ignore define VIDEO_CMD_STOP_TO_BLACK -ignore define VIDEO_CMD_STOP_IMMEDIATELY -ignore define VIDEO_PLAY_FMT_NONE -ignore define VIDEO_PLAY_FMT_GOP -ignore define VIDEO_VSYNC_FIELD_UNKNOWN -ignore define VIDEO_VSYNC_FIELD_ODD -ignore define VIDEO_VSYNC_FIELD_EVEN -ignore define VIDEO_VSYNC_FIELD_PROGRESSIVE -ignore define VIDEO_EVENT_SIZE_CHANGED -ignore define VIDEO_EVENT_FRAME_RATE_CHANGED -ignore define VIDEO_EVENT_DECODER_STOPPED -ignore define VIDEO_EVENT_VSYNC -ignore define VIDEO_CAP_MPEG1 -ignore define VIDEO_CAP_MPEG2 -ignore define VIDEO_CAP_SYS -ignore define VIDEO_CAP_PROG -ignore define VIDEO_CAP_SPU -ignore define VIDEO_CAP_NAVI -ignore define VIDEO_CAP_CSS - -# some typedefs should point to struct/enums -replace typedef video_format_t :c:type:`video_format` -replace typedef video_system_t :c:type:`video_system` -replace typedef video_displayformat_t :c:type:`video_displayformat` -replace typedef video_size_t :c:type:`video_size` -replace typedef video_stream_source_t :c:type:`video_stream_source` -replace typedef video_play_state_t :c:type:`video_play_state` -replace typedef video_navi_pack_t :c:type:`video_navi_pack` diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions index a625fb90e3a9..3e58aac4ef0b 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions @@ -70,6 +70,7 @@ replace symbol V4L2_COLORSPACE_REC709 :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_SMPTE170M :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_SMPTE240M :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_SRGB :c:type:`v4l2_colorspace` +replace symbol V4L2_COLORSPACE_LAST :c:type:`v4l2_colorspace` # Documented enum v4l2_xfer_func replace symbol V4L2_XFER_FUNC_709 :c:type:`v4l2_xfer_func` @@ -81,6 +82,7 @@ replace symbol V4L2_XFER_FUNC_NONE :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_SMPTE2084 :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_SMPTE240M :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_SRGB :c:type:`v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_LAST :c:type:`v4l2_xfer_func` # Documented enum v4l2_ycbcr_encoding replace symbol V4L2_YCBCR_ENC_601 :c:type:`v4l2_ycbcr_encoding` @@ -92,6 +94,7 @@ replace symbol V4L2_YCBCR_ENC_SYCC :c:type:`v4l2_ycbcr_encoding` replace symbol V4L2_YCBCR_ENC_XV601 :c:type:`v4l2_ycbcr_encoding` replace symbol V4L2_YCBCR_ENC_XV709 :c:type:`v4l2_ycbcr_encoding` replace symbol V4L2_YCBCR_ENC_SMPTE240M :c:type:`v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_LAST :c:type:`v4l2_ycbcr_encoding` # Documented enum v4l2_hsv_encoding replace symbol V4L2_HSV_ENC_180 :c:type:`v4l2_hsv_encoding` @@ -134,17 +137,34 @@ replace symbol V4L2_CTRL_TYPE_STRING :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_U16 :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_U32 :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_U8 :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTIZATION :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MPEG2_SEQUENCE :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MPEG2_PICTURE :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTISATION :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_SPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_PPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_SCALING_MATRIX :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_PRED_WEIGHTS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_H264_DECODE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AREA :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_FWHT_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP8_FRAME :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP9_FRAME :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HDR10_CLL_INFO :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_SEQUENCE :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_FRAME :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_FILM_GRAIN :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities @@ -180,13 +200,21 @@ replace define V4L2_CAP_IO_MC device-capabilities # V4L2 pix flags replace define V4L2_PIX_FMT_PRIV_MAGIC :c:type:`v4l2_pix_format` -replace define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA reserved-formats +replace define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA format-flags +replace define V4L2_PIX_FMT_HM12 :c:type:`v4l2_pix_format` +replace define V4L2_PIX_FMT_SUNXI_TILED_NV12 :c:type:`v4l2_pix_format` # V4L2 format flags replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags replace define V4L2_FMT_FLAG_EMULATED fmtdesc-flags replace define V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM fmtdesc-flags replace define V4L2_FMT_FLAG_DYN_RESOLUTION fmtdesc-flags +replace define V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL fmtdesc-flags +replace define V4L2_FMT_FLAG_CSC_COLORSPACE fmtdesc-flags +replace define V4L2_FMT_FLAG_CSC_XFER_FUNC fmtdesc-flags +replace define V4L2_FMT_FLAG_CSC_YCBCR_ENC fmtdesc-flags +replace define V4L2_FMT_FLAG_CSC_HSV_ENC fmtdesc-flags +replace define V4L2_FMT_FLAG_CSC_QUANTIZATION fmtdesc-flags # V4L2 timecode types replace define V4L2_TC_TYPE_24FPS timecode-type @@ -363,6 +391,7 @@ replace define V4L2_CTRL_FLAG_VOLATILE control-flags replace define V4L2_CTRL_FLAG_HAS_PAYLOAD control-flags replace define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE control-flags replace define V4L2_CTRL_FLAG_MODIFY_LAYOUT control-flags +replace define V4L2_CTRL_FLAG_DYNAMIC_ARRAY control-flags replace define V4L2_CTRL_FLAG_NEXT_CTRL control replace define V4L2_CTRL_FLAG_NEXT_COMPOUND control @@ -489,6 +518,7 @@ replace define V4L2_EVENT_PRIVATE_START event-type replace define V4L2_EVENT_CTRL_CH_VALUE ctrl-changes-flags replace define V4L2_EVENT_CTRL_CH_FLAGS ctrl-changes-flags replace define V4L2_EVENT_CTRL_CH_RANGE ctrl-changes-flags +replace define V4L2_EVENT_CTRL_CH_DIMENSIONS ctrl-changes-flags replace define V4L2_EVENT_SRC_CH_RESOLUTION src-changes-flags |
