:maxdepth: 2
kernel-documentation
+ linux_tv/index
Indices and tables
==================
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: audio.h
+=============
+
+.. code-block:: c
+
+ /*
+ * audio.h
+ *
+ * Copyright (C) 2000 Ralph Metzler <ralph@convergence.de>
+ * & Marcus Metzler <marcus@convergence.de>
+ * for convergence integrated media GmbH
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Lesser Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program 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.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+ #ifndef _DVBAUDIO_H_
+ #define _DVBAUDIO_H_
+
+ #include <linux/types.h>
+
+ typedef enum {
+ AUDIO_SOURCE_DEMUX, /* Select the demux as the main source */
+ AUDIO_SOURCE_MEMORY /* Select internal memory as the main source */
+ } audio_stream_source_t;
+
+
+ typedef enum {
+ AUDIO_STOPPED, /* Device is stopped */
+ AUDIO_PLAYING, /* Device is currently playing */
+ AUDIO_PAUSED /* Device is paused */
+ } audio_play_state_t;
+
+
+ typedef enum {
+ AUDIO_STEREO,
+ AUDIO_MONO_LEFT,
+ AUDIO_MONO_RIGHT,
+ AUDIO_MONO,
+ AUDIO_STEREO_SWAPPED
+ } audio_channel_select_t;
+
+
+ typedef struct audio_mixer {
+ unsigned int volume_left;
+ unsigned int volume_right;
+ // what else do we need? bass, pass-through, ...
+ } audio_mixer_t;
+
+
+ typedef struct audio_status {
+ int AV_sync_state; /* sync audio and video? */
+ int mute_state; /* audio is muted */
+ audio_play_state_t play_state; /* current playback state */
+ audio_stream_source_t stream_source; /* current stream source */
+ audio_channel_select_t channel_select; /* currently selected channel */
+ int bypass_mode; /* pass on audio data to */
+ audio_mixer_t mixer_state; /* current mixer state */
+ } audio_status_t; /* separate decoder hardware */
+
+
+ typedef
+ struct audio_karaoke { /* if Vocal1 or Vocal2 are non-zero, they get mixed */
+ int vocal1; /* into left and right t at 70% each */
+ int vocal2; /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets*/
+ int melody; /* mixed into the left channel and */
+ /* Vocal2 into the right channel at 100% each. */
+ /* if Melody is non-zero, the melody channel gets mixed*/
+ } audio_karaoke_t; /* into left and right */
+
+
+ typedef __u16 audio_attributes_t;
+ /* bits: descr. */
+ /* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */
+ /* 12 multichannel extension */
+ /* 11-10 audio type (0=not spec, 1=language included) */
+ /* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */
+ /* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */
+ /* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */
+ /* 2- 0 number of audio channels (n+1 channels) */
+
+
+ /* for GET_CAPABILITIES and SET_FORMAT, the latter should only set one bit */
+ #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
+
+ #define AUDIO_STOP _IO('o', 1)
+ #define AUDIO_PLAY _IO('o', 2)
+ #define AUDIO_PAUSE _IO('o', 3)
+ #define AUDIO_CONTINUE _IO('o', 4)
+ #define AUDIO_SELECT_SOURCE _IO('o', 5)
+ #define AUDIO_SET_MUTE _IO('o', 6)
+ #define AUDIO_SET_AV_SYNC _IO('o', 7)
+ #define AUDIO_SET_BYPASS_MODE _IO('o', 8)
+ #define AUDIO_CHANNEL_SELECT _IO('o', 9)
+ #define AUDIO_GET_STATUS _IOR('o', 10, audio_status_t)
+
+ #define AUDIO_GET_CAPABILITIES _IOR('o', 11, unsigned int)
+ #define AUDIO_CLEAR_BUFFER _IO('o', 12)
+ #define AUDIO_SET_ID _IO('o', 13)
+ #define AUDIO_SET_MIXER _IOW('o', 14, audio_mixer_t)
+ #define AUDIO_SET_STREAMTYPE _IO('o', 15)
+ #define AUDIO_SET_EXT_ID _IO('o', 16)
+ #define AUDIO_SET_ATTRIBUTES _IOW('o', 17, audio_attributes_t)
+ #define AUDIO_SET_KARAOKE _IOW('o', 18, audio_karaoke_t)
+
+ /**
+ * AUDIO_GET_PTS
+ *
+ * Read the 33 bit presentation time stamp 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.
+ */
+ #define AUDIO_GET_PTS _IOR('o', 19, __u64)
+ #define AUDIO_BILINGUAL_CHANNEL_SELECT _IO('o', 20)
+
+ #endif /* _DVBAUDIO_H_ */
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: ca.h
+==========
+
+.. code-block:: c
+
+ /*
+ * ca.h
+ *
+ * Copyright (C) 2000 Ralph Metzler <ralph@convergence.de>
+ * & Marcus Metzler <marcus@convergence.de>
+ * for convergence integrated media GmbH
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Lesser Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program 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.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+ #ifndef _DVBCA_H_
+ #define _DVBCA_H_
+
+ /* slot interface types and info */
+
+ typedef struct ca_slot_info {
+ int num; /* slot number */
+
+ int type; /* CA interface this slot supports */
+ #define CA_CI 1 /* CI high level interface */
+ #define CA_CI_LINK 2 /* CI link layer level interface */
+ #define CA_CI_PHYS 4 /* CI physical layer level interface */
+ #define CA_DESCR 8 /* built-in descrambler */
+ #define CA_SC 128 /* simple smart card interface */
+
+ unsigned int flags;
+ #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
+ #define CA_CI_MODULE_READY 2
+ } ca_slot_info_t;
+
+
+ /* descrambler types and info */
+
+ typedef struct ca_descr_info {
+ unsigned int num; /* number of available descramblers (keys) */
+ unsigned int type; /* type of supported scrambling system */
+ #define CA_ECD 1
+ #define CA_NDS 2
+ #define CA_DSS 4
+ } ca_descr_info_t;
+
+ typedef struct ca_caps {
+ unsigned int slot_num; /* total number of CA card and module slots */
+ unsigned int slot_type; /* OR of all supported types */
+ unsigned int descr_num; /* total number of descrambler slots (keys) */
+ unsigned int descr_type; /* OR of all supported types */
+ } ca_caps_t;
+
+ /* a message to/from a CI-CAM */
+ typedef struct ca_msg {
+ unsigned int index;
+ unsigned int type;
+ unsigned int length;
+ unsigned char msg[256];
+ } ca_msg_t;
+
+ typedef struct ca_descr {
+ unsigned int index;
+ unsigned int parity; /* 0 == even, 1 == odd */
+ unsigned char cw[8];
+ } ca_descr_t;
+
+ typedef struct ca_pid {
+ unsigned int pid;
+ int index; /* -1 == disable*/
+ } ca_pid_t;
+
+ #define CA_RESET _IO('o', 128)
+ #define CA_GET_CAP _IOR('o', 129, ca_caps_t)
+ #define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t)
+ #define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
+ #define CA_GET_MSG _IOR('o', 132, ca_msg_t)
+ #define CA_SEND_MSG _IOW('o', 133, ca_msg_t)
+ #define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
+ #define CA_SET_PID _IOW('o', 135, ca_pid_t)
+
+ #endif
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+# -*- coding: utf-8; mode: python -*-
+#
+# This is the project specific sphinx-build configuration, which is loaded from
+# the base configuration file (``../conf.py``). About config values consult:
+#
+# * http://www.sphinx-doc.org/en/stable/config.html
+#
+# While setting values here, please take care to not overwrite common needed
+# configurations. This means, do not *overwrite* composite values (e.g. the
+# list- or dictionary-value of "latex_elements" resp. "extensions") by
+# thoughtless assignments. Manipulate composite values always by *update*
+# (dict-values) or extend (list-values). Nevertheless, if you know what you are
+# doing, you are free to *overwrite* values to your needs.
+#
+# useful preset names:
+#
+# * BASE_FOLDER: the folder where the top conf.py is located
+# * main_name: the basename of this project-folder
+
+# Set parser's default kernel-doc mode ``reST|kernel-doc``.
+kernel_doc_mode = "kernel-doc"
+
+# ------------------------------------------------------------------------------
+# General configuration
+# ------------------------------------------------------------------------------
+
+project = u'LINUX MEDIA INFRASTRUCTURE API'
+copyright = u'2009-2015 : LinuxTV Developers'
+author = u'The LinuxTV Developers'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+#version = 'v4.7'
+# The full version, including alpha/beta/rc tags.
+#release = 'v4.7-rc2'
+
+# extlinks["man"] = ('http://manpages.ubuntu.com/cgi-bin/search.py?q=%s', ' ')
+
+# intersphinx_mapping['kernel-doc'] = ('http://return42.github.io/sphkerneldoc/books/kernel-doc-HOWTO/', None)
+
+extensions.extend([
+ # 'sphinx.ext.pngmath'
+ #, 'sphinx.ext.mathjax'
+])
+
+# ------------------------------------------------------------------------------
+# Options for HTML output
+# ------------------------------------------------------------------------------
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = pathjoin(BASE_FOLDER, "_tex", "logo.png")
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path.extend([])
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = main_name
+
+# ------------------------------------------------------------------------------
+# Options for rst2pdf output
+# ------------------------------------------------------------------------------
+
+# Grouping the document tree into PDF files. List of tuples
+# (source start file, target name, title, author, options).
+#
+# The options element is a dictionary that lets you override
+# this config per-document.
+# For example,
+# ('index', u'MyProject', u'My Project', u'Author Name',
+# dict(pdf_compressed = True))
+# would mean that specific document would be compressed
+# regardless of the global pdf_compressed setting.
+#
+# further: http://rst2pdf.ralsina.me/handbook.html#sphinx
+
+# FIXME: at this time, the rst2pdf fails with a bug
+#pdf_documents = [
+# (master_doc, main_name, project, author)
+# , ]
+
+# If false, no index is generated.
+pdf_use_index = False
+
+# How many levels deep should the table of contents be?
+pdf_toc_depth = 3
+
+# Add section number to section references
+pdf_use_numbered_links = False
+
+# Background images fitting mode
+pdf_fit_background_mode = 'scale'
+
+
+# ------------------------------------------------------------------------------
+# Options for manual page output
+# ------------------------------------------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+# man_pages = [
+# (master_doc, 'kernel-doc', u'Kernel-Doc',
+# [author], 1)
+# ]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+# ------------------------------------------------------------------------------
+# Options for Texinfo output
+# ------------------------------------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+# texinfo_documents = [
+# (master_doc, 'Kernel-Doc', u'Kernel-Doc Documentation',
+# author, 'Kernel-Doc', 'One line description of project.',
+# 'Miscellaneous'),
+# ]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+# ------------------------------------------------------------------------------
+# Options for Epub output
+# ------------------------------------------------------------------------------
+
+# Bibliographic Dublin Core info.
+# epub_title = project
+# epub_author = author
+# epub_publisher = author
+# epub_copyright = copyright
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = project
+
+# The HTML theme for the epub output. Since the default themes are not
+# optimized for small screen space, using the same theme for HTML and epub
+# output is usually not wise. This defaults to 'epub', a theme designed to save
+# visual space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or 'en' if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files.extend([])
+
+# HTML files that should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files.extend([])
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files.extend([])
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the Pillow.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
+
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: dmx.h
+===========
+
+.. code-block:: c
+
+ /*
+ * dmx.h
+ *
+ * Copyright (C) 2000 Marcus Metzler <marcus@convergence.de>
+ * & Ralph Metzler <ralph@convergence.de>
+ * for convergence integrated media GmbH
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program 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.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+ #ifndef _UAPI_DVBDMX_H_
+ #define _UAPI_DVBDMX_H_
+
+ #include <linux/types.h>
+ #ifndef __KERNEL__
+ #include <time.h>
+ #endif
+
+
+ #define DMX_FILTER_SIZE 16
+
+ enum dmx_output
+ {
+ DMX_OUT_DECODER, /* Streaming directly to decoder. */
+ DMX_OUT_TAP, /* Output going to a memory buffer */
+ /* (to be retrieved via the read command).*/
+ DMX_OUT_TS_TAP, /* Output multiplexed into a new TS */
+ /* (to be retrieved by reading from the */
+ /* logical DVR device). */
+ DMX_OUT_TSDEMUX_TAP /* Like TS_TAP but retrieved from the DMX device */
+ };
+
+ typedef enum dmx_output dmx_output_t;
+
+ typedef enum dmx_input
+ {
+ DMX_IN_FRONTEND, /* Input from a front-end device. */
+ DMX_IN_DVR /* Input from the logical DVR device. */
+ } dmx_input_t;
+
+
+ typedef enum dmx_ts_pes
+ {
+ DMX_PES_AUDIO0,
+ DMX_PES_VIDEO0,
+ DMX_PES_TELETEXT0,
+ DMX_PES_SUBTITLE0,
+ DMX_PES_PCR0,
+
+ DMX_PES_AUDIO1,
+ DMX_PES_VIDEO1,
+ DMX_PES_TELETEXT1,
+ DMX_PES_SUBTITLE1,
+ DMX_PES_PCR1,
+
+ DMX_PES_AUDIO2,
+ DMX_PES_VIDEO2,
+ DMX_PES_TELETEXT2,
+ DMX_PES_SUBTITLE2,
+ DMX_PES_PCR2,
+
+ DMX_PES_AUDIO3,
+ DMX_PES_VIDEO3,
+ DMX_PES_TELETEXT3,
+ DMX_PES_SUBTITLE3,
+ DMX_PES_PCR3,
+
+ DMX_PES_OTHER
+ } dmx_pes_type_t;
+
+ #define DMX_PES_AUDIO DMX_PES_AUDIO0
+ #define DMX_PES_VIDEO DMX_PES_VIDEO0
+ #define DMX_PES_TELETEXT DMX_PES_TELETEXT0
+ #define DMX_PES_SUBTITLE DMX_PES_SUBTITLE0
+ #define DMX_PES_PCR DMX_PES_PCR0
+
+
+ typedef struct dmx_filter
+ {
+ __u8 filter[DMX_FILTER_SIZE];
+ __u8 mask[DMX_FILTER_SIZE];
+ __u8 mode[DMX_FILTER_SIZE];
+ } dmx_filter_t;
+
+
+ struct dmx_sct_filter_params
+ {
+ __u16 pid;
+ dmx_filter_t filter;
+ __u32 timeout;
+ __u32 flags;
+ #define DMX_CHECK_CRC 1
+ #define DMX_ONESHOT 2
+ #define DMX_IMMEDIATE_START 4
+ #define DMX_KERNEL_CLIENT 0x8000
+ };
+
+
+ struct dmx_pes_filter_params
+ {
+ __u16 pid;
+ dmx_input_t input;
+ dmx_output_t output;
+ dmx_pes_type_t pes_type;
+ __u32 flags;
+ };
+
+ typedef struct dmx_caps {
+ __u32 caps;
+ int num_decoders;
+ } dmx_caps_t;
+
+ typedef enum dmx_source {
+ DMX_SOURCE_FRONT0 = 0,
+ DMX_SOURCE_FRONT1,
+ DMX_SOURCE_FRONT2,
+ DMX_SOURCE_FRONT3,
+ DMX_SOURCE_DVR0 = 16,
+ DMX_SOURCE_DVR1,
+ DMX_SOURCE_DVR2,
+ DMX_SOURCE_DVR3
+ } dmx_source_t;
+
+ struct dmx_stc {
+ unsigned int num; /* input : which STC? 0..N */
+ unsigned int base; /* output: divisor for stc to get 90 kHz clock */
+ __u64 stc; /* output: stc in 'base'*90 kHz units */
+ };
+
+ #define DMX_START _IO('o', 41)
+ #define DMX_STOP _IO('o', 42)
+ #define DMX_SET_FILTER _IOW('o', 43, struct dmx_sct_filter_params)
+ #define DMX_SET_PES_FILTER _IOW('o', 44, struct dmx_pes_filter_params)
+ #define DMX_SET_BUFFER_SIZE _IO('o', 45)
+ #define DMX_GET_PES_PIDS _IOR('o', 47, __u16[5])
+ #define DMX_GET_CAPS _IOR('o', 48, dmx_caps_t)
+ #define DMX_SET_SOURCE _IOW('o', 49, dmx_source_t)
+ #define DMX_GET_STC _IOWR('o', 50, struct dmx_stc)
+ #define DMX_ADD_PID _IOW('o', 51, __u16)
+ #define DMX_REMOVE_PID _IOW('o', 52, __u16)
+
+ #endif /* _UAPI_DVBDMX_H_ */
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: frontend.h
+================
+
+.. code-block:: c
+
+ /*
+ * frontend.h
+ *
+ * Copyright (C) 2000 Marcus Metzler <marcus@convergence.de>
+ * Ralph Metzler <ralph@convergence.de>
+ * Holger Waechtler <holger@convergence.de>
+ * Andre Draszik <ad@convergence.de>
+ * for convergence integrated media GmbH
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program 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.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+ #ifndef _DVBFRONTEND_H_
+ #define _DVBFRONTEND_H_
+
+ #include <linux/types.h>
+
+ enum fe_type {
+ FE_QPSK,
+ FE_QAM,
+ FE_OFDM,
+ FE_ATSC
+ };
+
+ enum fe_caps {
+ FE_IS_STUPID = 0,
+ FE_CAN_INVERSION_AUTO = 0x1,
+ FE_CAN_FEC_1_2 = 0x2,
+ FE_CAN_FEC_2_3 = 0x4,
+ FE_CAN_FEC_3_4 = 0x8,
+ FE_CAN_FEC_4_5 = 0x10,
+ FE_CAN_FEC_5_6 = 0x20,
+ FE_CAN_FEC_6_7 = 0x40,
+ FE_CAN_FEC_7_8 = 0x80,
+ FE_CAN_FEC_8_9 = 0x100,
+ FE_CAN_FEC_AUTO = 0x200,
+ FE_CAN_QPSK = 0x400,
+ FE_CAN_QAM_16 = 0x800,
+ FE_CAN_QAM_32 = 0x1000,
+ FE_CAN_QAM_64 = 0x2000,
+ FE_CAN_QAM_128 = 0x4000,
+ FE_CAN_QAM_256 = 0x8000,
+ FE_CAN_QAM_AUTO = 0x10000,
+ FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000,
+ FE_CAN_BANDWIDTH_AUTO = 0x40000,
+ FE_CAN_GUARD_INTERVAL_AUTO = 0x80000,
+ FE_CAN_HIERARCHY_AUTO = 0x100000,
+ FE_CAN_8VSB = 0x200000,
+ FE_CAN_16VSB = 0x400000,
+ FE_HAS_EXTENDED_CAPS = 0x800000, /* We need more bitspace for newer APIs, indicate this. */
+ FE_CAN_MULTISTREAM = 0x4000000, /* frontend supports multistream filtering */
+ FE_CAN_TURBO_FEC = 0x8000000, /* frontend supports "turbo fec modulation" */
+ FE_CAN_2G_MODULATION = 0x10000000, /* frontend supports "2nd generation modulation" (DVB-S2) */
+ FE_NEEDS_BENDING = 0x20000000, /* not supported anymore, don't use (frontend requires frequency bending) */
+ FE_CAN_RECOVER = 0x40000000, /* frontend can recover from a cable unplug automatically */
+ FE_CAN_MUTE_TS = 0x80000000 /* frontend can stop spurious TS data output */
+ };
+
+ struct dvb_frontend_info {
+ char name[128];
+ enum fe_type type; /* DEPRECATED. Use DTV_ENUM_DELSYS instead */
+ __u32 frequency_min;
+ __u32 frequency_max;
+ __u32 frequency_stepsize;
+ __u32 frequency_tolerance;
+ __u32 symbol_rate_min;
+ __u32 symbol_rate_max;
+ __u32 symbol_rate_tolerance; /* ppm */
+ __u32 notifier_delay; /* DEPRECATED */
+ enum fe_caps caps;
+ };
+
+
+ /**
+ * Check out the DiSEqC bus spec available on http://www.eutelsat.org/ for
+ * the meaning of this struct...
+ */
+ struct dvb_diseqc_master_cmd {
+ __u8 msg [6]; /* { framing, address, command, data [3] } */
+ __u8 msg_len; /* valid values are 3...6 */
+ };
+
+ struct dvb_diseqc_slave_reply {
+ __u8 msg [4]; /* { framing, data [3] } */
+ __u8 msg_len; /* valid values are 0...4, 0 means no msg */
+ int timeout; /* return from ioctl after timeout ms with */
+ }; /* errorcode when no message was received */
+
+ enum fe_sec_voltage {
+ SEC_VOLTAGE_13,
+ SEC_VOLTAGE_18,
+ SEC_VOLTAGE_OFF
+ };
+
+ enum fe_sec_tone_mode {
+ SEC_TONE_ON,
+ SEC_TONE_OFF
+ };
+
+ enum fe_sec_mini_cmd {
+ SEC_MINI_A,
+ SEC_MINI_B
+ };
+
+ /**
+ * enum fe_status - enumerates the possible frontend status
+ * @FE_HAS_SIGNAL: found something above the noise level
+ * @FE_HAS_CARRIER: found a DVB signal
+ * @FE_HAS_VITERBI: FEC is stable
+ * @FE_HAS_SYNC: found sync bytes
+ * @FE_HAS_LOCK: everything's working
+ * @FE_TIMEDOUT: no lock within the last ~2 seconds
+ * @FE_REINIT: frontend was reinitialized, application is recommended
+ * to reset DiSEqC, tone and parameters
+ */
+ enum fe_status {
+ FE_HAS_SIGNAL = 0x01,
+ FE_HAS_CARRIER = 0x02,
+ FE_HAS_VITERBI = 0x04,
+ FE_HAS_SYNC = 0x08,
+ FE_HAS_LOCK = 0x10,
+ FE_TIMEDOUT = 0x20,
+ FE_REINIT = 0x40,
+ };
+
+ enum fe_spectral_inversion {
+ INVERSION_OFF,
+ INVERSION_ON,
+ INVERSION_AUTO
+ };
+
+ enum fe_code_rate {
+ FEC_NONE = 0,
+ FEC_1_2,
+ FEC_2_3,
+ FEC_3_4,
+ FEC_4_5,
+ FEC_5_6,
+ FEC_6_7,
+ FEC_7_8,
+ FEC_8_9,
+ FEC_AUTO,
+ FEC_3_5,
+ FEC_9_10,
+ FEC_2_5,
+ };
+
+ enum fe_modulation {
+ QPSK,
+ QAM_16,
+ QAM_32,
+ QAM_64,
+ QAM_128,
+ QAM_256,
+ QAM_AUTO,
+ VSB_8,
+ VSB_16,
+ PSK_8,
+ APSK_16,
+ APSK_32,
+ DQPSK,
+ QAM_4_NR,
+ };
+
+ enum fe_transmit_mode {
+ TRANSMISSION_MODE_2K,
+ TRANSMISSION_MODE_8K,
+ TRANSMISSION_MODE_AUTO,
+ TRANSMISSION_MODE_4K,
+ TRANSMISSION_MODE_1K,
+ TRANSMISSION_MODE_16K,
+ TRANSMISSION_MODE_32K,
+ TRANSMISSION_MODE_C1,
+ TRANSMISSION_MODE_C3780,
+ };
+
+ enum fe_guard_interval {
+ GUARD_INTERVAL_1_32,
+ GUARD_INTERVAL_1_16,
+ GUARD_INTERVAL_1_8,
+ GUARD_INTERVAL_1_4,
+ GUARD_INTERVAL_AUTO,
+ GUARD_INTERVAL_1_128,
+ GUARD_INTERVAL_19_128,
+ GUARD_INTERVAL_19_256,
+ GUARD_INTERVAL_PN420,
+ GUARD_INTERVAL_PN595,
+ GUARD_INTERVAL_PN945,
+ };
+
+ enum fe_hierarchy {
+ HIERARCHY_NONE,
+ HIERARCHY_1,
+ HIERARCHY_2,
+ HIERARCHY_4,
+ HIERARCHY_AUTO
+ };
+
+ enum fe_interleaving {
+ INTERLEAVING_NONE,
+ INTERLEAVING_AUTO,
+ INTERLEAVING_240,
+ INTERLEAVING_720,
+ };
+
+ /* S2API Commands */
+ #define DTV_UNDEFINED 0
+ #define DTV_TUNE 1
+ #define DTV_CLEAR 2
+ #define DTV_FREQUENCY 3
+ #define DTV_MODULATION 4
+ #define DTV_BANDWIDTH_HZ 5
+ #define DTV_INVERSION 6
+ #define DTV_DISEQC_MASTER 7
+ #define DTV_SYMBOL_RATE 8
+ #define DTV_INNER_FEC 9
+ #define DTV_VOLTAGE 10
+ #define DTV_TONE 11
+ #define DTV_PILOT 12
+ #define DTV_ROLLOFF 13
+ #define DTV_DISEQC_SLAVE_REPLY 14
+
+ /* Basic enumeration set for querying unlimited capabilities */
+ #define DTV_FE_CAPABILITY_COUNT 15
+ #define DTV_FE_CAPABILITY 16
+ #define DTV_DELIVERY_SYSTEM 17
+
+ /* ISDB-T and ISDB-Tsb */
+ #define DTV_ISDBT_PARTIAL_RECEPTION 18
+ #define DTV_ISDBT_SOUND_BROADCASTING 19
+
+ #define DTV_ISDBT_SB_SUBCHANNEL_ID 20
+ #define DTV_ISDBT_SB_SEGMENT_IDX 21
+ #define DTV_ISDBT_SB_SEGMENT_COUNT 22
+
+ #define DTV_ISDBT_LAYERA_FEC 23
+ #define DTV_ISDBT_LAYERA_MODULATION 24
+ #define DTV_ISDBT_LAYERA_SEGMENT_COUNT 25
+ #define DTV_ISDBT_LAYERA_TIME_INTERLEAVING 26
+
+ #define DTV_ISDBT_LAYERB_FEC 27
+ #define DTV_ISDBT_LAYERB_MODULATION 28
+ #define DTV_ISDBT_LAYERB_SEGMENT_COUNT 29
+ #define DTV_ISDBT_LAYERB_TIME_INTERLEAVING 30
+
+ #define DTV_ISDBT_LAYERC_FEC 31
+ #define DTV_ISDBT_LAYERC_MODULATION 32
+ #define DTV_ISDBT_LAYERC_SEGMENT_COUNT 33
+ #define DTV_ISDBT_LAYERC_TIME_INTERLEAVING 34
+
+ #define DTV_API_VERSION 35
+
+ #define DTV_CODE_RATE_HP 36
+ #define DTV_CODE_RATE_LP 37
+ #define DTV_GUARD_INTERVAL 38
+ #define DTV_TRANSMISSION_MODE 39
+ #define DTV_HIERARCHY 40
+
+ #define DTV_ISDBT_LAYER_ENABLED 41
+
+ #define DTV_STREAM_ID 42
+ #define DTV_ISDBS_TS_ID_LEGACY DTV_STREAM_ID
+ #define DTV_DVBT2_PLP_ID_LEGACY 43
+
+ #define DTV_ENUM_DELSYS 44
+
+ /* ATSC-MH */
+ #define DTV_ATSCMH_FIC_VER 45
+ #define DTV_ATSCMH_PARADE_ID 46
+ #define DTV_ATSCMH_NOG 47
+ #define DTV_ATSCMH_TNOG 48
+ #define DTV_ATSCMH_SGN 49
+ #define DTV_ATSCMH_PRC 50
+ #define DTV_ATSCMH_RS_FRAME_MODE 51
+ #define DTV_ATSCMH_RS_FRAME_ENSEMBLE 52
+ #define DTV_ATSCMH_RS_CODE_MODE_PRI 53
+ #define DTV_ATSCMH_RS_CODE_MODE_SEC 54
+ #define DTV_ATSCMH_SCCC_BLOCK_MODE 55
+ #define DTV_ATSCMH_SCCC_CODE_MODE_A 56
+ #define DTV_ATSCMH_SCCC_CODE_MODE_B 57
+ #define DTV_ATSCMH_SCCC_CODE_MODE_C 58
+ #define DTV_ATSCMH_SCCC_CODE_MODE_D 59
+
+ #define DTV_INTERLEAVING 60
+ #define DTV_LNA 61
+
+ /* Quality parameters */
+ #define DTV_STAT_SIGNAL_STRENGTH 62
+ #define DTV_STAT_CNR 63
+ #define DTV_STAT_PRE_ERROR_BIT_COUNT 64
+ #define DTV_STAT_PRE_TOTAL_BIT_COUNT 65
+ #define DTV_STAT_POST_ERROR_BIT_COUNT 66
+ #define DTV_STAT_POST_TOTAL_BIT_COUNT 67
+ #define DTV_STAT_ERROR_BLOCK_COUNT 68
+ #define DTV_STAT_TOTAL_BLOCK_COUNT 69
+
+ #define DTV_MAX_COMMAND DTV_STAT_TOTAL_BLOCK_COUNT
+
+ enum fe_pilot {
+ PILOT_ON,
+ PILOT_OFF,
+ PILOT_AUTO,
+ };
+
+ enum fe_rolloff {
+ ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */
+ ROLLOFF_20,
+ ROLLOFF_25,
+ ROLLOFF_AUTO,
+ };
+
+ enum fe_delivery_system {
+ SYS_UNDEFINED,
+ SYS_DVBC_ANNEX_A,
+ SYS_DVBC_ANNEX_B,
+ SYS_DVBT,
+ SYS_DSS,
+ SYS_DVBS,
+ SYS_DVBS2,
+ SYS_DVBH,
+ SYS_ISDBT,
+ SYS_ISDBS,
+ SYS_ISDBC,
+ SYS_ATSC,
+ SYS_ATSCMH,
+ SYS_DTMB,
+ SYS_CMMB,
+ SYS_DAB,
+ SYS_DVBT2,
+ SYS_TURBO,
+ SYS_DVBC_ANNEX_C,
+ };
+
+ /* backward compatibility */
+ #define SYS_DVBC_ANNEX_AC SYS_DVBC_ANNEX_A
+ #define SYS_DMBTH SYS_DTMB /* DMB-TH is legacy name, use DTMB instead */
+
+ /* ATSC-MH */
+
+ enum atscmh_sccc_block_mode {
+ ATSCMH_SCCC_BLK_SEP = 0,
+ ATSCMH_SCCC_BLK_COMB = 1,
+ ATSCMH_SCCC_BLK_RES = 2,
+ };
+
+ enum atscmh_sccc_code_mode {
+ ATSCMH_SCCC_CODE_HLF = 0,
+ ATSCMH_SCCC_CODE_QTR = 1,
+ ATSCMH_SCCC_CODE_RES = 2,
+ };
+
+ enum atscmh_rs_frame_ensemble {
+ ATSCMH_RSFRAME_ENS_PRI = 0,
+ ATSCMH_RSFRAME_ENS_SEC = 1,
+ };
+
+ enum atscmh_rs_frame_mode {
+ ATSCMH_RSFRAME_PRI_ONLY = 0,
+ ATSCMH_RSFRAME_PRI_SEC = 1,
+ ATSCMH_RSFRAME_RES = 2,
+ };
+
+ enum atscmh_rs_code_mode {
+ ATSCMH_RSCODE_211_187 = 0,
+ ATSCMH_RSCODE_223_187 = 1,
+ ATSCMH_RSCODE_235_187 = 2,
+ ATSCMH_RSCODE_RES = 3,
+ };
+
+ #define NO_STREAM_ID_FILTER (~0U)
+ #define LNA_AUTO (~0U)
+
+ struct dtv_cmds_h {
+ char *name; /* A display name for debugging purposes */
+
+ __u32 cmd; /* A unique ID */
+
+ /* Flags */
+ __u32 set:1; /* Either a set or get property */
+ __u32 buffer:1; /* Does this property use the buffer? */
+ __u32 reserved:30; /* Align */
+ };
+
+ /**
+ * Scale types for the quality parameters.
+ * @FE_SCALE_NOT_AVAILABLE: That QoS measure is not available. That
+ * could indicate a temporary or a permanent
+ * condition.
+ * @FE_SCALE_DECIBEL: The scale is measured in 0.001 dB steps, typically
+ * used on signal measures.
+ * @FE_SCALE_RELATIVE: The scale is a relative percentual measure,
+ * ranging from 0 (0%) to 0xffff (100%).
+ * @FE_SCALE_COUNTER: The scale counts the occurrence of an event, like
+ * bit error, block error, lapsed time.
+ */
+ enum fecap_scale_params {
+ FE_SCALE_NOT_AVAILABLE = 0,
+ FE_SCALE_DECIBEL,
+ FE_SCALE_RELATIVE,
+ FE_SCALE_COUNTER
+ };
+
+ /**
+ * struct dtv_stats - Used for reading a DTV status property
+ *
+ * @value: value of the measure. Should range from 0 to 0xffff;
+ * @scale: Filled with enum fecap_scale_params - the scale
+ * in usage for that parameter
+ *
+ * For most delivery systems, this will return a single value for each
+ * parameter.
+ * It should be noticed, however, that new OFDM delivery systems like
+ * ISDB can use different modulation types for each group of carriers.
+ * On such standards, up to 8 groups of statistics can be provided, one
+ * for each carrier group (called "layer" on ISDB).
+ * In order to be consistent with other delivery systems, the first
+ * value refers to the entire set of carriers ("global").
+ * dtv_status:scale should use the value FE_SCALE_NOT_AVAILABLE when
+ * the value for the entire group of carriers or from one specific layer
+ * is not provided by the hardware.
+ * st.len should be filled with the latest filled status + 1.
+ *
+ * In other words, for ISDB, those values should be filled like:
+ * u.st.stat.svalue[0] = global statistics;
+ * u.st.stat.scale[0] = FE_SCALE_DECIBEL;
+ * u.st.stat.value[1] = layer A statistics;
+ * u.st.stat.scale[1] = FE_SCALE_NOT_AVAILABLE (if not available);
+ * u.st.stat.svalue[2] = layer B statistics;
+ * u.st.stat.scale[2] = FE_SCALE_DECIBEL;
+ * u.st.stat.svalue[3] = layer C statistics;
+ * u.st.stat.scale[3] = FE_SCALE_DECIBEL;
+ * u.st.len = 4;
+ */
+ struct dtv_stats {
+ __u8 scale; /* enum fecap_scale_params type */
+ union {
+ __u64 uvalue; /* for counters and relative scales */
+ __s64 svalue; /* for 0.001 dB measures */
+ };
+ } __attribute__ ((packed));
+
+
+ #define MAX_DTV_STATS 4
+
+ struct dtv_fe_stats {
+ __u8 len;
+ struct dtv_stats stat[MAX_DTV_STATS];
+ } __attribute__ ((packed));
+
+ struct dtv_property {
+ __u32 cmd;
+ __u32 reserved[3];
+ union {
+ __u32 data;
+ struct dtv_fe_stats st;
+ struct {
+ __u8 data[32];
+ __u32 len;
+ __u32 reserved1[3];
+ void *reserved2;
+ } buffer;
+ } u;
+ int result;
+ } __attribute__ ((packed));
+
+ /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
+ #define DTV_IOCTL_MAX_MSGS 64
+
+ struct dtv_properties {
+ __u32 num;
+ struct dtv_property *props;
+ };
+
+ #if defined(__DVB_CORE__) || !defined (__KERNEL__)
+
+ /*
+ * DEPRECATED: The DVBv3 ioctls, structs and enums should not be used on
+ * newer programs, as it doesn't support the second generation of digital
+ * TV standards, nor supports newer delivery systems.
+ */
+
+ enum fe_bandwidth {
+ BANDWIDTH_8_MHZ,
+ BANDWIDTH_7_MHZ,
+ BANDWIDTH_6_MHZ,
+ BANDWIDTH_AUTO,
+ BANDWIDTH_5_MHZ,
+ BANDWIDTH_10_MHZ,
+ BANDWIDTH_1_712_MHZ,
+ };
+
+ /* This is needed for legacy userspace support */
+ typedef enum fe_sec_voltage fe_sec_voltage_t;
+ typedef enum fe_caps fe_caps_t;
+ typedef enum fe_type fe_type_t;
+ typedef enum fe_sec_tone_mode fe_sec_tone_mode_t;
+ typedef enum fe_sec_mini_cmd fe_sec_mini_cmd_t;
+ typedef enum fe_status fe_status_t;
+ typedef enum fe_spectral_inversion fe_spectral_inversion_t;
+ typedef enum fe_code_rate fe_code_rate_t;
+ typedef enum fe_modulation fe_modulation_t;
+ typedef enum fe_transmit_mode fe_transmit_mode_t;
+ typedef enum fe_bandwidth fe_bandwidth_t;
+ typedef enum fe_guard_interval fe_guard_interval_t;
+ typedef enum fe_hierarchy fe_hierarchy_t;
+ typedef enum fe_pilot fe_pilot_t;
+ typedef enum fe_rolloff fe_rolloff_t;
+ typedef enum fe_delivery_system fe_delivery_system_t;
+
+ struct dvb_qpsk_parameters {
+ __u32 symbol_rate; /* symbol rate in Symbols per second */
+ fe_code_rate_t fec_inner; /* forward error correction (see above) */
+ };
+
+ struct dvb_qam_parameters {
+ __u32 symbol_rate; /* symbol rate in Symbols per second */
+ fe_code_rate_t fec_inner; /* forward error correction (see above) */
+ fe_modulation_t modulation; /* modulation type (see above) */
+ };
+
+ struct dvb_vsb_parameters {
+ fe_modulation_t modulation; /* modulation type (see above) */
+ };
+
+ struct dvb_ofdm_parameters {
+ fe_bandwidth_t bandwidth;
+ fe_code_rate_t code_rate_HP; /* high priority stream code rate */
+ fe_code_rate_t code_rate_LP; /* low priority stream code rate */
+ fe_modulation_t constellation; /* modulation type (see above) */
+ fe_transmit_mode_t transmission_mode;
+ fe_guard_interval_t guard_interval;
+ fe_hierarchy_t hierarchy_information;
+ };
+
+ struct dvb_frontend_parameters {
+ __u32 frequency; /* (absolute) frequency in Hz for DVB-C/DVB-T/ATSC */
+ /* intermediate frequency in kHz for DVB-S */
+ fe_spectral_inversion_t inversion;
+ union {
+ struct dvb_qpsk_parameters qpsk; /* DVB-S */
+ struct dvb_qam_parameters qam; /* DVB-C */
+ struct dvb_ofdm_parameters ofdm; /* DVB-T */
+ struct dvb_vsb_parameters vsb; /* ATSC */
+ } u;
+ };
+
+ struct dvb_frontend_event {
+ fe_status_t status;
+ struct dvb_frontend_parameters parameters;
+ };
+ #endif
+
+ #define FE_SET_PROPERTY _IOW('o', 82, struct dtv_properties)
+ #define FE_GET_PROPERTY _IOR('o', 83, struct dtv_properties)
+
+ /**
+ * When set, this flag will disable any zigzagging or other "normal" tuning
+ * behaviour. Additionally, there will be no automatic monitoring of the lock
+ * status, and hence no frontend events will be generated. If a frontend device
+ * is closed, this flag will be automatically turned off when the device is
+ * reopened read-write.
+ */
+ #define FE_TUNE_MODE_ONESHOT 0x01
+
+ #define FE_GET_INFO _IOR('o', 61, struct dvb_frontend_info)
+
+ #define FE_DISEQC_RESET_OVERLOAD _IO('o', 62)
+ #define FE_DISEQC_SEND_MASTER_CMD _IOW('o', 63, struct dvb_diseqc_master_cmd)
+ #define FE_DISEQC_RECV_SLAVE_REPLY _IOR('o', 64, struct dvb_diseqc_slave_reply)
+ #define FE_DISEQC_SEND_BURST _IO('o', 65) /* fe_sec_mini_cmd_t */
+
+ #define FE_SET_TONE _IO('o', 66) /* fe_sec_tone_mode_t */
+ #define FE_SET_VOLTAGE _IO('o', 67) /* fe_sec_voltage_t */
+ #define FE_ENABLE_HIGH_LNB_VOLTAGE _IO('o', 68) /* int */
+
+ #define FE_READ_STATUS _IOR('o', 69, fe_status_t)
+ #define FE_READ_BER _IOR('o', 70, __u32)
+ #define FE_READ_SIGNAL_STRENGTH _IOR('o', 71, __u16)
+ #define FE_READ_SNR _IOR('o', 72, __u16)
+ #define FE_READ_UNCORRECTED_BLOCKS _IOR('o', 73, __u32)
+
+ #define FE_SET_FRONTEND _IOW('o', 76, struct dvb_frontend_parameters)
+ #define FE_GET_FRONTEND _IOR('o', 77, struct dvb_frontend_parameters)
+ #define FE_SET_FRONTEND_TUNE_MODE _IO('o', 81) /* unsigned int */
+ #define FE_GET_EVENT _IOR('o', 78, struct dvb_frontend_event)
+
+ #define FE_DISHNETWORK_SEND_LEGACY_CMD _IO('o', 80) /* unsigned int */
+
+ #endif /*_DVBFRONTEND_H_*/
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+##############################
+LINUX MEDIA INFRASTRUCTURE API
+##############################
+
+**Copyright** 2009-2015 : LinuxTV Developers
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation. A copy of
+the license is included in the chapter entitled "GNU Free Documentation
+License"
+
+
+============
+Introduction
+============
+
+This document covers the Linux Kernel to Userspace API's used by video
+and radio streaming devices, including video cameras, analog and digital
+TV receiver cards, AM/FM receiver cards, streaming capture and output
+devices, codec devices and remote controllers.
+
+A typical media device hardware is shown at
+:ref:`typical_media_device`.
+
+
+.. _typical_media_device:
+
+.. figure:: media_api_files/typical_media_device.*
+ :alt: typical_media_device.svg
+ :align: center
+
+ Typical Media Device
+
+ Typical Media Device Block Diagram
+
+
+
+The media infrastructure API was designed to control such devices. It is
+divided into four parts.
+
+The first part covers radio, video capture and output, cameras, analog
+TV devices and codecs.
+
+The second part covers the API used for digital TV and Internet
+reception via one of the several digital tv standards. While it is
+called as DVB API, in fact it covers several different video standards
+including DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S,etc. The
+complete list of supported standards can be found at
+:ref:`fe-delivery-system-t`.
+
+The third part covers the Remote Controller API.
+
+The fourth part covers the Media Controller API.
+
+It should also be noted that a media device may also have audio
+components, like mixers, PCM capture, PCM playback, etc, which are
+controlled via ALSA API.
+
+For additional information and for the latest development code, see:
+`https://linuxtv.org <https://linuxtv.org>`__.
+
+For discussing improvements, reporting troubles, sending new drivers,
+etc, please mail to:
+`Linux Media Mailing List (LMML). <http://vger.kernel.org/vger-lists.html#linux-media>`__.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ media/v4l/v4l2
+ media/dvb/dvbapi
+ media/v4l/remote_controllers
+ media/v4l/media-controller
+ media/v4l/gen-errors
+ media/v4l/fdl-appendix
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
+
+
+.. only:: html
+
+ Retrieval
+ =========
+
+ * :ref:`genindex`
+
+.. todolist::
+
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISHNETWORK_SEND_LEGACY_CMD:
+
+******************************
+FE_DISHNETWORK_SEND_LEGACY_CMD
+******************************
+
+DESCRIPTION
+
+WARNING: This is a very obscure legacy command, used only at stv0299
+driver. Should not be used on newer drivers.
+
+It provides a non-standard method for selecting Diseqc voltage on the
+frontend, for Dish Network legacy switches.
+
+As support for this ioctl were added in 2004, this means that such
+dishes were already legacy in 2004.
+
+SYNOPSIS
+
+int ioctl(int fd, int request =
+:ref:`FE_DISHNETWORK_SEND_LEGACY_CMD <FE_DISHNETWORK_SEND_LEGACY_CMD>`,
+unsigned long cmd);
+
+PARAMETERS
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - unsigned long cmd
+
+ - sends the specified raw cmd to the dish via DISEqC.
+
+
+RETURN VALUE
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_GET_EVENT:
+
+************
+FE_GET_EVENT
+************
+
+DESCRIPTION
+
+This ioctl call returns a frontend 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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = QPSK_GET_EVENT, struct
+dvb_frontend_event *ev);
+
+PARAMETERS
+
+
+
+.. 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 :ref:`FE_GET_EVENT <FE_GET_EVENT>` for this command.
+
+ - .. row 3
+
+ - struct dvb_frontend_event *ev
+
+ - Points to the location where the event,
+
+ - .. row 4
+
+ -
+ - if any, is to be stored.
+
+
+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.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_GET_FRONTEND:
+
+***************
+FE_GET_FRONTEND
+***************
+
+DESCRIPTION
+
+This ioctl call queries the currently effective frontend parameters. For
+this command, read-only access to the device is sufficient.
+
+SYNOPSIS
+
+int ioctl(int fd, int request =
+:ref:`FE_GET_FRONTEND <FE_GET_FRONTEND>`, struct
+dvb_frontend_parameters *p);
+
+PARAMETERS
+
+
+
+.. 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 :ref:`FE_SET_FRONTEND <FE_SET_FRONTEND>` for this
+ command.
+
+ - .. row 3
+
+ - struct dvb_frontend_parameters *p
+
+ - Points to parameters for tuning operation.
+
+
+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
+
+ - Maximum supported symbol rate reached.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_BER:
+
+***********
+FE_READ_BER
+***********
+
+DESCRIPTION
+
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = :ref:`FE_READ_BER <FE_READ_BER>`,
+uint32_t *ber);
+
+PARAMETERS
+
+
+
+.. 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 :ref:`FE_READ_BER <FE_READ_BER>` for this command.
+
+ - .. row 3
+
+ - uint32_t *ber
+
+ - The bit error rate is stored into *ber.
+
+
+RETURN VALUE
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_SIGNAL_STRENGTH:
+
+***********************
+FE_READ_SIGNAL_STRENGTH
+***********************
+
+DESCRIPTION
+
+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.
+
+SYNOPSIS
+
+int ioctl( int fd, int request =
+:ref:`FE_READ_SIGNAL_STRENGTH <FE_READ_SIGNAL_STRENGTH>`,
+uint16_t *strength);
+
+PARAMETERS
+
+
+
+.. 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
+ :ref:`FE_READ_SIGNAL_STRENGTH <FE_READ_SIGNAL_STRENGTH>`
+ for this command.
+
+ - .. row 3
+
+ - uint16_t *strength
+
+ - The signal strength value is stored into *strength.
+
+
+RETURN VALUE
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_SNR:
+
+***********
+FE_READ_SNR
+***********
+
+DESCRIPTION
+
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = :ref:`FE_READ_SNR <FE_READ_SNR>`,
+uint16_t *snr);
+
+PARAMETERS
+
+
+
+.. 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 :ref:`FE_READ_SNR <FE_READ_SNR>` for this command.
+
+ - .. row 3
+
+ - uint16_t *snr
+
+ - The signal-to-noise ratio is stored into *snr.
+
+
+RETURN VALUE
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_UNCORRECTED_BLOCKS:
+
+**************************
+FE_READ_UNCORRECTED_BLOCKS
+**************************
+
+DESCRIPTION
+
+This ioctl call returns the number of uncorrected blocks detected by the
+device driver during its lifetime. For meaningful measurements, the
+increment in block count during a specific time interval should be
+calculated. For this command, read-only access to the device is
+sufficient.
+
+SYNOPSIS
+
+int ioctl( int fd, int request =
+:ref:`FE_READ_UNCORRECTED_BLOCKS <FE_READ_UNCORRECTED_BLOCKS>`,
+uint32_t *ublocks);
+
+PARAMETERS
+
+
+
+.. 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
+ :ref:`FE_READ_UNCORRECTED_BLOCKS <FE_READ_UNCORRECTED_BLOCKS>`
+ for this command.
+
+ - .. row 3
+
+ - uint32_t *ublocks
+
+ - The total number of uncorrected blocks seen by the driver 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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_SET_FRONTEND:
+
+***************
+FE_SET_FRONTEND
+***************
+
+DESCRIPTION
+
+This ioctl call starts a tuning operation using specified parameters.
+The result of this call will be successful if the parameters were valid
+and the tuning could be initiated. The result of the tuning operation in
+itself, however, will arrive asynchronously as an event (see
+documentation for :ref:`FE_GET_EVENT <FE_GET_EVENT>` and
+FrontendEvent.) If a new :ref:`FE_SET_FRONTEND <FE_SET_FRONTEND>`
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request =
+:ref:`FE_SET_FRONTEND <FE_SET_FRONTEND>`, struct
+dvb_frontend_parameters *p);
+
+PARAMETERS
+
+
+
+.. 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 :ref:`FE_SET_FRONTEND <FE_SET_FRONTEND>` for this
+ command.
+
+ - .. row 3
+
+ - struct dvb_frontend_parameters *p
+
+ - Points to parameters for tuning operation.
+
+
+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
+
+ - Maximum supported symbol rate reached.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_audio:
+
+################
+DVB Audio Device
+################
+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 and ioctl definitions can be accessed by including
+``linux/dvb/audio.h`` in your application.
+
+Please note that some 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.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ audio_data_types
+ audio_function_calls
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_data_types:
+
+****************
+Audio Data Types
+****************
+
+This section describes the structures, data types and defines used when
+talking to the audio device.
+
+
+.. _audio-stream-source-t:
+
+audio_stream_source_t
+=====================
+
+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.
+
+
+.. _audio-play-state-t:
+
+audio_play_state_t
+==================
+
+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;
+
+
+.. _audio-channel-select-t:
+
+audio_channel_select_t
+======================
+
+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;
+
+
+.. _audio-status:
+
+struct 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;
+
+
+.. _audio-mixer:
+
+struct 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
+
+
+.. _audio-karaoke:
+
+struct audio_karaoke
+====================
+
+The ioctl AUDIO_SET_KARAOKE uses the following format:
+
+
+.. code-block:: c
+
+ typedef
+ struct audio_karaoke {
+ int vocal1;
+ int vocal2;
+ int melody;
+ } audio_karaoke_t;
+
+If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t
+at 70% each. If both, Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed
+into the left channel and Vocal2 into the right channel at 100% each. Ff
+Melody is non-zero, the melody channel gets mixed into left and right.
+
+
+.. _audio-attributes-t:
+
+audio attributes
+================
+
+The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES:
+
+
+.. code-block:: c
+
+ typedef uint16_t audio_attributes_t;
+ /* bits: descr. */
+ /* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */
+ /* 12 multichannel extension */
+ /* 11-10 audio type (0=not spec, 1=language included) */
+ /* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */
+ /* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */
+ /* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */
+ /* 2- 0 number of audio channels (n+1 channels) */
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_function_calls:
+
+********************
+Audio Function Calls
+********************
+
+
+.. _audio_fopen:
+
+open()
+======
+
+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.
+
+SYNOPSIS
+
+int open(const char *deviceName, int flags);
+
+PARAMETERS
+
+
+
+.. 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)
+
+
+RETURN VALUE
+
+
+
+.. 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.
+
+
+
+.. _audio_fclose:
+
+close()
+=======
+
+DESCRIPTION
+
+This system call closes a previously opened audio device.
+
+SYNOPSIS
+
+int close(int fd);
+
+PARAMETERS
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+
+RETURN VALUE
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EBADF
+
+ - fd is not a valid open file descriptor.
+
+
+
+.. _audio_fwrite:
+
+write()
+=======
+
+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.
+
+SYNOPSIS
+
+size_t write(int fd, const void *buf, size_t count);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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.
+
+
+
+.. _AUDIO_STOP:
+
+AUDIO_STOP
+==========
+
+DESCRIPTION
+
+This ioctl call asks the Audio Device to stop playing the current
+stream.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_STOP);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_STOP for this 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_PLAY:
+
+AUDIO_PLAY
+==========
+
+DESCRIPTION
+
+This ioctl call asks the Audio Device to start playing an audio stream
+from the selected source.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_PLAY);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_PLAY for this 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_PAUSE:
+
+AUDIO_PAUSE
+===========
+
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_PAUSE);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_PAUSE for this 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:
+
+AUDIO_CONTINUE
+==============
+
+DESCRIPTION
+
+This ioctl restarts the decoding and playing process previously paused
+with AUDIO_PAUSE command.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_CONTINUE);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_CONTINUE for this 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:
+
+AUDIO_SELECT_SOURCE
+===================
+
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
+audio_stream_source_t source);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SELECT_SOURCE for this command.
+
+ - .. row 3
+
+ - audio_stream_source_t source
+
+ - Indicates the source that shall be used for the Audio 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_SET_MUTE:
+
+AUDIO_SET_MUTE
+==============
+
+DESCRIPTION
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD <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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SET_MUTE for this command.
+
+ - .. row 3
+
+ - boolean state
+
+ - Indicates if audio device shall mute or not.
+
+ - .. row 4
+
+ -
+ - TRUE Audio Mute
+
+ - .. row 5
+
+ -
+ - FALSE Audio Un-mute
+
+
+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:
+
+AUDIO_SET_AV_SYNC
+=================
+
+DESCRIPTION
+
+This ioctl call asks the Audio Device to turn ON or OFF A/V
+synchronization.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_AV_SYNC for this command.
+
+ - .. row 3
+
+ - boolean state
+
+ - Tells the DVB subsystem if A/V synchronization shall be ON or OFF.
+
+ - .. row 4
+
+ -
+ - TRUE AV-sync ON
+
+ - .. row 5
+
+ -
+ - FALSE AV-sync OFF
+
+
+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:
+
+AUDIO_SET_BYPASS_MODE
+=====================
+
+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 DVB system shall be decoded. Dolby
+DigitalTM streams are automatically forwarded by the DVB subsystem if
+the hardware can handle it.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SET_BYPASS_MODE for this command.
+
+ - .. row 3
+
+ - boolean mode
+
+ - Enables or disables the decoding of the current Audio stream in
+ the DVB subsystem.
+
+ - .. row 4
+
+ -
+ - TRUE Bypass is disabled
+
+ - .. row 5
+
+ -
+ - FALSE Bypass is enabled
+
+
+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:
+
+AUDIO_CHANNEL_SELECT
+====================
+
+DESCRIPTION
+
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT,
+audio_channel_select_t);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_CHANNEL_SELECT for this command.
+
+ - .. row 3
+
+ - audio_channel_select_t ch
+
+ - Select the output format of the audio (mono left/right, stereo).
+
+
+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_BILINGUAL_CHANNEL_SELECT:
+
+AUDIO_BILINGUAL_CHANNEL_SELECT
+==============================
+
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT,
+audio_channel_select_t);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_BILINGUAL_CHANNEL_SELECT for this command.
+
+ - .. row 3
+
+ - audio_channel_select_t ch
+
+ - Select the output format of the audio (mono left/right, stereo).
+
+
+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_PTS:
+
+AUDIO_GET_PTS
+=============
+
+DESCRIPTION
+
+This ioctl is obsolete. Do not use in new drivers. If you need this
+functionality, then please contact the linux-media mailing list
+(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__).
+
+This ioctl call asks the Audio Device to return the current PTS
+timestamp.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_GET_PTS, __u64 *pts);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_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.
+
+
+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:
+
+AUDIO_GET_STATUS
+================
+
+DESCRIPTION
+
+This ioctl call asks the Audio Device to return the current state of the
+Audio Device.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audio_status
+*status);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_GET_STATUS for this command.
+
+ - .. row 3
+
+ - struct audio_status *status
+
+ - Returns the current state of 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:
+
+AUDIO_GET_CAPABILITIES
+======================
+
+DESCRIPTION
+
+This ioctl call asks the Audio Device to tell us about the decoding
+capabilities of the audio hardware.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, unsigned int
+*cap);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_GET_CAPABILITIES for this command.
+
+ - .. row 3
+
+ - unsigned int *cap
+
+ - Returns a bit array of supported sound formats.
+
+
+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:
+
+AUDIO_CLEAR_BUFFER
+==================
+
+DESCRIPTION
+
+This ioctl call asks the Audio Device to clear all software and hardware
+buffers of the audio decoder device.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_CLEAR_BUFFER for this 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_SET_ID:
+
+AUDIO_SET_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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_SET_ID, int id);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SET_ID for this command.
+
+ - .. row 3
+
+ - int id
+
+ - audio sub-stream id
+
+
+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:
+
+AUDIO_SET_MIXER
+===============
+
+DESCRIPTION
+
+This ioctl lets you adjust the mixer settings of the audio decoder.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t
+*mix);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SET_ID for this command.
+
+ - .. row 3
+
+ - audio_mixer_t *mix
+
+ - mixer settings.
+
+
+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:
+
+AUDIO_SET_STREAMTYPE
+====================
+
+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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SET_STREAMTYPE for this command.
+
+ - .. row 3
+
+ - int type
+
+ - stream type
+
+
+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.
+
+
+
+.. _AUDIO_SET_EXT_ID:
+
+AUDIO_SET_EXT_ID
+================
+
+DESCRIPTION
+
+This ioctl can be used to set the extension id for MPEG streams in DVD
+playback. Only the first 3 bits are recognized.
+
+SYNOPSIS
+
+int ioctl(fd, int request = AUDIO_SET_EXT_ID, int id);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SET_EXT_ID for this command.
+
+ - .. row 3
+
+ - int id
+
+ - audio sub_stream_id
+
+
+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
+
+ - id is not a valid id.
+
+
+
+.. _AUDIO_SET_ATTRIBUTES:
+
+AUDIO_SET_ATTRIBUTES
+====================
+
+DESCRIPTION
+
+This ioctl is intended for DVD playback and allows you to set certain
+information about the audio stream.
+
+SYNOPSIS
+
+int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, audio_attributes_t
+attr );
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SET_ATTRIBUTES for this command.
+
+ - .. row 3
+
+ - audio_attributes_t attr
+
+ - audio attributes according to 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.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EINVAL
+
+ - attr is not a valid or supported attribute setting.
+
+
+
+.. _AUDIO_SET_KARAOKE:
+
+AUDIO_SET_KARAOKE
+=================
+
+DESCRIPTION
+
+This ioctl allows one to set the mixer settings for a karaoke DVD.
+
+SYNOPSIS
+
+int ioctl(fd, int request = AUDIO_SET_KARAOKE, audio_karaoke_t
+*karaoke);
+
+PARAMETERS
+
+
+
+.. 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 AUDIO_SET_KARAOKE for this command.
+
+ - .. row 3
+
+ - audio_karaoke_t *karaoke
+
+ - karaoke settings according to 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.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EINVAL
+
+ - karaoke is not a valid or supported karaoke setting.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_h:
+
+*********************
+DVB Audio Header File
+*********************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ../../audio.h
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_ca:
+
+#############
+DVB CA Device
+#############
+The DVB CA device controls the conditional access hardware. It can be
+accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl
+definitions can be accessed by including ``linux/dvb/ca.h`` in your
+application.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ca_data_types
+ ca_function_calls
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ca_data_types:
+
+*************
+CA Data Types
+*************
+
+
+.. _ca-slot-info:
+
+ca_slot_info_t
+==============
+
+
+.. code-block:: c
+
+ typedef struct ca_slot_info {
+ int num; /* slot number */
+
+ int type; /* CA interface this slot supports */
+ #define CA_CI 1 /* CI high level interface */
+ #define CA_CI_LINK 2 /* CI link layer level interface */
+ #define CA_CI_PHYS 4 /* CI physical layer level interface */
+ #define CA_DESCR 8 /* built-in descrambler */
+ #define CA_SC 128 /* simple smart card interface */
+
+ unsigned int flags;
+ #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
+ #define CA_CI_MODULE_READY 2
+ } ca_slot_info_t;
+
+
+.. _ca-descr-info:
+
+ca_descr_info_t
+===============
+
+
+.. code-block:: c
+
+ typedef struct ca_descr_info {
+ unsigned int num; /* number of available descramblers (keys) */
+ unsigned int type; /* type of supported scrambling system */
+ #define CA_ECD 1
+ #define CA_NDS 2
+ #define CA_DSS 4
+ } ca_descr_info_t;
+
+
+.. _ca-caps:
+
+ca_caps_t
+=========
+
+
+.. code-block:: c
+
+ typedef struct ca_caps {
+ unsigned int slot_num; /* total number of CA card and module slots */
+ unsigned int slot_type; /* OR of all supported types */
+ unsigned int descr_num; /* total number of descrambler slots (keys) */
+ unsigned int descr_type;/* OR of all supported types */
+ } ca_cap_t;
+
+
+.. _ca-msg:
+
+ca_msg_t
+========
+
+
+.. code-block:: c
+
+ /* a message to/from a CI-CAM */
+ typedef struct ca_msg {
+ unsigned int index;
+ unsigned int type;
+ unsigned int length;
+ unsigned char msg[256];
+ } ca_msg_t;
+
+
+.. _ca-descr:
+
+ca_descr_t
+==========
+
+
+.. code-block:: c
+
+ typedef struct ca_descr {
+ unsigned int index;
+ unsigned int parity;
+ unsigned char cw[8];
+ } ca_descr_t;
+
+
+.. _ca-pid:
+
+ca-pid
+======
+
+
+.. code-block:: c
+
+ typedef struct ca_pid {
+ unsigned int pid;
+ int index; /* -1 == disable*/
+ } ca_pid_t;
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ca_function_calls:
+
+*****************
+CA Function Calls
+*****************
+
+
+.. _ca_fopen:
+
+open()
+======
+
+DESCRIPTION
+
+This system call opens a named ca device (e.g. /dev/ost/ca) 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 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.
+
+SYNOPSIS
+
+int open(const char *deviceName, int flags);
+
+PARAMETERS
+
+
+
+.. 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)
+
+
+RETURN VALUE
+
+
+
+.. 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.
+
+
+
+.. _ca_fclose:
+
+close()
+=======
+
+DESCRIPTION
+
+This system call closes a previously opened audio device.
+
+SYNOPSIS
+
+int close(int fd);
+
+PARAMETERS
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+
+RETURN VALUE
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EBADF
+
+ - fd is not a valid open file descriptor.
+
+
+
+.. _CA_RESET:
+
+CA_RESET
+========
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = CA_RESET);
+
+PARAMETERS
+
+
+
+.. 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 CA_RESET for this 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.
+
+
+.. _CA_GET_CAP:
+
+CA_GET_CAP
+==========
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = CA_GET_CAP, ca_caps_t *);
+
+PARAMETERS
+
+
+
+.. 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 CA_GET_CAP for this command.
+
+ - .. row 3
+
+ - ca_caps_t *
+
+ - Undocumented.
+
+
+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.
+
+
+.. _CA_GET_SLOT_INFO:
+
+CA_GET_SLOT_INFO
+================
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = CA_GET_SLOT_INFO, ca_slot_info_t *);
+
+PARAMETERS
+
+
+
+.. 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 CA_GET_SLOT_INFO for this command.
+
+ - .. row 3
+
+ - ca_slot_info_t *
+
+ - Undocumented.
+
+
+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.
+
+
+.. _CA_GET_DESCR_INFO:
+
+CA_GET_DESCR_INFO
+=================
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = CA_GET_DESCR_INFO, ca_descr_info_t *);
+
+PARAMETERS
+
+
+
+.. 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 CA_GET_DESCR_INFO for this command.
+
+ - .. row 3
+
+ - ca_descr_info_t *
+
+ - Undocumented.
+
+
+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.
+
+
+.. _CA_GET_MSG:
+
+CA_GET_MSG
+==========
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = CA_GET_MSG, ca_msg_t *);
+
+PARAMETERS
+
+
+
+.. 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 CA_GET_MSG for this command.
+
+ - .. row 3
+
+ - ca_msg_t *
+
+ - Undocumented.
+
+
+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.
+
+
+.. _CA_SEND_MSG:
+
+CA_SEND_MSG
+===========
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = CA_SEND_MSG, ca_msg_t *);
+
+PARAMETERS
+
+
+
+.. 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 CA_SEND_MSG for this command.
+
+ - .. row 3
+
+ - ca_msg_t *
+
+ - Undocumented.
+
+
+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.
+
+
+.. _CA_SET_DESCR:
+
+CA_SET_DESCR
+============
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = CA_SET_DESCR, ca_descr_t *);
+
+PARAMETERS
+
+
+
+.. 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 CA_SET_DESCR for this command.
+
+ - .. row 3
+
+ - ca_descr_t *
+
+ - Undocumented.
+
+
+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.
+
+
+.. _CA_SET_PID:
+
+CA_SET_PID
+==========
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = CA_SET_PID, ca_pid_t *);
+
+PARAMETERS
+
+
+
+.. 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 CA_SET_PID for this command.
+
+ - .. row 3
+
+ - ca_pid_t *
+
+ - Undocumented.
+
+
+RETURN VALUE
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ca_h:
+
+**********************************
+DVB Conditional Access Header File
+**********************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ../../ca.h
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_demux:
+
+################
+DVB Demux Device
+################
+The DVB demux device controls the filters of the DVB hardware/software.
+It can be accessed through ``/dev/adapter?/demux?``. Data types and and
+ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in
+your application.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ dmx_types
+ dmx_fcalls
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_fcalls:
+
+********************
+Demux Function Calls
+********************
+
+
+.. _dmx_fopen:
+
+open()
+======
+
+DESCRIPTION
+
+This system call, used with a device name of /dev/dvb/adapter0/demux0,
+allocates a new filter and returns a handle which can be used for
+subsequent control of that filter. This call has to be made for each
+filter to be used, i.e. every returned file descriptor is a reference to
+a single filter. /dev/dvb/adapter0/dvr0 is a logical device to be used
+for retrieving Transport Streams for digital video recording. When
+reading from this device a transport stream containing the packets from
+all PES filters set in the corresponding demux device
+(/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
+recorded Transport Stream is replayed by writing to this device.
+
+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.
+
+SYNOPSIS
+
+int open(const char *deviceName, int flags);
+
+PARAMETERS
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - const char *deviceName
+
+ - Name of demux device.
+
+ - .. row 2
+
+ - int flags
+
+ - A bit-wise OR of the following flags:
+
+ - .. row 3
+
+ -
+ - O_RDWR read/write access
+
+ - .. row 4
+
+ -
+ - O_NONBLOCK open in non-blocking mode
+
+ - .. row 5
+
+ -
+ - (blocking mode is the default)
+
+
+RETURN VALUE
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ENODEV
+
+ - Device driver not loaded/available.
+
+ - .. row 2
+
+ - EINVAL
+
+ - Invalid argument.
+
+ - .. row 3
+
+ - EMFILE
+
+ - “Too many open files”, i.e. no more filters available.
+
+ - .. row 4
+
+ - ENOMEM
+
+ - The driver failed to allocate enough memory.
+
+
+
+.. _dmx_fclose:
+
+close()
+=======
+
+DESCRIPTION
+
+This system call deactivates and deallocates a filter that was
+previously allocated via the open() call.
+
+SYNOPSIS
+
+int close(int fd);
+
+PARAMETERS
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+
+RETURN VALUE
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EBADF
+
+ - fd is not a valid open file descriptor.
+
+
+
+.. _dmx_fread:
+
+read()
+======
+
+DESCRIPTION
+
+This system call returns filtered data, which might be section or PES
+data. The filtered data is transferred from the driver’s internal
+circular buffer to buf. The maximum amount of data to be transferred is
+implied by count.
+
+SYNOPSIS
+
+size_t read(int fd, void *buf, size_t count);
+
+PARAMETERS
+
+
+
+.. 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 to be used for returned filtered data.
+
+ - .. row 3
+
+ - size_t count
+
+ - Size of buf.
+
+
+RETURN VALUE
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EWOULDBLOCK
+
+ - No data to return and O_NONBLOCK was specified.
+
+ - .. row 2
+
+ - EBADF
+
+ - fd is not a valid open file descriptor.
+
+ - .. row 3
+
+ - ECRC
+
+ - Last section had a CRC error - no data returned. The buffer is
+ flushed.
+
+ - .. row 4
+
+ - EOVERFLOW
+
+ -
+
+ - .. row 5
+
+ -
+ - The filtered data was not read from the buffer in due time,
+ resulting in non-read data being lost. The buffer is flushed.
+
+ - .. row 6
+
+ - ETIMEDOUT
+
+ - The section was not loaded within the stated timeout period. See
+ ioctl DMX_SET_FILTER for how to set a timeout.
+
+ - .. row 7
+
+ - EFAULT
+
+ - The driver failed to write to the callers buffer due to an invalid
+ *buf pointer.
+
+
+
+.. _dmx_fwrite:
+
+write()
+=======
+
+DESCRIPTION
+
+This system call is only provided by the logical device
+/dev/dvb/adapter0/dvr0, associated with the physical demux device that
+provides the actual DVR functionality. It is used for replay of a
+digitally recorded Transport Stream. Matching filters have to be defined
+in the corresponding physical demux device, /dev/dvb/adapter0/demux0.
+The amount of data to be transferred is implied by count.
+
+SYNOPSIS
+
+ssize_t write(int fd, const void *buf, size_t count);
+
+PARAMETERS
+
+
+
+.. 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 Transport Stream.
+
+ - .. row 3
+
+ - size_t count
+
+ - Size of buf.
+
+
+RETURN VALUE
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EWOULDBLOCK
+
+ - No data was written. This might happen if O_NONBLOCK was
+ specified and there is no more buffer space available (if
+ O_NONBLOCK is not specified the function will block until buffer
+ space is available).
+
+ - .. row 2
+
+ - EBUSY
+
+ - This error code indicates that there are conflicting requests. The
+ corresponding demux device is setup to receive data from the
+ front- end. Make sure that these filters are stopped and that the
+ filters with input set to DMX_IN_DVR are started.
+
+ - .. row 3
+
+ - EBADF
+
+ - fd is not a valid open file descriptor.
+
+
+
+.. _DMX_START:
+
+DMX_START
+=========
+
+DESCRIPTION
+
+This ioctl call is used to start the actual filtering operation defined
+via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER.
+
+SYNOPSIS
+
+int ioctl( int fd, int request = DMX_START);
+
+PARAMETERS
+
+
+
+.. 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 DMX_START for this 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.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EINVAL
+
+ - Invalid argument, i.e. no filtering parameters provided via the
+ DMX_SET_FILTER or DMX_SET_PES_FILTER functions.
+
+ - .. row 2
+
+ - EBUSY
+
+ - This error code indicates that there are conflicting requests.
+ There are active filters filtering data from another input source.
+ Make sure that these filters are stopped before starting this
+ filter.
+
+
+
+.. _DMX_STOP:
+
+DMX_STOP
+========
+
+DESCRIPTION
+
+This ioctl call is used to stop the actual filtering operation defined
+via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and
+started via the DMX_START command.
+
+SYNOPSIS
+
+int ioctl( int fd, int request = DMX_STOP);
+
+PARAMETERS
+
+
+
+.. 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 DMX_STOP for this 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.
+
+
+.. _DMX_SET_FILTER:
+
+DMX_SET_FILTER
+==============
+
+DESCRIPTION
+
+This ioctl call sets up a filter according to the filter and mask
+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
+stopped after the first section is received, and whether the filtering
+operation should be started immediately (without waiting for a
+DMX_START ioctl call). If a filter was previously set-up, this filter
+will be canceled, and the receive buffer will be flushed.
+
+SYNOPSIS
+
+int ioctl( int fd, int request = DMX_SET_FILTER, struct
+dmx_sct_filter_params *params);
+
+PARAMETERS
+
+
+
+.. 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 DMX_SET_FILTER for this command.
+
+ - .. row 3
+
+ - struct dmx_sct_filter_params *params
+
+ - Pointer to structure containing filter parameters.
+
+
+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.
+
+
+.. _DMX_SET_PES_FILTER:
+
+DMX_SET_PES_FILTER
+==================
+
+DESCRIPTION
+
+This ioctl call sets up a PES filter according to the parameters
+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.
+
+SYNOPSIS
+
+int ioctl( int fd, int request = DMX_SET_PES_FILTER, struct
+dmx_pes_filter_params *params);
+
+PARAMETERS
+
+
+
+.. 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 DMX_SET_PES_FILTER for this command.
+
+ - .. row 3
+
+ - struct dmx_pes_filter_params *params
+
+ - Pointer to structure containing filter parameters.
+
+
+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
+
+ - EBUSY
+
+ - This error code indicates that there are conflicting requests.
+ There are active filters filtering data from another input source.
+ Make sure that these filters are stopped before starting this
+ filter.
+
+
+
+.. _DMX_SET_BUFFER_SIZE:
+
+DMX_SET_BUFFER_SIZE
+===================
+
+DESCRIPTION
+
+This ioctl call is used to set the size of the circular buffer used for
+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.
+
+SYNOPSIS
+
+int ioctl( int fd, int request = DMX_SET_BUFFER_SIZE, unsigned long
+size);
+
+PARAMETERS
+
+
+
+.. 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 DMX_SET_BUFFER_SIZE for this command.
+
+ - .. row 3
+
+ - unsigned long size
+
+ - Size of circular buffer.
+
+
+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.
+
+
+.. _DMX_GET_EVENT:
+
+DMX_GET_EVENT
+=============
+
+DESCRIPTION
+
+This ioctl call returns an 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.
+
+SYNOPSIS
+
+int ioctl( int fd, int request = DMX_GET_EVENT, struct dmx_event
+*ev);
+
+PARAMETERS
+
+
+
+.. 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 DMX_GET_EVENT for this command.
+
+ - .. row 3
+
+ - struct dmx_event *ev
+
+ - Pointer to the location where the event is to be stored.
+
+
+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.
+
+
+
+.. _DMX_GET_STC:
+
+DMX_GET_STC
+===========
+
+DESCRIPTION
+
+This ioctl call returns the current value of the system time counter
+(which is driven by a PES filter of type DMX_PES_PCR). Some hardware
+supports more than one STC, so you must specify which one by setting the
+num field of stc before the ioctl (range 0...n). 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 .
+
+SYNOPSIS
+
+int ioctl( int fd, int request = DMX_GET_STC, struct dmx_stc *stc);
+
+PARAMETERS
+
+
+
+.. 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 DMX_GET_STC for this command.
+
+ - .. row 3
+
+ - struct dmx_stc *stc
+
+ - Pointer to the location where the stc is to be stored.
+
+
+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
+
+ - Invalid stc number.
+
+
+
+.. _DMX_GET_PES_PIDS:
+
+DMX_GET_PES_PIDS
+================
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = DMX_GET_PES_PIDS, __u16[5]);
+
+PARAMETERS
+
+
+
+.. 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 DMX_GET_PES_PIDS for this command.
+
+ - .. row 3
+
+ - __u16[5]
+
+ - Undocumented.
+
+
+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.
+
+
+.. _DMX_GET_CAPS:
+
+DMX_GET_CAPS
+============
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = DMX_GET_CAPS, dmx_caps_t *);
+
+PARAMETERS
+
+
+
+.. 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 DMX_GET_CAPS for this command.
+
+ - .. row 3
+
+ - dmx_caps_t *
+
+ - Undocumented.
+
+
+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.
+
+
+.. _DMX_SET_SOURCE:
+
+DMX_SET_SOURCE
+==============
+
+DESCRIPTION
+
+This ioctl is undocumented. Documentation is welcome.
+
+SYNOPSIS
+
+int ioctl(fd, int request = DMX_SET_SOURCE, dmx_source_t *);
+
+PARAMETERS
+
+
+
+.. 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 DMX_SET_SOURCE for this command.
+
+ - .. row 3
+
+ - dmx_source_t *
+
+ - Undocumented.
+
+
+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.
+
+
+.. _DMX_ADD_PID:
+
+DMX_ADD_PID
+===========
+
+DESCRIPTION
+
+This ioctl call allows to add multiple PIDs to a transport stream filter
+previously set up with DMX_SET_PES_FILTER and output equal to
+DMX_OUT_TSDEMUX_TAP.
+
+SYNOPSIS
+
+int ioctl(fd, int request = DMX_ADD_PID, __u16 *);
+
+PARAMETERS
+
+
+
+.. 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 DMX_ADD_PID for this command.
+
+ - .. row 3
+
+ - __u16 *
+
+ - PID number to be filtered.
+
+
+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.
+
+
+.. _DMX_REMOVE_PID:
+
+DMX_REMOVE_PID
+==============
+
+DESCRIPTION
+
+This ioctl call allows to remove a PID when multiple PIDs are set on a
+transport stream filter, e. g. a filter previously set up with output
+equal to DMX_OUT_TSDEMUX_TAP, created via either
+DMX_SET_PES_FILTER or DMX_ADD_PID.
+
+SYNOPSIS
+
+int ioctl(fd, int request = DMX_REMOVE_PID, __u16 *);
+
+PARAMETERS
+
+
+
+.. 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 DMX_REMOVE_PID for this command.
+
+ - .. row 3
+
+ - __u16 *
+
+ - PID of the PES filter to be removed.
+
+
+RETURN VALUE
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_h:
+
+*********************
+DVB Demux Header File
+*********************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ../../dmx.h
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_types:
+
+****************
+Demux Data Types
+****************
+
+
+.. _dmx-output-t:
+
+Output for the demux
+====================
+
+
+.. _dmx-output:
+
+.. flat-table:: enum dmx_output
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`DMX-OUT-DECODER`:
+
+ DMX_OUT_DECODER
+
+ - Streaming directly to decoder.
+
+ - .. row 3
+
+ - .. _`DMX-OUT-TAP`:
+
+ DMX_OUT_TAP
+
+ - Output going to a memory buffer (to be retrieved via the read
+ command). Delivers the stream output to the demux device on which
+ the ioctl is called.
+
+ - .. row 4
+
+ - .. _`DMX-OUT-TS-TAP`:
+
+ DMX_OUT_TS_TAP
+
+ - Output multiplexed into a new TS (to be retrieved by reading from
+ the logical DVR device). Routes output to the logical DVR device
+ ``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from
+ all filters for which ``DMX_OUT_TS_TAP`` was specified.
+
+ - .. row 5
+
+ - .. _`DMX-OUT-TSDEMUX-TAP`:
+
+ DMX_OUT_TSDEMUX_TAP
+
+ - Like :ref:`DMX_OUT_TS_TAP <DMX-OUT-TS-TAP>` but retrieved
+ from the DMX device.
+
+
+
+.. _dmx-input-t:
+
+dmx_input_t
+===========
+
+
+.. code-block:: c
+
+ typedef enum
+ {
+ DMX_IN_FRONTEND, /* Input from a front-end device. */
+ DMX_IN_DVR /* Input from the logical DVR device. */
+ } dmx_input_t;
+
+
+.. _dmx-pes-type-t:
+
+dmx_pes_type_t
+==============
+
+
+.. code-block:: c
+
+ typedef enum
+ {
+ DMX_PES_AUDIO0,
+ DMX_PES_VIDEO0,
+ DMX_PES_TELETEXT0,
+ DMX_PES_SUBTITLE0,
+ DMX_PES_PCR0,
+
+ DMX_PES_AUDIO1,
+ DMX_PES_VIDEO1,
+ DMX_PES_TELETEXT1,
+ DMX_PES_SUBTITLE1,
+ DMX_PES_PCR1,
+
+ DMX_PES_AUDIO2,
+ DMX_PES_VIDEO2,
+ DMX_PES_TELETEXT2,
+ DMX_PES_SUBTITLE2,
+ DMX_PES_PCR2,
+
+ DMX_PES_AUDIO3,
+ DMX_PES_VIDEO3,
+ DMX_PES_TELETEXT3,
+ DMX_PES_SUBTITLE3,
+ DMX_PES_PCR3,
+
+ DMX_PES_OTHER
+ } dmx_pes_type_t;
+
+
+.. _dmx-filter:
+
+struct dmx_filter
+=================
+
+
+.. code-block:: c
+
+ typedef struct dmx_filter
+ {
+ __u8 filter[DMX_FILTER_SIZE];
+ __u8 mask[DMX_FILTER_SIZE];
+ __u8 mode[DMX_FILTER_SIZE];
+ } dmx_filter_t;
+
+
+.. _dmx-sct-filter-params:
+
+struct dmx_sct_filter_params
+============================
+
+
+.. code-block:: c
+
+ struct dmx_sct_filter_params
+ {
+ __u16 pid;
+ dmx_filter_t filter;
+ __u32 timeout;
+ __u32 flags;
+ #define DMX_CHECK_CRC 1
+ #define DMX_ONESHOT 2
+ #define DMX_IMMEDIATE_START 4
+ #define DMX_KERNEL_CLIENT 0x8000
+ };
+
+
+.. _dmx-pes-filter-params:
+
+struct dmx_pes_filter_params
+============================
+
+
+.. code-block:: c
+
+ struct dmx_pes_filter_params
+ {
+ __u16 pid;
+ dmx_input_t input;
+ dmx_output_t output;
+ dmx_pes_type_t pes_type;
+ __u32 flags;
+ };
+
+
+.. _dmx-event:
+
+struct dmx_event
+================
+
+
+.. code-block:: c
+
+ struct dmx_event
+ {
+ dmx_event_t event;
+ time_t timeStamp;
+ union
+ {
+ dmx_scrambling_status_t scrambling;
+ } u;
+ };
+
+
+.. _dmx-stc:
+
+struct dmx_stc
+==============
+
+
+.. code-block:: c
+
+ struct dmx_stc {
+ unsigned int num; /* input : which STC? 0..N */
+ unsigned int base; /* output: divisor for stc to get 90 kHz clock */
+ __u64 stc; /* output: stc in 'base'*90 kHz units */
+ };
+
+
+.. _dmx-caps:
+
+struct dmx_caps
+===============
+
+
+.. code-block:: c
+
+ typedef struct dmx_caps {
+ __u32 caps;
+ int num_decoders;
+ } dmx_caps_t;
+
+
+.. _dmx-source-t:
+
+enum dmx_source_t
+=================
+
+
+.. code-block:: c
+
+ typedef enum {
+ DMX_SOURCE_FRONT0 = 0,
+ DMX_SOURCE_FRONT1,
+ DMX_SOURCE_FRONT2,
+ DMX_SOURCE_FRONT3,
+ DMX_SOURCE_DVR0 = 16,
+ DMX_SOURCE_DVR1,
+ DMX_SOURCE_DVR2,
+ DMX_SOURCE_DVR3
+ } dmx_source_t;
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dtv-fe-stats:
+
+*******************
+struct dtv_fe_stats
+*******************
+
+
+.. code-block:: c
+
+ #define MAX_DTV_STATS 4
+
+ struct dtv_fe_stats {
+ __u8 len;
+ struct dtv_stats stat[MAX_DTV_STATS];
+ } __packed;
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dtv-properties:
+
+*********************
+struct dtv_properties
+*********************
+
+
+.. code-block:: c
+
+ struct dtv_properties {
+ __u32 num;
+ struct dtv_property *props;
+ };
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dtv-property:
+
+*******************
+struct dtv_property
+*******************
+
+
+.. code-block:: c
+
+ /* Reserved fields should be set to 0 */
+
+ struct dtv_property {
+ __u32 cmd;
+ __u32 reserved[3];
+ union {
+ __u32 data;
+ struct dtv_fe_stats st;
+ struct {
+ __u8 data[32];
+ __u32 len;
+ __u32 reserved1[3];
+ void *reserved2;
+ } buffer;
+ } u;
+ int result;
+ } __attribute__ ((packed));
+
+ /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
+ #define DTV_IOCTL_MAX_MSGS 64
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dtv-stats:
+
+****************
+struct dtv_stats
+****************
+
+
+.. code-block:: c
+
+ struct dtv_stats {
+ __u8 scale; /* enum fecap_scale_params type */
+ union {
+ __u64 uvalue; /* for counters and relative scales */
+ __s64 svalue; /* for 1/1000 dB measures */
+ };
+ } __packed;
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb-fe-read-status:
+
+***************************************
+Querying frontend status and statistics
+***************************************
+
+Once :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` is called, the
+frontend will run a kernel thread that will periodically check for the
+tuner lock status and provide statistics about the quality of the
+signal.
+
+The information about the frontend tuner locking status can be queried
+using :ref:`FE_READ_STATUS <FE_READ_STATUS>`.
+
+Signal statistics are provided via
+:ref:`FE_GET_PROPERTY <FE_GET_PROPERTY>`. Please note that several
+statistics require the demodulator to be fully locked (e. g. with
+FE_HAS_LOCK bit set). See
+:ref:`Frontend statistics indicators <frontend-stat-properties>` for
+more details.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb-frontend-event:
+
+***************
+frontend events
+***************
+
+
+.. code-block:: c
+
+ struct dvb_frontend_event {
+ fe_status_t status;
+ struct dvb_frontend_parameters parameters;
+ };
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb-frontend-parameters:
+
+*******************
+frontend parameters
+*******************
+
+The kind of parameters passed to the frontend device for tuning depend
+on the kind of hardware you are using.
+
+The struct ``dvb_frontend_parameters`` uses an union with specific
+per-system parameters. However, as newer delivery systems required more
+data, the structure size weren't enough to fit, and just extending its
+size would break the existing applications. So, those parameters were
+replaced by the usage of
+:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
+ioctl's. The new API is flexible enough to add new parameters to
+existing delivery systems, and to add newer delivery systems.
+
+So, newer applications should use
+:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
+instead, in order to be able to support the newer System Delivery like
+DVB-S2, DVB-T2, DVB-C2, ISDB, etc.
+
+All kinds of parameters are combined as an union in the
+FrontendParameters structure:
+
+
+.. code-block:: c
+
+ struct dvb_frontend_parameters {
+ uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */
+ /* intermediate frequency in kHz for QPSK */
+ fe_spectral_inversion_t inversion;
+ union {
+ struct dvb_qpsk_parameters qpsk;
+ struct dvb_qam_parameters qam;
+ struct dvb_ofdm_parameters ofdm;
+ struct dvb_vsb_parameters vsb;
+ } u;
+ };
+
+In the case of QPSK frontends the ``frequency`` field specifies the
+intermediate frequency, i.e. the offset which is effectively added to
+the local oscillator frequency (LOF) of the LNB. The intermediate
+frequency has to be specified in units of kHz. For QAM and OFDM
+frontends the ``frequency`` specifies the absolute frequency and is
+given in Hz.
+
+
+.. _dvb-qpsk-parameters:
+
+QPSK parameters
+===============
+
+For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters``
+structure:
+
+
+.. code-block:: c
+
+ struct dvb_qpsk_parameters {
+ uint32_t symbol_rate; /* symbol rate in Symbols per second */
+ fe_code_rate_t fec_inner; /* forward error correction (see above) */
+ };
+
+
+.. _dvb-qam-parameters:
+
+QAM parameters
+==============
+
+for cable QAM frontend you use the ``dvb_qam_parameters`` structure:
+
+
+.. code-block:: c
+
+ struct dvb_qam_parameters {
+ uint32_t symbol_rate; /* symbol rate in Symbols per second */
+ fe_code_rate_t fec_inner; /* forward error correction (see above) */
+ fe_modulation_t modulation; /* modulation type (see above) */
+ };
+
+
+.. _dvb-vsb-parameters:
+
+VSB parameters
+==============
+
+ATSC frontends are supported by the ``dvb_vsb_parameters`` structure:
+
+
+.. code-block:: c
+
+ struct dvb_vsb_parameters {
+ fe_modulation_t modulation; /* modulation type (see above) */
+ };
+
+
+.. _dvb-ofdm-parameters:
+
+OFDM parameters
+===============
+
+DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure:
+
+
+.. code-block:: c
+
+ struct dvb_ofdm_parameters {
+ fe_bandwidth_t bandwidth;
+ fe_code_rate_t code_rate_HP; /* high priority stream code rate */
+ fe_code_rate_t code_rate_LP; /* low priority stream code rate */
+ fe_modulation_t constellation; /* modulation type (see above) */
+ fe_transmit_mode_t transmission_mode;
+ fe_guard_interval_t guard_interval;
+ fe_hierarchy_t hierarchy_information;
+ };
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvbapi:
+
+#############
+LINUX DVB API
+#############
+
+**Version 5.10**
+
+.. toctree::
+ :maxdepth: 1
+
+ intro
+ frontend
+ demux
+ ca
+ net
+ legacy_dvb_apis
+ examples
+ audio_h
+ ca_h
+ dmx_h
+ frontend_h
+ net_h
+ video_h
+
+
+**********************
+Revision and Copyright
+**********************
+
+
+:author: Metzler Ralph (*J. K.*)
+:address: rjkm@metzlerbros.de
+
+:author: Metzler Marcus (*O. C.*)
+:address: rjkm@metzlerbros.de
+
+:author: Chehab Mauro (*Carvalho*)
+:address: m.chehab@samsung.com
+:contrib: Ported document to Docbook XML.
+
+**Copyright** 2002, 2003 : Convergence GmbH
+
+**Copyright** 2009-2015 : Mauro Carvalho Chehab
+
+:revision: 2.1.0 / 2015-05-29 (*mcc*)
+
+DocBook improvements and cleanups, in order to document the system calls
+on a more standard way and provide more description about the current
+DVB API.
+
+
+:revision: 2.0.4 / 2011-05-06 (*mcc*)
+
+Add more information about DVB APIv5, better describing the frontend
+GET/SET props ioctl's.
+
+
+:revision: 2.0.3 / 2010-07-03 (*mcc*)
+
+Add some frontend capabilities flags, present on kernel, but missing at
+the specs.
+
+
+:revision: 2.0.2 / 2009-10-25 (*mcc*)
+
+documents FE_SET_FRONTEND_TUNE_MODE and
+FE_DISHETWORK_SEND_LEGACY_CMD ioctls.
+
+
+:revision: 2.0.1 / 2009-09-16 (*mcc*)
+
+Added ISDB-T test originally written by Patrick Boettcher
+
+
+:revision: 2.0.0 / 2009-09-06 (*mcc*)
+
+Conversion from LaTex to DocBook XML. The contents is the same as the
+original LaTex version.
+
+
+:revision: 1.0.0 / 2003-07-24 (*rjkm*)
+
+Initial revision on LaTEX.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+**************
+Property types
+**************
+
+On :ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>`,
+the actual action is determined by the dtv_property cmd/data pairs.
+With one single ioctl, is possible to get/set up to 64 properties. The
+actual meaning of each property is described on the next sections.
+
+The available frontend property types are shown on the next section.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-properties:
+
+DVB Frontend properties
+=======================
+
+Tuning into a Digital TV physical channel and starting decoding it
+requires changing a set of parameters, in order to control the tuner,
+the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
+antenna subsystem via Satellite Equipment Control (SEC), on satellite
+systems. The actual parameters are specific to each particular digital
+TV standards, and may change as the digital TV specs evolves.
+
+In the past, the strategy used was to have a union with the parameters
+needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped
+there. The problem is that, as the second generation standards appeared,
+those structs were not big enough to contain the additional parameters.
+Also, the union didn't have any space left to be expanded without
+breaking userspace. So, the decision was to deprecate the legacy
+union/struct based approach, in favor of a properties set approach.
+
+NOTE: on Linux DVB API version 3, setting a frontend were done via
+:ref:`struct dvb_frontend_parameters <dvb-frontend-parameters>`.
+This got replaced on version 5 (also called "S2API", as this API were
+added originally_enabled to provide support for DVB-S2), because the
+old API has a very limited support to new standards and new hardware.
+This section describes the new and recommended way to set the frontend,
+with suppports all digital TV delivery systems.
+
+Example: with the properties based approach, in order to set the tuner
+to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and
+symbol rate of 5.217 Mbauds, those properties should be sent to
+:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` =
+ SYS_DVBC_ANNEX_A
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
+
+- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+The code that would do the above is:
+
+
+.. code-block:: c
+
+ #include <stdio.h>
+ #include <fcntl.h>
+ #include <sys/ioctl.h>
+ #include <linux/dvb/frontend.h>
+
+ static struct dtv_property props[] = {
+ { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
+ { .cmd = DTV_FREQUENCY, .u.data = 651000000 },
+ { .cmd = DTV_MODULATION, .u.data = QAM_256 },
+ { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO },
+ { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 },
+ { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 },
+ { .cmd = DTV_TUNE }
+ };
+
+ static struct dtv_properties dtv_prop = {
+ .num = 6, .props = props
+ };
+
+ int main(void)
+ {
+ int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
+
+ if (!fd) {
+ perror ("open");
+ return -1;
+ }
+ if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
+ perror("ioctl");
+ return -1;
+ }
+ printf("Frontend set\\n");
+ return 0;
+ }
+
+NOTE: While it is possible to directly call the Kernel code like the
+above example, it is strongly recommended to use
+`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
+provides abstraction to work with the supported digital TV standards and
+provides methods for usual operations like program scanning and to
+read/write channel descriptor files.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ dtv-stats
+ dtv-fe-stats
+ dtv-property
+ dtv-properties
+ dvbproperty-006
+ fe_property_parameters
+ frontend-stat-properties
+ frontend-property-terrestrial-systems
+ frontend-property-cable-systems
+ frontend-property-satellite-systems
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_examples:
+
+********
+Examples
+********
+
+In this section we would like to present some examples for using the DVB
+API.
+
+NOTE: This section is out of date, and the code below won't even
+compile. Please refer to the
+`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__ for
+updated/recommended examples.
+
+
+.. _tuning:
+
+Tuning
+======
+
+We will start with a generic tuning subroutine that uses the frontend
+and SEC, as well as the demux devices. The example is given for QPSK
+tuners, but can easily be adjusted for QAM.
+
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+ #include <stdio.h>
+ #include <stdint.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <fcntl.h>
+ #include <time.h>
+ #include <unistd.h>
+
+ #include <linux/dvb/dmx.h>
+ #include <linux/dvb/frontend.h>
+ #include <linux/dvb/sec.h>
+ #include <sys/poll.h>
+
+ #define DMX "/dev/dvb/adapter0/demux1"
+ #define FRONT "/dev/dvb/adapter0/frontend1"
+ #define SEC "/dev/dvb/adapter0/sec1"
+
+ /* routine for checking if we have a signal and other status information*/
+ int FEReadStatus(int fd, fe_status_t *stat)
+ {
+ int ans;
+
+ if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){
+ perror("FE READ STATUS: ");
+ return -1;
+ }
+
+ if (*stat & FE_HAS_POWER)
+ printf("FE HAS POWER\\n");
+
+ if (*stat & FE_HAS_SIGNAL)
+ printf("FE HAS SIGNAL\\n");
+
+ if (*stat & FE_SPECTRUM_INV)
+ printf("SPEKTRUM INV\\n");
+
+ return 0;
+ }
+
+
+ /* tune qpsk */
+ /* freq: frequency of transponder */
+ /* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */
+ /* diseqc: DiSEqC address of the used LNB */
+ /* pol: Polarisation */
+ /* srate: Symbol Rate */
+ /* fec. FEC */
+ /* lnb_lof1: local frequency of lower LNB band */
+ /* lnb_lof2: local frequency of upper LNB band */
+ /* lnb_slof: switch frequency of LNB */
+
+ int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
+ int diseqc, int pol, int srate, int fec, int lnb_lof1,
+ int lnb_lof2, int lnb_slof)
+ {
+ struct secCommand scmd;
+ struct secCmdSequence scmds;
+ struct dmx_pes_filter_params pesFilterParams;
+ FrontendParameters frp;
+ struct pollfd pfd[1];
+ FrontendEvent event;
+ int demux1, demux2, demux3, front;
+
+ frequency = (uint32_t) freq;
+ symbolrate = (uint32_t) srate;
+
+ if((front = open(FRONT,O_RDWR)) < 0){
+ perror("FRONTEND DEVICE: ");
+ return -1;
+ }
+
+ if((sec = open(SEC,O_RDWR)) < 0){
+ perror("SEC DEVICE: ");
+ return -1;
+ }
+
+ if (demux1 < 0){
+ if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ if (demux2 < 0){
+ if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ if (demux3 < 0){
+ if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ if (freq < lnb_slof) {
+ frp.Frequency = (freq - lnb_lof1);
+ scmds.continuousTone = SEC_TONE_OFF;
+ } else {
+ frp.Frequency = (freq - lnb_lof2);
+ scmds.continuousTone = SEC_TONE_ON;
+ }
+ frp.Inversion = INVERSION_AUTO;
+ if (pol) scmds.voltage = SEC_VOLTAGE_18;
+ else scmds.voltage = SEC_VOLTAGE_13;
+
+ scmd.type=0;
+ scmd.u.diseqc.addr=0x10;
+ scmd.u.diseqc.cmd=0x38;
+ scmd.u.diseqc.numParams=1;
+ scmd.u.diseqc.params[0] = 0xF0 | ((diseqc * 4) & 0x0F) |
+ (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
+ (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
+
+ scmds.miniCommand=SEC_MINI_NONE;
+ scmds.numCommands=1;
+ scmds.commands=&scmd;
+ if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
+ perror("SEC SEND: ");
+ return -1;
+ }
+
+ if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
+ perror("SEC SEND: ");
+ return -1;
+ }
+
+ frp.u.qpsk.SymbolRate = srate;
+ frp.u.qpsk.FEC_inner = fec;
+
+ if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){
+ perror("QPSK TUNE: ");
+ return -1;
+ }
+
+ pfd[0].fd = front;
+ pfd[0].events = POLLIN;
+
+ if (poll(pfd,1,3000)){
+ if (pfd[0].revents & POLLIN){
+ printf("Getting QPSK event\\n");
+ if ( ioctl(front, FE_GET_EVENT, &event)
+
+ == -EOVERFLOW){
+ perror("qpsk get event");
+ return -1;
+ }
+ printf("Received ");
+ switch(event.type){
+ case FE_UNEXPECTED_EV:
+ printf("unexpected event\\n");
+ return -1;
+ case FE_FAILURE_EV:
+ printf("failure event\\n");
+ return -1;
+
+ case FE_COMPLETION_EV:
+ printf("completion event\\n");
+ }
+ }
+ }
+
+
+ pesFilterParams.pid = vpid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_DECODER;
+ pesFilterParams.pes_type = DMX_PES_VIDEO;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("set_vpid");
+ return -1;
+ }
+
+ pesFilterParams.pid = apid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_DECODER;
+ pesFilterParams.pes_type = DMX_PES_AUDIO;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("set_apid");
+ return -1;
+ }
+
+ pesFilterParams.pid = tpid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_DECODER;
+ pesFilterParams.pes_type = DMX_PES_TELETEXT;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("set_tpid");
+ return -1;
+ }
+
+ return has_signal(fds);
+ }
+
+The program assumes that you are using a universal LNB and a standard
+DiSEqC switch with up to 4 addresses. Of course, you could build in some
+more checking if tuning was successful and maybe try to repeat the
+tuning process. Depending on the external hardware, i.e. LNB and DiSEqC
+switch, and weather conditions this may be necessary.
+
+
+.. _the_dvr_device:
+
+The DVR device
+==============
+
+The following program code shows how to use the DVR device for
+recording.
+
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+ #include <stdio.h>
+ #include <stdint.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <fcntl.h>
+ #include <time.h>
+ #include <unistd.h>
+
+ #include <linux/dvb/dmx.h>
+ #include <linux/dvb/video.h>
+ #include <sys/poll.h>
+ #define DVR "/dev/dvb/adapter0/dvr1"
+ #define AUDIO "/dev/dvb/adapter0/audio1"
+ #define VIDEO "/dev/dvb/adapter0/video1"
+
+ #define BUFFY (188*20)
+ #define MAX_LENGTH (1024*1024*5) /* record 5MB */
+
+
+ /* switch the demuxes to recording, assuming the transponder is tuned */
+
+ /* demux1, demux2: file descriptor of video and audio filters */
+ /* vpid, apid: PIDs of video and audio channels */
+
+ int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
+ {
+ struct dmx_pes_filter_params pesFilterParams;
+
+ if (demux1 < 0){
+ if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ if (demux2 < 0){
+ if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ pesFilterParams.pid = vpid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_TS_TAP;
+ pesFilterParams.pes_type = DMX_PES_VIDEO;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("DEMUX DEVICE");
+ return -1;
+ }
+ pesFilterParams.pid = apid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_TS_TAP;
+ pesFilterParams.pes_type = DMX_PES_AUDIO;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("DEMUX DEVICE");
+ return -1;
+ }
+ return 0;
+ }
+
+ /* start recording MAX_LENGTH , assuming the transponder is tuned */
+
+ /* demux1, demux2: file descriptor of video and audio filters */
+ /* vpid, apid: PIDs of video and audio channels */
+ int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
+ {
+ int i;
+ int len;
+ int written;
+ uint8_t buf[BUFFY];
+ uint64_t length;
+ struct pollfd pfd[1];
+ int dvr, dvr_out;
+
+ /* open dvr device */
+ if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){
+ perror("DVR DEVICE");
+ return -1;
+ }
+
+ /* switch video and audio demuxes to dvr */
+ printf ("Switching dvr on\\n");
+ i = switch_to_record(demux1, demux2, vpid, apid);
+ printf("finished: ");
+
+ printf("Recording %2.0f MB of test file in TS format\\n",
+ MAX_LENGTH/(1024.0*1024.0));
+ length = 0;
+
+ /* open output file */
+ if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
+ |O_TRUNC, S_IRUSR|S_IWUSR
+ |S_IRGRP|S_IWGRP|S_IROTH|
+ S_IWOTH)) < 0){
+ perror("Can't open file for dvr test");
+ return -1;
+ }
+
+ pfd[0].fd = dvr;
+ pfd[0].events = POLLIN;
+
+ /* poll for dvr data and write to file */
+ while (length < MAX_LENGTH ) {
+ if (poll(pfd,1,1)){
+ if (pfd[0].revents & POLLIN){
+ len = read(dvr, buf, BUFFY);
+ if (len < 0){
+ perror("recording");
+ return -1;
+ }
+ if (len > 0){
+ written = 0;
+ while (written < len)
+ written +=
+ write (dvr_out,
+ buf, len);
+ length += len;
+ printf("written %2.0f MB\\r",
+ length/1024./1024.);
+ }
+ }
+ }
+ }
+ return 0;
+ }
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _fe-bandwidth-t:
+
+******************
+Frontend bandwidth
+******************
+
+
+.. _fe-bandwidth:
+
+.. flat-table:: enum fe_bandwidth
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`BANDWIDTH-AUTO`:
+
+ ``BANDWIDTH_AUTO``
+
+ - Autodetect bandwidth (if supported)
+
+ - .. row 3
+
+ - .. _`BANDWIDTH-1-712-MHZ`:
+
+ ``BANDWIDTH_1_712_MHZ``
+
+ - 1.712 MHz
+
+ - .. row 4
+
+ - .. _`BANDWIDTH-5-MHZ`:
+
+ ``BANDWIDTH_5_MHZ``
+
+ - 5 MHz
+
+ - .. row 5
+
+ - .. _`BANDWIDTH-6-MHZ`:
+
+ ``BANDWIDTH_6_MHZ``
+
+ - 6 MHz
+
+ - .. row 6
+
+ - .. _`BANDWIDTH-7-MHZ`:
+
+ ``BANDWIDTH_7_MHZ``
+
+ - 7 MHz
+
+ - .. row 7
+
+ - .. _`BANDWIDTH-8-MHZ`:
+
+ ``BANDWIDTH_8_MHZ``
+
+ - 8 MHz
+
+ - .. row 8
+
+ - .. _`BANDWIDTH-10-MHZ`:
+
+ ``BANDWIDTH_10_MHZ``
+
+ - 10 MHz
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISEQC_RECV_SLAVE_REPLY:
+
+********************************
+ioctl FE_DISEQC_RECV_SLAVE_REPLY
+********************************
+
+*man FE_DISEQC_RECV_SLAVE_REPLY(2)*
+
+Receives reply from a DiSEqC 2.0 command
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct dvb_diseqc_slave_reply *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_DISEQC_RECV_SLAVE_REPLY
+
+``argp``
+ pointer to struct
+ :ref:`dvb_diseqc_slave_reply <dvb-diseqc-slave-reply>`
+
+
+Description
+===========
+
+Receives reply from a DiSEqC 2.0 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.
+
+
+.. _dvb-diseqc-slave-reply:
+
+.. flat-table:: struct dvb_diseqc_slave_reply
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - uint8_t
+
+ - msg[4]
+
+ - DiSEqC message (framing, data[3])
+
+ - .. row 2
+
+ - uint8_t
+
+ - msg_len
+
+ - Length of the DiSEqC message. Valid values are 0 to 4, where 0
+ means no msg
+
+ - .. row 3
+
+ - int
+
+ - timeout
+
+ - Return from ioctl after timeout ms with errorcode when no message
+ was received
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISEQC_RESET_OVERLOAD:
+
+******************************
+ioctl FE_DISEQC_RESET_OVERLOAD
+******************************
+
+*man FE_DISEQC_RESET_OVERLOAD(2)*
+
+Restores the power to the antenna subsystem, if it was powered off due
+to power overload.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, NULL )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_DISEQC_RESET_OVERLOAD
+
+
+Description
+===========
+
+If the bus has been automatically powered off due to power overload,
+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 DVB adapters support this ioctl.
+
+RETURN VALUE
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISEQC_SEND_BURST:
+
+**************************
+ioctl FE_DISEQC_SEND_BURST
+**************************
+
+*man FE_DISEQC_SEND_BURST(2)*
+
+Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, enum fe_sec_mini_cmd *tone )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_DISEQC_SEND_BURST
+
+``tone``
+ pointer to enum :ref:`fe_sec_mini_cmd <fe-sec-mini-cmd>`
+
+
+Description
+===========
+
+This ioctl is used to set the generation of a 22kHz tone burst for mini
+DiSEqC satellite selection for 2x1 switches. This call requires
+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
+
+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.
+
+
+.. _fe-sec-mini-cmd-t:
+
+enum fe_sec_mini_cmd
+====================
+
+
+.. _fe-sec-mini-cmd:
+
+.. flat-table:: enum fe_sec_mini_cmd
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`SEC-MINI-A`:
+
+ ``SEC_MINI_A``
+
+ - Sends a mini-DiSEqC 22kHz '0' Tone Burst to select satellite-A
+
+ - .. row 3
+
+ - .. _`SEC-MINI-B`:
+
+ ``SEC_MINI_B``
+
+ - Sends a mini-DiSEqC 22kHz '1' Data Burst to select satellite-B
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISEQC_SEND_MASTER_CMD:
+
+*******************************
+ioctl FE_DISEQC_SEND_MASTER_CMD
+*******************************
+
+*man FE_DISEQC_SEND_MASTER_CMD(2)*
+
+Sends a DiSEqC command
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct dvb_diseqc_master_cmd *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_DISEQC_SEND_MASTER_CMD
+
+``argp``
+ pointer to struct
+ :ref:`dvb_diseqc_master_cmd <dvb-diseqc-master-cmd>`
+
+
+Description
+===========
+
+Sends a DiSEqC command to the antenna subsystem.
+
+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.
+
+
+.. _dvb-diseqc-master-cmd:
+
+.. flat-table:: struct dvb_diseqc_master_cmd
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - uint8_t
+
+ - msg[6]
+
+ - DiSEqC message (framing, address, command, data[3])
+
+ - .. row 2
+
+ - uint8_t
+
+ - msg_len
+
+ - Length of the DiSEqC message. Valid values are 3 to 6
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_ENABLE_HIGH_LNB_VOLTAGE:
+
+********************************
+ioctl FE_ENABLE_HIGH_LNB_VOLTAGE
+********************************
+
+*man FE_ENABLE_HIGH_LNB_VOLTAGE(2)*
+
+Select output DC level between normal LNBf voltages or higher LNBf
+voltages.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, unsigned int high )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_ENABLE_HIGH_LNB_VOLTAGE
+
+``high``
+ Valid flags:
+
+ - 0 - normal 13V and 18V.
+
+ - >0 - enables slightly higher voltages instead of 13/18V, in order
+ to compensate for long antenna cables.
+
+
+Description
+===========
+
+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
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_GET_INFO:
+
+*****************
+ioctl FE_GET_INFO
+*****************
+
+*man FE_GET_INFO(2)*
+
+Query DVB 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, int request, struct dvb_frontend_info *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_GET_INFO
+
+``argp``
+ pointer to struct struct
+ :ref:`dvb_frontend_info <dvb-frontend-info>`
+
+
+Description
+===========
+
+All DVB frontend devices support the ``FE_GET_INFO`` ioctl. It is used
+to identify kernel devices compatible with this specification and to
+obtain information about driver and hardware capabilities. The ioctl
+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.
+
+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.
+
+
+.. _dvb-frontend-info:
+
+.. flat-table:: struct dvb_frontend_info
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - char
+
+ - name[128]
+
+ - Name of the frontend
+
+ - .. row 2
+
+ - fe_type_t
+
+ - type
+
+ - **DEPRECATED**. DVBv3 type. Should not be used on modern programs,
+ as a frontend may have more than one type. So, the DVBv5 API
+ should be used instead to enumerate and select the frontend type.
+
+ - .. row 3
+
+ - uint32_t
+
+ - frequency_min
+
+ - Minimal frequency supported by the frontend
+
+ - .. row 4
+
+ - uint32_t
+
+ - frequency_max
+
+ - Maximal frequency supported by the frontend
+
+ - .. row 5
+
+ - uint32_t
+
+ - frequency_stepsize
+
+ - Frequency step - all frequencies are multiple of this value
+
+ - .. row 6
+
+ - uint32_t
+
+ - frequency_tolerance
+
+ - Tolerance of the frequency
+
+ - .. row 7
+
+ - uint32_t
+
+ - symbol_rate_min
+
+ - Minimal symbol rate (for Cable/Satellite systems), in bauds
+
+ - .. row 8
+
+ - uint32_t
+
+ - symbol_rate_max
+
+ - Maximal symbol rate (for Cable/Satellite systems), in bauds
+
+ - .. row 9
+
+ - uint32_t
+
+ - symbol_rate_tolerance
+
+ - Maximal symbol rate tolerance, in ppm
+
+ - .. row 10
+
+ - uint32_t
+
+ - notifier_delay
+
+ - **DEPRECATED**. Not used by any driver.
+
+ - .. row 11
+
+ - enum :ref:`fe_caps <fe-caps>`
+
+ - caps
+
+ - Capabilities supported by the frontend
+
+
+NOTE: The frequencies are specified in Hz for Terrestrial and Cable
+systems. They're specified in kHz for Satellite systems
+
+
+.. _fe-caps-t:
+
+frontend capabilities
+=====================
+
+Capabilities describe what a frontend can do. Some capabilities are
+supported only on some specific frontend types.
+
+
+.. _fe-caps:
+
+.. flat-table:: enum fe_caps
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`FE-IS-STUPID`:
+
+ ``FE_IS_STUPID``
+
+ - There's something wrong at the frontend, and it can't report its
+ capabilities
+
+ - .. row 3
+
+ - .. _`FE-CAN-INVERSION-AUTO`:
+
+ ``FE_CAN_INVERSION_AUTO``
+
+ - The frontend is capable of auto-detecting inversion
+
+ - .. row 4
+
+ - .. _`FE-CAN-FEC-1-2`:
+
+ ``FE_CAN_FEC_1_2``
+
+ - The frontend supports FEC 1/2
+
+ - .. row 5
+
+ - .. _`FE-CAN-FEC-2-3`:
+
+ ``FE_CAN_FEC_2_3``
+
+ - The frontend supports FEC 2/3
+
+ - .. row 6
+
+ - .. _`FE-CAN-FEC-3-4`:
+
+ ``FE_CAN_FEC_3_4``
+
+ - The frontend supports FEC 3/4
+
+ - .. row 7
+
+ - .. _`FE-CAN-FEC-4-5`:
+
+ ``FE_CAN_FEC_4_5``
+
+ - The frontend supports FEC 4/5
+
+ - .. row 8
+
+ - .. _`FE-CAN-FEC-5-6`:
+
+ ``FE_CAN_FEC_5_6``
+
+ - The frontend supports FEC 5/6
+
+ - .. row 9
+
+ - .. _`FE-CAN-FEC-6-7`:
+
+ ``FE_CAN_FEC_6_7``
+
+ - The frontend supports FEC 6/7
+
+ - .. row 10
+
+ - .. _`FE-CAN-FEC-7-8`:
+
+ ``FE_CAN_FEC_7_8``
+
+ - The frontend supports FEC 7/8
+
+ - .. row 11
+
+ - .. _`FE-CAN-FEC-8-9`:
+
+ ``FE_CAN_FEC_8_9``
+
+ - The frontend supports FEC 8/9
+
+ - .. row 12
+
+ - .. _`FE-CAN-FEC-AUTO`:
+
+ ``FE_CAN_FEC_AUTO``
+
+ - The frontend can autodetect FEC.
+
+ - .. row 13
+
+ - .. _`FE-CAN-QPSK`:
+
+ ``FE_CAN_QPSK``
+
+ - The frontend supports QPSK modulation
+
+ - .. row 14
+
+ - .. _`FE-CAN-QAM-16`:
+
+ ``FE_CAN_QAM_16``
+
+ - The frontend supports 16-QAM modulation
+
+ - .. row 15
+
+ - .. _`FE-CAN-QAM-32`:
+
+ ``FE_CAN_QAM_32``
+
+ - The frontend supports 32-QAM modulation
+
+ - .. row 16
+
+ - .. _`FE-CAN-QAM-64`:
+
+ ``FE_CAN_QAM_64``
+
+ - The frontend supports 64-QAM modulation
+
+ - .. row 17
+
+ - .. _`FE-CAN-QAM-128`:
+
+ ``FE_CAN_QAM_128``
+
+ - The frontend supports 128-QAM modulation
+
+ - .. row 18
+
+ - .. _`FE-CAN-QAM-256`:
+
+ ``FE_CAN_QAM_256``
+
+ - The frontend supports 256-QAM modulation
+
+ - .. row 19
+
+ - .. _`FE-CAN-QAM-AUTO`:
+
+ ``FE_CAN_QAM_AUTO``
+
+ - The frontend can autodetect modulation
+
+ - .. row 20
+
+ - .. _`FE-CAN-TRANSMISSION-MODE-AUTO`:
+
+ ``FE_CAN_TRANSMISSION_MODE_AUTO``
+
+ - The frontend can autodetect the transmission mode
+
+ - .. row 21
+
+ - .. _`FE-CAN-BANDWIDTH-AUTO`:
+
+ ``FE_CAN_BANDWIDTH_AUTO``
+
+ - The frontend can autodetect the bandwidth
+
+ - .. row 22
+
+ - .. _`FE-CAN-GUARD-INTERVAL-AUTO`:
+
+ ``FE_CAN_GUARD_INTERVAL_AUTO``
+
+ - The frontend can autodetect the guard interval
+
+ - .. row 23
+
+ - .. _`FE-CAN-HIERARCHY-AUTO`:
+
+ ``FE_CAN_HIERARCHY_AUTO``
+
+ - The frontend can autodetect hierarch
+
+ - .. row 24
+
+ - .. _`FE-CAN-8VSB`:
+
+ ``FE_CAN_8VSB``
+
+ - The frontend supports 8-VSB modulation
+
+ - .. row 25
+
+ - .. _`FE-CAN-16VSB`:
+
+ ``FE_CAN_16VSB``
+
+ - The frontend supports 16-VSB modulation
+
+ - .. row 26
+
+ - .. _`FE-HAS-EXTENDED-CAPS`:
+
+ ``FE_HAS_EXTENDED_CAPS``
+
+ - Currently, unused
+
+ - .. row 27
+
+ - .. _`FE-CAN-MULTISTREAM`:
+
+ ``FE_CAN_MULTISTREAM``
+
+ - The frontend supports multistream filtering
+
+ - .. row 28
+
+ - .. _`FE-CAN-TURBO-FEC`:
+
+ ``FE_CAN_TURBO_FEC``
+
+ - The frontend supports turbo FEC modulation
+
+ - .. row 29
+
+ - .. _`FE-CAN-2G-MODULATION`:
+
+ ``FE_CAN_2G_MODULATION``
+
+ - The frontend supports "2nd generation modulation" (DVB-S2/T2)>
+
+ - .. row 30
+
+ - .. _`FE-NEEDS-BENDING`:
+
+ ``FE_NEEDS_BENDING``
+
+ - Not supported anymore, don't use it
+
+ - .. row 31
+
+ - .. _`FE-CAN-RECOVER`:
+
+ ``FE_CAN_RECOVER``
+
+ - The frontend can recover from a cable unplug automatically
+
+ - .. row 32
+
+ - .. _`FE-CAN-MUTE-TS`:
+
+ ``FE_CAN_MUTE_TS``
+
+ - The frontend can stop spurious TS data output
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_GET_PROPERTY:
+
+**************************************
+ioctl FE_SET_PROPERTY, FE_GET_PROPERTY
+**************************************
+
+*man FE_SET_PROPERTY(2)*
+
+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, int request, struct dtv_properties *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_PROPERTY, FE_GET_PROPERTY
+
+``argp``
+ pointer to struct :ref:`dtv_properties <dtv-properties>`
+
+
+Description
+===========
+
+All DVB frontend devices support the ``FE_SET_PROPERTY`` and
+``FE_GET_PROPERTY`` ioctls. The supported properties and statistics
+depends on the delivery system and on the device:
+
+- ``FE_SET_PROPERTY:``
+
+ - This ioctl is used to set one or more frontend properties.
+
+ - This is the basic command to request the frontend to tune into
+ some frequency and to start decoding the digital TV signal.
+
+ - This call requires read/write access to the device.
+
+ - At return, the values are updated to reflect the actual parameters
+ used.
+
+- ``FE_GET_PROPERTY:``
+
+ - This ioctl is used to get properties and statistics from the
+ frontend.
+
+ - No properties are changed, and statistics aren't reset.
+
+ - This call only requires read-only access to 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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_STATUS:
+
+********************
+ioctl FE_READ_STATUS
+********************
+
+*man FE_READ_STATUS(2)*
+
+Returns status information about the front-end. This call only requires
+read-only access to the device
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, unsigned int *status )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_READ_STATUS
+
+``status``
+ pointer to a bitmask integer filled with the values defined by enum
+ :ref:`fe_status <fe-status>`.
+
+
+Description
+===========
+
+All DVB frontend devices support the ``FE_READ_STATUS`` ioctl. It is
+used to check about the locking status of the frontend after being
+tuned. The ioctl takes a pointer to an integer where the status will be
+written.
+
+NOTE: the size of status is actually sizeof(enum fe_status), with
+varies according with the architecture. This needs to be fixed in the
+future.
+
+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.
+
+
+.. _fe-status-t:
+
+int fe_status
+=============
+
+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
+:ref:`fe_status <fe-status>` values on a bitmask
+
+
+.. _fe-status:
+
+.. flat-table:: enum fe_status
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`FE-HAS-SIGNAL`:
+
+ ``FE_HAS_SIGNAL``
+
+ - The frontend has found something above the noise level
+
+ - .. row 3
+
+ - .. _`FE-HAS-CARRIER`:
+
+ ``FE_HAS_CARRIER``
+
+ - The frontend has found a DVB signal
+
+ - .. row 4
+
+ - .. _`FE-HAS-VITERBI`:
+
+ ``FE_HAS_VITERBI``
+
+ - The frontend FEC inner coding (Viterbi, LDPC or other inner code)
+ is stable
+
+ - .. row 5
+
+ - .. _`FE-HAS-SYNC`:
+
+ ``FE_HAS_SYNC``
+
+ - Synchronization bytes was found
+
+ - .. row 6
+
+ - .. _`FE-HAS-LOCK`:
+
+ ``FE_HAS_LOCK``
+
+ - The DVB were locked and everything is working
+
+ - .. row 7
+
+ - .. _`FE-TIMEDOUT`:
+
+ ``FE_TIMEDOUT``
+
+ - no lock within the last about 2 seconds
+
+ - .. row 8
+
+ - .. _`FE-REINIT`:
+
+ ``FE_REINIT``
+
+ - The frontend was reinitialized, application is recommended to
+ reset DiSEqC, tone and parameters
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_SET_FRONTEND_TUNE_MODE:
+
+*******************************
+ioctl FE_SET_FRONTEND_TUNE_MODE
+*******************************
+
+*man FE_SET_FRONTEND_TUNE_MODE(2)*
+
+Allow setting tuner mode flags to the frontend.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, unsigned int flags )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_FRONTEND_TUNE_MODE
+
+``flags``
+ Valid flags:
+
+ - 0 - normal tune mode
+
+ - FE_TUNE_MODE_ONESHOT - When set, this flag will disable any
+ zigzagging or other "normal" tuning behaviour. Additionally,
+ there will be no automatic monitoring of the lock status, and
+ hence no frontend events will be generated. If a frontend device
+ 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
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_SET_TONE:
+
+*****************
+ioctl FE_SET_TONE
+*****************
+
+*man FE_SET_TONE(2)*
+
+Sets/resets the generation of the continuous 22kHz tone.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, enum fe_sec_tone_mode *tone )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_TONE
+
+``tone``
+ pointer to enum :ref:`fe_sec_tone_mode <fe-sec-tone-mode>`
+
+
+Description
+===========
+
+This ioctl is used to set the generation of the continuous 22kHz tone.
+This call requires read/write permissions.
+
+Usually, satellite antenna subsystems require that the digital TV device
+to send a 22kHz tone in order to select between high/low band on some
+dual-band LNBf. It is also used to send signals to DiSEqC equipment, but
+this is done using the DiSEqC ioctls.
+
+NOTE: if more than one device is connected to the same antenna, setting
+a tone may interfere on other devices, as they may lose the capability
+of selecting the band. So, it is recommended that applications would
+change to SEC_TONE_OFF when the device is not used.
+
+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.
+
+
+.. _fe-sec-tone-mode-t:
+
+enum fe_sec_tone_mode
+=====================
+
+
+.. _fe-sec-tone-mode:
+
+.. flat-table:: enum fe_sec_tone_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`SEC-TONE-ON`:
+
+ ``SEC_TONE_ON``
+
+ - Sends a 22kHz tone burst to the antenna
+
+ - .. row 3
+
+ - .. _`SEC-TONE-OFF`:
+
+ ``SEC_TONE_OFF``
+
+ - Don't send a 22kHz tone to the antenna (except if the
+ FE_DISEQC_* ioctls are called)
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_SET_VOLTAGE:
+
+********************
+ioctl FE_SET_VOLTAGE
+********************
+
+*man FE_SET_VOLTAGE(2)*
+
+Allow setting the DC level sent to the antenna subsystem.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, enum fe_sec_voltage *voltage )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_VOLTAGE
+
+``voltage``
+ pointer to enum :ref:`fe_sec_voltage <fe-sec-voltage>`
+
+ Valid values are described at enum
+ :ref:`fe_sec_voltage <fe-sec-voltage>`.
+
+
+Description
+===========
+
+This ioctl allows to set the DC voltage level sent through the antenna
+cable to 13V, 18V or off.
+
+Usually, a satellite antenna subsystems require that the digital TV
+device to send a DC voltage to feed power to the LNBf. Depending on the
+LNBf type, the polarization or the intermediate frequency (IF) of the
+LNBf can controlled by the voltage level. Other devices (for example,
+the ones that implement DISEqC and multipoint LNBf's don't need to
+control the voltage level, provided that either 13V or 18V is sent to
+power up the LNBf.
+
+NOTE: if more than one device is connected to the same antenna, setting
+a voltage level may interfere on other devices, as they may lose the
+capability of setting polarization or IF. So, on those cases, setting
+the voltage to SEC_VOLTAGE_OFF while the device is not is used is
+recommended.
+
+RETURN VALUE
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _fe-type-t:
+
+*************
+Frontend type
+*************
+
+For historical reasons, frontend types are named by the type of
+modulation used in transmission. The fontend types are given by
+fe_type_t type, defined as:
+
+
+.. _fe-type:
+
+.. flat-table:: Frontend types
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - fe_type
+
+ - Description
+
+ - :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` equivalent
+ type
+
+ - .. row 2
+
+ - .. _`FE-QPSK`:
+
+ ``FE_QPSK``
+
+ - For DVB-S standard
+
+ - ``SYS_DVBS``
+
+ - .. row 3
+
+ - .. _`FE-QAM`:
+
+ ``FE_QAM``
+
+ - For DVB-C annex A standard
+
+ - ``SYS_DVBC_ANNEX_A``
+
+ - .. row 4
+
+ - .. _`FE-OFDM`:
+
+ ``FE_OFDM``
+
+ - For DVB-T standard
+
+ - ``SYS_DVBT``
+
+ - .. row 5
+
+ - .. _`FE-ATSC`:
+
+ ``FE_ATSC``
+
+ - For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used
+ in US.
+
+ - ``SYS_ATSC`` (terrestrial) or ``SYS_DVBC_ANNEX_B`` (cable)
+
+
+Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described
+at the above, as they're supported via the new
+:ref:`FE_GET_PROPERTY/FE_GET_SET_PROPERTY <FE_GET_PROPERTY>`
+ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+parameter.
+
+In the old days, struct :ref:`dvb_frontend_info <dvb-frontend-info>`
+used to contain ``fe_type_t`` field to indicate the delivery systems,
+filled with either FE_QPSK, FE_QAM, FE_OFDM or FE_ATSC. While this
+is still filled to keep backward compatibility, the usage of this field
+is deprecated, as it can report just one delivery system, but some
+devices support multiple delivery systems. Please use
+:ref:`DTV_ENUM_DELSYS <DTV-ENUM-DELSYS>` instead.
+
+On devices that support multiple delivery systems, struct
+:ref:`dvb_frontend_info <dvb-frontend-info>`::``fe_type_t`` is
+filled with the currently standard, as selected by the last call to
+:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` using the
+:ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` property.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _fe_property_parameters:
+
+******************************
+Digital TV property parameters
+******************************
+
+
+.. _DTV-UNDEFINED:
+
+DTV_UNDEFINED
+=============
+
+Used internally. A GET/SET operation for it won't change or return
+anything.
+
+
+.. _DTV-TUNE:
+
+DTV_TUNE
+========
+
+Interpret the cache of data, build either a traditional frontend
+tunerequest so we can pass validation in the ``FE_SET_FRONTEND`` ioctl.
+
+
+.. _DTV-CLEAR:
+
+DTV_CLEAR
+=========
+
+Reset a cache of data specific to the frontend here. This does not
+effect hardware.
+
+
+.. _DTV-FREQUENCY:
+
+DTV_FREQUENCY
+=============
+
+Central frequency of the channel.
+
+Notes:
+
+1)For satellite delivery systems, it is measured in kHz. For the other
+ones, it is measured in Hz.
+
+2)For ISDB-T, the channels are usually transmitted with an offset of
+143kHz. E.g. a valid frequency could be 474143 kHz. The stepping is
+bound to the bandwidth of the channel which is 6MHz.
+
+3)As in ISDB-Tsb the channel consists of only one or three segments the
+frequency step is 429kHz, 3*429 respectively. As for ISDB-T the central
+frequency of the channel is expected.
+
+
+.. _DTV-MODULATION:
+
+DTV_MODULATION
+==============
+
+Specifies the frontend modulation type for delivery systems that
+supports more than one modulation type. The modulation can be one of the
+types defined by enum :ref:`fe_modulation <fe-modulation>`.
+
+
+.. _fe-modulation-t:
+
+Modulation property
+-------------------
+
+Most of the digital TV standards currently offers more than one possible
+modulation (sometimes called as "constellation" on some standards). This
+enum contains the values used by the Kernel. Please note that not all
+modulations are supported by a given standard.
+
+
+.. _fe-modulation:
+
+.. flat-table:: enum fe_modulation
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`QPSK`:
+
+ ``QPSK``
+
+ - QPSK modulation
+
+ - .. row 3
+
+ - .. _`QAM-16`:
+
+ ``QAM_16``
+
+ - 16-QAM modulation
+
+ - .. row 4
+
+ - .. _`QAM-32`:
+
+ ``QAM_32``
+
+ - 32-QAM modulation
+
+ - .. row 5
+
+ - .. _`QAM-64`:
+
+ ``QAM_64``
+
+ - 64-QAM modulation
+
+ - .. row 6
+
+ - .. _`QAM-128`:
+
+ ``QAM_128``
+
+ - 128-QAM modulation
+
+ - .. row 7
+
+ - .. _`QAM-256`:
+
+ ``QAM_256``
+
+ - 256-QAM modulation
+
+ - .. row 8
+
+ - .. _`QAM-AUTO`:
+
+ ``QAM_AUTO``
+
+ - Autodetect QAM modulation
+
+ - .. row 9
+
+ - .. _`VSB-8`:
+
+ ``VSB_8``
+
+ - 8-VSB modulation
+
+ - .. row 10
+
+ - .. _`VSB-16`:
+
+ ``VSB_16``
+
+ - 16-VSB modulation
+
+ - .. row 11
+
+ - .. _`PSK-8`:
+
+ ``PSK_8``
+
+ - 8-PSK modulation
+
+ - .. row 12
+
+ - .. _`APSK-16`:
+
+ ``APSK_16``
+
+ - 16-APSK modulation
+
+ - .. row 13
+
+ - .. _`APSK-32`:
+
+ ``APSK_32``
+
+ - 32-APSK modulation
+
+ - .. row 14
+
+ - .. _`DQPSK`:
+
+ ``DQPSK``
+
+ - DQPSK modulation
+
+ - .. row 15
+
+ - .. _`QAM-4-NR`:
+
+ ``QAM_4_NR``
+
+ - 4-QAM-NR modulation
+
+
+
+.. _DTV-BANDWIDTH-HZ:
+
+DTV_BANDWIDTH_HZ
+================
+
+Bandwidth for the channel, in HZ.
+
+Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``,
+``8000000``, ``10000000``.
+
+Notes:
+
+1) For ISDB-T it should be always 6000000Hz (6MHz)
+
+2) For ISDB-Tsb it can vary depending on the number of connected
+segments
+
+3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth for
+DVB-C depends on the symbol rate
+
+4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
+other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
+DTV_ISDBT_SB_SEGMENT_COUNT).
+
+5) DVB-T supports 6, 7 and 8MHz.
+
+6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.
+
+
+.. _DTV-INVERSION:
+
+DTV_INVERSION
+=============
+
+Specifies if the frontend should do spectral inversion or not.
+
+
+.. _fe-spectral-inversion-t:
+
+enum fe_modulation: Frontend spectral inversion
+-----------------------------------------------
+
+This parameter indicates if spectral inversion should be presumed or
+not. In the automatic setting (``INVERSION_AUTO``) the hardware will try
+to figure out the correct setting by itself. If the hardware doesn't
+support, the DVB core will try to lock at the carrier first with
+inversion off. If it fails, it will try to enable inversion.
+
+
+.. _fe-spectral-inversion:
+
+.. flat-table:: enum fe_modulation
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`INVERSION-OFF`:
+
+ ``INVERSION_OFF``
+
+ - Don't do spectral band inversion.
+
+ - .. row 3
+
+ - .. _`INVERSION-ON`:
+
+ ``INVERSION_ON``
+
+ - Do spectral band inversion.
+
+ - .. row 4
+
+ - .. _`INVERSION-AUTO`:
+
+ ``INVERSION_AUTO``
+
+ - Autodetect spectral band inversion.
+
+
+
+.. _DTV-DISEQC-MASTER:
+
+DTV_DISEQC_MASTER
+=================
+
+Currently not implemented.
+
+
+.. _DTV-SYMBOL-RATE:
+
+DTV_SYMBOL_RATE
+===============
+
+Digital TV symbol rate, in bauds (symbols/second). Used on cable
+standards.
+
+
+.. _DTV-INNER-FEC:
+
+DTV_INNER_FEC
+=============
+
+Used cable/satellite transmissions. The acceptable values are:
+
+
+.. _fe-code-rate-t:
+
+enum fe_code_rate: type of the Forward Error Correction.
+--------------------------------------------------------
+
+
+.. _fe-code-rate:
+
+.. flat-table:: enum fe_code_rate
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`FEC-NONE`:
+
+ ``FEC_NONE``
+
+ - No Forward Error Correction Code
+
+ - .. row 3
+
+ - .. _`FEC-AUTO`:
+
+ ``FEC_AUTO``
+
+ - Autodetect Error Correction Code
+
+ - .. row 4
+
+ - .. _`FEC-1-2`:
+
+ ``FEC_1_2``
+
+ - Forward Error Correction Code 1/2
+
+ - .. row 5
+
+ - .. _`FEC-2-3`:
+
+ ``FEC_2_3``
+
+ - Forward Error Correction Code 2/3
+
+ - .. row 6
+
+ - .. _`FEC-3-4`:
+
+ ``FEC_3_4``
+
+ - Forward Error Correction Code 3/4
+
+ - .. row 7
+
+ - .. _`FEC-4-5`:
+
+ ``FEC_4_5``
+
+ - Forward Error Correction Code 4/5
+
+ - .. row 8
+
+ - .. _`FEC-5-6`:
+
+ ``FEC_5_6``
+
+ - Forward Error Correction Code 5/6
+
+ - .. row 9
+
+ - .. _`FEC-6-7`:
+
+ ``FEC_6_7``
+
+ - Forward Error Correction Code 6/7
+
+ - .. row 10
+
+ - .. _`FEC-7-8`:
+
+ ``FEC_7_8``
+
+ - Forward Error Correction Code 7/8
+
+ - .. row 11
+
+ - .. _`FEC-8-9`:
+
+ ``FEC_8_9``
+
+ - Forward Error Correction Code 8/9
+
+ - .. row 12
+
+ - .. _`FEC-9-10`:
+
+ ``FEC_9_10``
+
+ - Forward Error Correction Code 9/10
+
+ - .. row 13
+
+ - .. _`FEC-2-5`:
+
+ ``FEC_2_5``
+
+ - Forward Error Correction Code 2/5
+
+ - .. row 14
+
+ - .. _`FEC-3-5`:
+
+ ``FEC_3_5``
+
+ - Forward Error Correction Code 3/5
+
+
+
+.. _DTV-VOLTAGE:
+
+DTV_VOLTAGE
+===========
+
+The voltage is usually used with non-DiSEqC capable LNBs to switch the
+polarzation (horizontal/vertical). When using DiSEqC epuipment this
+voltage has to be switched consistently to the DiSEqC commands as
+described in the DiSEqC spec.
+
+
+.. _fe-sec-voltage:
+
+.. flat-table:: enum fe_sec_voltage
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`SEC-VOLTAGE-13`:
+
+ ``SEC_VOLTAGE_13``
+
+ - Set DC voltage level to 13V
+
+ - .. row 3
+
+ - .. _`SEC-VOLTAGE-18`:
+
+ ``SEC_VOLTAGE_18``
+
+ - Set DC voltage level to 18V
+
+ - .. row 4
+
+ - .. _`SEC-VOLTAGE-OFF`:
+
+ ``SEC_VOLTAGE_OFF``
+
+ - Don't send any voltage to the antenna
+
+
+
+.. _DTV-TONE:
+
+DTV_TONE
+========
+
+Currently not used.
+
+
+.. _DTV-PILOT:
+
+DTV_PILOT
+=========
+
+Sets DVB-S2 pilot
+
+
+.. _fe-pilot-t:
+
+fe_pilot type
+-------------
+
+
+.. _fe-pilot:
+
+.. flat-table:: enum fe_pilot
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`PILOT-ON`:
+
+ ``PILOT_ON``
+
+ - Pilot tones enabled
+
+ - .. row 3
+
+ - .. _`PILOT-OFF`:
+
+ ``PILOT_OFF``
+
+ - Pilot tones disabled
+
+ - .. row 4
+
+ - .. _`PILOT-AUTO`:
+
+ ``PILOT_AUTO``
+
+ - Autodetect pilot tones
+
+
+
+.. _DTV-ROLLOFF:
+
+DTV_ROLLOFF
+===========
+
+Sets DVB-S2 rolloff
+
+
+.. _fe-rolloff-t:
+
+fe_rolloff type
+---------------
+
+
+.. _fe-rolloff:
+
+.. flat-table:: enum fe_rolloff
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`ROLLOFF-35`:
+
+ ``ROLLOFF_35``
+
+ - Roloff factor: α=35%
+
+ - .. row 3
+
+ - .. _`ROLLOFF-20`:
+
+ ``ROLLOFF_20``
+
+ - Roloff factor: α=20%
+
+ - .. row 4
+
+ - .. _`ROLLOFF-25`:
+
+ ``ROLLOFF_25``
+
+ - Roloff factor: α=25%
+
+ - .. row 5
+
+ - .. _`ROLLOFF-AUTO`:
+
+ ``ROLLOFF_AUTO``
+
+ - Auto-detect the roloff factor.
+
+
+
+.. _DTV-DISEQC-SLAVE-REPLY:
+
+DTV_DISEQC_SLAVE_REPLY
+======================
+
+Currently not implemented.
+
+
+.. _DTV-FE-CAPABILITY-COUNT:
+
+DTV_FE_CAPABILITY_COUNT
+=======================
+
+Currently not implemented.
+
+
+.. _DTV-FE-CAPABILITY:
+
+DTV_FE_CAPABILITY
+=================
+
+Currently not implemented.
+
+
+.. _DTV-DELIVERY-SYSTEM:
+
+DTV_DELIVERY_SYSTEM
+===================
+
+Specifies the type of Delivery system
+
+
+.. _fe-delivery-system-t:
+
+fe_delivery_system type
+-----------------------
+
+Possible values:
+
+
+.. _fe-delivery-system:
+
+.. flat-table:: enum fe_delivery_system
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`SYS-UNDEFINED`:
+
+ ``SYS_UNDEFINED``
+
+ - Undefined standard. Generally, indicates an error
+
+ - .. row 3
+
+ - .. _`SYS-DVBC-ANNEX-A`:
+
+ ``SYS_DVBC_ANNEX_A``
+
+ - Cable TV: DVB-C following ITU-T J.83 Annex A spec
+
+ - .. row 4
+
+ - .. _`SYS-DVBC-ANNEX-B`:
+
+ ``SYS_DVBC_ANNEX_B``
+
+ - Cable TV: DVB-C following ITU-T J.83 Annex B spec (ClearQAM)
+
+ - .. row 5
+
+ - .. _`SYS-DVBC-ANNEX-C`:
+
+ ``SYS_DVBC_ANNEX_C``
+
+ - Cable TV: DVB-C following ITU-T J.83 Annex C spec
+
+ - .. row 6
+
+ - .. _`SYS-ISDBC`:
+
+ ``SYS_ISDBC``
+
+ - Cable TV: ISDB-C (no drivers yet)
+
+ - .. row 7
+
+ - .. _`SYS-DVBT`:
+
+ ``SYS_DVBT``
+
+ - Terrestral TV: DVB-T
+
+ - .. row 8
+
+ - .. _`SYS-DVBT2`:
+
+ ``SYS_DVBT2``
+
+ - Terrestral TV: DVB-T2
+
+ - .. row 9
+
+ - .. _`SYS-ISDBT`:
+
+ ``SYS_ISDBT``
+
+ - Terrestral TV: ISDB-T
+
+ - .. row 10
+
+ - .. _`SYS-ATSC`:
+
+ ``SYS_ATSC``
+
+ - Terrestral TV: ATSC
+
+ - .. row 11
+
+ - .. _`SYS-ATSCMH`:
+
+ ``SYS_ATSCMH``
+
+ - Terrestral TV (mobile): ATSC-M/H
+
+ - .. row 12
+
+ - .. _`SYS-DTMB`:
+
+ ``SYS_DTMB``
+
+ - Terrestrial TV: DTMB
+
+ - .. row 13
+
+ - .. _`SYS-DVBS`:
+
+ ``SYS_DVBS``
+
+ - Satellite TV: DVB-S
+
+ - .. row 14
+
+ - .. _`SYS-DVBS2`:
+
+ ``SYS_DVBS2``
+
+ - Satellite TV: DVB-S2
+
+ - .. row 15
+
+ - .. _`SYS-TURBO`:
+
+ ``SYS_TURBO``
+
+ - Satellite TV: DVB-S Turbo
+
+ - .. row 16
+
+ - .. _`SYS-ISDBS`:
+
+ ``SYS_ISDBS``
+
+ - Satellite TV: ISDB-S
+
+ - .. row 17
+
+ - .. _`SYS-DAB`:
+
+ ``SYS_DAB``
+
+ - Digital audio: DAB (not fully supported)
+
+ - .. row 18
+
+ - .. _`SYS-DSS`:
+
+ ``SYS_DSS``
+
+ - Satellite TV:"DSS (not fully supported)
+
+ - .. row 19
+
+ - .. _`SYS-CMMB`:
+
+ ``SYS_CMMB``
+
+ - Terrestral TV (mobile):CMMB (not fully supported)
+
+ - .. row 20
+
+ - .. _`SYS-DVBH`:
+
+ ``SYS_DVBH``
+
+ - Terrestral TV (mobile): DVB-H (standard deprecated)
+
+
+
+.. _DTV-ISDBT-PARTIAL-RECEPTION:
+
+DTV_ISDBT_PARTIAL_RECEPTION
+===========================
+
+If ``DTV_ISDBT_SOUND_BROADCASTING`` is '0' this bit-field represents
+whether the channel is in partial reception mode or not.
+
+If '1' ``DTV_ISDBT_LAYERA_*`` values are assigned to the center segment
+and ``DTV_ISDBT_LAYERA_SEGMENT_COUNT`` has to be '1'.
+
+If in addition ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'
+``DTV_ISDBT_PARTIAL_RECEPTION`` represents whether this ISDB-Tsb channel
+is consisting of one segment and layer or three segments and two layers.
+
+Possible values: 0, 1, -1 (AUTO)
+
+
+.. _DTV-ISDBT-SOUND-BROADCASTING:
+
+DTV_ISDBT_SOUND_BROADCASTING
+============================
+
+This field represents whether the other DTV_ISDBT_*-parameters are
+referring to an ISDB-T and an ISDB-Tsb channel. (See also
+``DTV_ISDBT_PARTIAL_RECEPTION``).
+
+Possible values: 0, 1, -1 (AUTO)
+
+
+.. _DTV-ISDBT-SB-SUBCHANNEL-ID:
+
+DTV_ISDBT_SB_SUBCHANNEL_ID
+==========================
+
+This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
+
+(Note of the author: This might not be the correct description of the
+``SUBCHANNEL-ID`` in all details, but it is my understanding of the
+technical background needed to program a device)
+
+An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
+set of connected ISDB-Tsb channels. In this set of channels every
+channel can be received independently. The number of connected ISDB-Tsb
+segment can vary, e.g. depending on the frequency spectrum bandwidth
+available.
+
+Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
+broadcaster has several possibilities to put those channels in the air:
+Assuming a normal 13-segment ISDB-T spectrum he can align the 8 segments
+from position 1-8 to 5-13 or anything in between.
+
+The underlying layer of segments are subchannels: each segment is
+consisting of several subchannels with a predefined IDs. A sub-channel
+is used to help the demodulator to synchronize on the channel.
+
+An ISDB-T channel is always centered over all sub-channels. As for the
+example above, in ISDB-Tsb it is no longer as simple as that.
+
+``The DTV_ISDBT_SB_SUBCHANNEL_ID`` parameter is used to give the
+sub-channel ID of the segment to be demodulated.
+
+Possible values: 0 .. 41, -1 (AUTO)
+
+
+.. _DTV-ISDBT-SB-SEGMENT-IDX:
+
+DTV_ISDBT_SB_SEGMENT_IDX
+========================
+
+This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
+
+``DTV_ISDBT_SB_SEGMENT_IDX`` gives the index of the segment to be
+demodulated for an ISDB-Tsb channel where several of them are
+transmitted in the connected manner.
+
+Possible values: 0 .. ``DTV_ISDBT_SB_SEGMENT_COUNT`` - 1
+
+Note: This value cannot be determined by an automatic channel search.
+
+
+.. _DTV-ISDBT-SB-SEGMENT-COUNT:
+
+DTV_ISDBT_SB_SEGMENT_COUNT
+==========================
+
+This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
+
+``DTV_ISDBT_SB_SEGMENT_COUNT`` gives the total count of connected
+ISDB-Tsb channels.
+
+Possible values: 1 .. 13
+
+Note: This value cannot be determined by an automatic channel search.
+
+
+.. _isdb-hierq-layers:
+
+DTV-ISDBT-LAYER* parameters
+===========================
+
+ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
+ISDB-T hierarchical layers can be decoded simultaneously. For that
+reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders.
+
+ISDB-T has 3 hierarchical layers which each can use a part of the
+available segments. The total number of segments over all layers has to
+13 in ISDB-T.
+
+There are 3 parameter sets, for Layers A, B and C.
+
+
+.. _DTV-ISDBT-LAYER-ENABLED:
+
+DTV_ISDBT_LAYER_ENABLED
+-----------------------
+
+Hierarchical reception in ISDB-T is achieved by enabling or disabling
+layers in the decoding process. Setting all bits of
+``DTV_ISDBT_LAYER_ENABLED`` to '1' forces all layers (if applicable) to
+be demodulated. This is the default.
+
+If the channel is in the partial reception mode
+(``DTV_ISDBT_PARTIAL_RECEPTION`` = 1) the central segment can be decoded
+independently of the other 12 segments. In that mode layer A has to have
+a ``SEGMENT_COUNT`` of 1.
+
+In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb according
+to ``DTV_ISDBT_PARTIAL_RECEPTION``. ``SEGMENT_COUNT`` must be filled
+accordingly.
+
+Possible values: 0x1, 0x2, 0x4 (|-able)
+
+``DTV_ISDBT_LAYER_ENABLED[0:0]`` - layer A
+
+``DTV_ISDBT_LAYER_ENABLED[1:1]`` - layer B
+
+``DTV_ISDBT_LAYER_ENABLED[2:2]`` - layer C
+
+``DTV_ISDBT_LAYER_ENABLED[31:3]`` unused
+
+
+.. _DTV-ISDBT-LAYER-FEC:
+
+DTV_ISDBT_LAYER*_FEC
+--------------------
+
+Possible values: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``,
+``FEC_5_6``, ``FEC_7_8``
+
+
+.. _DTV-ISDBT-LAYER-MODULATION:
+
+DTV_ISDBT_LAYER*_MODULATION
+---------------------------
+
+Possible values: ``QAM_AUTO``, QP\ ``SK, QAM_16``, ``QAM_64``, ``DQPSK``
+
+Note: If layer C is ``DQPSK`` layer B has to be ``DQPSK``. If layer B is
+``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ =0 layer has to be
+``DQPSK``.
+
+
+.. _DTV-ISDBT-LAYER-SEGMENT-COUNT:
+
+DTV_ISDBT_LAYER*_SEGMENT_COUNT
+------------------------------
+
+Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)
+
+Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and
+``DTV_ISDBT_PARTIAL_RECEPTION`` and ``LAYER`` *_SEGMENT_COUNT
+
+
+.. _isdbt-layer_seg-cnt-table:
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - PR
+
+ - SB
+
+ - Layer A width
+
+ - Layer B width
+
+ - Layer C width
+
+ - total width
+
+ - .. row 2
+
+ - 0
+
+ - 0
+
+ - 1 .. 13
+
+ - 1 .. 13
+
+ - 1 .. 13
+
+ - 13
+
+ - .. row 3
+
+ - 1
+
+ - 0
+
+ - 1
+
+ - 1 .. 13
+
+ - 1 .. 13
+
+ - 13
+
+ - .. row 4
+
+ - 0
+
+ - 1
+
+ - 1
+
+ - 0
+
+ - 0
+
+ - 1
+
+ - .. row 5
+
+ - 1
+
+ - 1
+
+ - 1
+
+ - 2
+
+ - 0
+
+ - 13
+
+
+
+.. _DTV-ISDBT-LAYER-TIME-INTERLEAVING:
+
+DTV_ISDBT_LAYER*_TIME_INTERLEAVING
+----------------------------------
+
+Valid values: 0, 1, 2, 4, -1 (AUTO)
+
+when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.
+
+Note: The real time interleaving length depends on the mode (fft-size).
+The values here are referring to what can be found in the
+TMCC-structure, as shown in the table below.
+
+
+.. _isdbt-layer-interleaving-table:
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - DTV_ISDBT_LAYER*_TIME_INTERLEAVING
+
+ - Mode 1 (2K FFT)
+
+ - Mode 2 (4K FFT)
+
+ - Mode 3 (8K FFT)
+
+ - .. row 2
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - .. row 3
+
+ - 1
+
+ - 4
+
+ - 2
+
+ - 1
+
+ - .. row 4
+
+ - 2
+
+ - 8
+
+ - 4
+
+ - 2
+
+ - .. row 5
+
+ - 4
+
+ - 16
+
+ - 8
+
+ - 4
+
+
+
+.. _DTV-ATSCMH-FIC-VER:
+
+DTV_ATSCMH_FIC_VER
+------------------
+
+Version number of the FIC (Fast Information Channel) signaling data.
+
+FIC is used for relaying information to allow rapid service acquisition
+by the receiver.
+
+Possible values: 0, 1, 2, 3, ..., 30, 31
+
+
+.. _DTV-ATSCMH-PARADE-ID:
+
+DTV_ATSCMH_PARADE_ID
+--------------------
+
+Parade identification number
+
+A parade is a collection of up to eight MH groups, conveying one or two
+ensembles.
+
+Possible values: 0, 1, 2, 3, ..., 126, 127
+
+
+.. _DTV-ATSCMH-NOG:
+
+DTV_ATSCMH_NOG
+--------------
+
+Number of MH groups per MH subframe for a designated parade.
+
+Possible values: 1, 2, 3, 4, 5, 6, 7, 8
+
+
+.. _DTV-ATSCMH-TNOG:
+
+DTV_ATSCMH_TNOG
+---------------
+
+Total number of MH groups including all MH groups belonging to all MH
+parades in one MH subframe.
+
+Possible values: 0, 1, 2, 3, ..., 30, 31
+
+
+.. _DTV-ATSCMH-SGN:
+
+DTV_ATSCMH_SGN
+--------------
+
+Start group number.
+
+Possible values: 0, 1, 2, 3, ..., 14, 15
+
+
+.. _DTV-ATSCMH-PRC:
+
+DTV_ATSCMH_PRC
+--------------
+
+Parade repetition cycle.
+
+Possible values: 1, 2, 3, 4, 5, 6, 7, 8
+
+
+.. _DTV-ATSCMH-RS-FRAME-MODE:
+
+DTV_ATSCMH_RS_FRAME_MODE
+------------------------
+
+Reed Solomon (RS) frame mode.
+
+Possible values are:
+
+
+.. _atscmh-rs-frame-mode:
+
+.. flat-table:: enum atscmh_rs_frame_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`ATSCMH-RSFRAME-PRI-ONLY`:
+
+ ``ATSCMH_RSFRAME_PRI_ONLY``
+
+ - Single Frame: There is only a primary RS Frame for all Group
+ Regions.
+
+ - .. row 3
+
+ - .. _`ATSCMH-RSFRAME-PRI-SEC`:
+
+ ``ATSCMH_RSFRAME_PRI_SEC``
+
+ - Dual Frame: There are two separate RS Frames: Primary RS Frame for
+ Group Region A and B and Secondary RS Frame for Group Region C and
+ D.
+
+
+
+.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE:
+
+DTV_ATSCMH_RS_FRAME_ENSEMBLE
+----------------------------
+
+Reed Solomon(RS) frame ensemble.
+
+Possible values are:
+
+
+.. _atscmh-rs-frame-ensemble:
+
+.. flat-table:: enum atscmh_rs_frame_ensemble
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`ATSCMH-RSFRAME-ENS-PRI`:
+
+ ``ATSCMH_RSFRAME_ENS_PRI``
+
+ - Primary Ensemble.
+
+ - .. row 3
+
+ - .. _`ATSCMH-RSFRAME-ENS-SEC`:
+
+ ``AATSCMH_RSFRAME_PRI_SEC``
+
+ - Secondary Ensemble.
+
+ - .. row 4
+
+ - .. _`ATSCMH-RSFRAME-RES`:
+
+ ``AATSCMH_RSFRAME_RES``
+
+ - Reserved. Shouldn't be used.
+
+
+
+.. _DTV-ATSCMH-RS-CODE-MODE-PRI:
+
+DTV_ATSCMH_RS_CODE_MODE_PRI
+---------------------------
+
+Reed Solomon (RS) code mode (primary).
+
+Possible values are:
+
+
+.. _atscmh-rs-code-mode:
+
+.. flat-table:: enum atscmh_rs_code_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`ATSCMH-RSCODE-211-187`:
+
+ ``ATSCMH_RSCODE_211_187``
+
+ - Reed Solomon code (211,187).
+
+ - .. row 3
+
+ - .. _`ATSCMH-RSCODE-223-187`:
+
+ ``ATSCMH_RSCODE_223_187``
+
+ - Reed Solomon code (223,187).
+
+ - .. row 4
+
+ - .. _`ATSCMH-RSCODE-235-187`:
+
+ ``ATSCMH_RSCODE_235_187``
+
+ - Reed Solomon code (235,187).
+
+ - .. row 5
+
+ - .. _`ATSCMH-RSCODE-RES`:
+
+ ``ATSCMH_RSCODE_RES``
+
+ - Reserved. Shouldn't be used.
+
+
+
+.. _DTV-ATSCMH-RS-CODE-MODE-SEC:
+
+DTV_ATSCMH_RS_CODE_MODE_SEC
+---------------------------
+
+Reed Solomon (RS) code mode (secondary).
+
+Possible values are the same as documented on enum
+:ref:`atscmh_rs_code_mode <atscmh-rs-code-mode>`:
+
+
+.. _DTV-ATSCMH-SCCC-BLOCK-MODE:
+
+DTV_ATSCMH_SCCC_BLOCK_MODE
+--------------------------
+
+Series Concatenated Convolutional Code Block Mode.
+
+Possible values are:
+
+
+.. _atscmh-sccc-block-mode:
+
+.. flat-table:: enum atscmh_scc_block_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`ATSCMH-SCCC-BLK-SEP`:
+
+ ``ATSCMH_SCCC_BLK_SEP``
+
+ - Separate SCCC: the SCCC outer code mode shall be set independently
+ for each Group Region (A, B, C, D)
+
+ - .. row 3
+
+ - .. _`ATSCMH-SCCC-BLK-COMB`:
+
+ ``ATSCMH_SCCC_BLK_COMB``
+
+ - Combined SCCC: all four Regions shall have the same SCCC outer
+ code mode.
+
+ - .. row 4
+
+ - .. _`ATSCMH-SCCC-BLK-RES`:
+
+ ``ATSCMH_SCCC_BLK_RES``
+
+ - Reserved. Shouldn't be used.
+
+
+
+.. _DTV-ATSCMH-SCCC-CODE-MODE-A:
+
+DTV_ATSCMH_SCCC_CODE_MODE_A
+---------------------------
+
+Series Concatenated Convolutional Code Rate.
+
+Possible values are:
+
+
+.. _atscmh-sccc-code-mode:
+
+.. flat-table:: enum atscmh_sccc_code_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`ATSCMH-SCCC-CODE-HLF`:
+
+ ``ATSCMH_SCCC_CODE_HLF``
+
+ - The outer code rate of a SCCC Block is 1/2 rate.
+
+ - .. row 3
+
+ - .. _`ATSCMH-SCCC-CODE-QTR`:
+
+ ``ATSCMH_SCCC_CODE_QTR``
+
+ - The outer code rate of a SCCC Block is 1/4 rate.
+
+ - .. row 4
+
+ - .. _`ATSCMH-SCCC-CODE-RES`:
+
+ ``ATSCMH_SCCC_CODE_RES``
+
+ - to be documented.
+
+
+
+.. _DTV-ATSCMH-SCCC-CODE-MODE-B:
+
+DTV_ATSCMH_SCCC_CODE_MODE_B
+---------------------------
+
+Series Concatenated Convolutional Code Rate.
+
+Possible values are the same as documented on enum
+:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
+
+
+.. _DTV-ATSCMH-SCCC-CODE-MODE-C:
+
+DTV_ATSCMH_SCCC_CODE_MODE_C
+---------------------------
+
+Series Concatenated Convolutional Code Rate.
+
+Possible values are the same as documented on enum
+:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
+
+
+.. _DTV-ATSCMH-SCCC-CODE-MODE-D:
+
+DTV_ATSCMH_SCCC_CODE_MODE_D
+---------------------------
+
+Series Concatenated Convolutional Code Rate.
+
+Possible values are the same as documented on enum
+:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
+
+
+.. _DTV-API-VERSION:
+
+DTV_API_VERSION
+===============
+
+Returns the major/minor version of the DVB API
+
+
+.. _DTV-CODE-RATE-HP:
+
+DTV_CODE_RATE_HP
+================
+
+Used on terrestrial transmissions. The acceptable values are the ones
+described at :ref:`fe_transmit_mode_t <fe-transmit-mode-t>`.
+
+
+.. _DTV-CODE-RATE-LP:
+
+DTV_CODE_RATE_LP
+================
+
+Used on terrestrial transmissions. The acceptable values are the ones
+described at :ref:`fe_transmit_mode_t <fe-transmit-mode-t>`.
+
+
+.. _DTV-GUARD-INTERVAL:
+
+DTV_GUARD_INTERVAL
+==================
+
+Possible values are:
+
+
+.. _fe-guard-interval-t:
+
+Modulation guard interval
+-------------------------
+
+
+.. _fe-guard-interval:
+
+.. flat-table:: enum fe_guard_interval
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`GUARD-INTERVAL-AUTO`:
+
+ ``GUARD_INTERVAL_AUTO``
+
+ - Autodetect the guard interval
+
+ - .. row 3
+
+ - .. _`GUARD-INTERVAL-1-128`:
+
+ ``GUARD_INTERVAL_1_128``
+
+ - Guard interval 1/128
+
+ - .. row 4
+
+ - .. _`GUARD-INTERVAL-1-32`:
+
+ ``GUARD_INTERVAL_1_32``
+
+ - Guard interval 1/32
+
+ - .. row 5
+
+ - .. _`GUARD-INTERVAL-1-16`:
+
+ ``GUARD_INTERVAL_1_16``
+
+ - Guard interval 1/16
+
+ - .. row 6
+
+ - .. _`GUARD-INTERVAL-1-8`:
+
+ ``GUARD_INTERVAL_1_8``
+
+ - Guard interval 1/8
+
+ - .. row 7
+
+ - .. _`GUARD-INTERVAL-1-4`:
+
+ ``GUARD_INTERVAL_1_4``
+
+ - Guard interval 1/4
+
+ - .. row 8
+
+ - .. _`GUARD-INTERVAL-19-128`:
+
+ ``GUARD_INTERVAL_19_128``
+
+ - Guard interval 19/128
+
+ - .. row 9
+
+ - .. _`GUARD-INTERVAL-19-256`:
+
+ ``GUARD_INTERVAL_19_256``
+
+ - Guard interval 19/256
+
+ - .. row 10
+
+ - .. _`GUARD-INTERVAL-PN420`:
+
+ ``GUARD_INTERVAL_PN420``
+
+ - PN length 420 (1/4)
+
+ - .. row 11
+
+ - .. _`GUARD-INTERVAL-PN595`:
+
+ ``GUARD_INTERVAL_PN595``
+
+ - PN length 595 (1/6)
+
+ - .. row 12
+
+ - .. _`GUARD-INTERVAL-PN945`:
+
+ ``GUARD_INTERVAL_PN945``
+
+ - PN length 945 (1/9)
+
+
+Notes:
+
+1) 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.
+
+2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at
+present
+
+3) DTMB specifies PN420, PN595 and PN945.
+
+
+.. _DTV-TRANSMISSION-MODE:
+
+DTV_TRANSMISSION_MODE
+=====================
+
+Specifies the number of carriers used by the standard. This is used only
+on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB
+
+
+.. _fe-transmit-mode-t:
+
+enum fe_transmit_mode: Number of carriers per channel
+-----------------------------------------------------
+
+
+.. _fe-transmit-mode:
+
+.. flat-table:: enum fe_transmit_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`TRANSMISSION-MODE-AUTO`:
+
+ ``TRANSMISSION_MODE_AUTO``
+
+ - Autodetect transmission mode. The hardware will try to find the
+ correct FFT-size (if capable) to fill in the missing parameters.
+
+ - .. row 3
+
+ - .. _`TRANSMISSION-MODE-1K`:
+
+ ``TRANSMISSION_MODE_1K``
+
+ - Transmission mode 1K
+
+ - .. row 4
+
+ - .. _`TRANSMISSION-MODE-2K`:
+
+ ``TRANSMISSION_MODE_2K``
+
+ - Transmission mode 2K
+
+ - .. row 5
+
+ - .. _`TRANSMISSION-MODE-8K`:
+
+ ``TRANSMISSION_MODE_8K``
+
+ - Transmission mode 8K
+
+ - .. row 6
+
+ - .. _`TRANSMISSION-MODE-4K`:
+
+ ``TRANSMISSION_MODE_4K``
+
+ - Transmission mode 4K
+
+ - .. row 7
+
+ - .. _`TRANSMISSION-MODE-16K`:
+
+ ``TRANSMISSION_MODE_16K``
+
+ - Transmission mode 16K
+
+ - .. row 8
+
+ - .. _`TRANSMISSION-MODE-32K`:
+
+ ``TRANSMISSION_MODE_32K``
+
+ - Transmission mode 32K
+
+ - .. row 9
+
+ - .. _`TRANSMISSION-MODE-C1`:
+
+ ``TRANSMISSION_MODE_C1``
+
+ - Single Carrier (C=1) transmission mode (DTMB)
+
+ - .. row 10
+
+ - .. _`TRANSMISSION-MODE-C3780`:
+
+ ``TRANSMISSION_MODE_C3780``
+
+ - Multi Carrier (C=3780) transmission mode (DTMB)
+
+
+Notes:
+
+1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
+'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K
+
+2) If ``DTV_TRANSMISSION_MODE`` is set the ``TRANSMISSION_MODE_AUTO``
+the hardware will try to find the correct FFT-size (if capable) and will
+use TMCC to fill in the missing parameters.
+
+3) DVB-T specifies 2K and 8K as valid sizes.
+
+4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.
+
+5) DTMB specifies C1 and C3780.
+
+
+.. _DTV-HIERARCHY:
+
+DTV_HIERARCHY
+=============
+
+Frontend hierarchy
+
+
+.. _fe-hierarchy-t:
+
+Frontend hierarchy
+------------------
+
+
+.. _fe-hierarchy:
+
+.. flat-table:: enum fe_hierarchy
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`HIERARCHY-NONE`:
+
+ ``HIERARCHY_NONE``
+
+ - No hierarchy
+
+ - .. row 3
+
+ - .. _`HIERARCHY-AUTO`:
+
+ ``HIERARCHY_AUTO``
+
+ - Autodetect hierarchy (if supported)
+
+ - .. row 4
+
+ - .. _`HIERARCHY-1`:
+
+ ``HIERARCHY_1``
+
+ - Hierarchy 1
+
+ - .. row 5
+
+ - .. _`HIERARCHY-2`:
+
+ ``HIERARCHY_2``
+
+ - Hierarchy 2
+
+ - .. row 6
+
+ - .. _`HIERARCHY-4`:
+
+ ``HIERARCHY_4``
+
+ - Hierarchy 4
+
+
+
+.. _DTV-STREAM-ID:
+
+DTV_STREAM_ID
+=============
+
+DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on
+a single transport stream. This property enables the DVB 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 ISDB, the valid substream id range is from 1 to 65535.
+
+To disable it, you should use the special macro NO_STREAM_ID_FILTER.
+
+Note: any value outside the id range also disables filtering.
+
+
+.. _DTV-DVBT2-PLP-ID-LEGACY:
+
+DTV_DVBT2_PLP_ID_LEGACY
+=======================
+
+Obsolete, replaced with DTV_STREAM_ID.
+
+
+.. _DTV-ENUM-DELSYS:
+
+DTV_ENUM_DELSYS
+===============
+
+A Multi standard frontend needs to advertise the delivery systems
+provided. Applications need to enumerate the provided delivery systems,
+before using any other operation with the frontend. Prior to it's
+introduction, FE_GET_INFO was used to determine a frontend type. A
+frontend which provides more than a single delivery system,
+FE_GET_INFO doesn't help much. Applications which intends to use a
+multistandard frontend must enumerate the delivery systems associated
+with it, rather than trying to use FE_GET_INFO. In the case of a
+legacy frontend, the result is just the same as with FE_GET_INFO, but
+in a more structured format
+
+
+.. _DTV-INTERLEAVING:
+
+DTV_INTERLEAVING
+================
+
+Time interleaving to be used. Currently, used only on DTMB.
+
+
+.. _fe-interleaving:
+
+.. flat-table:: enum fe_interleaving
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _`INTERLEAVING-NONE`:
+
+ ``INTERLEAVING_NONE``
+
+ - No interleaving.
+
+ - .. row 3
+
+ - .. _`INTERLEAVING-AUTO`:
+
+ ``INTERLEAVING_AUTO``
+
+ - Auto-detect interleaving.
+
+ - .. row 4
+
+ - .. _`INTERLEAVING-240`:
+
+ ``INTERLEAVING_240``
+
+ - Interleaving of 240 symbols.
+
+ - .. row 5
+
+ - .. _`INTERLEAVING-720`:
+
+ ``INTERLEAVING_720``
+
+ - Interleaving of 720 symbols.
+
+
+
+.. _DTV-LNA:
+
+DTV_LNA
+=======
+
+Low-noise amplifier.
+
+Hardware might offer controllable LNA which can be set manually using
+that parameter. Usually LNA could be found only from terrestrial devices
+if at all.
+
+Possible values: 0, 1, LNA_AUTO
+
+0, LNA off
+
+1, LNA on
+
+use the special macro LNA_AUTO to set LNA auto
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-property-cable-systems:
+
+*****************************************
+Properties used on cable delivery systems
+*****************************************
+
+
+.. _dvbc-params:
+
+DVB-C delivery system
+=====================
+
+The DVB-C Annex-A is the widely used cable standard. Transmission uses
+QAM modulation.
+
+The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It
+supports a subset of the Annex A modulation types, and a roll-off of
+0.13, instead of 0.15
+
+The following parameters are valid for DVB-C Annex A/C:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _dvbc-annex-b-params:
+
+DVB-C Annex B delivery system
+=============================
+
+The DVB-C Annex-B is only used on a few Countries like the United
+States.
+
+The following parameters are valid for DVB-C Annex B:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-property-satellite-systems:
+
+*********************************************
+Properties used on satellite delivery systems
+*********************************************
+
+
+.. _dvbs-params:
+
+DVB-S delivery system
+=====================
+
+The following parameters are valid for DVB-S:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
+
+- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>`
+
+- :ref:`DTV_TONE <DTV-TONE>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+Future implementations might add those two missing parameters:
+
+- :ref:`DTV_DISEQC_MASTER <DTV-DISEQC-MASTER>`
+
+- :ref:`DTV_DISEQC_SLAVE_REPLY <DTV-DISEQC-SLAVE-REPLY>`
+
+
+.. _dvbs2-params:
+
+DVB-S2 delivery system
+======================
+
+In addition to all parameters valid for DVB-S, DVB-S2 supports the
+following parameters:
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_PILOT <DTV-PILOT>`
+
+- :ref:`DTV_ROLLOFF <DTV-ROLLOFF>`
+
+- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _turbo-params:
+
+Turbo code delivery system
+==========================
+
+In addition to all parameters valid for DVB-S, turbo code supports the
+following parameters:
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+
+.. _isdbs-params:
+
+ISDB-S delivery system
+======================
+
+The following parameters are valid for ISDB-S:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
+
+- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>`
+
+- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-property-terrestrial-systems:
+
+***********************************************
+Properties used on terrestrial delivery systems
+***********************************************
+
+
+.. _dvbt-params:
+
+DVB-T delivery system
+=====================
+
+The following parameters are valid for DVB-T:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`
+
+- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`
+
+- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
+
+- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
+
+- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _dvbt2-params:
+
+DVB-T2 delivery system
+======================
+
+DVB-T2 support is currently in the early stages of development, so
+expect that this section maygrow and become more detailed with time.
+
+The following parameters are valid for DVB-T2:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`
+
+- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`
+
+- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
+
+- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
+
+- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`
+
+- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _isdbt:
+
+ISDB-T delivery system
+======================
+
+This ISDB-T/ISDB-Tsb API extension should reflect all information needed
+to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some
+very sophisticated devices won't need certain parameters to tune.
+
+The information given here should help application writers to know how
+to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.
+
+The details given here about ISDB-T and ISDB-Tsb are just enough to
+basically show the dependencies between the needed parameter values, but
+surely some information is left out. For more detailed information see
+the following documents:
+
+ARIB STD-B31 - "Transmission System for Digital Terrestrial Television
+Broadcasting" and
+
+ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television
+Broadcasting".
+
+In order to understand the ISDB specific parameters, one has to have
+some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has
+to be known to the reader that an ISDB-T channel consists of 13
+segments, that it can have up to 3 layer sharing those segments, and
+things like that.
+
+The following parameters are valid for ISDB-T:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
+
+- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
+
+- :ref:`DTV_ISDBT_LAYER_ENABLED <DTV-ISDBT-LAYER-ENABLED>`
+
+- :ref:`DTV_ISDBT_PARTIAL_RECEPTION <DTV-ISDBT-PARTIAL-RECEPTION>`
+
+- :ref:`DTV_ISDBT_SOUND_BROADCASTING <DTV-ISDBT-SOUND-BROADCASTING>`
+
+- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID <DTV-ISDBT-SB-SUBCHANNEL-ID>`
+
+- :ref:`DTV_ISDBT_SB_SEGMENT_IDX <DTV-ISDBT-SB-SEGMENT-IDX>`
+
+- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT <DTV-ISDBT-SB-SEGMENT-COUNT>`
+
+- :ref:`DTV_ISDBT_LAYERA_FEC <DTV-ISDBT-LAYER-FEC>`
+
+- :ref:`DTV_ISDBT_LAYERA_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
+
+- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
+
+- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
+
+- :ref:`DTV_ISDBT_LAYERB_FEC <DTV-ISDBT-LAYER-FEC>`
+
+- :ref:`DTV_ISDBT_LAYERB_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
+
+- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
+
+- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
+
+- :ref:`DTV_ISDBT_LAYERC_FEC <DTV-ISDBT-LAYER-FEC>`
+
+- :ref:`DTV_ISDBT_LAYERC_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
+
+- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
+
+- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _atsc-params:
+
+ATSC delivery system
+====================
+
+The following parameters are valid for ATSC:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _atscmh-params:
+
+ATSC-MH delivery system
+=======================
+
+The following parameters are valid for ATSC-MH:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_ATSCMH_FIC_VER <DTV-ATSCMH-FIC-VER>`
+
+- :ref:`DTV_ATSCMH_PARADE_ID <DTV-ATSCMH-PARADE-ID>`
+
+- :ref:`DTV_ATSCMH_NOG <DTV-ATSCMH-NOG>`
+
+- :ref:`DTV_ATSCMH_TNOG <DTV-ATSCMH-TNOG>`
+
+- :ref:`DTV_ATSCMH_SGN <DTV-ATSCMH-SGN>`
+
+- :ref:`DTV_ATSCMH_PRC <DTV-ATSCMH-PRC>`
+
+- :ref:`DTV_ATSCMH_RS_FRAME_MODE <DTV-ATSCMH-RS-FRAME-MODE>`
+
+- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE <DTV-ATSCMH-RS-FRAME-ENSEMBLE>`
+
+- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI <DTV-ATSCMH-RS-CODE-MODE-PRI>`
+
+- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC <DTV-ATSCMH-RS-CODE-MODE-SEC>`
+
+- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE <DTV-ATSCMH-SCCC-BLOCK-MODE>`
+
+- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A <DTV-ATSCMH-SCCC-CODE-MODE-A>`
+
+- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B <DTV-ATSCMH-SCCC-CODE-MODE-B>`
+
+- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C <DTV-ATSCMH-SCCC-CODE-MODE-C>`
+
+- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D <DTV-ATSCMH-SCCC-CODE-MODE-D>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _dtmb-params:
+
+DTMB delivery system
+====================
+
+The following parameters are valid for DTMB:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
+
+- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
+
+- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
+
+- :ref:`DTV_INTERLEAVING <DTV-INTERLEAVING>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-stat-properties:
+
+******************************
+Frontend statistics indicators
+******************************
+
+The values are returned via ``dtv_property.stat``. If the property is
+supported, ``dtv_property.stat.len`` is bigger than zero.
+
+For most delivery systems, ``dtv_property.stat.len`` will be 1 if the
+stats is supported, and the properties will return a single value for
+each parameter.
+
+It should be noted, however, that new OFDM delivery systems like ISDB
+can use different modulation types for each group of carriers. On such
+standards, up to 3 groups of statistics can be provided, and
+``dtv_property.stat.len`` is updated to reflect the "global" metrics,
+plus one metric per each carrier group (called "layer" on ISDB).
+
+So, in order to be consistent with other delivery systems, the first
+value at :ref:`dtv_property.stat.dtv_stats <dtv-stats>` array refers
+to the global metric. The other elements of the array represent each
+layer, starting from layer A(index 1), layer B (index 2) and so on.
+
+The number of filled elements are stored at ``dtv_property.stat.len``.
+
+Each element of the ``dtv_property.stat.dtv_stats`` array consists on
+two elements:
+
+- ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of
+ the measure (dB measures) and ``uvalue`` is for unsigned values
+ (counters, relative scale)
+
+- ``scale`` - Scale for the value. It can be:
+
+ - ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the
+ frontend, but it was not possible to collect it (could be a
+ transitory or permanent condition)
+
+ - ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in
+ 1/1000 dB
+
+ - ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0
+ means 0% and 65535 means 100%.
+
+ - ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts
+ the occurrence of an event, like bit error, block error, or lapsed
+ time.
+
+
+.. _DTV-STAT-SIGNAL-STRENGTH:
+
+DTV_STAT_SIGNAL_STRENGTH
+========================
+
+Indicates the signal strength level at the analog part of the tuner or
+of the demod.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power
+ measured in miliwatts. This value is generally negative.
+
+- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
+ measurement for power (actually, 0 to 65535).
+
+
+.. _DTV-STAT-CNR:
+
+DTV_STAT_CNR
+============
+
+Indicates the Signal to Noise ratio for the main carrier.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units.
+
+- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
+ measurement for Signal/Noise (actually, 0 to 65535).
+
+
+.. _DTV-STAT-PRE-ERROR-BIT-COUNT:
+
+DTV_STAT_PRE_ERROR_BIT_COUNT
+============================
+
+Measures the number of bit errors before the forward error correction
+(FEC) on the inner coding block (before Viterbi, LDPC or other inner
+code).
+
+This measure is taken during the same interval as
+``DTV_STAT_PRE_TOTAL_BIT_COUNT``.
+
+In order to get the BER (Bit Error Rate) measurement, it should be
+divided by
+:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner
+ coding.
+
+
+.. _DTV-STAT-PRE-TOTAL-BIT-COUNT:
+
+DTV_STAT_PRE_TOTAL_BIT_COUNT
+============================
+
+Measures the amount of bits received before the inner code block, during
+the same period as
+:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
+measurement was taken.
+
+It should be noted that this measurement can be smaller than the total
+amount of bits on the transport stream, as the frontend may need to
+manually restart the measurement, losing some data between each
+measurement interval.
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
+ :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`.
+
+
+.. _DTV-STAT-POST-ERROR-BIT-COUNT:
+
+DTV_STAT_POST_ERROR_BIT_COUNT
+=============================
+
+Measures the number of bit errors after the forward error correction
+(FEC) done by inner code block (after Viterbi, LDPC or other inner
+code).
+
+This measure is taken during the same interval as
+``DTV_STAT_POST_TOTAL_BIT_COUNT``.
+
+In order to get the BER (Bit Error Rate) measurement, it should be
+divided by
+:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner
+ coding.
+
+
+.. _DTV-STAT-POST-TOTAL-BIT-COUNT:
+
+DTV_STAT_POST_TOTAL_BIT_COUNT
+=============================
+
+Measures the amount of bits received after the inner coding, during the
+same period as
+:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
+measurement was taken.
+
+It should be noted that this measurement can be smaller than the total
+amount of bits on the transport stream, as the frontend may need to
+manually restart the measurement, losing some data between each
+measurement interval.
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
+ :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`.
+
+
+.. _DTV-STAT-ERROR-BLOCK-COUNT:
+
+DTV_STAT_ERROR_BLOCK_COUNT
+==========================
+
+Measures the number of block errors after the outer forward error
+correction coding (after Reed-Solomon or other outer code).
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer
+ coding.
+
+
+.. _DTV-STAT-TOTAL-BLOCK-COUNT:
+
+DTV-STAT_TOTAL_BLOCK_COUNT
+==========================
+
+Measures the total number of blocks received during the same period as
+:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
+measurement was taken.
+
+It can be used to calculate the PER indicator, by dividing
+:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` by
+:ref:`DTV-STAT-TOTAL-BLOCK-COUNT <DTV-STAT-TOTAL-BLOCK-COUNT>`.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring
+ :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_frontend:
+
+################
+DVB Frontend API
+################
+The DVB frontend API was designed to support three types of delivery
+systems:
+
+- Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H,
+ DTMB, CMMB
+
+- Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C
+
+- Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS
+
+The DVB frontend controls several sub-devices including:
+
+- Tuner
+
+- Digital TV demodulator
+
+- Low noise amplifier (LNA)
+
+- Satellite Equipment Control (SEC) hardware (only for Satellite).
+
+The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``.
+Data types and ioctl definitions can be accessed by including
+``linux/dvb/frontend.h`` in your application.
+
+NOTE: Transmission via the internet (DVB-IP) is not yet handled by this
+API but a future extension is possible.
+
+On Satellite systems, the API support for the Satellite Equipment
+Control (SEC) allows to power control and to send/receive signals to
+control the antenna subsystem, selecting the polarization and choosing
+the Intermediate Frequency IF) of the Low Noise Block Converter Feed
+Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC
+(digital SEC) specification is available at
+`Eutelsat <http://www.eutelsat.com/satellites/4_5_5.html>`__.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ query-dvb-frontend-info
+ dvb-fe-read-status
+ dvbproperty
+ frontend_fcalls
+ frontend_legacy_dvbv3_api
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_f_close:
+
+********************
+DVB frontend close()
+********************
+
+*man fe-close(2)*
+
+Close a frontend device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. c:function:: int close( int fd )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+
+Description
+===========
+
+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
+============
+
+The function returns 0 on success, -1 on failure and the ``errno`` is
+set appropriately. Possible error codes:
+
+EBADF
+ ``fd`` is not a valid open file descriptor.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_f_open:
+
+*******************
+DVB frontend open()
+*******************
+
+*man fe-open(2)*
+
+Open a frontend device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+
+.. c:function:: int open( const char *device_name, int flags )
+
+Arguments
+=========
+
+``device_name``
+ Device to be opened.
+
+``flags``
+ Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``.
+
+ Multiple opens are allowed with ``O_RDONLY``. In this mode, only
+ query and read ioctls are allowed.
+
+ Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are
+ allowed.
+
+ When the ``O_NONBLOCK`` flag is given, the system calls may return
+ EAGAIN error code when no data is available or when the device
+ driver is temporarily busy.
+
+ Other flags have no effect.
+
+
+Description
+===========
+
+This system call opens a named frontend device
+(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
+thing to do after a successful open is to find out the frontend type
+with :ref:`FE_GET_INFO <FE_GET_INFO>`.
+
+The device can be opened in read-only mode, which only allows monitoring
+of device status and statistics, or read/write mode, which allows any
+kind of use (e.g. performing tuning operations.)
+
+In a system with multiple front-ends, it is usually the case that
+multiple devices cannot be open in read/write mode simultaneously. As
+long as a front-end device is opened in read/write mode, other open()
+calls in read/write mode will either fail or block, depending on whether
+non-blocking or blocking mode was specified. A front-end 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.
+When an open() call has succeeded, the device will be ready for use in
+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 :c:func:`open()` returns the new file descriptor. On error
+-1 is returned, and the ``errno`` variable is set appropriately.
+Possible error codes are:
+
+EACCES
+ The caller has no permission to access the device.
+
+EBUSY
+ The the device driver is already in use.
+
+ENXIO
+ No device corresponding to this device special file exists.
+
+ENOMEM
+ Not enough kernel memory was available to complete the request.
+
+EMFILE
+ The process already has the maximum number of files open.
+
+ENFILE
+ The limit on the total number of files open on the system has been
+ reached.
+
+ENODEV
+ The device got removed.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_fcalls:
+
+#######################
+Frontend Function Calls
+#######################
+
+.. toctree::
+ :maxdepth: 1
+
+ frontend_f_open
+ frontend_f_close
+ fe-get-info
+ fe-read-status
+ fe-get-property
+ fe-diseqc-reset-overload
+ fe-diseqc-send-master-cmd
+ fe-diseqc-recv-slave-reply
+ fe-diseqc-send-burst
+ fe-set-tone
+ fe-set-voltage
+ fe-enable-high-lnb-voltage
+ fe-set-frontend-tune-mode
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_h:
+
+************************
+DVB Frontend Header File
+************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ../../frontend.h
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_legacy_types:
+
+Frontend Legacy Data Types
+==========================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ fe-type-t
+ fe-bandwidth-t
+ dvb-frontend-parameters
+ dvb-frontend-event
+
+
+.. _frontend_legacy_fcalls:
+
+Frontend Legacy Function Calls
+==============================
+
+Those functions are defined at DVB version 3. The support is kept in the
+kernel due to compatibility issues only. Their usage is strongly not
+recommended
+
+
+.. toctree::
+ :maxdepth: 1
+
+ FE_READ_BER
+ FE_READ_SNR
+ FE_READ_SIGNAL_STRENGTH
+ FE_READ_UNCORRECTED_BLOCKS
+ FE_SET_FRONTEND
+ FE_GET_FRONTEND
+ FE_GET_EVENT
+ FE_DISHNETWORK_SEND_LEGACY_CMD
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_legacy_dvbv3_api:
+
+****************************************
+DVB Frontend legacy API (a. k. a. DVBv3)
+****************************************
+
+The usage of this API is deprecated, as it doesn't support all digital
+TV standards, doesn't provide good statistics measurements and provides
+incomplete information. This is kept only to support legacy
+applications.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ frontend_legacy_api
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_introdution:
+
+************
+Introduction
+************
+
+
+.. _requisites:
+
+What you need to know
+=====================
+
+The reader of this document is required to have some knowledge in the
+area of digital video broadcasting (DVB) and should be familiar with
+part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
+you should know what a program/transport stream (PS/TS) is and what is
+meant by a packetized elementary stream (PES) or an I-frame.
+
+Various DVB standards documents are available from http://www.dvb.org
+and/or http://www.etsi.org.
+
+It is also necessary to know how to access unix/linux devices and how to
+use ioctl calls. This also includes the knowledge of C or C++.
+
+
+.. _history:
+
+History
+=======
+
+The first API for DVB cards we used at Convergence in late 1999 was an
+extension of the Video4Linux API which was primarily developed for frame
+grabber cards. As such it was not really well suited to be used for DVB
+cards and their new features like recording MPEG streams and filtering
+several section and PES data streams at the same time.
+
+In early 2000, we were approached by Nokia with a proposal for a new
+standard Linux DVB API. As a commitment to the development of terminals
+based on open standards, Nokia and Convergence made it available to all
+Linux developers and published it on https://linuxtv.org in September
+2000. Convergence is the maintainer of the Linux DVB API. Together with
+the LinuxTV community (i.e. you, the reader of this document), the Linux
+DVB API will be constantly reviewed and improved. With the Linux driver
+for the Siemens/Hauppauge DVB PCI card Convergence provides a first
+implementation of the Linux DVB API.
+
+
+.. _overview:
+
+Overview
+========
+
+
+.. _stb_components:
+
+.. figure:: intro_files/dvbstb.*
+ :alt: dvbstb.pdf / dvbstb.png
+ :align: center
+
+ Components of a DVB card/STB
+
+A DVB PCI card or DVB set-top-box (STB) usually consists of the
+following main hardware components:
+
+- Frontend consisting of tuner and DVB demodulator
+
+ Here the raw signal reaches the DVB hardware from a satellite dish or
+ antenna or directly from cable. The frontend down-converts and
+ demodulates this signal into an MPEG transport stream (TS). In case
+ of a satellite frontend, this includes a facility for satellite
+ equipment control (SEC), which allows control of LNB polarization,
+ multi feed switches or dish rotors.
+
+- Conditional Access (CA) hardware like CI adapters and smartcard slots
+
+ The complete TS is passed through the CA hardware. Programs to which
+ the user has access (controlled by the smart card) are decoded in
+ real time and re-inserted into the TS.
+
+- Demultiplexer which filters the incoming DVB stream
+
+ The demultiplexer splits the TS into its components like audio and
+ video streams. Besides usually several of such audio and video
+ streams it also contains data streams with information about the
+ programs offered in this or other streams of the same provider.
+
+- MPEG2 audio and video decoder
+
+ The main targets of the demultiplexer are the MPEG2 audio and video
+ decoders. After decoding they pass on the uncompressed audio and
+ video to the computer screen or (through a PAL/NTSC encoder) to a TV
+ set.
+
+:ref:`stb_components` shows a crude schematic of the control and data
+flow between those components.
+
+On a DVB PCI card not all of these have to be present since some
+functionality can be provided by the main CPU of the PC (e.g. MPEG
+picture and sound decoding) or is not needed (e.g. for data-only uses
+like “internet over satellite”). Also not every card or STB provides
+conditional access hardware.
+
+
+.. _dvb_devices:
+
+Linux DVB Devices
+=================
+
+The Linux DVB API lets you control these hardware components through
+currently six Unix-style character devices for video, audio, frontend,
+demux, CA and IP-over-DVB networking. The video and audio devices
+control the MPEG2 decoder hardware, the frontend device the tuner and
+the DVB demodulator. The demux device gives you control over the PES and
+section filters of the hardware. If the hardware does not support
+filtering these filters can be implemented in software. Finally, the CA
+device controls all the conditional access capabilities of the hardware.
+It can depend on the individual security requirements of the platform,
+if and how many of the CA functions are made available to the
+application through this device.
+
+All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The
+individual devices are called:
+
+- ``/dev/dvb/adapterN/audioM``,
+
+- ``/dev/dvb/adapterN/videoM``,
+
+- ``/dev/dvb/adapterN/frontendM``,
+
+- ``/dev/dvb/adapterN/netM``,
+
+- ``/dev/dvb/adapterN/demuxM``,
+
+- ``/dev/dvb/adapterN/dvrM``,
+
+- ``/dev/dvb/adapterN/caM``,
+
+where N enumerates the DVB PCI 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
+discussion of these devices.
+
+More details about the data structures and function calls of all the
+devices are described in the following chapters.
+
+
+.. _include_files:
+
+API include files
+=================
+
+For each of the DVB devices a corresponding include file exists. The DVB
+API include files should be included in application sources with a
+partial path like:
+
+
+.. code-block:: c
+
+ #include <linux/dvb/audio.h>
+
+
+.. code-block:: c
+
+ #include <linux/dvb/ca.h>
+
+
+.. code-block:: c
+
+ #include <linux/dvb/dmx.h>
+
+
+.. code-block:: c
+
+ #include <linux/dvb/frontend.h>
+
+
+.. code-block:: c
+
+ #include <linux/dvb/net.h>
+
+
+.. code-block:: c
+
+ #include <linux/dvb/osd.h>
+
+
+.. code-block:: c
+
+ #include <linux/dvb/video.h>
+
+To enable applications to support different API version, an additional
+include file ``linux/dvb/version.h`` exists, which defines the constant
+``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _legacy_dvb_apis:
+
+*******************
+DVB Deprecated APIs
+*******************
+
+The APIs described here are kept only for historical reasons. There's
+just one driver for a very legacy hardware that uses this API. No modern
+drivers should use it. Instead, audio and video should be using the V4L2
+and ALSA APIs, and the pipelines should be set using the Media
+Controller API
+
+
+.. toctree::
+ :maxdepth: 1
+
+ video
+ audio
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _net:
+
+###############
+DVB Network API
+###############
+The DVB net device controls the mapping of data packages that are part
+of a transport stream to be mapped into a virtual network interface,
+visible through the standard Linux network protocol stack.
+
+Currently, two encapsulations are supported:
+
+- `Multi Protocol Encapsulation (MPE) <http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation>`__
+
+- `Ultra Lightweight Encapsulation (ULE) <http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation>`__
+
+In order to create the Linux virtual network interfaces, an application
+needs to tell to the Kernel what are the PIDs and the encapsulation
+types that are present on the transport stream. This is done through
+``/dev/dvb/adapter?/net?`` device node. The data will be available via
+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``
+header.
+
+
+.. _net_fcalls:
+
+######################
+DVB net Function Calls
+######################
+
+.. _NET_ADD_IF:
+
+****************
+ioctl NET_ADD_IF
+****************
+
+*man NET_ADD_IF(2)*
+
+Creates a new network interface for a given Packet ID.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_TONE
+
+``net_if``
+ pointer to struct :ref:`dvb_net_if <dvb-net-if>`
+
+
+Description
+===========
+
+The NET_ADD_IF ioctl system call selects the Packet ID (PID) that
+contains a TCP/IP traffic, the type of encapsulation to be used (MPE or
+ULE) and the interface number for the new interface to be created. When
+the system call successfully returns, a new virtual network interface is
+created.
+
+The struct :ref:`dvb_net_if <dvb-net-if>`::ifnum field will be
+filled with the number of the created interface.
+
+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.
+
+
+.. _dvb-net-if-t:
+
+struct dvb_net_if description
+=============================
+
+
+.. _dvb-net-if:
+
+.. flat-table:: struct dvb_net_if
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - pid
+
+ - Packet ID (PID) of the MPEG-TS that contains data
+
+ - .. row 3
+
+ - ifnum
+
+ - number of the DVB interface.
+
+ - .. row 4
+
+ - feedtype
+
+ - Encapsulation type of the feed. It can be:
+ ``DVB_NET_FEEDTYPE_MPE`` for MPE encoding or
+ ``DVB_NET_FEEDTYPE_ULE`` for ULE encoding.
+
+
+
+.. _NET_REMOVE_IF:
+
+*******************
+ioctl NET_REMOVE_IF
+*******************
+
+*man NET_REMOVE_IF(2)*
+
+Removes a network interface.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, int ifnum )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_TONE
+
+``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
+
+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.
+
+
+.. _NET_GET_IF:
+
+****************
+ioctl NET_GET_IF
+****************
+
+*man NET_GET_IF(2)*
+
+Read the configuration data of an interface created via
+:ref:`NET_ADD_IF <net>`.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_TONE
+
+``net_if``
+ pointer to struct :ref:`dvb_net_if <dvb-net-if>`
+
+
+Description
+===========
+
+The NET_GET_IF ioctl uses the interface number given by the struct
+:ref:`dvb_net_if <dvb-net-if>`::ifnum field and fills the content of
+struct :ref:`dvb_net_if <dvb-net-if>` with the packet ID and
+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
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _net_h:
+
+***********************
+DVB Network Header File
+***********************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ../../net.h
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _query-dvb-frontend-info:
+
+*****************************
+Querying frontend information
+*****************************
+
+Usually, the first thing to do when the frontend is opened is to check
+the frontend capabilities. This is done using
+:ref:`FE_GET_INFO <FE_GET_INFO>`. This ioctl will enumerate the
+DVB API version and other characteristics about the frontend, and can be
+opened either in read only or read/write mode.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_video:
+
+################
+DVB Video Device
+################
+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 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.
+
+Some 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.
+
+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
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video_function_calls:
+
+********************
+Video Function Calls
+********************
+
+
+.. _video_fopen:
+
+open()
+======
+
+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.
+
+SYNOPSIS
+
+int open(const char *deviceName, int flags);
+
+PARAMETERS
+
+
+
+.. 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)
+
+
+RETURN VALUE
+
+
+
+.. 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.
+
+
+
+.. _video_fclose:
+
+close()
+=======
+
+DESCRIPTION
+
+This system call closes a previously opened video device.
+
+SYNOPSIS
+
+int close(int fd);
+
+PARAMETERS
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+
+RETURN VALUE
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EBADF
+
+ - fd is not a valid open file descriptor.
+
+
+
+.. _video_fwrite:
+
+write()
+=======
+
+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.
+
+SYNOPSIS
+
+size_t write(int fd, const void *buf, size_t count);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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.
+
+
+
+.. _VIDEO_STOP:
+
+VIDEO_STOP
+==========
+
+DESCRIPTION
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD <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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_STOP, boolean mode);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_PLAY
+==========
+
+DESCRIPTION
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>` instead.
+
+This ioctl call asks the Video Device to start playing a video stream
+from the selected source.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_PLAY);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_FREEZE
+============
+
+DESCRIPTION
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD <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 DVB subsystem will not decode any more data
+until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_FREEZE);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_CONTINUE
+==============
+
+DESCRIPTION
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD <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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_CONTINUE);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_SELECT_SOURCE
+===================
+
+DESCRIPTION
+
+This ioctl is for DVB 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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SELECT_SOURCE,
+video_stream_source_t source);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_SET_BLANK
+===============
+
+DESCRIPTION
+
+This ioctl call asks the Video Device to blank out the picture.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_BLANK, boolean mode);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_GET_STATUS
+================
+
+DESCRIPTION
+
+This ioctl call asks the Video Device to return the current status of
+the device.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_GET_STATUS, struct video_status
+*status);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_GET_FRAME_COUNT
+=====================
+
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = VIDEO_GET_FRAME_COUNT, __u64 *pts);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_GET_PTS
+=============
+
+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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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_RATE:
+
+VIDEO_GET_FRAME_RATE
+====================
+
+DESCRIPTION
+
+This ioctl call asks the Video Device to return the current framerate.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = VIDEO_GET_FRAME_RATE, unsigned int
+*rate);
+
+PARAMETERS
+
+
+
+.. 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_RATE for this command.
+
+ - .. row 3
+
+ - unsigned int *rate
+
+ - Returns the framerate in number of frames per 1000 seconds.
+
+
+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:
+
+VIDEO_GET_EVENT
+===============
+
+DESCRIPTION
+
+This ioctl is for DVB devices only. To get events from a V4L2 decoder
+use the V4L2 :ref:`VIDIOC_DQEVENT <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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_GET_EVENT, struct video_event *ev);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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.
+
+
+
+.. _VIDEO_COMMAND:
+
+VIDEO_COMMAND
+=============
+
+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 <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 <vidioc-decoder-cmd>` documentation for
+more information.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = VIDEO_COMMAND, struct video_command
+*cmd);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_TRY_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.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = VIDEO_TRY_COMMAND, struct
+video_command *cmd);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_GET_SIZE
+==============
+
+DESCRIPTION
+
+This ioctl returns the size and aspect ratio.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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_DISPLAY_FORMAT:
+
+VIDEO_SET_DISPLAY_FORMAT
+========================
+
+DESCRIPTION
+
+This ioctl call asks the Video Device to select the video format to be
+applied by the MPEG chip on the video.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT,
+video_display_format_t format);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_STILLPICTURE
+==================
+
+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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_STILLPICTURE, struct
+video_still_picture *sp);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_FAST_FORWARD
+==================
+
+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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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.
+
+
+
+.. _VIDEO_SLOWMOTION:
+
+VIDEO_SLOWMOTION
+================
+
+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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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.
+
+
+
+.. _VIDEO_GET_CAPABILITIES:
+
+VIDEO_GET_CAPABILITIES
+======================
+
+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 ??.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int
+*cap);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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_ID:
+
+VIDEO_SET_ID
+============
+
+DESCRIPTION
+
+This ioctl selects which sub-stream is to be decoded if a program or
+system stream is sent to the video device.
+
+SYNOPSIS
+
+int ioctl(int fd, int request = VIDEO_SET_ID, int id);
+
+PARAMETERS
+
+
+
+.. 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_ID for this command.
+
+ - .. row 3
+
+ - int id
+
+ - video sub-stream id
+
+
+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
+
+ - Invalid sub-stream id.
+
+
+
+.. _VIDEO_CLEAR_BUFFER:
+
+VIDEO_CLEAR_BUFFER
+==================
+
+DESCRIPTION
+
+This ioctl call clears all video buffers in the driver and in the
+decoder hardware.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);
+
+PARAMETERS
+
+
+
+.. 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.
+
+
+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:
+
+VIDEO_SET_STREAMTYPE
+====================
+
+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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type);
+
+PARAMETERS
+
+
+
+.. 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
+
+
+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:
+
+VIDEO_SET_FORMAT
+================
+
+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.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t
+format);
+
+PARAMETERS
+
+
+
+.. 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 ??.
+
+
+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.
+
+
+
+.. _VIDEO_SET_SYSTEM:
+
+VIDEO_SET_SYSTEM
+================
+
+DESCRIPTION
+
+This ioctl sets the television output format. The format (see section
+??) may vary from the color format of the displayed MPEG stream. If the
+hardware is not able to display the requested format the call will
+return an error.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_SYSTEM , video_system_t
+system);
+
+PARAMETERS
+
+
+
+.. 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_system_t system
+
+ - video system of TV output.
+
+
+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
+
+ - system is not a valid or supported video system.
+
+
+
+.. _VIDEO_SET_HIGHLIGHT:
+
+VIDEO_SET_HIGHLIGHT
+===================
+
+DESCRIPTION
+
+This ioctl sets the SPU highlight information for the menu access of a
+DVD.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT ,video_highlight_t
+*vhilite)
+
+PARAMETERS
+
+
+
+.. 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_HIGHLIGHT for this command.
+
+ - .. row 3
+
+ - video_highlight_t *vhilite
+
+ - SPU Highlight information according to 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.
+
+
+.. _VIDEO_SET_SPU:
+
+VIDEO_SET_SPU
+=============
+
+DESCRIPTION
+
+This ioctl activates or deactivates SPU decoding in a DVD input stream.
+It can only be used, if the driver is able to handle a DVD stream.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_SPU , video_spu_t *spu)
+
+PARAMETERS
+
+
+
+.. 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_SPU for this command.
+
+ - .. row 3
+
+ - video_spu_t *spu
+
+ - SPU decoding (de)activation and subid setting according to 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.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EINVAL
+
+ - input is not a valid spu setting or driver cannot handle SPU.
+
+
+
+.. _VIDEO_SET_SPU_PALETTE:
+
+VIDEO_SET_SPU_PALETTE
+=====================
+
+DESCRIPTION
+
+This ioctl sets the SPU color palette.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE
+,video_spu_palette_t *palette )
+
+PARAMETERS
+
+
+
+.. 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_SPU_PALETTE for this command.
+
+ - .. row 3
+
+ - video_spu_palette_t *palette
+
+ - SPU palette according to 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.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EINVAL
+
+ - input is not a valid palette or driver doesn’t handle SPU.
+
+
+
+.. _VIDEO_GET_NAVI:
+
+VIDEO_GET_NAVI
+==============
+
+DESCRIPTION
+
+This ioctl returns navigational information from the DVD stream. This is
+especially needed if an encoded stream has to be decoded by the
+hardware.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_GET_NAVI , video_navi_pack_t
+*navipack)
+
+PARAMETERS
+
+
+
+.. 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_NAVI for this command.
+
+ - .. row 3
+
+ - video_navi_pack_t *navipack
+
+ - PCI or DSI pack (private stream 2) according to 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.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EFAULT
+
+ - driver is not able to return navigational information
+
+
+
+.. _VIDEO_SET_ATTRIBUTES:
+
+VIDEO_SET_ATTRIBUTES
+====================
+
+DESCRIPTION
+
+This ioctl is intended for DVD playback and allows you to set certain
+information about the stream. Some hardware may not need this
+information, but the call also tells the hardware to prepare for DVD
+playback.
+
+SYNOPSIS
+
+int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE ,video_attributes_t
+vattr)
+
+PARAMETERS
+
+
+
+.. 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_ATTRIBUTE for this command.
+
+ - .. row 3
+
+ - video_attributes_t vattr
+
+ - video attributes according to 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.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EINVAL
+
+ - input is not a valid attribute setting.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video_h:
+
+*********************
+DVB Video Header File
+*********************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ../../video.h
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _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;
+
+
+.. _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;
+
+
+.. _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
+ __kernel_time_t timestamp;
+ union {
+ video_size_t size;
+ unsigned int frame_rate; /* in frames per 1000sec */
+ unsigned char vsync_field; /* unknown/odd/even/progressive */
+ } u;
+ };
+
+
+.. _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
+seleted 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.
+
+
+.. _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
+
+
+.. _video-system:
+
+video_system_t
+==============
+
+A call to VIDEO_SET_SYSTEM sets the desired video system for TV
+output. The following system types can be set:
+
+
+.. code-block:: c
+
+ typedef enum {
+ VIDEO_SYSTEM_PAL,
+ VIDEO_SYSTEM_NTSC,
+ VIDEO_SYSTEM_PALN,
+ VIDEO_SYSTEM_PALNc,
+ VIDEO_SYSTEM_PALM,
+ VIDEO_SYSTEM_NTSC60,
+ VIDEO_SYSTEM_PAL60,
+ VIDEO_SYSTEM_PALM60
+ } video_system_t;
+
+
+.. _video-highlight:
+
+struct video_highlight
+======================
+
+Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight
+information. The call expects the following format for that information:
+
+
+.. code-block:: c
+
+ typedef
+ struct video_highlight {
+ boolean active; /* 1=show highlight, 0=hide highlight */
+ uint8_t contrast1; /* 7- 4 Pattern pixel contrast */
+ /* 3- 0 Background pixel contrast */
+ uint8_t contrast2; /* 7- 4 Emphasis pixel-2 contrast */
+ /* 3- 0 Emphasis pixel-1 contrast */
+ uint8_t color1; /* 7- 4 Pattern pixel color */
+ /* 3- 0 Background pixel color */
+ uint8_t color2; /* 7- 4 Emphasis pixel-2 color */
+ /* 3- 0 Emphasis pixel-1 color */
+ uint32_t ypos; /* 23-22 auto action mode */
+ /* 21-12 start y */
+ /* 9- 0 end y */
+ uint32_t xpos; /* 23-22 button color number */
+ /* 21-12 start x */
+ /* 9- 0 end x */
+ } video_highlight_t;
+
+
+.. _video-spu:
+
+struct video_spu
+================
+
+Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according
+to the following format:
+
+
+.. code-block:: c
+
+ typedef
+ struct video_spu {
+ boolean active;
+ int stream_id;
+ } video_spu_t;
+
+
+.. _video-spu-palette:
+
+struct video_spu_palette
+========================
+
+The following structure is used to set the SPU palette by calling
+VIDEO_SPU_PALETTE:
+
+
+.. code-block:: c
+
+ typedef
+ struct video_spu_palette {
+ int length;
+ uint8_t *palette;
+ } video_spu_palette_t;
+
+
+.. _video-navi-pack:
+
+struct video_navi_pack
+======================
+
+In order to get the navigational data the following structure has to be
+passed to the ioctl VIDEO_GET_NAVI:
+
+
+.. code-block:: c
+
+ typedef
+ struct video_navi_pack {
+ int length; /* 0 ... 1024 */
+ uint8_t data[1024];
+ } video_navi_pack_t;
+
+
+.. _video-attributes-t:
+
+video_attributes_t
+==================
+
+The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES:
+
+
+.. code-block:: c
+
+ typedef uint16_t video_attributes_t;
+ /* bits: descr. */
+ /* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */
+ /* 13-12 TV system (0=525/60, 1=625/50) */
+ /* 11-10 Aspect ratio (0=4:3, 3=16:9) */
+ /* 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */
+ /* 7 line 21-1 data present in GOP (1=yes, 0=no) */
+ /* 6 line 21-2 data present in GOP (1=yes, 0=no) */
+ /* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */
+ /* 2 source letterboxed (1=yes, 0=no) */
+ /* 0 film/camera mode (0=camera, 1=film (625/50 only)) */
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_Intro:
+
+************
+Introduction
+************
+
+Currently, most analog and digital devices have a Infrared input for
+remote controllers. Each manufacturer has their own type of control. It
+is not rare for the same manufacturer to ship different types of
+controls, depending on the device.
+
+A Remote Controller interface is mapped as a normal evdev/input
+interface, just like a keyboard or a mouse. So, it uses all ioctls
+already defined for any other input devices.
+
+However, remove controllers are more flexible than a normal input
+device, as the IR receiver (and/or transmitter) can be used in
+conjunction with a wide variety of different IR remotes.
+
+In order to allow flexibility, the Remote Controller subsystem allows
+controlling the RC-specific attributes via
+:ref:`the sysfs class nodes <remote_controllers_sysfs_nodes>`.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_table_change:
+
+*******************************************
+Changing default Remote Controller mappings
+*******************************************
+
+The event interface provides two ioctls to be used against the
+/dev/input/event device, to allow changing the default keymapping.
+
+This program demonstrates how to replace the keymap tables.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ keytable.c
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_tables:
+
+************************
+Remote controller tables
+************************
+
+Unfortunately, for several years, there was no effort to create uniform
+IR keycodes for different devices. This caused the same IR keyname to be
+mapped completely differently on different IR devices. This resulted
+that the same IR keyname to be mapped completely different on different
+IR's. Due to that, V4L2 API now specifies a standard for mapping Media
+keys on IR.
+
+This standard should be used by both V4L/DVB drivers and userspace
+applications
+
+The modules register the remote as keyboard within the linux input
+layer. This means that the IR key strokes will look like normal keyboard
+key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event
+devices (CONFIG_INPUT_EVDEV) it is possible for applications to access
+the remote via /dev/input/event devices.
+
+
+.. _rc_standard_keymap:
+
+.. flat-table:: IR default keymapping
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Key code
+
+ - Meaning
+
+ - Key examples on IR
+
+ - .. row 2
+
+ - **Numeric keys**
+
+ - .. row 3
+
+ - ``KEY_0``
+
+ - Keyboard digit 0
+
+ - 0
+
+ - .. row 4
+
+ - ``KEY_1``
+
+ - Keyboard digit 1
+
+ - 1
+
+ - .. row 5
+
+ - ``KEY_2``
+
+ - Keyboard digit 2
+
+ - 2
+
+ - .. row 6
+
+ - ``KEY_3``
+
+ - Keyboard digit 3
+
+ - 3
+
+ - .. row 7
+
+ - ``KEY_4``
+
+ - Keyboard digit 4
+
+ - 4
+
+ - .. row 8
+
+ - ``KEY_5``
+
+ - Keyboard digit 5
+
+ - 5
+
+ - .. row 9
+
+ - ``KEY_6``
+
+ - Keyboard digit 6
+
+ - 6
+
+ - .. row 10
+
+ - ``KEY_7``
+
+ - Keyboard digit 7
+
+ - 7
+
+ - .. row 11
+
+ - ``KEY_8``
+
+ - Keyboard digit 8
+
+ - 8
+
+ - .. row 12
+
+ - ``KEY_9``
+
+ - Keyboard digit 9
+
+ - 9
+
+ - .. row 13
+
+ - **Movie play control**
+
+ - .. row 14
+
+ - ``KEY_FORWARD``
+
+ - Instantly advance in time
+
+ - >> / FORWARD
+
+ - .. row 15
+
+ - ``KEY_BACK``
+
+ - Instantly go back in time
+
+ - <<< / BACK
+
+ - .. row 16
+
+ - ``KEY_FASTFORWARD``
+
+ - Play movie faster
+
+ - >>> / FORWARD
+
+ - .. row 17
+
+ - ``KEY_REWIND``
+
+ - Play movie back
+
+ - REWIND / BACKWARD
+
+ - .. row 18
+
+ - ``KEY_NEXT``
+
+ - Select next chapter / sub-chapter / interval
+
+ - NEXT / SKIP
+
+ - .. row 19
+
+ - ``KEY_PREVIOUS``
+
+ - Select previous chapter / sub-chapter / interval
+
+ - << / PREV / PREVIOUS
+
+ - .. row 20
+
+ - ``KEY_AGAIN``
+
+ - Repeat the video or a video interval
+
+ - REPEAT / LOOP / RECALL
+
+ - .. row 21
+
+ - ``KEY_PAUSE``
+
+ - Pause sroweam
+
+ - PAUSE / FREEZE
+
+ - .. row 22
+
+ - ``KEY_PLAY``
+
+ - Play movie at the normal timeshift
+
+ - NORMAL TIMESHIFT / LIVE / >
+
+ - .. row 23
+
+ - ``KEY_PLAYPAUSE``
+
+ - Alternate between play and pause
+
+ - PLAY / PAUSE
+
+ - .. row 24
+
+ - ``KEY_STOP``
+
+ - Stop sroweam
+
+ - STOP
+
+ - .. row 25
+
+ - ``KEY_RECORD``
+
+ - Start/stop recording sroweam
+
+ - CAPTURE / REC / RECORD/PAUSE
+
+ - .. row 26
+
+ - ``KEY_CAMERA``
+
+ - Take a picture of the image
+
+ - CAMERA ICON / CAPTURE / SNAPSHOT
+
+ - .. row 27
+
+ - ``KEY_SHUFFLE``
+
+ - Enable shuffle mode
+
+ - SHUFFLE
+
+ - .. row 28
+
+ - ``KEY_TIME``
+
+ - Activate time shift mode
+
+ - TIME SHIFT
+
+ - .. row 29
+
+ - ``KEY_TITLE``
+
+ - Allow changing the chapter
+
+ - CHAPTER
+
+ - .. row 30
+
+ - ``KEY_SUBTITLE``
+
+ - Allow changing the subtitle
+
+ - SUBTITLE
+
+ - .. row 31
+
+ - **Image control**
+
+ - .. row 32
+
+ - ``KEY_BRIGHTNESSDOWN``
+
+ - Decrease Brightness
+
+ - BRIGHTNESS DECREASE
+
+ - .. row 33
+
+ - ``KEY_BRIGHTNESSUP``
+
+ - Increase Brightness
+
+ - BRIGHTNESS INCREASE
+
+ - .. row 34
+
+ - ``KEY_ANGLE``
+
+ - Switch video camera angle (on videos with more than one angle
+ stored)
+
+ - ANGLE / SWAP
+
+ - .. row 35
+
+ - ``KEY_EPG``
+
+ - Open the Elecrowonic Play Guide (EPG)
+
+ - EPG / GUIDE
+
+ - .. row 36
+
+ - ``KEY_TEXT``
+
+ - Activate/change closed caption mode
+
+ - CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
+
+ - .. row 37
+
+ - **Audio control**
+
+ - .. row 38
+
+ - ``KEY_AUDIO``
+
+ - Change audio source
+
+ - AUDIO SOURCE / AUDIO / MUSIC
+
+ - .. row 39
+
+ - ``KEY_MUTE``
+
+ - Mute/unmute audio
+
+ - MUTE / DEMUTE / UNMUTE
+
+ - .. row 40
+
+ - ``KEY_VOLUMEDOWN``
+
+ - Decrease volume
+
+ - VOLUME- / VOLUME DOWN
+
+ - .. row 41
+
+ - ``KEY_VOLUMEUP``
+
+ - Increase volume
+
+ - VOLUME+ / VOLUME UP
+
+ - .. row 42
+
+ - ``KEY_MODE``
+
+ - Change sound mode
+
+ - MONO/STEREO
+
+ - .. row 43
+
+ - ``KEY_LANGUAGE``
+
+ - Select Language
+
+ - 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
+
+ - .. row 44
+
+ - **Channel control**
+
+ - .. row 45
+
+ - ``KEY_CHANNEL``
+
+ - Go to the next favorite channel
+
+ - ALT / CHANNEL / CH SURFING / SURF / FAV
+
+ - .. row 46
+
+ - ``KEY_CHANNELDOWN``
+
+ - Decrease channel sequencially
+
+ - CHANNEL - / CHANNEL DOWN / DOWN
+
+ - .. row 47
+
+ - ``KEY_CHANNELUP``
+
+ - Increase channel sequencially
+
+ - CHANNEL + / CHANNEL UP / UP
+
+ - .. row 48
+
+ - ``KEY_DIGITS``
+
+ - Use more than one digit for channel
+
+ - PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
+
+ - .. row 49
+
+ - ``KEY_SEARCH``
+
+ - Start channel autoscan
+
+ - SCAN / AUTOSCAN
+
+ - .. row 50
+
+ - **Colored keys**
+
+ - .. row 51
+
+ - ``KEY_BLUE``
+
+ - IR Blue key
+
+ - BLUE
+
+ - .. row 52
+
+ - ``KEY_GREEN``
+
+ - IR Green Key
+
+ - GREEN
+
+ - .. row 53
+
+ - ``KEY_RED``
+
+ - IR Red key
+
+ - RED
+
+ - .. row 54
+
+ - ``KEY_YELLOW``
+
+ - IR Yellow key
+
+ - YELLOW
+
+ - .. row 55
+
+ - **Media selection**
+
+ - .. row 56
+
+ - ``KEY_CD``
+
+ - Change input source to Compact Disc
+
+ - CD
+
+ - .. row 57
+
+ - ``KEY_DVD``
+
+ - Change input to DVD
+
+ - DVD / DVD MENU
+
+ - .. row 58
+
+ - ``KEY_EJECTCLOSECD``
+
+ - Open/close the CD/DVD player
+
+ - -> ) / CLOSE / OPEN
+
+ - .. row 59
+
+ - ``KEY_MEDIA``
+
+ - Turn on/off Media application
+
+ - PC/TV / TURN ON/OFF APP
+
+ - .. row 60
+
+ - ``KEY_PC``
+
+ - Selects from TV to PC
+
+ - PC
+
+ - .. row 61
+
+ - ``KEY_RADIO``
+
+ - Put into AM/FM radio mode
+
+ - RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
+
+ - .. row 62
+
+ - ``KEY_TV``
+
+ - Select tv mode
+
+ - TV / LIVE TV
+
+ - .. row 63
+
+ - ``KEY_TV2``
+
+ - Select Cable mode
+
+ - AIR/CBL
+
+ - .. row 64
+
+ - ``KEY_VCR``
+
+ - Select VCR mode
+
+ - VCR MODE / DTR
+
+ - .. row 65
+
+ - ``KEY_VIDEO``
+
+ - Alternate between input modes
+
+ - SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
+
+ - .. row 66
+
+ - **Power control**
+
+ - .. row 67
+
+ - ``KEY_POWER``
+
+ - Turn on/off computer
+
+ - SYSTEM POWER / COMPUTER POWER
+
+ - .. row 68
+
+ - ``KEY_POWER2``
+
+ - Turn on/off application
+
+ - TV ON/OFF / POWER
+
+ - .. row 69
+
+ - ``KEY_SLEEP``
+
+ - Activate sleep timer
+
+ - SLEEP / SLEEP TIMER
+
+ - .. row 70
+
+ - ``KEY_SUSPEND``
+
+ - Put computer into suspend mode
+
+ - STANDBY / SUSPEND
+
+ - .. row 71
+
+ - **Window control**
+
+ - .. row 72
+
+ - ``KEY_CLEAR``
+
+ - Stop sroweam and return to default input video/audio
+
+ - CLEAR / RESET / BOSS KEY
+
+ - .. row 73
+
+ - ``KEY_CYCLEWINDOWS``
+
+ - Minimize windows and move to the next one
+
+ - ALT-TAB / MINIMIZE / DESKTOP
+
+ - .. row 74
+
+ - ``KEY_FAVORITES``
+
+ - Open the favorites sroweam window
+
+ - TV WALL / Favorites
+
+ - .. row 75
+
+ - ``KEY_MENU``
+
+ - Call application menu
+
+ - 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
+
+ - .. row 76
+
+ - ``KEY_NEW``
+
+ - Open/Close Picture in Picture
+
+ - PIP
+
+ - .. row 77
+
+ - ``KEY_OK``
+
+ - Send a confirmation code to application
+
+ - OK / ENTER / RETURN
+
+ - .. row 78
+
+ - ``KEY_SCREEN``
+
+ - Select screen aspect ratio
+
+ - 4:3 16:9 SELECT
+
+ - .. row 79
+
+ - ``KEY_ZOOM``
+
+ - Put device into zoom/full screen mode
+
+ - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
+
+ - .. row 80
+
+ - **Navigation keys**
+
+ - .. row 81
+
+ - ``KEY_ESC``
+
+ - Cancel current operation
+
+ - CANCEL / BACK
+
+ - .. row 82
+
+ - ``KEY_HELP``
+
+ - Open a Help window
+
+ - HELP
+
+ - .. row 83
+
+ - ``KEY_HOMEPAGE``
+
+ - Navigate to Homepage
+
+ - HOME
+
+ - .. row 84
+
+ - ``KEY_INFO``
+
+ - Open On Screen Display
+
+ - DISPLAY INFORMATION / OSD
+
+ - .. row 85
+
+ - ``KEY_WWW``
+
+ - Open the default browser
+
+ - WEB
+
+ - .. row 86
+
+ - ``KEY_UP``
+
+ - Up key
+
+ - UP
+
+ - .. row 87
+
+ - ``KEY_DOWN``
+
+ - Down key
+
+ - DOWN
+
+ - .. row 88
+
+ - ``KEY_LEFT``
+
+ - Left key
+
+ - LEFT
+
+ - .. row 89
+
+ - ``KEY_RIGHT``
+
+ - Right key
+
+ - RIGHT
+
+ - .. row 90
+
+ - **Miscellaneous keys**
+
+ - .. row 91
+
+ - ``KEY_DOT``
+
+ - Return a dot
+
+ - .
+
+ - .. row 92
+
+ - ``KEY_FN``
+
+ - Select a function
+
+ - FUNCTION
+
+
+It should be noted that, sometimes, there some fundamental missing keys
+at some cheaper IR's. Due to that, it is recommended to:
+
+
+.. _rc_keymap_notes:
+
+.. flat-table:: Notes
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - On simpler IR's, without separate channel keys, you need to map UP
+ as ``KEY_CHANNELUP``
+
+ - .. row 2
+
+ - On simpler IR's, without separate channel keys, you need to map
+ DOWN as ``KEY_CHANNELDOWN``
+
+ - .. row 3
+
+ - On simpler IR's, without separate volume keys, you need to map
+ LEFT as ``KEY_VOLUMEDOWN``
+
+ - .. row 4
+
+ - On simpler IR's, without separate volume keys, you need to map
+ RIGHT as ``KEY_VOLUMEUP``
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _app-pri:
+
+********************
+Application Priority
+********************
+
+When multiple applications share a device it may be desirable to assign
+them different priorities. Contrary to the traditional "rm -rf /" school
+of thought a video recording application could for example block other
+applications from changing video controls or switching the current TV
+channel. Another objective is to permit low priority applications
+working in background, which can be preempted by user controlled
+applications and automatically regain control of the device at a later
+time.
+
+Since these features cannot be implemented entirely in user space V4L2
+defines the :ref:`VIDIOC_G_PRIORITY <vidioc-g-priority>` and
+:ref:`VIDIOC_S_PRIORITY <vidioc-g-priority>` ioctls to request and
+query the access priority associate with a file descriptor. Opening a
+device assigns a medium priority, compatible with earlier versions of
+V4L2 and drivers not supporting these ioctls. Applications requiring a
+different priority will usually call ``VIDIOC_S_PRIORITY`` after
+verifying the device with the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl.
+
+Ioctls changing driver properties, such as
+:ref:`VIDIOC_S_INPUT <vidioc-g-input>`, return an EBUSY error code
+after another application obtained higher priority.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _async:
+
+****************
+Asynchronous I/O
+****************
+
+This method is not defined yet.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio:
+
+************************
+Audio Inputs and Outputs
+************************
+
+Audio inputs and outputs are physical connectors of a device. Video
+capture devices have inputs, output devices have outputs, zero or more
+each. Radio devices have no audio inputs or outputs. They have exactly
+one tuner which in fact *is* an audio source, but this API associates
+tuners with video inputs or outputs only, and radio devices have none of
+these. [1]_ A connector on a TV card to loop back the received audio
+signal to a sound card is not considered an audio output.
+
+Audio and video inputs and outputs are associated. Selecting a video
+source also selects an audio source. This is most evident when the video
+and audio source is a tuner. Further audio connectors can combine with
+more than one video input or output. Assumed two composite video inputs
+and two audio inputs exist, there may be up to four valid combinations.
+The relation of video and audio connectors is defined in the
+``audioset`` field of the respective struct
+:ref:`v4l2_input <v4l2-input>` or struct
+:ref:`v4l2_output <v4l2-output>`, where each bit represents the index
+number, starting at zero, of one audio input or output.
+
+To learn about the number and attributes of the available inputs and
+outputs applications can enumerate them with the
+:ref:`VIDIOC_ENUMAUDIO <vidioc-enumaudio>` and
+:ref:`VIDIOC_ENUMAUDOUT <vidioc-enumaudioout>` ioctl, respectively.
+The struct :ref:`v4l2_audio <v4l2-audio>` returned by the
+``VIDIOC_ENUMAUDIO`` ioctl also contains signal status information
+applicable when the current audio input is queried.
+
+The :ref:`VIDIOC_G_AUDIO <vidioc-g-audio>` and
+:ref:`VIDIOC_G_AUDOUT <vidioc-g-audioout>` ioctls report the current
+audio input and output, respectively. Note that, unlike
+:ref:`VIDIOC_G_INPUT <vidioc-g-input>` and
+:ref:`VIDIOC_G_OUTPUT <vidioc-g-output>` these ioctls return a
+structure as ``VIDIOC_ENUMAUDIO`` and ``VIDIOC_ENUMAUDOUT`` do, not just
+an index.
+
+To select an audio input and change its properties applications call the
+:ref:`VIDIOC_S_AUDIO <vidioc-g-audio>` ioctl. To select an audio
+output (which presently has no changeable properties) applications call
+the :ref:`VIDIOC_S_AUDOUT <vidioc-g-audioout>` ioctl.
+
+Drivers must implement all audio input ioctls when the device has
+multiple selectable audio inputs, all audio output ioctls when the
+device has multiple selectable audio outputs. When the device has any
+audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
+in the struct :ref:`v4l2_capability <v4l2-capability>` returned by
+the :ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl.
+
+
+.. code-block:: c
+
+ struct v4l2_audio audio;
+
+ memset(&audio, 0, sizeof(audio));
+
+ if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
+ perror("VIDIOC_G_AUDIO");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input: %s\\n", audio.name);
+
+
+.. code-block:: c
+
+ struct v4l2_audio audio;
+
+ memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
+
+ audio.index = 0;
+
+ if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
+ perror("VIDIOC_S_AUDIO");
+ exit(EXIT_FAILURE);
+ }
+
+.. [1]
+ Actually struct :ref:`v4l2_audio <v4l2-audio>` ought to have a
+ ``tuner`` field like struct :ref:`v4l2_input <v4l2-input>`, not
+ only making the API more consistent but also permitting radio devices
+ with multiple tuners.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+**********
+References
+**********
+
+
+.. _cea608:
+
+CEA 608-E
+=========
+
+
+:title: CEA-608-E R-2014 "Line 21 Data Services"
+
+:author: Consumer Electronics Association (http://www.ce.org)
+
+.. _en300294:
+
+EN 300 294
+==========
+
+
+:title: EN 300 294 "625-line television Wide Screen Signalling (WSS)"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _ets300231:
+
+ETS 300 231
+===========
+
+
+:title: ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _ets300706:
+
+ETS 300 706
+===========
+
+
+:title: ETS 300 706 "Enhanced Teletext specification"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _mpeg2part1:
+
+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"
+
+:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
+
+.. _mpeg2part2:
+
+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"
+
+:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
+
+.. _itu470:
+
+ITU BT.470
+==========
+
+
+:title: ITU-R Recommendation BT.470-6 "Conventional Television Systems"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu601:
+
+ITU BT.601
+==========
+
+
+:title: ITU-R Recommendation BT.601-5 "Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect Ratios"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu653:
+
+ITU BT.653
+==========
+
+
+:title: ITU-R Recommendation BT.653-3 "Teletext systems"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu709:
+
+ITU BT.709
+==========
+
+
+:title: ITU-R Recommendation BT.709-5 "Parameter values for the HDTV standards for production and international programme exchange"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu1119:
+
+ITU BT.1119
+===========
+
+
+:title: ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _jfif:
+
+JFIF
+====
+
+
+:title: JPEG File Interchange Format
+:subtitle: Version 1.02
+
+:author: Independent JPEG Group (http://www.ijg.org)
+
+.. _itu-t81:
+
+ITU-T.81
+========
+
+
+: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)
+
+.. _w3c-jpeg-jfif:
+
+W3C JPEG JFIF
+=============
+
+
+:title: JPEG JFIF
+
+:author: The World Wide Web Consortium (http://www.w3.org)
+
+.. _smpte12m:
+
+SMPTE 12M
+=========
+
+
+:title: SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte170m:
+
+SMPTE 170M
+==========
+
+
+:title: SMPTE 170M-1999 "Television - Composite Analog Video Signal - NTSC for Studio Applications"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte240m:
+
+SMPTE 240M
+==========
+
+
+:title: SMPTE 240M-1999 "Television - Signal Parameters - 1125-Line High-Definition Production"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte431:
+
+SMPTE RP 431-2
+==============
+
+
+:title: SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte2084:
+
+SMPTE ST 2084
+=============
+
+
+:title: SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _srgb:
+
+sRGB
+====
+
+
+:title: IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _sycc:
+
+sYCC
+====
+
+
+:title: IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _xvycc:
+
+xvYCC
+=====
+
+
+:title: IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video applications - xvYCC"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _adobergb:
+
+AdobeRGB
+========
+
+
+:title: Adobe© RGB (1998) Color Image Encoding Version 2005-05
+
+:author: Adobe Systems Incorporated (http://www.adobe.com)
+
+.. _oprgb:
+
+opRGB
+=====
+
+
+:title: IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _itu2020:
+
+ITU BT.2020
+===========
+
+
+:title: ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high definition television systems for production and international programme exchange"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _tech3213:
+
+EBU Tech 3213
+=============
+
+
+:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"
+
+:author: European Broadcast Union (http://www.ebu.ch)
+
+.. _iec62106:
+
+IEC 62106
+=========
+
+
+:title: Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _nrsc4:
+
+NRSC-4-B
+========
+
+
+:title: NRSC-4-B: United States RBDS Standard
+
+:author: National Radio Systems Committee (http://www.nrscstandards.org)
+
+.. _iso12232:
+
+ISO 12232:2006
+==============
+
+
+: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)
+
+.. _cea861:
+
+CEA-861-E
+=========
+
+
+:title: A DTV Profile for Uncompressed High Speed Digital Interfaces
+
+:author: Consumer Electronics Association (http://www.ce.org)
+
+.. _vesadmt:
+
+VESA DMT
+========
+
+
+:title: VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _vesaedid:
+
+EDID
+====
+
+
+:title: VESA Enhanced Extended Display Identification Data Standard
+:subtitle: Release A, Revision 2
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _hdcp:
+
+HDCP
+====
+
+
+:title: High-bandwidth Digital Content Protection System
+:subtitle: Revision 1.3
+
+:author: Digital Content Protection LLC (http://www.digital-cp.com)
+
+.. _hdmi:
+
+HDMI
+====
+
+
+:title: High-Definition Multimedia Interface
+:subtitle: Specification Version 1.4a
+
+:author: HDMI Licensing LLC (http://www.hdmi.org)
+
+.. _dp:
+
+DP
+==
+
+
+:title: VESA DisplayPort Standard
+:subtitle: Version 1, Revision 2
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _poynton:
+
+poynton
+=======
+
+
+:title: Digital Video and HDTV, Algorithms and Interfaces
+
+:author: Charles Poynton
+
+.. _colimg:
+
+colimg
+======
+
+
+:title: Color Imaging: Fundamentals and Applications
+
+:author: Erik Reinhard et al.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _buffer:
+
+*******
+Buffers
+*******
+
+A buffer contains data exchanged by application and driver using one of
+the Streaming I/O methods. In the multi-planar API, the data is held in
+planes, while the buffer structure acts as a container for the planes.
+Only pointers to buffers (planes) are exchanged, the data itself is not
+copied. These pointers, together with meta-information like timestamps
+or field parity, are stored in a struct :c:type:`struct v4l2_buffer`,
+argument to the :ref:`VIDIOC_QUERYBUF <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:`struct v4l2_buffer`,
+such as pointers and sizes for each plane, are stored in struct
+:c:type:`struct v4l2_plane` instead. In that case, struct
+:c:type:`struct v4l2_buffer` contains an array of plane structures.
+
+Dequeued video buffers come with timestamps. The driver decides at which
+part of the frame and with which clock the timestamp is taken. Please
+see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and
+``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
+are always valid and constant across all buffers during the whole video
+stream. Changes in these flags may take place as a side effect of
+:ref:`VIDIOC_S_INPUT <vidioc-g-input>` or
+:ref:`VIDIOC_S_OUTPUT <vidioc-g-output>` however. The
+``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on
+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.
+
+
+.. _v4l2-buffer:
+
+.. flat-table:: struct v4l2_buffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - Number of the buffer, set by the application except when calling
+ :ref:`VIDIOC_DQBUF <vidioc-qbuf>`, then it is set by the
+ driver. This field can range from zero to the number of buffers
+ allocated with the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl
+ (struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>`
+ ``count``), plus any buffers allocated with
+ :ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>` minus one.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the buffer, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` or struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
+ by the application. See :ref:`v4l2-buf-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``bytesused``
+
+ -
+ - The number of bytes occupied by the data in the buffer. It depends
+ 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
+ ``planes`` pointer is used instead.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - Flags set by the application or driver, see :ref:`buffer-flags`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``field``
+
+ -
+ - Indicates the field order of the image in the buffer, see
+ :ref:`v4l2-field`. This field is not used when the buffer
+ contains VBI data. Drivers must set it when ``type`` refers to a
+ capture stream, applications when it refers to an output stream.
+
+ - .. row 6
+
+ - struct timeval
+
+ - ``timestamp``
+
+ -
+ - For capture streams this is time when the first data byte was
+ captured, as returned by the :c:func:`clock_gettime()` function
+ for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
+ :ref:`buffer-flags`. For output streams the driver stores the
+ time at which the last data byte was actually sent out in the
+ ``timestamp`` field. This permits applications to monitor the
+ drift between the video and system clock. For output streams that
+ use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
+ in the timestamp which will be copied by the driver to the capture
+ stream.
+
+ - .. row 7
+
+ - struct :ref:`v4l2_timecode <v4l2-timecode>`
+
+ - ``timecode``
+
+ -
+ - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the
+ ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
+ structure contains a frame timecode. In
+ :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
+ bottom field contain the same timecode. Timecodes are intended to
+ help video editing and are typically recorded on video tapes, but
+ also embedded in compressed formats like MPEG. This field is
+ independent of the ``timestamp`` and ``sequence`` fields.
+
+ - .. row 8
+
+ - __u32
+
+ - ``sequence``
+
+ -
+ - Set by the driver, counting the frames (not fields!) in sequence.
+ This field is set for both input and output devices.
+
+ - .. row 9
+
+ - :cspan:`3`
+
+ In :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
+ bottom field have the same sequence number. The count starts at
+ zero and includes dropped or repeated frames. A dropped frame was
+ received by an input device but could not be stored due to lack of
+ free buffer space. A repeated frame was displayed again by an
+ output device because the application did not pass new data in
+ time.
+
+ Note this may count the frames received e.g. over USB, without
+ taking into account the frames dropped by the remote hardware due
+ to limited compression throughput or bus bandwidth. These devices
+ identify by not enumerating any video standards, see
+ :ref:`standard`.
+
+ - .. row 10
+
+ - __u32
+
+ - ``memory``
+
+ -
+ - This field must be set by applications and/or drivers in
+ accordance with the selected I/O method. See :ref:`v4l2-memory`
+
+ - .. row 11
+
+ - union
+
+ - ``m``
+
+ - .. row 12
+
+ -
+ - __u32
+
+ - ``offset``
+
+ - For the single-planar API and when ``memory`` is
+ ``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.
+ See :ref:`mmap` for details
+
+ - .. row 13
+
+ -
+ - unsigned long
+
+ - ``userptr``
+
+ - For the single-planar API and when ``memory`` is
+ ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
+ unsigned long type) in virtual memory, set by the application. See
+ :ref:`userp` for details.
+
+ - .. row 14
+
+ -
+ - struct v4l2_plane
+
+ - ``*planes``
+
+ - When using the multi-planar API, contains a userspace pointer to
+ an array of struct :ref:`v4l2_plane <v4l2-plane>`. The size of
+ the array should be put in the ``length`` field of this
+ :c:type:`struct v4l2_buffer` structure.
+
+ - .. row 15
+
+ -
+ - int
+
+ - ``fd``
+
+ - For the single-plane API and when ``memory`` is
+ ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
+ a DMABUF buffer.
+
+ - .. row 16
+
+ - __u32
+
+ - ``length``
+
+ -
+ - Size of the buffer (not the payload) in bytes for the
+ single-planar API. This is set by the driver based on the calls to
+ :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and/or
+ :ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>`. For the
+ multi-planar API the application sets this to the number of
+ elements in the ``planes`` array. The driver will fill in the
+ actual number of valid elements in that array.
+
+ - .. row 17
+
+ - __u32
+
+ - ``reserved2``
+
+ -
+ - A place holder for future extensions. Drivers and applications
+ must set this to 0.
+
+ - .. row 18
+
+ - __u32
+
+ - ``reserved``
+
+ -
+ - A place holder for future extensions. Drivers and applications
+ must set this to 0.
+
+
+
+.. _v4l2-plane:
+
+.. flat-table:: struct v4l2_plane
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``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. Note that the
+ actual image data starts at ``data_offset`` which may not be 0.
+
+ - .. row 2
+
+ - __u32
+
+ - ``length``
+
+ -
+ - Size in bytes of the plane (not its payload). This is set by the
+ driver based on the calls to
+ :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and/or
+ :ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>`.
+
+ - .. row 3
+
+ - union
+
+ - ``m``
+
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __u32
+
+ - ``mem_offset``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_MMAP``, this
+ is the value that should be passed to :ref:`mmap() <func-mmap>`,
+ similar to the ``offset`` field in struct
+ :ref:`v4l2_buffer <v4l2-buffer>`.
+
+ - .. row 5
+
+ -
+ - unsigned long
+
+ - ``userptr``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_USERPTR``,
+ this is a userspace pointer to the memory allocated for this plane
+ by an application.
+
+ - .. row 6
+
+ -
+ - int
+
+ - ``fd``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_DMABUF``,
+ this is a file descriptor associated with a DMABUF buffer, similar
+ to the ``fd`` field in struct :ref:`v4l2_buffer <v4l2-buffer>`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``data_offset``
+
+ -
+ - Offset in bytes to video data in the plane. Drivers must set this
+ field when ``type`` refers to a capture stream, applications when
+ it refers to an output stream. Note that data_offset is included
+ in ``bytesused``. So the size of the image in the plane is
+ ``bytesused``-``data_offset`` at offset ``data_offset`` from the
+ start of the plane.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved[11]``
+
+ -
+ - Reserved for future use. Should be zeroed by drivers and
+ applications.
+
+
+
+.. _v4l2-buf-type:
+
+.. flat-table:: enum v4l2_buf_type
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
+
+ - 1
+
+ - Buffer of a single-planar video capture stream, see
+ :ref:`capture`.
+
+ - .. row 2
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
+
+ - 9
+
+ - Buffer of a multi-planar video capture stream, see
+ :ref:`capture`.
+
+ - .. row 3
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+
+ - 2
+
+ - Buffer of a single-planar video output stream, see
+ :ref:`output`.
+
+ - .. row 4
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
+
+ - 10
+
+ - Buffer of a multi-planar video output stream, see :ref:`output`.
+
+ - .. row 5
+
+ - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
+
+ - 3
+
+ - Buffer for video overlay, see :ref:`overlay`.
+
+ - .. row 6
+
+ - ``V4L2_BUF_TYPE_VBI_CAPTURE``
+
+ - 4
+
+ - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
+
+ - .. row 7
+
+ - ``V4L2_BUF_TYPE_VBI_OUTPUT``
+
+ - 5
+
+ - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
+
+ - .. row 8
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
+
+ - 6
+
+ - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
+
+ - .. row 9
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
+
+ - 7
+
+ - Buffer of a sliced VBI output stream, see :ref:`sliced`.
+
+ - .. row 10
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
+
+ - 8
+
+ - Buffer for video output overlay (OSD), see :ref:`osd`.
+
+ - .. row 11
+
+ - ``V4L2_BUF_TYPE_SDR_CAPTURE``
+
+ - 11
+
+ - Buffer for Software Defined Radio (SDR) capture stream, see
+ :ref:`sdr`.
+
+ - .. row 12
+
+ - ``V4L2_BUF_TYPE_SDR_OUTPUT``
+
+ - 12
+
+ - Buffer for Software Defined Radio (SDR) output stream, see
+ :ref:`sdr`.
+
+
+
+.. _buffer-flags:
+
+.. flat-table:: Buffer Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BUF_FLAG_MAPPED``
+
+ - 0x00000001
+
+ - The buffer resides in device memory and has been mapped into the
+ application's address space, see :ref:`mmap` for details.
+ Drivers set or clear this flag when the
+ :ref:`VIDIOC_QUERYBUF <vidioc-querybuf>`,
+ :ref:`VIDIOC_QBUF <vidioc-qbuf>` or
+ :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl is called. Set by the
+ driver.
+
+ - .. row 2
+
+ - ``V4L2_BUF_FLAG_QUEUED``
+
+ - 0x00000002
+
+ - Internally drivers maintain two buffer queues, an incoming and
+ outgoing queue. When this flag is set, the buffer is currently on
+ the incoming queue. It automatically moves to the outgoing queue
+ after the buffer has been filled (capture devices) or displayed
+ (output devices). Drivers set or clear this flag when the
+ ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
+ the ``VIDIOC_QBUF``\ ioctl it is always set and after
+ ``VIDIOC_DQBUF`` always cleared.
+
+ - .. row 3
+
+ - ``V4L2_BUF_FLAG_DONE``
+
+ - 0x00000004
+
+ - When this flag is set, the buffer is currently on the outgoing
+ queue, ready to be dequeued from the driver. Drivers set or clear
+ this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
+ calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
+ cleared. Of course a buffer cannot be on both queues at the same
+ time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
+ are mutually exclusive. They can be both cleared however, then the
+ buffer is in "dequeued" state, in the application domain so to
+ say.
+
+ - .. row 4
+
+ - ``V4L2_BUF_FLAG_ERROR``
+
+ - 0x00000040
+
+ - When this flag is set, the buffer has been dequeued successfully,
+ although the data might have been corrupted. This is recoverable,
+ streaming may continue as normal and the buffer may be reused
+ normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
+ called.
+
+ - .. row 5
+
+ - ``V4L2_BUF_FLAG_KEYFRAME``
+
+ - 0x00000008
+
+ - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
+ ioctl. It may be set by video capture devices when the buffer
+ contains a compressed image which is a key frame (or field), i. e.
+ can be decompressed on its own. Also known as an I-frame.
+ Applications can set this bit when ``type`` refers to an output
+ stream.
+
+ - .. row 6
+
+ - ``V4L2_BUF_FLAG_PFRAME``
+
+ - 0x00000010
+
+ - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
+ or fields which contain only differences to a previous key frame.
+ Applications can set this bit when ``type`` refers to an output
+ stream.
+
+ - .. row 7
+
+ - ``V4L2_BUF_FLAG_BFRAME``
+
+ - 0x00000020
+
+ - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
+ predicted frame or field which contains only the differences
+ between the current frame and both the preceding and following key
+ frames to specify its content. Applications can set this bit when
+ ``type`` refers to an output stream.
+
+ - .. row 8
+
+ - ``V4L2_BUF_FLAG_TIMECODE``
+
+ - 0x00000100
+
+ - The ``timecode`` field is valid. Drivers set or clear this flag
+ when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
+ this bit and the corresponding ``timecode`` structure when
+ ``type`` refers to an output stream.
+
+ - .. row 9
+
+ - ``V4L2_BUF_FLAG_PREPARED``
+
+ - 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 <vidioc-querybuf>`,
+ :ref:`VIDIOC_PREPARE_BUF <vidioc-qbuf>`,
+ :ref:`VIDIOC_QBUF <vidioc-qbuf>` or
+ :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl is called.
+
+ - .. row 10
+
+ - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
+
+ - 0x00000800
+
+ - Caches do not have to be invalidated for this buffer. Typically
+ 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.
+
+ - .. row 11
+
+ - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
+
+ - 0x00001000
+
+ - 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.
+
+ - .. row 12
+
+ - ``V4L2_BUF_FLAG_LAST``
+
+ - 0x00100000
+
+ - Last buffer produced by the hardware. mem2mem codec drivers set
+ this flag on the capture queue for the last buffer when the
+ :ref:`VIDIOC_QUERYBUF <vidioc-querybuf>` or
+ :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
+ :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl will not block anymore,
+ but return an EPIPE error code.
+
+ - .. row 13
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
+
+ - 0x0000e000
+
+ - Mask for timestamp types below. To test the timestamp type, mask
+ out bits not belonging to timestamp type by performing a logical
+ and operation with buffer flags and timestamp mask.
+
+ - .. row 14
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
+
+ - 0x00000000
+
+ - Unknown timestamp type. This type is used by drivers before Linux
+ 3.9 and may be either monotonic (see below) or realtime (wall
+ clock). Monotonic clock has been favoured in embedded systems
+ whereas most of the drivers use the realtime clock. Either kinds
+ of timestamps are available in user space via
+ :c:func:`clock_gettime(2)` using clock IDs ``CLOCK_MONOTONIC``
+ and ``CLOCK_REALTIME``, respectively.
+
+ - .. row 15
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
+
+ - 0x00002000
+
+ - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
+ clock. To access the same clock outside V4L2, use
+ :c:func:`clock_gettime(2)`.
+
+ - .. row 16
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
+
+ - 0x00004000
+
+ - The CAPTURE buffer timestamp has been taken from the corresponding
+ OUTPUT buffer. This flag applies only to mem2mem devices.
+
+ - .. row 17
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
+
+ - 0x00070000
+
+ - Mask for timestamp sources below. The timestamp source defines the
+ point of time the timestamp is taken in relation to the frame.
+ Logical 'and' operation between the ``flags`` field and
+ ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
+ timestamp source. Applications must set the timestamp source when
+ ``type`` refers to an output stream and
+ ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
+
+ - .. row 18
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
+
+ - 0x00000000
+
+ - End Of Frame. The buffer timestamp has been taken when the last
+ pixel of the frame has been received or the last pixel of the
+ frame has been transmitted. In practice, software generated
+ timestamps will typically be read from the clock a small amount of
+ time after the last pixel has been received or transmitten,
+ depending on the system and other activity in it.
+
+ - .. row 19
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
+
+ - 0x00010000
+
+ - Start Of Exposure. The buffer timestamp has been taken when the
+ exposure of the frame has begun. This is only valid for the
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
+
+
+
+.. _v4l2-memory:
+
+.. flat-table:: enum v4l2_memory
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_MEMORY_MMAP``
+
+ - 1
+
+ - The buffer is used for :ref:`memory mapping <mmap>` I/O.
+
+ - .. row 2
+
+ - ``V4L2_MEMORY_USERPTR``
+
+ - 2
+
+ - The buffer is used for :ref:`user pointer <userp>` I/O.
+
+ - .. row 3
+
+ - ``V4L2_MEMORY_OVERLAY``
+
+ - 3
+
+ - [to do]
+
+ - .. row 4
+
+ - ``V4L2_MEMORY_DMABUF``
+
+ - 4
+
+ - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
+
+
+
+Timecodes
+=========
+
+The :c:type:`struct v4l2_timecode` structure is designed to hold a
+:ref:`smpte12m` or similar timecode. (struct
+:c:type:`struct timeval` timestamps are stored in struct
+:ref:`v4l2_buffer <v4l2-buffer>` field ``timestamp``.)
+
+
+.. _v4l2-timecode:
+
+.. flat-table:: struct v4l2_timecode
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Frame rate the timecodes are based on, see :ref:`timecode-type`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ - Timecode flags, see :ref:`timecode-flags`.
+
+ - .. row 3
+
+ - __u8
+
+ - ``frames``
+
+ - Frame count, 0 ... 23/24/29/49/59, depending on the type of
+ timecode.
+
+ - .. row 4
+
+ - __u8
+
+ - ``seconds``
+
+ - Seconds count, 0 ... 59. This is a binary, not BCD number.
+
+ - .. row 5
+
+ - __u8
+
+ - ``minutes``
+
+ - Minutes count, 0 ... 59. This is a binary, not BCD number.
+
+ - .. row 6
+
+ - __u8
+
+ - ``hours``
+
+ - Hours count, 0 ... 29. This is a binary, not BCD number.
+
+ - .. row 7
+
+ - __u8
+
+ - ``userbits``\ [4]
+
+ - The "user group" bits from the timecode.
+
+
+
+.. _timecode-type:
+
+.. flat-table:: Timecode Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TC_TYPE_24FPS``
+
+ - 1
+
+ - 24 frames per second, i. e. film.
+
+ - .. row 2
+
+ - ``V4L2_TC_TYPE_25FPS``
+
+ - 2
+
+ - 25 frames per second, i. e. PAL or SECAM video.
+
+ - .. row 3
+
+ - ``V4L2_TC_TYPE_30FPS``
+
+ - 3
+
+ - 30 frames per second, i. e. NTSC video.
+
+ - .. row 4
+
+ - ``V4L2_TC_TYPE_50FPS``
+
+ - 4
+
+ -
+
+ - .. row 5
+
+ - ``V4L2_TC_TYPE_60FPS``
+
+ - 5
+
+ -
+
+
+
+.. _timecode-flags:
+
+.. flat-table:: Timecode Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TC_FLAG_DROPFRAME``
+
+ - 0x0001
+
+ - Indicates "drop frame" semantics for counting frames in 29.97 fps
+ material. When set, frame numbers 0 and 1 at the start of each
+ minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
+ count.
+
+ - .. row 2
+
+ - ``V4L2_TC_FLAG_COLORFRAME``
+
+ - 0x0002
+
+ - The "color frame" flag.
+
+ - .. row 3
+
+ - ``V4L2_TC_USERBITS_field``
+
+ - 0x000C
+
+ - Field mask for the "binary group flags".
+
+ - .. row 4
+
+ - ``V4L2_TC_USERBITS_USERDEFINED``
+
+ - 0x0000
+
+ - Unspecified format.
+
+ - .. row 5
+
+ - ``V4L2_TC_USERBITS_8BITCHARS``
+
+ - 0x0008
+
+ - 8-bit ISO characters.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _capture-example:
+
+*********************
+Video Capture Example
+*********************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ capture.c
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: media/v4l/capture.c
+=========================
+
+.. code-block:: c
+
+ /*
+ * V4L2 video capture example
+ *
+ * This program can be used and distributed without restrictions.
+ *
+ * This program is provided with the V4L2 API
+ * see https://linuxtv.org/docs.php for more information
+ */
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <assert.h>
+
+ #include <getopt.h> /* getopt_long() */
+
+ #include <fcntl.h> /* low-level i/o */
+ #include <unistd.h>
+ #include <errno.h>
+ #include <sys/stat.h>
+ #include <sys/types.h>
+ #include <sys/time.h>
+ #include <sys/mman.h>
+ #include <sys/ioctl.h>
+
+ #include <linux/videodev2.h>
+
+ #define CLEAR(x) memset(&(x), 0, sizeof(x))
+
+ enum io_method {
+ IO_METHOD_READ,
+ IO_METHOD_MMAP,
+ IO_METHOD_USERPTR,
+ };
+
+ struct buffer {
+ void *start;
+ size_t length;
+ };
+
+ static char *dev_name;
+ static enum io_method io = IO_METHOD_MMAP;
+ static int fd = -1;
+ struct buffer *buffers;
+ static unsigned int n_buffers;
+ static int out_buf;
+ static int force_format;
+ static int frame_count = 70;
+
+ static void errno_exit(const char *s)
+ {
+ fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+
+ static int xioctl(int fh, int request, void *arg)
+ {
+ int r;
+
+ do {
+ r = ioctl(fh, request, arg);
+ } while (-1 == r && EINTR == errno);
+
+ return r;
+ }
+
+ static void process_image(const void *p, int size)
+ {
+ if (out_buf)
+ fwrite(p, size, 1, stdout);
+
+ fflush(stderr);
+ fprintf(stderr, ".");
+ fflush(stdout);
+ }
+
+ static int read_frame(void)
+ {
+ struct v4l2_buffer buf;
+ unsigned int i;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("read");
+ }
+ }
+
+ process_image(buffers[0].start, buffers[0].length);
+ break;
+
+ case IO_METHOD_MMAP:
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+
+ if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("VIDIOC_DQBUF");
+ }
+ }
+
+ assert(buf.index < n_buffers);
+
+ process_image(buffers[buf.index].start, buf.bytesused);
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ break;
+
+ case IO_METHOD_USERPTR:
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_USERPTR;
+
+ if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("VIDIOC_DQBUF");
+ }
+ }
+
+ for (i = 0; i < n_buffers; ++i)
+ if (buf.m.userptr == (unsigned long)buffers[i].start
+ && buf.length == buffers[i].length)
+ break;
+
+ assert(i < n_buffers);
+
+ process_image((void *)buf.m.userptr, buf.bytesused);
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ break;
+ }
+
+ return 1;
+ }
+
+ static void mainloop(void)
+ {
+ unsigned int count;
+
+ count = frame_count;
+
+ while (count-- > 0) {
+ for (;;) {
+ fd_set fds;
+ struct timeval tv;
+ int r;
+
+ FD_ZERO(&fds);
+ FD_SET(fd, &fds);
+
+ /* Timeout. */
+ tv.tv_sec = 2;
+ tv.tv_usec = 0;
+
+ r = select(fd + 1, &fds, NULL, NULL, &tv);
+
+ if (-1 == r) {
+ if (EINTR == errno)
+ continue;
+ errno_exit("select");
+ }
+
+ if (0 == r) {
+ fprintf(stderr, "select timeout\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ if (read_frame())
+ break;
+ /* EAGAIN - continue select loop. */
+ }
+ }
+ }
+
+ static void stop_capturing(void)
+ {
+ enum v4l2_buf_type type;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ /* Nothing to do. */
+ break;
+
+ case IO_METHOD_MMAP:
+ case IO_METHOD_USERPTR:
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type))
+ errno_exit("VIDIOC_STREAMOFF");
+ break;
+ }
+ }
+
+ static void start_capturing(void)
+ {
+ unsigned int i;
+ enum v4l2_buf_type type;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ /* Nothing to do. */
+ break;
+
+ case IO_METHOD_MMAP:
+ for (i = 0; i < n_buffers; ++i) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = i;
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
+ errno_exit("VIDIOC_STREAMON");
+ break;
+
+ case IO_METHOD_USERPTR:
+ for (i = 0; i < n_buffers; ++i) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_USERPTR;
+ buf.index = i;
+ buf.m.userptr = (unsigned long)buffers[i].start;
+ buf.length = buffers[i].length;
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
+ errno_exit("VIDIOC_STREAMON");
+ break;
+ }
+ }
+
+ static void uninit_device(void)
+ {
+ unsigned int i;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ free(buffers[0].start);
+ break;
+
+ case IO_METHOD_MMAP:
+ for (i = 0; i < n_buffers; ++i)
+ if (-1 == munmap(buffers[i].start, buffers[i].length))
+ errno_exit("munmap");
+ break;
+
+ case IO_METHOD_USERPTR:
+ for (i = 0; i < n_buffers; ++i)
+ free(buffers[i].start);
+ break;
+ }
+
+ free(buffers);
+ }
+
+ static void init_read(unsigned int buffer_size)
+ {
+ buffers = calloc(1, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers[0].length = buffer_size;
+ buffers[0].start = malloc(buffer_size);
+
+ if (!buffers[0].start) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ static void init_mmap(void)
+ {
+ struct v4l2_requestbuffers req;
+
+ CLEAR(req);
+
+ req.count = 4;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_MMAP;
+
+ if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s does not support "
+ "memory mappingn", dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_REQBUFS");
+ }
+ }
+
+ if (req.count < 2) {
+ fprintf(stderr, "Insufficient buffer memory on %s\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(req.count, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = n_buffers;
+
+ if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf))
+ errno_exit("VIDIOC_QUERYBUF");
+
+ buffers[n_buffers].length = buf.length;
+ buffers[n_buffers].start =
+ mmap(NULL /* start anywhere */,
+ buf.length,
+ PROT_READ | PROT_WRITE /* required */,
+ MAP_SHARED /* recommended */,
+ fd, buf.m.offset);
+
+ if (MAP_FAILED == buffers[n_buffers].start)
+ errno_exit("mmap");
+ }
+ }
+
+ static void init_userp(unsigned int buffer_size)
+ {
+ struct v4l2_requestbuffers req;
+
+ CLEAR(req);
+
+ req.count = 4;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_USERPTR;
+
+ if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s does not support "
+ "user pointer i/on", dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_REQBUFS");
+ }
+ }
+
+ buffers = calloc(4, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ for (n_buffers = 0; n_buffers < 4; ++n_buffers) {
+ buffers[n_buffers].length = buffer_size;
+ buffers[n_buffers].start = malloc(buffer_size);
+
+ if (!buffers[n_buffers].start) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+ }
+ }
+
+ static void init_device(void)
+ {
+ struct v4l2_capability cap;
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+ struct v4l2_format fmt;
+ unsigned int min;
+
+ if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s is no V4L2 device\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_QUERYCAP");
+ }
+ }
+
+ if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) {
+ fprintf(stderr, "%s is no video capture device\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ switch (io) {
+ case IO_METHOD_READ:
+ if (!(cap.capabilities & V4L2_CAP_READWRITE)) {
+ fprintf(stderr, "%s does not support read i/o\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+ break;
+
+ case IO_METHOD_MMAP:
+ case IO_METHOD_USERPTR:
+ if (!(cap.capabilities & V4L2_CAP_STREAMING)) {
+ fprintf(stderr, "%s does not support streaming i/o\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+ break;
+ }
+
+
+ /* Select video input, video standard and tune here. */
+
+
+ CLEAR(cropcap);
+
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) {
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ crop.c = cropcap.defrect; /* reset to default */
+
+ if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) {
+ switch (errno) {
+ case EINVAL:
+ /* Cropping not supported. */
+ break;
+ default:
+ /* Errors ignored. */
+ break;
+ }
+ }
+ } else {
+ /* Errors ignored. */
+ }
+
+
+ CLEAR(fmt);
+
+ fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (force_format) {
+ fmt.fmt.pix.width = 640;
+ fmt.fmt.pix.height = 480;
+ fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
+ fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
+
+ if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt))
+ errno_exit("VIDIOC_S_FMT");
+
+ /* Note VIDIOC_S_FMT may change width and height. */
+ } else {
+ /* Preserve original settings as set by v4l2-ctl for example */
+ if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt))
+ errno_exit("VIDIOC_G_FMT");
+ }
+
+ /* Buggy driver paranoia. */
+ min = fmt.fmt.pix.width * 2;
+ if (fmt.fmt.pix.bytesperline < min)
+ fmt.fmt.pix.bytesperline = min;
+ min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
+ if (fmt.fmt.pix.sizeimage < min)
+ fmt.fmt.pix.sizeimage = min;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ init_read(fmt.fmt.pix.sizeimage);
+ break;
+
+ case IO_METHOD_MMAP:
+ init_mmap();
+ break;
+
+ case IO_METHOD_USERPTR:
+ init_userp(fmt.fmt.pix.sizeimage);
+ break;
+ }
+ }
+
+ static void close_device(void)
+ {
+ if (-1 == close(fd))
+ errno_exit("close");
+
+ fd = -1;
+ }
+
+ static void open_device(void)
+ {
+ struct stat st;
+
+ if (-1 == stat(dev_name, &st)) {
+ fprintf(stderr, "Cannot identify '%s': %d, %s\\n",
+ dev_name, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+
+ if (!S_ISCHR(st.st_mode)) {
+ fprintf(stderr, "%s is no devicen", dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
+
+ if (-1 == fd) {
+ fprintf(stderr, "Cannot open '%s': %d, %s\\n",
+ dev_name, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ 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"
+ "",
+ argv[0], dev_name, frame_count);
+ }
+
+ static const char short_options[] = "d:hmruofc:";
+
+ static const struct option
+ long_options[] = {
+ { "device", required_argument, NULL, 'd' },
+ { "help", no_argument, NULL, 'h' },
+ { "mmap", no_argument, NULL, 'm' },
+ { "read", no_argument, NULL, 'r' },
+ { "userp", no_argument, NULL, 'u' },
+ { "output", no_argument, NULL, 'o' },
+ { "format", no_argument, NULL, 'f' },
+ { "count", required_argument, NULL, 'c' },
+ { 0, 0, 0, 0 }
+ };
+
+ int main(int argc, char **argv)
+ {
+ dev_name = "/dev/video0";
+
+ for (;;) {
+ int idx;
+ int c;
+
+ c = getopt_long(argc, argv,
+ short_options, long_options, &idx);
+
+ if (-1 == c)
+ break;
+
+ switch (c) {
+ case 0: /* getopt_long() flag */
+ break;
+
+ case 'd':
+ dev_name = optarg;
+ break;
+
+ case 'h':
+ usage(stdout, argc, argv);
+ exit(EXIT_SUCCESS);
+
+ case 'm':
+ io = IO_METHOD_MMAP;
+ break;
+
+ case 'r':
+ io = IO_METHOD_READ;
+ break;
+
+ case 'u':
+ io = IO_METHOD_USERPTR;
+ break;
+
+ case 'o':
+ out_buf++;
+ break;
+
+ case 'f':
+ force_format++;
+ break;
+
+ case 'c':
+ errno = 0;
+ frame_count = strtol(optarg, NULL, 0);
+ if (errno)
+ errno_exit(optarg);
+ break;
+
+ default:
+ usage(stderr, argc, argv);
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ open_device();
+ init_device();
+ start_capturing();
+ mainloop();
+ stop_capturing();
+ uninit_device();
+ close_device();
+ fprintf(stderr, "\\n");
+ return 0;
+ }
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _colorspaces:
+
+***********
+Colorspaces
+***********
+
+'Color' is a very complex concept and depends on physics, chemistry and
+biology. Just because you have three numbers that describe the 'red',
+'green' and 'blue' components of the color of a pixel does not mean that
+you can accurately display that color. A colorspace defines what it
+actually *means* to have an RGB value of e.g. (255, 0, 0). That is,
+which color should be reproduced on the screen in a perfectly calibrated
+environment.
+
+In order to do that we first need to have a good definition of color,
+i.e. some way to uniquely and unambiguously define a color so that
+someone else can reproduce it. Human color vision is trichromatic since
+the human eye has color receptors that are sensitive to three different
+wavelengths of light. Hence the need to use three numbers to describe
+color. Be glad you are not a mantis shrimp as those are sensitive to 12
+different wavelengths, so instead of RGB we would be using the
+ABCDEFGHIJKL colorspace...
+
+Color exists only in the eye and brain and is the result of how strongly
+color receptors are stimulated. This is based on the Spectral Power
+Distribution (SPD) which is a graph showing the intensity (radiant
+power) of the light at wavelengths covering the visible spectrum as it
+enters the eye. The science of colorimetry is about the relationship
+between the SPD and color as perceived by the human brain.
+
+Since the human eye has only three color receptors it is perfectly
+possible that different SPDs will result in the same stimulation of
+those receptors and are perceived as the same color, even though the SPD
+of the light is different.
+
+In the 1920s experiments were devised to determine the relationship
+between SPDs and the perceived color and that resulted in the CIE 1931
+standard that defines spectral weighting functions that model the
+perception of color. Specifically that standard defines functions that
+can take an SPD and calculate the stimulus for each color receptor.
+After some further mathematical transforms these stimuli are known as
+the *CIE XYZ tristimulus* values and these X, Y and Z values describe a
+color as perceived by a human unambiguously. These X, Y and Z values are
+all in the range [0…1].
+
+The Y value in the CIE XYZ colorspace corresponds to luminance. Often
+the CIE XYZ colorspace is transformed to the normalized CIE xyY
+colorspace:
+
+x = X / (X + Y + Z)
+
+y = Y / (X + Y + Z)
+
+The x and y values are the chromaticity coordinates and can be used to
+define a color without the luminance component Y. It is very confusing
+to have such similar names for these colorspaces. Just be aware that if
+colors are specified with lower case 'x' and 'y', then the CIE xyY
+colorspace is used. Upper case 'X' and 'Y' refer to the CIE XYZ
+colorspace. Also, y has nothing to do with luminance. Together x and y
+specify a color, and Y the luminance. That is really all you need to
+remember from a practical point of view. At the end of this section you
+will find reading resources that go into much more detail if you are
+interested.
+
+A monitor or TV will reproduce colors by emitting light at three
+different wavelengths, the combination of which will stimulate the color
+receptors in the eye and thus cause the perception of color.
+Historically these wavelengths were defined by the red, green and blue
+phosphors used in the displays. These *color primaries* are part of what
+defines a colorspace.
+
+Different display devices will have different primaries and some
+primaries are more suitable for some display technologies than others.
+This has resulted in a variety of colorspaces that are used for
+different display technologies or uses. To define a colorspace you need
+to define the three color primaries (these are typically defined as x, y
+chromaticity coordinates from the CIE xyY colorspace) but also the white
+reference: that is the color obtained when all three primaries are at
+maximum power. This determines the relative power or energy of the
+primaries. This is usually chosen to be close to daylight which has been
+defined as the CIE D65 Illuminant.
+
+To recapitulate: the CIE XYZ colorspace uniquely identifies colors.
+Other colorspaces are defined by three chromaticity coordinates defined
+in the CIE xyY colorspace. Based on those a 3x3 matrix can be
+constructed that transforms CIE XYZ colors to colors in the new
+colorspace.
+
+Both the CIE XYZ and the RGB colorspace that are derived from the
+specific chromaticity primaries are linear colorspaces. But neither the
+eye, nor display technology is linear. Doubling the values of all
+components in the linear colorspace will not be perceived as twice the
+intensity of the color. So each colorspace also defines a transfer
+function that takes a linear color component value and transforms it to
+the non-linear component value, which is a closer match to the
+non-linear performance of both the eye and displays. Linear component
+values are denoted RGB, non-linear are denoted as R'G'B'. In general
+colors used in graphics are all R'G'B', except in openGL which uses
+linear RGB. Special care should be taken when dealing with openGL to
+provide linear RGB colors or to use the built-in openGL support to apply
+the inverse transfer function.
+
+The final piece that defines a colorspace is a function that transforms
+non-linear R'G'B' to non-linear Y'CbCr. This function is determined by
+the so-called luma coefficients. There may be multiple possible Y'CbCr
+encodings allowed for the same colorspace. Many encodings of color
+prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the
+human eye is more sensitive to differences in luminance than in color
+this encoding allows one to reduce the amount of color information
+compared to the luma data. Note that the luma (Y') is unrelated to the Y
+in the CIE XYZ colorspace. Also note that Y'CbCr is often called YCbCr
+or YUV even though these are strictly speaking wrong.
+
+Sometimes people confuse Y'CbCr as being a colorspace. This is not
+correct, it is just an encoding of an R'G'B' color into luma and chroma
+values. The underlying colorspace that is associated with the R'G'B'
+color is also associated with the Y'CbCr color.
+
+The final step is how the RGB, R'G'B' or Y'CbCr values are quantized.
+The CIE XYZ colorspace where X, Y and Z are in the range [0…1] describes
+all colors that humans can perceive, but the transform to another
+colorspace will produce colors that are outside the [0…1] range. Once
+clamped to the [0…1] range those colors can no longer be reproduced in
+that colorspace. This clamping is what reduces the extent or gamut of
+the colorspace. How the range of [0…1] is translated to integer values
+in the range of [0…255] (or higher, depending on the color depth) is
+called the quantization. This is *not* part of the colorspace
+definition. In practice RGB or R'G'B' values are full range, i.e. they
+use the full [0…255] range. Y'CbCr values on the other hand are limited
+range with Y' using [16…235] and Cb and Cr using [16…240].
+
+Unfortunately, in some cases limited range RGB is also used where the
+components use the range [16…235]. And full range Y'CbCr also exists
+using the [0…255] range.
+
+In order to correctly interpret a color you need to know the
+quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr
+encoding and the colorspace. From that information you can calculate the
+corresponding CIE XYZ color and map that again to whatever colorspace
+your display device uses.
+
+The colorspace definition itself consists of the three chromaticity
+primaries, the white reference chromaticity, a transfer function and the
+luma coefficients needed to transform R'G'B' to Y'CbCr. While some
+colorspace standards correctly define all four, quite often the
+colorspace standard only defines some, and you have to rely on other
+standards for the missing pieces. The fact that colorspaces are often a
+mix of different standards also led to very confusing naming conventions
+where the name of a standard was used to name a colorspace when in fact
+that standard was part of various other colorspaces as well.
+
+If you want to read more about colors and colorspaces, then the
+following resources are useful: :ref:`poynton` is a good practical
+book for video engineers, :ref:`colimg` has a much broader scope and
+describes many more aspects of color (physics, chemistry, biology,
+etc.). The
+`http://www.brucelindbloom.com <http://www.brucelindbloom.com>`__
+website is an excellent resource, especially with respect to the
+mathematics behind colorspace conversions. The wikipedia
+`CIE 1931 colorspace <http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space>`__
+article is also very useful.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _common-defs:
+
+******************************************************
+Common definitions for V4L2 and V4L2 subdev interfaces
+******************************************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ selections-common
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _common:
+
+###################
+Common API Elements
+###################
+Programming a V4L2 device consists of these steps:
+
+- Opening the device
+
+- Changing device properties, selecting a video and audio input, video
+ standard, picture brightness a. o.
+
+- Negotiating a data format
+
+- Negotiating an input/output method
+
+- The actual input/output loop
+
+- Closing the device
+
+In practice most steps are optional and can be executed out of order. It
+depends on the V4L2 device type, you can read about the details in
+:ref:`devices`. In this chapter we will discuss the basic concepts
+applicable to all devices.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ open
+ querycap
+ app-pri
+ video
+ audio
+ tuner
+ standard
+ dv-timings
+ controls
+ format
+ planar-apis
+ crop
+ selection-api
+ streaming-par
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _compat:
+
+*******
+Changes
+*******
+
+The following chapters document the evolution of the V4L2 API, errata or
+extensions. They are also intended to help application and driver
+writers to port or update their code.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ diff-v4l
+ hist-v4l2
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _control:
+
+*************
+User Controls
+*************
+
+Devices typically have a number of user-settable controls such as
+brightness, saturation and so on, which would be presented to the user
+on a graphical user interface. But, different devices will have
+different controls available, and furthermore, the range of possible
+values, and the default value will vary from device to device. The
+control ioctls provide the information and a mechanism to create a nice
+user interface for these controls that will work correctly with any
+device.
+
+All controls are accessed using an ID value. V4L2 defines several IDs
+for specific purposes. Drivers can also implement their own custom
+controls using ``V4L2_CID_PRIVATE_BASE`` [1]_ and higher values. The
+pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
+:ref:`control-id`. The ID is used when querying the attributes of a
+control, and when getting or setting the current value.
+
+Generally applications should present controls to the user without
+assumptions about their purpose. Each control comes with a name string
+the user is supposed to understand. When the purpose is non-intuitive
+the driver writer should provide a user manual, a user interface plug-in
+or a driver specific panel application. Predefined IDs were introduced
+to change a few controls programmatically, for example to mute a device
+during a channel switch.
+
+Drivers may enumerate different controls after switching the current
+video input or output, tuner or modulator, or audio input or output.
+Different in the sense of other bounds, another default and current
+value, step size or other menu items. A control with a certain *custom*
+ID can also change name and type.
+
+If a control is not applicable to the current configuration of the
+device (for example, it doesn't apply to the current video input)
+drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
+
+Control values are stored globally, they do not change when switching
+except to stay within the reported bounds. They also do not change e. g.
+when the device is opened or closed, when the tuner radio frequency is
+changed or generally never without application request.
+
+V4L2 specifies an event mechanism to notify applications when controls
+change value (see
+:ref:`VIDIOC_SUBSCRIBE_EVENT <vidioc-subscribe-event>`, event
+``V4L2_EVENT_CTRL``), panel applications might want to make use of that
+in order to always reflect the correct control value.
+
+All controls use machine endianness.
+
+
+.. _control-id:
+
+Control IDs
+===========
+
+``V4L2_CID_BASE``
+ First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
+
+``V4L2_CID_USER_BASE``
+ Synonym of ``V4L2_CID_BASE``.
+
+``V4L2_CID_BRIGHTNESS`` ``(integer)``
+ Picture brightness, or more precisely, the black level.
+
+``V4L2_CID_CONTRAST`` ``(integer)``
+ Picture contrast or luma gain.
+
+``V4L2_CID_SATURATION`` ``(integer)``
+ Picture color saturation or chroma gain.
+
+``V4L2_CID_HUE`` ``(integer)``
+ Hue or color balance.
+
+``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
+ Overall audio volume. Note some drivers also provide an OSS or ALSA
+ mixer interface.
+
+``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
+ Audio stereo balance. Minimum corresponds to all the way left,
+ maximum to right.
+
+``V4L2_CID_AUDIO_BASS`` ``(integer)``
+ Audio bass adjustment.
+
+``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
+ Audio treble adjustment.
+
+``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
+ Mute audio, i. e. set the volume to zero, however without affecting
+ ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
+ at load time to avoid excessive noise. Actually the entire device
+ should be reset to a low power consumption state.
+
+``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
+ Loudness mode (bass boost).
+
+``V4L2_CID_BLACK_LEVEL`` ``(integer)``
+ Another name for brightness (not a synonym of
+ ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
+ be used in new drivers and applications.
+
+``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
+ Automatic white balance (cameras).
+
+``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
+ This is an action control. When set (the value is ignored), the
+ device will do a white balance and then hold the current setting.
+ Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
+ which, when activated, keeps adjusting the white balance.
+
+``V4L2_CID_RED_BALANCE`` ``(integer)``
+ Red chroma balance.
+
+``V4L2_CID_BLUE_BALANCE`` ``(integer)``
+ Blue chroma balance.
+
+``V4L2_CID_GAMMA`` ``(integer)``
+ Gamma adjust.
+
+``V4L2_CID_WHITENESS`` ``(integer)``
+ Whiteness for grey-scale devices. This is a synonym for
+ ``V4L2_CID_GAMMA``. This control is deprecated and should not be
+ used in new drivers and applications.
+
+``V4L2_CID_EXPOSURE`` ``(integer)``
+ Exposure (cameras). [Unit?]
+
+``V4L2_CID_AUTOGAIN`` ``(boolean)``
+ Automatic gain/exposure control.
+
+``V4L2_CID_GAIN`` ``(integer)``
+ Gain control.
+
+``V4L2_CID_HFLIP`` ``(boolean)``
+ Mirror the picture horizontally.
+
+``V4L2_CID_VFLIP`` ``(boolean)``
+ Mirror the picture vertically.
+
+.. _`v4l2-power-line-frequency`:
+
+``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_HUE_AUTO`` ``(boolean)``
+ Enables automatic hue control by the device. The effect of setting
+ ``V4L2_CID_HUE`` while automatic hue control is enabled is
+ undefined, drivers should ignore such request.
+
+``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
+ This control specifies the white balance settings as a color
+ temperature in Kelvin. A driver should have a minimum of 2800
+ (incandescent) to 6500 (daylight). For more information about color
+ temperature see
+ `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
+
+``V4L2_CID_SHARPNESS`` ``(integer)``
+ Adjusts the sharpness filters in a camera. The minimum value
+ disables the filters, higher values give a sharper picture.
+
+``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
+ Adjusts the backlight compensation in a camera. The minimum value
+ disables backlight compensation.
+
+``V4L2_CID_CHROMA_AGC`` ``(boolean)``
+ Chroma automatic gain control.
+
+``V4L2_CID_CHROMA_GAIN`` ``(integer)``
+ Adjusts the Chroma gain control (for use when chroma AGC is
+ disabled).
+
+``V4L2_CID_COLOR_KILLER`` ``(boolean)``
+ Enable the color killer (i. e. force a black & white image in case
+ of a weak video signal).
+
+.. _`v4l2-colorfx`:
+
+``V4L2_CID_COLORFX`` ``(enum)``
+ Selects a color effect. The following values are defined:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_COLORFX_NONE``
+
+ - Color effect is disabled.
+
+ - .. row 2
+
+ - ``V4L2_COLORFX_ANTIQUE``
+
+ - An aging (old photo) effect.
+
+ - .. row 3
+
+ - ``V4L2_COLORFX_ART_FREEZE``
+
+ - Frost color effect.
+
+ - .. row 4
+
+ - ``V4L2_COLORFX_AQUA``
+
+ - Water color, cool tone.
+
+ - .. row 5
+
+ - ``V4L2_COLORFX_BW``
+
+ - Black and white.
+
+ - .. row 6
+
+ - ``V4L2_COLORFX_EMBOSS``
+
+ - Emboss, the highlights and shadows replace light/dark boundaries
+ and low contrast areas are set to a gray background.
+
+ - .. row 7
+
+ - ``V4L2_COLORFX_GRASS_GREEN``
+
+ - Grass green.
+
+ - .. row 8
+
+ - ``V4L2_COLORFX_NEGATIVE``
+
+ - Negative.
+
+ - .. row 9
+
+ - ``V4L2_COLORFX_SEPIA``
+
+ - Sepia tone.
+
+ - .. row 10
+
+ - ``V4L2_COLORFX_SKETCH``
+
+ - Sketch.
+
+ - .. row 11
+
+ - ``V4L2_COLORFX_SKIN_WHITEN``
+
+ - Skin whiten.
+
+ - .. row 12
+
+ - ``V4L2_COLORFX_SKY_BLUE``
+
+ - Sky blue.
+
+ - .. row 13
+
+ - ``V4L2_COLORFX_SOLARIZATION``
+
+ - Solarization, the image is partially reversed in tone, only color
+ values above or below a certain threshold are inverted.
+
+ - .. row 14
+
+ - ``V4L2_COLORFX_SILHOUETTE``
+
+ - Silhouette (outline).
+
+ - .. row 15
+
+ - ``V4L2_COLORFX_VIVID``
+
+ - Vivid colors.
+
+ - .. row 16
+
+ - ``V4L2_COLORFX_SET_CBCR``
+
+ - The Cb and Cr chroma components are replaced by fixed coefficients
+ determined by ``V4L2_CID_COLORFX_CBCR`` control.
+
+
+
+``V4L2_CID_COLORFX_CBCR`` ``(integer)``
+ Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
+ color effect. Bits [7:0] of the supplied 32 bit value are
+ interpreted as Cr component, bits [15:8] as Cb component and bits
+ [31:16] must be zero.
+
+``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
+ Enable Automatic Brightness.
+
+``V4L2_CID_ROTATE`` ``(integer)``
+ Rotates the image by specified angle. Common angles are 90, 270 and
+ 180. Rotating the image to 90 and 270 will reverse the height and
+ width of the display window. It is necessary to set the new height
+ and width of the picture using the
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl according to the
+ rotation angle selected.
+
+``V4L2_CID_BG_COLOR`` ``(integer)``
+ Sets the background color on the current output device. Background
+ color needs to be specified in the RGB24 format. The supplied 32 bit
+ value is interpreted as bits 0-7 Red color information, bits 8-15
+ Green color information, bits 16-23 Blue color information and bits
+ 24-31 must be zero.
+
+``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
+ Switch on or off the illuminator 1 or 2 of the device (usually a
+ microscope).
+
+``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
+ This is a read-only control that can be read by the application and
+ used as a hint to determine the number of CAPTURE buffers to pass to
+ REQBUFS. The value is the minimum number of CAPTURE buffers that is
+ necessary for hardware to work.
+
+``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
+ This is a read-only control that can be read by the application and
+ used as a hint to determine the number of OUTPUT buffers to pass to
+ REQBUFS. The value is the minimum number of OUTPUT buffers that is
+ necessary for hardware to work.
+
+.. _`v4l2-alpha-component`:
+
+``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
+ Sets the alpha color component. When a capture device (or capture
+ queue of a mem-to-mem device) produces a frame format that includes
+ an alpha component (e.g.
+ :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
+ is not defined by the device or the mem-to-mem input data this
+ control lets you select the alpha component value of all pixels.
+ When an output device (or output queue of a mem-to-mem device)
+ consumes a frame format that doesn't include an alpha component and
+ the device supports alpha channel processing this control lets you
+ set the alpha component value of all pixels for further processing
+ in the device.
+
+``V4L2_CID_LASTP1``
+ End of the predefined control IDs (currently
+ ``V4L2_CID_ALPHA_COMPONENT`` + 1).
+
+``V4L2_CID_PRIVATE_BASE``
+ ID of the first custom (driver specific) control. Applications
+ depending on particular custom controls should check the driver name
+ and version, see :ref:`querycap`.
+
+Applications can enumerate the available controls with the
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` and
+:ref:`VIDIOC_QUERYMENU <vidioc-queryctrl>` ioctls, get and set a
+control value with the :ref:`VIDIOC_G_CTRL <vidioc-g-ctrl>` and
+:ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` ioctls. Drivers must implement
+``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
+device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
+more menu type controls.
+
+
+.. code-block:: c
+
+ struct v4l2_queryctrl queryctrl;
+ struct v4l2_querymenu querymenu;
+
+ static void enumerate_menu(void)
+ {
+ printf(" Menu items:\\n");
+
+ memset(&querymenu, 0, sizeof(querymenu));
+ querymenu.id = queryctrl.id;
+
+ for (querymenu.index = queryctrl.minimum;
+ querymenu.index <= queryctrl.maximum;
+ querymenu.index++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
+ printf(" %s\\n", querymenu.name);
+ }
+ }
+ }
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+
+ for (queryctrl.id = V4L2_CID_BASE;
+ queryctrl.id < V4L2_CID_LASTP1;
+ queryctrl.id++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+ } else {
+ if (errno == EINVAL)
+ continue;
+
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
+ queryctrl.id++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+ } else {
+ if (errno == EINVAL)
+ break;
+
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+
+.. code-block:: c
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+
+ queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
+ break;
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+
+ queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+
+ struct v4l2_queryctrl queryctrl;
+ struct v4l2_control control;
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+ queryctrl.id = V4L2_CID_BRIGHTNESS;
+
+ if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ } else {
+ printf("V4L2_CID_BRIGHTNESS is not supportedn");
+ }
+ } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
+ printf("V4L2_CID_BRIGHTNESS is not supportedn");
+ } else {
+ memset(&control, 0, sizeof (control));
+ control.id = V4L2_CID_BRIGHTNESS;
+ control.value = queryctrl.default_value;
+
+ if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
+ perror("VIDIOC_S_CTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ memset(&control, 0, sizeof(control));
+ control.id = V4L2_CID_CONTRAST;
+
+ if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
+ control.value += 1;
+
+ /* The driver may clamp the value or return ERANGE, ignored here */
+
+ if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
+ && errno != ERANGE) {
+ perror("VIDIOC_S_CTRL");
+ exit(EXIT_FAILURE);
+ }
+ /* Ignore if V4L2_CID_CONTRAST is unsupported */
+ } else if (errno != EINVAL) {
+ perror("VIDIOC_G_CTRL");
+ exit(EXIT_FAILURE);
+ }
+
+ control.id = V4L2_CID_AUDIO_MUTE;
+ control.value = 1; /* silence */
+
+ /* Errors ignored */
+ ioctl(fd, VIDIOC_S_CTRL, &control);
+
+.. [1]
+ The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
+ drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
+ controls. This makes it hard to programatically set such controls
+ since the meaning of the control with that ID is driver dependent. In
+ order to resolve this drivers use unique IDs and the
+ ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
+ kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
+ the real IDs.
+
+ Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
+ instead of using :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` with
+ the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
+ support for ``V4L2_CID_PRIVATE_BASE`` is still around.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. toctree::
+ :maxdepth: 1
+
+ control
+ extended-controls
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _crop:
+
+*************************************
+Image Cropping, Insertion and Scaling
+*************************************
+
+Some video capture devices can sample a subsection of the picture and
+shrink or enlarge it to an image of arbitrary size. We call these
+abilities cropping and scaling. Some video output devices can scale an
+image up or down and insert it at an arbitrary scan line and horizontal
+offset into a video signal.
+
+Applications can use the following API to select an area in the video
+signal, query the default area and the hardware limits. *Despite their
+name, the :ref:`VIDIOC_CROPCAP <vidioc-cropcap>`,
+:ref:`VIDIOC_G_CROP <vidioc-g-crop>` and
+:ref:`VIDIOC_S_CROP <vidioc-g-crop>` ioctls apply to input as well
+as output devices.*
+
+Scaling requires a source and a target. On a video capture or overlay
+device the source is the video signal, and the cropping ioctls determine
+the area actually sampled. The target are images read by the application
+or overlaid onto the graphics screen. Their size (and position for an
+overlay) is negotiated with the :ref:`VIDIOC_G_FMT <vidioc-g-fmt>`
+and :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctls.
+
+On a video output device the source are the images passed in by the
+application, and their size is again negotiated with the
+``VIDIOC_G/S_FMT`` ioctls, or may be encoded in a compressed video
+stream. The target is the video signal, and the cropping ioctls
+determine the area where the images are inserted.
+
+Source and target rectangles are defined even if the device does not
+support scaling or the ``VIDIOC_G/S_CROP`` ioctls. Their size (and
+position where applicable) will be fixed in this case. *All capture and
+output device must support the ``VIDIOC_CROPCAP`` ioctl such that
+applications can determine if scaling takes place.*
+
+
+Cropping Structures
+===================
+
+
+.. _crop-scale:
+
+.. figure:: crop_files/crop.*
+ :alt: crop.pdf / crop.gif
+ :align: center
+
+ Image Cropping, Insertion and Scaling
+
+ The cropping, insertion and scaling process
+
+
+
+For capture devices the coordinates of the top left corner, width and
+height of the area which can be sampled is given by the ``bounds``
+substructure of the struct :ref:`v4l2_cropcap <v4l2-cropcap>`
+returned by the ``VIDIOC_CROPCAP`` ioctl. To support a wide range of
+hardware this specification does not define an origin or units. However
+by convention drivers should horizontally count unscaled samples
+relative to 0H (the leading edge of the horizontal sync pulse, see
+:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field
+(:ref:`vbi-525`, :ref:`vbi-625`), multiplied by two if the driver
+can capture both fields.
+
+The top left corner, width and height of the source rectangle, that is
+the area actually sampled, is given by struct
+:ref:`v4l2_crop <v4l2-crop>` using the same coordinate system as
+struct :ref:`v4l2_cropcap <v4l2-cropcap>`. Applications can use the
+``VIDIOC_G_CROP`` and ``VIDIOC_S_CROP`` ioctls to get and set this
+rectangle. It must lie completely within the capture boundaries and the
+driver may further adjust the requested size and/or position according
+to hardware limitations.
+
+Each capture device has a default source rectangle, given by the
+``defrect`` substructure of struct
+:ref:`v4l2_cropcap <v4l2-cropcap>`. The center of this rectangle
+shall align with the center of the active picture area of the video
+signal, and cover what the driver writer considers the complete picture.
+Drivers shall reset the source rectangle to the default when the driver
+is first loaded, but not later.
+
+For output devices these structures and ioctls are used accordingly,
+defining the *target* rectangle where the images will be inserted into
+the video signal.
+
+
+Scaling Adjustments
+===================
+
+Video hardware can have various cropping, insertion and scaling
+limitations. It may only scale up or down, support only discrete scaling
+factors, or have different scaling abilities in horizontal and vertical
+direction. Also it may not support scaling at all. At the same time the
+struct :ref:`v4l2_crop <v4l2-crop>` rectangle may have to be aligned,
+and both the source and target rectangles may have arbitrary upper and
+lower size limits. In particular the maximum ``width`` and ``height`` in
+struct :ref:`v4l2_crop <v4l2-crop>` may be smaller than the struct
+:ref:`v4l2_cropcap <v4l2-cropcap>`. ``bounds`` area. Therefore, as
+usual, drivers are expected to adjust the requested parameters and
+return the actual values selected.
+
+Applications can change the source or the target rectangle first, as
+they may prefer a particular image size or a certain area in the video
+signal. If the driver has to adjust both to satisfy hardware
+limitations, the last requested rectangle shall take priority, and the
+driver should preferably adjust the opposite one. The
+:ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl however shall not change
+the driver state and therefore only adjust the requested rectangle.
+
+Suppose scaling on a video capture device is restricted to a factor 1:1
+or 2:1 in either direction and the target image size must be a multiple
+of 16 × 16 pixels. The source cropping rectangle is set to defaults,
+which are also the upper limit in this example, of 640 × 400 pixels at
+offset 0, 0. An application requests an image size of 300 × 225 pixels,
+assuming video will be scaled down from the "full picture" accordingly.
+The driver sets the image size to the closest possible values 304 × 224,
+then chooses the cropping rectangle closest to the requested size, that
+is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is
+still valid, thus unmodified. Given the default cropping rectangle
+reported by ``VIDIOC_CROPCAP`` the application can easily propose
+another offset to center the cropping rectangle.
+
+Now the application may insist on covering an area using a picture
+aspect ratio closer to the original request, so it asks for a cropping
+rectangle of 608 × 456 pixels. The present scaling factors limit
+cropping to 640 × 384, so the driver returns the cropping size 608 × 384
+and adjusts the image size to closest possible 304 × 192.
+
+
+Examples
+========
+
+Source and target rectangles shall remain unchanged across closing and
+reopening a device, such that piping data into or out of a device will
+work without special preparations. More advanced applications should
+ensure the parameters are suitable before starting I/O.
+
+(A video capture device is assumed; change
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices.)
+
+
+.. code-block:: c
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ crop.c = cropcap.defrect;
+
+ /* Ignore if cropping is not supported (EINVAL). */
+
+ if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
+ && errno != EINVAL) {
+ perror ("VIDIOC_S_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+(A video capture device is assumed.)
+
+
+.. code-block:: c
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_format format;
+
+ reset_cropping_parameters ();
+
+ /* Scale down to 1/4 size of full picture. */
+
+ memset (&format, 0, sizeof (format)); /* defaults */
+
+ format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ format.fmt.pix.width = cropcap.defrect.width >> 1;
+ format.fmt.pix.height = cropcap.defrect.height >> 1;
+ format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
+
+ if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
+ perror ("VIDIOC_S_FORMAT");
+ exit (EXIT_FAILURE);
+ }
+
+ /* We could check the actual image size now, the actual scaling factor
+ or if the driver can scale at all. */
+
+
+.. code-block:: c
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+
+ crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
+ crop.c = cropcap.defrect;
+
+ /* Scale the width and height to 50 % of their original size
+ and center the output. */
+
+ crop.c.width /= 2;
+ crop.c.height /= 2;
+ crop.c.left += crop.c.width / 2;
+ crop.c.top += crop.c.height / 2;
+
+ /* Ignore if cropping is not supported (EINVAL). */
+
+ if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
+ && errno != EINVAL) {
+ perror ("VIDIOC_S_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+(A video capture device is assumed.)
+
+
+.. code-block:: c
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+ struct v4l2_format format;
+ double hscale, vscale;
+ double aspect;
+ int dwidth, dheight;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
+ if (errno != EINVAL) {
+ perror ("VIDIOC_G_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+ /* Cropping not supported. */
+ crop.c = cropcap.defrect;
+ }
+
+ memset (&format, 0, sizeof (format));
+ format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
+ perror ("VIDIOC_G_FMT");
+ exit (EXIT_FAILURE);
+ }
+
+ /* The scaling applied by the driver. */
+
+ hscale = format.fmt.pix.width / (double) crop.c.width;
+ vscale = format.fmt.pix.height / (double) crop.c.height;
+
+ aspect = cropcap.pixelaspect.numerator /
+ (double) cropcap.pixelaspect.denominator;
+ aspect = aspect * hscale / vscale;
+
+ /* Devices following ITU-R BT.601 do not capture
+ square pixels. For playback on a computer monitor
+ we should scale the images to this size. */
+
+ dwidth = format.fmt.pix.width / aspect;
+ dheight = format.fmt.pix.height;
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _depth-formats:
+
+*************
+Depth Formats
+*************
+
+Depth data provides distance to points, mapped onto the image plane
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-z16
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _capture:
+
+***********************
+Video Capture Interface
+***********************
+
+Video capture devices sample an analog video signal and store the
+digitized images in memory. Today nearly all devices can capture at full
+25 or 30 frames/second. With this interface applications can control the
+capture process and move images from the driver into user space.
+
+Conventionally V4L2 video capture devices are accessed through character
+device special files named ``/dev/video`` and ``/dev/video0`` to
+``/dev/video63`` with major number 81 and minor numbers 0 to 63.
+``/dev/video`` is typically a symbolic link to the preferred video
+device. Note the same device files are used for video output devices.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video capture interface set the
+``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in
+the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. As secondary device
+functions they may also support the :ref:`video overlay <overlay>`
+(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>`
+(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or
+streaming I/O methods must be supported. Tuners and audio inputs are
+optional.
+
+
+Supplemental Functions
+======================
+
+Video capture devices shall support :ref:`audio input <audio>`,
+:ref:`tuner <tuner>`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video input <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video capture devices.
+
+
+Image Format Negotiation
+========================
+
+The result of a capture operation is determined by cropping and image
+format parameters. The former select an area of the video picture to
+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>`
+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.
+
+Cropping initialization at minimum requires to reset the parameters to
+defaults. An example is given in :ref:`crop`.
+
+To query the current image format applications set the ``type`` field of
+a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl with a pointer to this
+structure. Drivers fill the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member of the ``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of ``VIDIOC_G_FMT``, and call the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
+ioctl with a pointer to this structure. Drivers may adjust the
+parameters and finally return the actual parameters as ``VIDIOC_G_FMT``
+does.
+
+Like ``VIDIOC_S_FMT`` the :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl
+can be used to learn about hardware limitations without disabling I/O or
+possibly time consuming hardware preparations.
+
+The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
+discussed in :ref:`pixfmt`. See also the specification of the
+``VIDIOC_G_FMT``, ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT`` ioctls for
+details. Video capture devices must implement both the ``VIDIOC_G_FMT``
+and ``VIDIOC_S_FMT`` ioctl, even if ``VIDIOC_S_FMT`` ignores all
+requests and always returns default parameters as ``VIDIOC_G_FMT`` does.
+``VIDIOC_TRY_FMT`` is optional.
+
+
+Reading Images
+==============
+
+A video capture device may support the :ref:`read() function <rw>`
+and/or streaming (:ref:`memory mapping <mmap>` or
+:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _codec:
+
+***************
+Codec Interface
+***************
+
+A V4L2 codec can compress, decompress, transform, or otherwise convert
+video data from one format into another format, in memory. Typically
+such devices are memory-to-memory devices (i.e. devices with the
+``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set).
+
+A memory-to-memory video node acts just like a normal video node, but it
+supports both output (sending frames from memory to the codec hardware)
+and capture (receiving the processed frames from the codec hardware into
+memory) stream I/O. An application will have to setup the stream I/O for
+both sides and finally call :ref:`VIDIOC_STREAMON <vidioc-streamon>`
+for both capture and output to start the codec.
+
+Video compression codecs use the MPEG controls to setup their codec
+parameters (note that the MPEG controls actually support many more
+codecs than just MPEG). See :ref:`mpeg-controls`.
+
+Memory-to-memory devices can often be used as a shared resource: you can
+open the video node multiple times, each application setting up their
+own codec properties that are local to the file handle, and each can use
+it independently from the others. The driver will arbitrate access to
+the codec and reprogram it whenever another file handler gets access.
+This is different from the usual video node behavior where the video
+properties are global to the device (i.e. changing something through one
+file handle is visible through another file handle).
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _effect:
+
+************************
+Effect Devices Interface
+************************
+
+ **Note**
+
+ This interface has been be suspended from the V4L2 API implemented
+ in Linux 2.6 until we have more experience with effect device
+ interfaces.
+
+A V4L2 video effect device can do image effects, filtering, or combine
+two or more images or image streams. For example video transitions or
+wipes. Applications send data to be processed and receive the result
+data either with :ref:`read() <func-read>` and
+:ref:`write() <func-write>` functions, or through the streaming I/O
+mechanism.
+
+[to do]
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _event:
+
+***************
+Event Interface
+***************
+
+The V4L2 event interface provides a means for a user to get immediately
+notified on certain conditions taking place on a device. This might
+include start of frame or loss of signal events, for example. Changes in
+the value or state of a V4L2 control can also be reported through
+events.
+
+To receive events, the events the user is interested in first must be
+subscribed using the
+:ref:`VIDIOC_SUBSCRIBE_EVENT <vidioc-subscribe-event>` ioctl. Once
+an event is subscribed, the events of subscribed types are dequeueable
+using the :ref:`VIDIOC_DQEVENT <vidioc-dqevent>` ioctl. Events may be
+unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
+type V4L2_EVENT_ALL may be used to unsubscribe all the events the
+driver supports.
+
+The event subscriptions and event queues are specific to file handles.
+Subscribing an event on one file handle does not affect other file
+handles.
+
+The information on dequeueable events is obtained by using select or
+poll system calls on video devices. The V4L2 events use POLLPRI events
+on poll system call and exceptions on select system call.
+
+Starting with kernel 3.1 certain guarantees can be given with regards to
+events:
+
+1. Each subscribed event has its own internal dedicated event queue.
+ This means that flooding of one event type will not interfere with
+ other event types.
+
+2. If the internal event queue for a particular subscribed event becomes
+ full, then the oldest event in that queue will be dropped.
+
+3. Where applicable, certain event types can ensure that the payload of
+ the oldest event that is about to be dropped will be merged with the
+ payload of the next oldest event. Thus ensuring that no information
+ is lost, but only an intermediate step leading up to that
+ information. See the documentation for the event you want to
+ subscribe to whether this is applicable for that event or not.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _osd:
+
+******************************
+Video Output Overlay Interface
+******************************
+
+
+**Also known as On-Screen Display (OSD)**
+Some video output devices can overlay a framebuffer image onto the
+outgoing video signal. Applications can set up such an overlay using
+this interface, which borrows structures and ioctls of the
+:ref:`Video Overlay <overlay>` interface.
+
+The OSD function is accessible through the same character special file
+as the :ref:`Video Output <capture>` function. Note the default
+function of such a ``/dev/video`` device is video capturing or output.
+The OSD function is only available after calling the
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the *Video Output Overlay* interface set the
+``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of
+struct :ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl.
+
+
+Framebuffer
+===========
+
+Contrary to the *Video Overlay* interface the framebuffer is normally
+implemented on the TV card and not the graphics card. On Linux it is
+accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device,
+applications can find the corresponding framebuffer device by calling
+the :ref:`VIDIOC_G_FBUF <vidioc-g-fbuf>` ioctl. It returns, amongst
+other information, the physical address of the framebuffer in the
+``base`` field of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`.
+The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same
+address in the ``smem_start`` field of struct
+:c:type:`struct fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
+ioctl and struct :c:type:`struct fb_fix_screeninfo` are defined in
+the ``linux/fb.h`` header file.
+
+The width and height of the framebuffer depends on the current video
+standard. A V4L2 driver may reject attempts to change the video standard
+(or any other ioctl which would imply a framebuffer size change) with an
+EBUSY error code until all applications closed the framebuffer device.
+
+
+.. code-block:: c
+
+ #include <linux/fb.h>
+
+ struct v4l2_framebuffer fbuf;
+ unsigned int i;
+ int fb_fd;
+
+ if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) {
+ perror("VIDIOC_G_FBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ for (i = 0; i < 30; i++) {
+ char dev_name[16];
+ struct fb_fix_screeninfo si;
+
+ snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
+
+ fb_fd = open(dev_name, O_RDWR);
+ if (-1 == fb_fd) {
+ switch (errno) {
+ case ENOENT: /* no such file */
+ case ENXIO: /* no driver */
+ continue;
+
+ default:
+ perror("open");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) {
+ if (si.smem_start == (unsigned long)fbuf.base)
+ break;
+ } else {
+ /* Apparently not a framebuffer device. */
+ }
+
+ close(fb_fd);
+ fb_fd = -1;
+ }
+
+ /* fb_fd is the file descriptor of the framebuffer device
+ for the video output overlay, or -1 if no device was found. */
+
+
+Overlay Window and Scaling
+==========================
+
+The overlay is controlled by source and target rectangles. The source
+rectangle selects a subsection of the framebuffer image to be overlaid,
+the target rectangle an area in the outgoing video signal where the
+image will appear. Drivers may or may not support scaling, and arbitrary
+sizes and positions of these rectangles. Further drivers may support any
+(or none) of the clipping/blending methods defined for the
+:ref:`Video Overlay <overlay>` interface.
+
+A struct :ref:`v4l2_window <v4l2-window>` defines the size of the
+source rectangle, its position in the framebuffer and the
+clipping/blending method to be used for the overlay. To get the current
+parameters applications set the ``type`` field of a struct
+:ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl. The driver fills the
+:c:type:`struct v4l2_window` substructure named ``win``. It is not
+possible to retrieve a previously programmed clipping list or bitmap.
+
+To program the source rectangle applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win``
+substructure and call the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl.
+The driver adjusts the parameters against hardware limits and returns
+the actual parameters as ``VIDIOC_G_FMT`` does. Like ``VIDIOC_S_FMT``,
+the :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl can be used to learn
+about driver capabilities without actually changing driver state. Unlike
+``VIDIOC_S_FMT`` this also works after the overlay has been enabled.
+
+A struct :ref:`v4l2_crop <v4l2-crop>` defines the size and position
+of the target rectangle. The scaling factor of the overlay is implied by
+the width and height given in struct :ref:`v4l2_window <v4l2-window>`
+and struct :ref:`v4l2_crop <v4l2-crop>`. The cropping API applies to
+*Video Output* and *Video Output Overlay* devices in the same way as to
+*Video Capture* and *Video Overlay* devices, merely reversing the
+direction of the data flow. For more information see :ref:`crop`.
+
+
+Enabling Overlay
+================
+
+There is no V4L2 ioctl to enable or disable the overlay, however the
+framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _output:
+
+**********************
+Video Output Interface
+**********************
+
+Video output devices encode stills or image sequences as analog video
+signal. With this interface applications can control the encoding
+process and move images from user space to the driver.
+
+Conventionally V4L2 video output devices are accessed through character
+device special files named ``/dev/video`` and ``/dev/video0`` to
+``/dev/video63`` with major number 81 and minor numbers 0 to 63.
+``/dev/video`` is typically a symbolic link to the preferred video
+device. Note the same device files are used for video capture devices.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video output interface set the
+``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
+the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. As secondary device
+functions they may also support the :ref:`raw VBI output <raw-vbi>`
+(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
+streaming I/O methods must be supported. Modulators and audio outputs
+are optional.
+
+
+Supplemental Functions
+======================
+
+Video output devices shall support :ref:`audio output <audio>`,
+:ref:`modulator <tuner>`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video output <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video output devices.
+
+
+Image Format Negotiation
+========================
+
+The output is determined by cropping and image format parameters. The
+former select an area of the video picture where the image will appear,
+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>`
+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.
+
+Cropping initialization at minimum requires to reset the parameters to
+defaults. An example is given in :ref:`crop`.
+
+To query the current image format applications set the ``type`` field of
+a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
+and call the :ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl with a pointer
+to this structure. Drivers fill the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member of the ``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of ``VIDIOC_G_FMT``, and call the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
+ioctl with a pointer to this structure. Drivers may adjust the
+parameters and finally return the actual parameters as ``VIDIOC_G_FMT``
+does.
+
+Like ``VIDIOC_S_FMT`` the :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl
+can be used to learn about hardware limitations without disabling I/O or
+possibly time consuming hardware preparations.
+
+The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
+discussed in :ref:`pixfmt`. See also the specification of the
+``VIDIOC_G_FMT``, ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT`` ioctls for
+details. Video output devices must implement both the ``VIDIOC_G_FMT``
+and ``VIDIOC_S_FMT`` ioctl, even if ``VIDIOC_S_FMT`` ignores all
+requests and always returns default parameters as ``VIDIOC_G_FMT`` does.
+``VIDIOC_TRY_FMT`` is optional.
+
+
+Writing Images
+==============
+
+A video output device may support the :ref:`write() function <rw>`
+and/or streaming (:ref:`memory mapping <mmap>` or
+:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _overlay:
+
+***********************
+Video Overlay Interface
+***********************
+
+
+**Also known as Framebuffer Overlay or Previewing**
+Video overlay devices have the ability to genlock (TV-)video into the
+(VGA-)video signal of a graphics card, or to store captured images
+directly in video memory of a graphics card, typically with clipping.
+This can be considerable more efficient than capturing images and
+displaying them by other means. In the old days when only nuclear power
+plants needed cooling towers this used to be the only way to put live
+video into a window.
+
+Video overlay devices are accessed through the same character special
+files as :ref:`video capture <capture>` devices. Note the default
+function of a ``/dev/video`` device is video capturing. The overlay
+function is only available after calling the
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl.
+
+The driver may support simultaneous overlay and capturing using the
+read/write and streaming I/O methods. If so, operation at the nominal
+frame rate of the video standard is not guaranteed. Frames may be
+directed away from overlay to capture, or one field may be used for
+overlay and the other for capture if the capture parameters permit this.
+
+Applications should use different file descriptors for capturing and
+overlay. This must be supported by all drivers capable of simultaneous
+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. [1]_
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video overlay interface set the
+``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. The overlay I/O
+method specified below must be supported. Tuners and audio inputs are
+optional.
+
+
+Supplemental Functions
+======================
+
+Video overlay devices shall support :ref:`audio input <audio>`,
+:ref:`tuner <tuner>`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video input <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video overlay devices.
+
+
+Setup
+=====
+
+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
+:ref:`VIDIOC_G_FBUF <vidioc-g-fbuf>` and
+:ref:`VIDIOC_S_FBUF <vidioc-g-fbuf>` ioctls are available to get and
+set these parameters, respectively. The ``VIDIOC_S_FBUF`` ioctl is
+privileged because it allows to set up DMA into physical memory,
+bypassing the memory protection mechanisms of the kernel. Only the
+superuser can change the frame buffer address and size. Users are not
+supposed to run TV applications as root or with SUID bit set. A small
+helper application with suitable privileges should query the graphics
+system and program the V4L2 driver at the appropriate time.
+
+Some devices add the video overlay to the output signal of the graphics
+card. In this case the frame buffer is not modified by the video device,
+and the frame buffer address and pixel format are not needed by the
+driver. The ``VIDIOC_S_FBUF`` ioctl is not privileged. An application
+can check for this type of device by calling the ``VIDIOC_G_FBUF``
+ioctl.
+
+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
+ 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*
+ 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
+ blend the framebuffer with the video.
+
+5. A global alpha value can be specified to blend the framebuffer
+ contents with video images.
+
+When simultaneous capturing and overlay is supported and the hardware
+prohibits different image and frame buffer formats, the format requested
+first takes precedence. The attempt to capture
+(:ref:`VIDIOC_S_FMT <vidioc-g-fmt>`) or overlay
+(:ref:`VIDIOC_S_FBUF <vidioc-g-fbuf>`) may fail with an EBUSY error
+code or return accordingly modified parameters..
+
+
+Overlay Window
+==============
+
+The overlaid image is determined by cropping and overlay window
+parameters. The former select an area of the video picture to capture,
+the latter how images are overlaid and clipped. Cropping initialization
+at minimum requires to reset the parameters to defaults. An example is
+given in :ref:`crop`.
+
+The overlay window is described by a struct
+:ref:`v4l2_window <v4l2-window>`. It defines the size of the image,
+its position over the graphics surface and the clipping to be applied.
+To get the current parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl. The driver fills the
+:c:type:`struct v4l2_window` substructure named ``win``. It is not
+possible to retrieve a previously programmed clipping list or bitmap.
+
+To program the overlay window applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and
+call the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl. The driver
+adjusts the parameters against hardware limits and returns the actual
+parameters as ``VIDIOC_G_FMT`` does. Like ``VIDIOC_S_FMT``, the
+:ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl can be used to learn
+about driver capabilities without actually changing driver state. Unlike
+``VIDIOC_S_FMT`` this also works after the overlay has been enabled.
+
+The scaling factor of the overlaid image is implied by the width and
+height given in struct :ref:`v4l2_window <v4l2-window>` and the size
+of the cropping rectangle. For more information see :ref:`crop`.
+
+When simultaneous capturing and overlay is supported and the hardware
+prohibits different image and window sizes, the size requested first
+takes precedence. The attempt to capture or overlay as well
+(:ref:`VIDIOC_S_FMT <vidioc-g-fmt>`) may fail with an EBUSY error
+code or return accordingly modified parameters.
+
+
+.. _v4l2-window:
+
+struct v4l2_window
+------------------
+
+``struct v4l2_rect w``
+ Size and position of the window relative to the top, left corner of
+ the frame buffer defined with
+ :ref:`VIDIOC_S_FBUF <vidioc-g-fbuf>`. The window can extend the
+ frame buffer width and height, the ``x`` and ``y`` coordinates can
+ be negative, and it can lie completely outside the frame buffer. The
+ driver clips the window accordingly, or if that is not possible,
+ modifies its size and/or position.
+
+``enum v4l2_field field``
+ Applications set this field to determine which video field shall be
+ overlaid, typically one of ``V4L2_FIELD_ANY`` (0),
+ ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or
+ ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different
+ field order and return the actual setting here.
+
+``__u32 chromakey``
+ When chroma-keying has been negotiated with
+ :ref:`VIDIOC_S_FBUF <vidioc-g-fbuf>` applications set this field
+ to the desired pixel value for the chroma key. The format is the
+ same as the pixel format of the framebuffer (struct
+ :ref:`v4l2_framebuffer <v4l2-framebuffer>` ``fmt.pixelformat``
+ field), with bytes in host order. E. g. for
+ :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should
+ be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host.
+
+``struct v4l2_clip * clips``
+ 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
+ rectangles.
+
+Like the window coordinates
+w
+, clipping rectangles are defined relative to the top, left corner of
+the frame buffer. However clipping rectangles must not extend the frame
+buffer width and height, and they must not overlap. If possible
+applications should merge adjacent rectangles. Whether this must create
+x-y or y-x bands, or the order of rectangles, is not defined. When clip
+lists are not supported the driver ignores this field. Its contents
+after calling
+!ri!:ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
+are undefined.
+
+``__u32 clipcount``
+ 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
+ after calling ``VIDIOC_S_FMT`` are undefined. When clip lists are
+ supported but no clipping is desired this field must be set to zero.
+
+``void * bitmap``
+ 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.
+
+It must be of the same size as the window, ``w.width`` and ``w.height``.
+Each bit corresponds to a pixel in the overlaid image, which is
+displayed only when the bit is *set*. Pixel coordinates translate to
+bits like:
+
+
+.. code-block:: c
+
+ ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))
+
+where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [2]_
+
+When a clipping bit mask is not supported the driver ignores this field,
+its contents after calling :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` are
+undefined. When a bit mask is supported but no clipping is desired this
+field must be set to ``NULL``.
+
+Applications need not create a clip list or bit mask. When they pass
+both, or despite negotiating chroma-keying, the results are undefined.
+Regardless of the chosen method, the clipping abilities of the hardware
+may be limited in quantity or quality. The results when these limits are
+exceeded are undefined. [3]_
+
+``__u8 global_alpha``
+ The global alpha value used to blend the framebuffer with video
+ images, if global alpha blending has been negotiated
+ (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see
+ :ref:`VIDIOC_S_FBUF <vidioc-g-fbuf>`,
+ :ref:`framebuffer-flags`).
+
+Note this field was added in Linux 2.6.23, extending the structure.
+However the
+!ri!:ref:`VIDIOC_G/S/TRY_FMT <vidioc-g-fmt>`
+ioctls, which take a pointer to a
+!ri!:ref:`v4l2_format <v4l2-format>`
+parent structure with padding bytes at the end, are not affected.
+
+
+.. _v4l2-clip:
+
+struct v4l2_clip
+----------------
+
+The X Window system defines "regions" which are vectors of struct BoxRec
+{ short x1, y1, x2, y2; } with width = x2 - x1 and height = y2 - y1, so
+one cannot pass X11 clip lists directly.
+
+``struct v4l2_rect c``
+ Coordinates of the clipping rectangle, relative to the top, left
+ corner of the frame buffer. Only window pixels *outside* all
+ clipping rectangles are displayed.
+
+``struct v4l2_clip * next``
+ Pointer to the next clipping rectangle, NULL when this is the last
+ rectangle. Drivers ignore this field, it cannot be used to pass a
+ linked list of clipping rectangles.
+
+
+.. _v4l2-rect:
+
+struct v4l2_rect
+----------------
+
+``__s32 left``
+ Horizontal offset of the top, left corner of the rectangle, in
+ pixels.
+
+``__s32 top``
+ Vertical offset of the top, left corner of the rectangle, in pixels.
+ Offsets increase to the right and down.
+
+``__u32 width``
+ Width of the rectangle, in pixels.
+
+``__u32 height``
+ Height of the rectangle, in pixels.
+
+
+Enabling Overlay
+================
+
+To start or stop the frame buffer overlay applications call the
+:ref:`VIDIOC_OVERLAY <vidioc-overlay>` ioctl.
+
+.. [1]
+ 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
+ V4L and earlier versions of V4L2. Making this optional means
+ applications depending on two file descriptors need backup routines
+ to be compatible with all drivers, which is considerable more work
+ than using two fds in applications which do not. Also two fd's fit
+ the general concept of one file descriptor for each logical stream.
+ Hence as a complexity trade-off drivers *must* support two file
+ descriptors and *may* support single fd operation.
+
+.. [2]
+ Should we require ``w.width`` to be a multiple of eight?
+
+.. [3]
+ When the image is written into frame buffer memory it will be
+ undesirable if the driver clips out less pixels than expected,
+ because the application and graphics system are not aware these
+ regions need to be refreshed. The driver should clip out more pixels
+ or not write the image at all.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _radio:
+
+***************
+Radio Interface
+***************
+
+This interface is intended for AM and FM (analog) radio receivers and
+transmitters.
+
+Conventionally V4L2 radio devices are accessed through character device
+special files named ``/dev/radio`` and ``/dev/radio0`` to
+``/dev/radio63`` with major number 81 and minor numbers 64 to 127.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the radio interface set the ``V4L2_CAP_RADIO`` and
+``V4L2_CAP_TUNER`` or ``V4L2_CAP_MODULATOR`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. Other combinations of
+capability flags are reserved for future extensions.
+
+
+Supplemental Functions
+======================
+
+Radio devices can support :ref:`controls <control>`, and must support
+the :ref:`tuner or modulator <tuner>` ioctls.
+
+They do not support the video input or output, audio input or output,
+video standard, cropping and scaling, compression and streaming
+parameter, or overlay ioctls. All other ioctls and I/O methods are
+reserved for future extensions.
+
+
+Programming
+===========
+
+Radio devices may have a couple audio controls (as discussed in
+:ref:`control`) such as a volume control, possibly custom controls.
+Further all radio devices have one tuner or modulator (these are
+discussed in :ref:`tuner`) with index number zero to select the radio
+frequency and to determine if a monaural or FM stereo program is
+received/emitted. Drivers switch automatically between AM and FM
+depending on the selected frequency. The
+:ref:`VIDIOC_G_TUNER <vidioc-g-tuner>` or
+:ref:`VIDIOC_G_MODULATOR <vidioc-g-modulator>` ioctl reports the
+supported frequency range.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _raw-vbi:
+
+**********************
+Raw VBI Data Interface
+**********************
+
+VBI is an abbreviation of Vertical Blanking Interval, a gap in the
+sequence of lines of an analog video signal. During VBI no picture
+information is transmitted, allowing some time while the electron beam
+of a cathode ray tube TV returns to the top of the screen. Using an
+oscilloscope you will find here the vertical synchronization pulses and
+short data packages ASK modulated [1]_ onto the video signal. These are
+transmissions of services such as Teletext or Closed Caption.
+
+Subject of this interface type is raw VBI data, as sampled off a video
+signal, or to be added to a signal for output. The data format is
+similar to uncompressed video images, a number of lines times a number
+of samples per line, we call this a VBI image.
+
+Conventionally V4L2 VBI devices are accessed through character device
+special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31``
+with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is
+typically a symbolic link to the preferred VBI device. This convention
+applies to both input and output devices.
+
+To address the problems of finding related video and VBI devices VBI
+capturing and output is also available as device function under
+``/dev/video``. To capture or output raw VBI data with these devices
+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
+=====================
+
+Devices supporting the raw VBI capturing or output API set the
+``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively,
+in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. At least one of the
+read/write, streaming or asynchronous I/O methods must be supported. VBI
+devices may or may not have a tuner or modulator.
+
+
+Supplemental Functions
+======================
+
+VBI devices shall support :ref:`video input or output <video>`,
+:ref:`tuner or modulator <tuner>`, and :ref:`controls <control>`
+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
+==========================
+
+Raw VBI sampling abilities can vary, in particular the sampling
+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>`
+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
+parameters and then checking if the actual parameters are suitable.
+
+To query the current raw VBI capture parameters applications set the
+``type`` field of a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call
+the :ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl with a pointer to this
+structure. Drivers fill the struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``vbi`` member of the
+``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of ``VIDIOC_G_FMT``, and call the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
+ioctl with a pointer to this structure. Drivers return an EINVAL error
+code only when the given parameters are ambiguous, otherwise they modify
+the parameters according to the hardware capabilities and return the
+actual parameters. When the driver allocates resources at this point, it
+may return an EBUSY error code to indicate the returned parameters are
+valid but the required resources are currently not available. That may
+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 <vidioc-streamon>` ioctl and the first read(),
+write() and select() call.
+
+VBI devices must implement both the ``VIDIOC_G_FMT`` and
+``VIDIOC_S_FMT`` ioctl, even if ``VIDIOC_S_FMT`` ignores all requests
+and always returns default parameters as ``VIDIOC_G_FMT`` does.
+``VIDIOC_TRY_FMT`` is optional.
+
+
+.. _v4l2-vbi-format:
+
+.. flat-table:: struct v4l2_vbi_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``sampling_rate``
+
+ - Samples per second, i. e. unit 1 Hz.
+
+ - .. row 2
+
+ - __u32
+
+ - ``offset``
+
+ - Horizontal offset of the VBI image, relative to the leading edge
+ of the line synchronization pulse and counted in samples: The
+ first sample in the VBI image will be located ``offset`` /
+ ``sampling_rate`` seconds following the leading edge. See also
+ :ref:`vbi-hsync`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``samples_per_line``
+
+ -
+
+ - .. row 4
+
+ - __u32
+
+ - ``sample_format``
+
+ - Defines the sample format as in :ref:`pixfmt`, a
+ four-character-code. [2]_ Usually this is ``V4L2_PIX_FMT_GREY``,
+ i. e. each sample consists of 8 bits with lower values oriented
+ towards the black level. Do not assume any other correlation of
+ values with the signal level. For example, the MSB does not
+ necessarily indicate if the signal is 'high' or 'low' because 128
+ may not be the mean value of the signal. Drivers shall not convert
+ the sample format by software.
+
+ - .. row 5
+
+ - __u32
+
+ - ``start``\ [2]
+
+ - This is the scanning system line number associated with the first
+ line of the VBI image, of the first and the second field
+ respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid
+ values. The ``V4L2_VBI_ITU_525_F1_START``,
+ ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and
+ ``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers
+ for each field for each 525 or 625 line format as a convenience.
+ Don't forget that ITU line numbering starts at 1, not 0. VBI input
+ drivers can return start values 0 if the hardware cannot reliable
+ identify scanning lines, VBI acquisition may not require this
+ information.
+
+ - .. row 6
+
+ - __u32
+
+ - ``count``\ [2]
+
+ - The number of lines in the first and second field image,
+ respectively.
+
+ - .. row 7
+
+ - :cspan:`2`
+
+ Drivers should be as flexibility as possible. For example, it may
+ be possible to extend or move the VBI capture window down to the
+ picture area, implementing a 'full field mode' to capture data
+ service transmissions embedded in the picture.
+
+ An application can set the first or second ``count`` value to zero
+ if no data is required from the respective field; ``count``\ [1]
+ if the scanning system is progressive, i. e. not interlaced. The
+ corresponding start value shall be ignored by the application and
+ driver. Anyway, drivers may not support single field capturing and
+ return both count values non-zero.
+
+ Both ``count`` values set to zero, or line numbers outside the
+ bounds depicted in :ref:`vbi-525` and :ref:`vbi-625`, or a
+ field image covering lines of two fields, are invalid and shall
+ not be returned by the driver.
+
+ To initialize the ``start`` and ``count`` fields, applications
+ must first determine the current video standard selection. The
+ :ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field
+ of struct :ref:`v4l2_standard <v4l2-standard>` can be evaluated
+ for this purpose.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - See :ref:`vbifmt-flags` below. Currently only drivers set flags,
+ applications must set this field to zero.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - This array is reserved for future extensions. Drivers and
+ applications must set it to zero.
+
+
+
+.. _vbifmt-flags:
+
+.. flat-table:: Raw VBI Format Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_VBI_UNSYNC``
+
+ - 0x0001
+
+ - This flag indicates hardware which does not properly distinguish
+ between fields. Normally the VBI image stores the first field
+ (lower scanning line numbers) first in memory. This may be a top
+ or bottom field depending on the video standard. When this flag is
+ set the first or second field may be stored first, however the
+ fields are still in correct temporal order with the older field
+ first in memory. [3]_
+
+ - .. row 2
+
+ - ``V4L2_VBI_INTERLACED``
+
+ - 0x0002
+
+ - By default the two field images will be passed sequentially; all
+ lines of the first field followed by all lines of the second field
+ (compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and
+ ``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in
+ memory depends on the video standard). When this flag is set, the
+ two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The
+ first line of the first field followed by the first line of the
+ second field, then the two second lines, and so on. Such a layout
+ may be necessary when the hardware has been programmed to capture
+ or output interlaced video images and is unable to separate the
+ fields for VBI capturing at the same time. For simplicity setting
+ this flag implies that both ``count`` values are equal and
+ non-zero.
+
+
+
+.. _vbi-hsync:
+
+.. figure:: dev-raw-vbi_files/vbi_hsync.*
+ :alt: vbi_hsync.pdf / vbi_hsync.gif
+ :align: center
+
+ Line synchronization
+
+ Line synchronization diagram
+
+
+
+
+.. _vbi-525:
+
+.. figure:: dev-raw-vbi_files/vbi_525.*
+ :alt: vbi_525.pdf / vbi_525.gif
+ :align: center
+
+ ITU-R 525 line numbering (M/NTSC and M/PAL)
+
+ NTSC field synchronization diagram
+
+
+
+
+.. _vbi-625:
+
+.. figure:: dev-raw-vbi_files/vbi_625.*
+ :alt: vbi_625.pdf / vbi_625.gif
+ :align: center
+
+ ITU-R 625 line numbering
+
+ PAL/SECAM field synchronization diagram
+
+
+
+Remember the VBI image format depends on the selected video standard,
+therefore the application must choose a new standard or query the
+current standard first. Attempts to read or write data ahead of format
+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
+==============================
+
+To assure synchronization with the field number and easier
+implementation, the smallest unit of data passed at a time is one frame,
+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
+
+The sample size is most likely always one byte, applications must check
+the ``sample_format`` field though, to function properly with other
+drivers.
+
+A VBI device may support :ref:`read/write <rw>` and/or streaming
+(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
+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 read(), write() and 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.
+
+.. [1]
+ ASK: Amplitude-Shift Keying. A high signal level represents a '1'
+ bit, a low level a '0' bit.
+
+.. [2]
+ A few devices may be unable to sample VBI data at all but can extend
+ the video capture window to the VBI region.
+
+.. [3]
+ Most VBI services transmit on both fields, but some have different
+ semantics depending on the field number. These cannot be reliable
+ decoded or encoded when ``V4L2_VBI_UNSYNC`` is set.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _rds:
+
+*************
+RDS Interface
+*************
+
+The Radio Data System transmits supplementary information in binary
+format, for example the station name or travel information, on an
+inaudible audio subcarrier of a radio program. This interface is aimed
+at devices capable of receiving and/or transmitting RDS information.
+
+For more information see the core RDS standard :ref:`iec62106` and the
+RBDS standard :ref:`nrsc4`.
+
+Note that the RBDS standard as is used in the USA is almost identical to
+the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only
+some of the fields have slightly different meanings. See the RBDS
+standard for more information.
+
+The RBDS standard also specifies support for MMBS (Modified Mobile
+Search). This is a proprietary format which seems to be discontinued.
+The RDS interface does not support this format. Should support for MMBS
+(or the so-called 'E blocks' in general) be needed, then please contact
+the linux-media mailing list:
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the RDS capturing API set the
+``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. Any tuner that
+supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
+``capability`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`. If the
+driver only passes RDS blocks without interpreting the data the
+``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see
+:ref:`Reading RDS data <reading-rds-data>`. For future use the flag
+``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver
+for a radio tuner with this capability does not yet exist, so if you are
+planning to write such a driver you should discuss this on the
+linux-media mailing list:
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+
+Whether an RDS signal is present can be detected by looking at the
+``rxsubchans`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`: the
+``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected.
+
+Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT``
+flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. Any modulator that
+supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
+``capability`` field of struct
+:ref:`v4l2_modulator <v4l2-modulator>`. In order to enable the RDS
+transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the
+``txsubchans`` field of struct
+:ref:`v4l2_modulator <v4l2-modulator>`. If the driver only passes RDS
+blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
+flag has to be set. If the tuner is capable of handling RDS entities
+like program identification codes and radio text, the flag
+``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see
+: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
+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
+three bytes, as follows:
+
+
+RDS datastructures
+==================
+
+
+.. _v4l2-rds-data:
+
+.. flat-table:: struct v4l2_rds_data
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 5
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``lsb``
+
+ - Least Significant Byte of RDS Block
+
+ - .. row 2
+
+ - __u8
+
+ - ``msb``
+
+ - Most Significant Byte of RDS Block
+
+ - .. row 3
+
+ - __u8
+
+ - ``block``
+
+ - Block description
+
+
+
+.. _v4l2-rds-block:
+
+.. flat-table:: Block description
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 5
+
+
+ - .. row 1
+
+ - Bits 0-2
+
+ - Block (aka offset) of the received data.
+
+ - .. row 2
+
+ - Bits 3-5
+
+ - Deprecated. Currently identical to bits 0-2. Do not use these
+ bits.
+
+ - .. row 3
+
+ - Bit 6
+
+ - Corrected bit. Indicates that an error was corrected for this data
+ block.
+
+ - .. row 4
+
+ - Bit 7
+
+ - Error bit. Indicates that an uncorrectable error occurred during
+ reception of this block.
+
+
+
+.. _v4l2-rds-block-codes:
+
+.. flat-table:: Block defines
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 5
+
+
+ - .. row 1
+
+ - V4L2_RDS_BLOCK_MSK
+
+ -
+ - 7
+
+ - Mask for bits 0-2 to get the block ID.
+
+ - .. row 2
+
+ - V4L2_RDS_BLOCK_A
+
+ -
+ - 0
+
+ - Block A.
+
+ - .. row 3
+
+ - V4L2_RDS_BLOCK_B
+
+ -
+ - 1
+
+ - Block B.
+
+ - .. row 4
+
+ - V4L2_RDS_BLOCK_C
+
+ -
+ - 2
+
+ - Block C.
+
+ - .. row 5
+
+ - V4L2_RDS_BLOCK_D
+
+ -
+ - 3
+
+ - Block D.
+
+ - .. row 6
+
+ - V4L2_RDS_BLOCK_C_ALT
+
+ -
+ - 4
+
+ - Block C'.
+
+ - .. row 7
+
+ - V4L2_RDS_BLOCK_INVALID
+
+ - read-only
+
+ - 7
+
+ - An invalid block.
+
+ - .. row 8
+
+ - V4L2_RDS_BLOCK_CORRECTED
+
+ - read-only
+
+ - 0x40
+
+ - A bit error was detected but corrected.
+
+ - .. row 9
+
+ - V4L2_RDS_BLOCK_ERROR
+
+ - read-only
+
+ - 0x80
+
+ - An uncorrectable error occurred.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sdr:
+
+**************************************
+Software Defined Radio Interface (SDR)
+**************************************
+
+SDR is an abbreviation of Software Defined Radio, the radio device which
+uses application software for modulation or demodulation. This interface
+is intended for controlling and data streaming of such devices.
+
+SDR devices are accessed through character device special files named
+``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and
+dynamically allocated minor numbers 0 to 255.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the SDR receiver interface set the
+``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. That flag means the
+device has an Analog to Digital Converter (ADC), which is a mandatory
+element for the SDR receiver.
+
+Devices supporting the SDR transmitter interface set the
+``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. That flag means 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
+must be supported.
+
+
+Supplemental Functions
+======================
+
+SDR devices can support :ref:`controls <control>`, and must support
+the :ref:`tuner <tuner>` ioctls. Tuner ioctls are used for setting the
+ADC/DAC sampling rate (sampling frequency) and the possible radio
+frequency (RF).
+
+The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC
+frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting
+radio frequency. The tuner index of the RF tuner (if any) must always
+follow the SDR tuner index. Normally the SDR tuner is #0 and the RF
+tuner is #1.
+
+The :ref:`VIDIOC_S_HW_FREQ_SEEK <vidioc-s-hw-freq-seek>` ioctl is
+not supported.
+
+
+Data Format Negotiation
+=======================
+
+The SDR device uses the :ref:`format <format>` ioctls to select the
+capture and output format. Both the sampling resolution and the data
+streaming format are bound to that selectable format. In addition to the
+basic :ref:`format <format>` ioctls, the
+:ref:`VIDIOC_ENUM_FMT <vidioc-enum-fmt>` ioctl must be supported as
+well.
+
+To use the :ref:`format <format>` ioctls applications set the ``type``
+field of a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use
+the struct :ref:`v4l2_sdr_format <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
+struct :ref:`v4l2_sdr_format <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
+data transfer, set by the driver in order to inform application.
+
+
+.. _v4l2-sdr-format:
+
+.. flat-table:: struct v4l2_sdr_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The data format or type of compression, set by the application.
+ This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR
+ formats in :ref:`sdr-formats`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``buffersize``
+
+ - Maximum size in bytes required for data. Value is set by the
+ driver.
+
+ - .. row 3
+
+ - __u8
+
+ - ``reserved[24]``
+
+ - This array is reserved for future extensions. Drivers and
+ applications must set it to zero.
+
+
+An SDR device may support :ref:`read/write <rw>` and/or streaming
+(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sliced:
+
+*************************
+Sliced VBI Data Interface
+*************************
+
+VBI stands for Vertical Blanking Interval, a gap in the sequence of
+lines of an analog video signal. During VBI no picture information is
+transmitted, allowing some time while the electron beam of a cathode ray
+tube TV returns to the top of the screen.
+
+Sliced VBI devices use hardware to demodulate data transmitted in the
+VBI. V4L2 drivers shall *not* do this by software, see also the
+:ref:`raw VBI interface <raw-vbi>`. The data is passed as short
+packets of fixed size, covering one scan line each. The number of
+packets per video frame is variable.
+
+Sliced VBI capture and output devices are accessed through the same
+character special files as raw VBI devices. When a driver supports both
+interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI
+capturing or output, and the sliced VBI function is only available after
+calling the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl as defined
+below. Likewise a ``/dev/video`` device may support the sliced VBI API,
+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
+=====================
+
+Devices supporting the sliced VBI capturing or output API set the
+``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag
+respectively, in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. At least one of the
+read/write, streaming or asynchronous :ref:`I/O methods <io>` must be
+supported. Sliced VBI devices may have a tuner or modulator.
+
+
+Supplemental Functions
+======================
+
+Sliced VBI devices shall support :ref:`video input or output <video>`
+and :ref:`tuner or modulator <tuner>` ioctls if they have these
+capabilities, and they may support :ref:`control <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
+=============================
+
+To find out which data services are supported by the hardware
+applications can call the
+:ref:`VIDIOC_G_SLICED_VBI_CAP <vidioc-g-sliced-vbi-cap>` ioctl.
+All drivers implementing the sliced VBI interface must support this
+ioctl. The results may differ from those of the
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl when the number of VBI
+lines the hardware can capture or output per frame, or the number of
+services it can identify on a given line are limited. For example on PAL
+line 16 the hardware may be able to look for a VPS or Teletext signal,
+but not both at the same time.
+
+To determine the currently selected services applications set the
+``type`` field of struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
+``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl fills the ``fmt.sliced``
+member, a struct
+:ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`.
+
+Applications can request different parameters by initializing or
+modifying the ``fmt.sliced`` member and calling the
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl with a pointer to the
+:c:type:`struct v4l2_format` structure.
+
+The sliced VBI API is more complicated than the raw VBI API because the
+hardware must be told which VBI service to expect on each scan line. Not
+all services may be supported by the hardware on all lines (this is
+especially true for VBI output where Teletext is often unsupported and
+other services can only be inserted in one specific line). In many
+cases, however, it is sufficient to just set the ``service_set`` field
+to the required services and let the driver fill the ``service_lines``
+array according to hardware capabilities. Only if more precise control
+is needed should the programmer set the ``service_lines`` array
+explicitly.
+
+The :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl modifies the parameters
+according to hardware capabilities. When the driver allocates resources
+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 <vidioc-streamon>` ioctl and the first
+:ref:`read() <func-read>`, :ref:`write() <func-write>` and
+:ref:`select() <func-select>` call.
+
+
+.. _v4l2-sliced-vbi-format:
+
+.. flat-table:: struct v4l2_sliced_vbi_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 3 2 2 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``service_set``
+
+ - :cspan:`2`
+
+ If ``service_set`` is non-zero when passed with
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` or
+ :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>`, the ``service_lines``
+ array will be filled by the driver according to the services
+ specified in this field. For example, if ``service_set`` is
+ initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``,
+ a driver for the cx25840 video decoder sets lines 7-22 of both
+ fields [1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first
+ field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to
+ zero, then the values of ``service_lines`` will be used instead.
+
+ On return the driver sets this field to the union of all elements
+ of the returned ``service_lines`` array. It may contain less
+ services than requested, perhaps just one, if the hardware cannot
+ handle more services simultaneously. It may be empty (zero) if
+ none of the requested services are supported by the hardware.
+
+ - .. row 2
+
+ - __u16
+
+ - ``service_lines``\ [2][24]
+
+ - :cspan:`2`
+
+ Applications initialize this array with sets of data services the
+ driver shall look for or insert on the respective scan line.
+ Subject to hardware capabilities drivers return the requested set,
+ a subset, which may be just a single service, or an empty set.
+ When the hardware cannot handle multiple services on the same line
+ the driver shall choose one. No assumptions can be made on which
+ service the driver chooses.
+
+ Data services are defined in :ref:`vbi-services2`. Array indices
+ map to ITU-R line numbers (see also :ref:`vbi-525` and
+ :ref:`vbi-625`) as follows:
+
+ - .. row 3
+
+ -
+ -
+ - Element
+
+ - 525 line systems
+
+ - 625 line systems
+
+ - .. row 4
+
+ -
+ -
+ - ``service_lines``\ [0][1]
+
+ - 1
+
+ - 1
+
+ - .. row 5
+
+ -
+ -
+ - ``service_lines``\ [0][23]
+
+ - 23
+
+ - 23
+
+ - .. row 6
+
+ -
+ -
+ - ``service_lines``\ [1][1]
+
+ - 264
+
+ - 314
+
+ - .. row 7
+
+ -
+ -
+ - ``service_lines``\ [1][23]
+
+ - 286
+
+ - 336
+
+ - .. row 8
+
+ -
+ -
+ - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
+ ``service_lines``\ [1][0] to zero. The
+ ``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``,
+ ``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START``
+ defines give the start line numbers for each field for each 525 or
+ 625 line format as a convenience. Don't forget that ITU line
+ numbering starts at 1, not 0.
+
+ - .. row 9
+
+ - __u32
+
+ - ``io_size``
+
+ - :cspan:`2` Maximum number of bytes passed by one
+ :ref:`read() <func-read>` or :ref:`write() <func-write>` call,
+ and the buffer size in bytes for the
+ :ref:`VIDIOC_QBUF <vidioc-qbuf>` and
+ :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl. Drivers set this field
+ to the size of struct
+ :ref:`v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` times the
+ number of non-zero elements in the returned ``service_lines``
+ array (that is the number of lines potentially carrying data).
+
+ - .. row 10
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - :cspan:`2` This array is reserved for future extensions.
+ Applications and drivers must set it to zero.
+
+
+
+.. _vbi-services2:
+
+.. flat-table:: Sliced VBI services
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 2 1 1 2 2
+
+
+ - .. row 1
+
+ - Symbol
+
+ - Value
+
+ - Reference
+
+ - Lines, usually
+
+ - Payload
+
+ - .. row 2
+
+ - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
+
+ - 0x0001
+
+ - :ref:`ets300706`, :ref:`itu653`
+
+ - PAL/SECAM line 7-22, 320-335 (second field 7-22)
+
+ - Last 42 of the 45 byte Teletext packet, that is without clock
+ run-in and framing code, lsb first transmitted.
+
+ - .. row 3
+
+ - ``V4L2_SLICED_VPS``
+
+ - 0x0400
+
+ - :ref:`ets300231`
+
+ - PAL line 16
+
+ - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
+ first transmitted.
+
+ - .. row 4
+
+ - ``V4L2_SLICED_CAPTION_525``
+
+ - 0x1000
+
+ - :ref:`cea608`
+
+ - NTSC line 21, 284 (second field 21)
+
+ - Two bytes in transmission order, including parity bit, lsb first
+ transmitted.
+
+ - .. row 5
+
+ - ``V4L2_SLICED_WSS_625``
+
+ - 0x4000
+
+ - :ref:`itu1119`, :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
+
+ - .. row 6
+
+ - ``V4L2_SLICED_VBI_525``
+
+ - 0x1000
+
+ - :cspan:`2` Set of services applicable to 525 line systems.
+
+ - .. row 7
+
+ - ``V4L2_SLICED_VBI_625``
+
+ - 0x4401
+
+ - :cspan:`2` Set of services applicable to 625 line systems.
+
+
+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
+after switching the video input (which may change the video standard as
+a side effect). The :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl may
+return an EBUSY error code when applications attempt to change the
+format while i/o is in progress (between a
+:ref:`VIDIOC_STREAMON <vidioc-streamon>` and
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>` call, and after the first
+:ref:`read() <func-read>` or :ref:`write() <func-write>` call).
+
+
+Reading and writing sliced VBI data
+===================================
+
+A single :ref:`read() <func-read>` or :ref:`write() <func-write>`
+call must pass all data belonging to one video frame. That is an array
+of :c:type:`struct v4l2_sliced_vbi_data` structures with one or
+more elements and a total size not exceeding ``io_size`` bytes. Likewise
+in streaming I/O mode one buffer of ``io_size`` bytes must contain data
+of one video frame. The ``id`` of unused
+:c:type:`struct v4l2_sliced_vbi_data` elements must be zero.
+
+
+.. _v4l2-sliced-vbi-data:
+
+.. flat-table:: struct v4l2_sliced_vbi_data
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - A flag from :ref:`vbi-services` identifying the type of data in
+ this packet. Only a single bit must be set. When the ``id`` of a
+ captured packet is zero, the packet is empty and the contents of
+ other fields are undefined. Applications shall ignore empty
+ packets. When the ``id`` of a packet for output is zero the
+ contents of the ``data`` field are undefined and the driver must
+ no longer insert data on the requested ``field`` and ``line``.
+
+ - .. row 2
+
+ - __u32
+
+ - ``field``
+
+ - The video field number this data has been captured from, or shall
+ be inserted at. ``0`` for the first field, ``1`` for the second
+ field.
+
+ - .. row 3
+
+ - __u32
+
+ - ``line``
+
+ - The field (as opposed to frame) line number this data has been
+ captured from, or shall be inserted at. See :ref:`vbi-525` and
+ :ref:`vbi-625` for valid values. Sliced VBI capture devices can
+ set the line number of all packets to ``0`` if the hardware cannot
+ reliably identify scan lines. The field number must always be
+ valid.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``
+
+ - This field is reserved for future extensions. Applications and
+ drivers must set it to zero.
+
+ - .. row 5
+
+ - __u8
+
+ - ``data``\ [48]
+
+ - The packet payload. See :ref:`vbi-services` for the contents and
+ number of bytes passed for each data type. The contents of padding
+ 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
+the :ref:`VIDIOC_QBUF <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
+number, or a combination of ``field``, ``line`` and ``id`` which has not
+been negotiated with the :ref:`VIDIOC_G_FMT <vidioc-g-fmt>` or
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl. When the line numbers are
+unknown the driver must pass the packets in transmitted order. The
+driver can insert empty packets with ``id`` set to zero anywhere in the
+packet array.
+
+To assure synchronization and to distinguish from frame dropping, when a
+captured frame does not carry any of the requested data services drivers
+must pass one or more empty packets. When an application fails to pass
+VBI data in time for output, the driver must output the last VPS and WSS
+packet again, and disable the output of Closed Caption and Teletext
+data, or output data which is ignored by Closed Caption and Teletext
+decoders.
+
+A sliced VBI device may support :ref:`read/write <rw>` and/or
+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
+===============================
+
+If a device can produce an MPEG output stream, it may be capable of
+providing
+:ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>`
+as data embedded in the MPEG stream. Users or applications control this
+sliced VBI data insertion with the
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control.
+
+If the driver does not provide the
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control, or only allows that control to be set to
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`,
+then the device cannot embed sliced VBI data in the MPEG stream.
+
+The
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control does not implicitly set the device driver to capture nor cease
+capturing sliced VBI data. The control only indicates to embed sliced
+VBI data in the MPEG stream, if an application has negotiated sliced VBI
+service be captured.
+
+It may also be the case that a device can embed sliced VBI data in only
+certain types of MPEG streams: for example in an MPEG-2 PS but not an
+MPEG-2 TS. In this situation, if sliced VBI data insertion is requested,
+the sliced VBI data will be embedded in MPEG stream types when
+supported, and silently omitted from MPEG stream types where sliced VBI
+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
+--------------------------------------------------
+
+The
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`
+embedded sliced VBI format shall be interpreted by drivers as a control
+to cease embedding sliced VBI data in MPEG streams. Neither the device
+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
+--------------------------------------------------
+
+The
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
+embedded sliced VBI format, when supported, indicates to the driver to
+embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private
+Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the
+MPEG stream.
+
+*Historical context*: This format specification originates from a
+custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
+This format has already been informally specified in the kernel sources
+in the file ``Documentation/video4linux/cx2341x/README.vbi`` . The
+maximum size of the payload and other aspects of this format are driven
+by the CX23415 MPEG decoder's capabilities and limitations with respect
+to extracting, decoding, and displaying sliced VBI data embedded within
+an MPEG stream.
+
+This format's use is *not* exclusive to the ``ivtv`` driver *nor*
+exclusive to CX2341x devices, as the sliced VBI data packet insertion
+into the MPEG stream is implemented in driver software. At least the
+``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in
+this format as well.
+
+The following definitions specify the payload of the MPEG-2 *Private
+Stream 1 PES* packets that contain sliced VBI data when
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
+is set. (The MPEG-2 *Private Stream 1 PES* packet header and
+encapsulating MPEG-2 *Program Pack* header are not detailed here. Please
+refer to the MPEG-2 specifications for details on those packet headers.)
+
+The payload of the MPEG-2 *Private Stream 1 PES* packets that contain
+sliced VBI data is specified by struct
+:ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>`. The
+payload is variable length, depending on the actual number of lines of
+sliced VBI data present in a video frame. The payload may be padded at
+the end with unspecified fill bytes to align the end of the payload to a
+4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
+with 18 lines/field with 43 bytes of data/line and a 4 byte magic
+number).
+
+
+.. _v4l2-mpeg-vbi-fmt-ivtv:
+
+.. flat-table:: struct v4l2_mpeg_vbi_fmt_ivtv
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``magic``\ [4]
+
+ -
+ - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that
+ indicates this is a valid sliced VBI data payload and also
+ indicates which member of the anonymous union, ``itv0`` or
+ ``ITV0``, to use for the payload data.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_mpeg_vbi_itv0 <v4l2-mpeg-vbi-itv0>`
+
+ - ``itv0``
+
+ - The primary form of the sliced VBI data payload that contains
+ anywhere from 1 to 35 lines of sliced VBI data. Line masks are
+ provided in this form of the payload indicating which VBI lines
+ are provided.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>`
+
+ - ``ITV0``
+
+ - 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.
+
+
+
+.. _v4l2-mpeg-vbi-fmt-ivtv-magic:
+
+.. flat-table:: Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Defined Symbol
+
+ - Value
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VBI_IVTV_MAGIC0``
+
+ - "itv0"
+
+ - Indicates the ``itv0`` member of the union in struct
+ :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
+ valid.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VBI_IVTV_MAGIC1``
+
+ - "ITV0"
+
+ - Indicates the ``ITV0`` member of the union in struct
+ :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
+ valid and that 36 lines of sliced VBI data are present.
+
+
+
+.. _v4l2-mpeg-vbi-itv0:
+
+.. flat-table:: struct v4l2_mpeg_vbi_itv0
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __le32
+
+ - ``linemask``\ [2]
+
+ - Bitmasks indicating the VBI service lines present. These
+ ``linemask`` values are stored in little endian byte order in the
+ MPEG stream. Some reference ``linemask`` bit positions with their
+ corresponding VBI line number and video field are given below.
+ b\ :sub:`0` indicates the least significant bit of a ``linemask``
+ value:
+
+
+
+ ::
+
+ linemask[0] b0: line 6 first field
+ linemask[0] b17: line 23 first field
+ linemask[0] b18: line 6 second field
+ linemask[0] b31: line 19 second field
+ linemask[1] b0: line 20 second field
+ linemask[1] b3: line 23 second field
+ linemask[1] b4-b31: unused and set to 0
+
+ - .. row 2
+
+ - struct
+ :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
+
+ - ``line``\ [35]
+
+ - This is a variable length array that holds from 1 to 35 lines of
+ sliced VBI data. The sliced VBI data lines present correspond to
+ the bits set in the ``linemask`` array, starting from b\ :sub:`0`
+ of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0],
+ and from b\ :sub:`0` of ``linemask``\ [1] up through b :sub:`3` of
+ ``linemask``\ [1]. ``line``\ [0] corresponds to the first bit
+ found set in the ``linemask`` array, ``line``\ [1] corresponds to
+ the second bit found set in the ``linemask`` array, etc. If no
+ ``linemask`` array bits are set, then ``line``\ [0] may contain
+ one line of unspecified data that should be ignored by
+ applications.
+
+
+
+.. _v4l2-mpeg-vbi-itv0-1:
+
+.. flat-table:: struct v4l2_mpeg_vbi_ITV0
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct
+ :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
+
+ - ``line``\ [36]
+
+ - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0]
+ through ``line``\ [17] correspond to lines 6 through 23 of the
+ first field. ``line``\ [18] through ``line``\ [35] corresponds to
+ lines 6 through 23 of the second field.
+
+
+
+.. _v4l2-mpeg-vbi-itv0-line:
+
+.. flat-table:: struct v4l2_mpeg_vbi_itv0_line
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``id``
+
+ - A line identifier value from
+ :ref:`ITV0-Line-Identifier-Constants` that indicates the type of
+ sliced VBI data stored on this line.
+
+ - .. row 2
+
+ - __u8
+
+ - ``data``\ [42]
+
+ - The sliced VBI data for the line.
+
+
+
+.. _ITV0-Line-Identifier-Constants:
+
+.. flat-table:: Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Defined Symbol
+
+ - Value
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B``
+
+ - 1
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VBI_IVTV_CAPTION_525``
+
+ - 4
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VBI_IVTV_WSS_625``
+
+ - 5
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VBI_IVTV_VPS``
+
+ - 7
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+
+
+.. [1]
+ 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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _subdev:
+
+********************
+Sub-device Interface
+********************
+
+The complex nature of V4L2 devices, where hardware is often made of
+several integrated circuits that need to interact with each other in a
+controlled way, leads to complex V4L2 drivers. The drivers usually
+reflect the hardware model in software, and model the different hardware
+components as software blocks called sub-devices.
+
+V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
+implements the media device API, they will automatically inherit from
+media entities. Applications will be able to enumerate the sub-devices
+and discover the hardware topology using the media entities, pads and
+links enumeration API.
+
+In addition to make sub-devices discoverable, drivers can also choose to
+make them directly configurable by applications. When both the
+sub-device driver and the V4L2 device driver support this, sub-devices
+will feature a character device node on which ioctls can be called to
+
+- query, read and write sub-devices controls
+
+- subscribe and unsubscribe to events and retrieve them
+
+- negotiate image formats on individual pads
+
+Sub-device character device nodes, conventionally named
+``/dev/v4l-subdev*``, use major number 81.
+
+
+Controls
+========
+
+Most V4L2 controls are implemented by sub-device hardware. Drivers
+usually merge all controls and expose them through video device nodes.
+Applications can control all sub-devices through a single interface.
+
+Complex devices sometimes implement the same control in different pieces
+of hardware. This situation is common in embedded platforms, where both
+sensors and image processing hardware implement identical functions,
+such as contrast adjustment, white balance or faulty pixels correction.
+As the V4L2 controls API doesn't support several identical controls in a
+single device, all but one of the identical controls are hidden.
+
+Applications can access those hidden controls through the sub-device
+node with the V4L2 control API described in :ref:`control`. The ioctls
+behave identically as when issued on V4L2 device nodes, with the
+exception that they deal only with controls implemented in the
+sub-device.
+
+Depending on the driver, those controls might also be exposed through
+one (or several) V4L2 device nodes.
+
+
+Events
+======
+
+V4L2 sub-devices can notify applications of events as described in
+:ref:`event`. The API behaves identically as when used on V4L2 device
+nodes, with the exception that it only deals with events generated by
+the sub-device. Depending on the driver, those events might also be
+reported on one (or several) V4L2 device nodes.
+
+
+.. _pad-level-formats:
+
+Pad-level Formats
+=================
+
+ **Warning**
+
+ Pad-level formats are only applicable to very complex device that
+ need to expose low-level format configuration to user space. Generic
+ V4L2 applications do *not* need to use the API described in this
+ section.
+
+ **Note**
+
+ For the purpose of this section, the term *format* means the
+ combination of media bus data format, frame width and frame height.
+
+Image formats are typically negotiated on video capture and output
+devices using the format and
+:ref:`selection <vidioc-subdev-g-selection>` ioctls. The driver is
+responsible for configuring every block in the video pipeline according
+to the requested format at the pipeline input and/or output.
+
+For complex devices, such as often found in embedded systems, identical
+image sizes at the output of a pipeline can be achieved using different
+hardware configurations. One such example is shown on
+:ref:`pipeline-scaling`, where image scaling can be performed on both
+the video sensor and the host image processing hardware.
+
+
+.. _pipeline-scaling:
+
+.. figure:: dev-subdev_files/pipeline.*
+ :alt: pipeline.pdf / pipeline.png
+ :align: center
+
+ Image Format Negotiation on Pipelines
+
+ High quality and high speed pipeline configuration
+
+
+
+The sensor scaler is usually of less quality than the host scaler, but
+scaling on the sensor is required to achieve higher frame rates.
+Depending on the use case (quality vs. speed), the pipeline must be
+configured differently. Applications need to configure the formats at
+every point in the pipeline explicitly.
+
+Drivers that implement the :ref:`media API <media-controller-intro>`
+can expose pad-level image format configuration to applications. When
+they do, applications can use the
+:ref:`VIDIOC_SUBDEV_G_FMT <vidioc-subdev-g-fmt>` and
+:ref:`VIDIOC_SUBDEV_S_FMT <vidioc-subdev-g-fmt>` ioctls. to
+negotiate formats on a per-pad basis.
+
+Applications are responsible for configuring coherent parameters on the
+whole pipeline and making sure that connected pads have compatible
+formats. The pipeline is checked for formats mismatch at
+:ref:`VIDIOC_STREAMON <vidioc-streamon>` time, and an EPIPE error
+code is then returned if the configuration is invalid.
+
+Pad-level image format configuration support can be tested by calling
+the :ref:`VIDIOC_SUBDEV_G_FMT <vidioc-subdev-g-fmt>` ioctl on pad
+0. If the driver returns an EINVAL error code pad-level format
+configuration is not supported by the sub-device.
+
+
+Format Negotiation
+------------------
+
+Acceptable formats on pads can (and usually do) depend on a number of
+external parameters, such as formats on other pads, active links, or
+even controls. Finding a combination of formats on all pads in a video
+pipeline, acceptable to both application and driver, can't rely on
+formats enumeration only. A format negotiation mechanism is required.
+
+Central to the format negotiation mechanism are the get/set format
+operations. When called with the ``which`` argument set to
+``V4L2_SUBDEV_FORMAT_TRY``, the
+:ref:`VIDIOC_SUBDEV_G_FMT <vidioc-subdev-g-fmt>` and
+:ref:`VIDIOC_SUBDEV_S_FMT <vidioc-subdev-g-fmt>` ioctls operate on
+a set of formats parameters that are not connected to the hardware
+configuration. Modifying those 'try' formats leaves the device state
+untouched (this applies to both the software state stored in the driver
+and the hardware state stored in the device itself).
+
+While not kept as part of the device state, try formats are stored in
+the sub-device file handles. A
+:ref:`VIDIOC_SUBDEV_G_FMT <vidioc-subdev-g-fmt>` call will return
+the last try format set *on the same sub-device file handle*. Several
+applications querying the same sub-device at the same time will thus not
+interact with each other.
+
+To find out whether a particular format is supported by the device,
+applications use the
+:ref:`VIDIOC_SUBDEV_S_FMT <vidioc-subdev-g-fmt>` ioctl. Drivers
+verify and, if needed, change the requested ``format`` based on device
+requirements and return the possibly modified value. Applications can
+then choose to try a different format or accept the returned value and
+continue.
+
+Formats returned by the driver during a negotiation iteration are
+guaranteed to be supported by the device. In particular, drivers
+guarantee that a returned format will not be further changed if passed
+to an :ref:`VIDIOC_SUBDEV_S_FMT <vidioc-subdev-g-fmt>` call as-is
+(as long as external parameters, such as formats on other pads or links'
+configuration are not changed).
+
+Drivers automatically propagate formats inside sub-devices. When a try
+or active format is set on a pad, corresponding formats on other pads of
+the same sub-device can be modified by the driver. Drivers are free to
+modify formats as required by the device. However, they should comply
+with the following rules when possible:
+
+- Formats should be propagated from sink pads to source pads. Modifying
+ a format on a source pad should not modify the format on any sink
+ pad.
+
+- Sub-devices that scale frames using variable scaling factors should
+ reset the scale factors to default values when sink pads formats are
+ modified. If the 1:1 scaling ratio is supported, this means that
+ source pads formats should be reset to the sink pads formats.
+
+Formats are not propagated across links, as that would involve
+propagating them from one sub-device file handle to another.
+Applications must then take care to configure both ends of every link
+explicitly with compatible formats. Identical formats on the two ends of
+a link are guaranteed to be compatible. Drivers are free to accept
+different formats matching device requirements as being compatible.
+
+:ref:`sample-pipeline-config` shows a sample configuration sequence
+for the pipeline described in :ref:`pipeline-scaling` (table columns
+list entity names and pad numbers).
+
+
+.. _sample-pipeline-config:
+
+.. flat-table:: Sample Pipeline Configuration
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - Sensor/0 format
+
+ - Frontend/0 format
+
+ - Frontend/1 format
+
+ - Scaler/0 format
+
+ - Scaler/0 compose selection rectangle
+
+ - Scaler/1 format
+
+ - .. row 2
+
+ - Initial state
+
+ - 2048x1536/SGRBG8_1X8
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - .. row 3
+
+ - Configure frontend sink format
+
+ - 2048x1536/SGRBG8_1X8
+
+ - *2048x1536/SGRBG8_1X8*
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - .. row 4
+
+ - Configure scaler sink format
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - *0,0/2046x1534*
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - .. row 5
+
+ - Configure scaler sink compose selection
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - *0,0/1280x960*
+
+ - *1280x960/SGRBG8_1X8*
+
+
+
+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
+ host frontend and scaler sink and source pads have the default
+ values, as well as the compose rectangle on the scaler's sink pad.
+
+2. The application configures the frontend sink pad format's size to
+ 2048x1536 and its media bus code to V4L2_MBUS_FMT_SGRBG_1X8. The
+ driver propagates the format to the frontend source pad.
+
+3. The application configures the scaler sink pad format's size to
+ 2046x1534 and the media bus code to V4L2_MBUS_FMT_SGRBG_1X8 to
+ match the frontend source size and media bus code. The media bus code
+ on the sink pad is set to V4L2_MBUS_FMT_SGRBG_1X8. The driver
+ propagates the size to the compose selection rectangle on the
+ scaler's sink pad, and the format to the scaler source pad.
+
+4. The application configures the size of the compose selection
+ rectangle of the scaler's sink pad 1280x960. The driver propagates
+ the size to the scaler's source pad format.
+
+When satisfied with the try results, applications can set the active
+formats by setting the ``which`` argument to
+``V4L2_SUBDEV_FORMAT_ACTIVE``. Active formats are changed exactly as try
+formats by drivers. To avoid modifying the hardware state during format
+negotiation, applications should negotiate try formats first and then
+modify the active settings using the try formats returned during the
+last negotiation iteration. This guarantees that the active format will
+be applied as-is by the driver without being modified.
+
+
+.. _v4l2-subdev-selections:
+
+Selections: cropping, scaling and composition
+---------------------------------------------
+
+Many sub-devices support cropping frames on their input or output pads
+(or possible even on both). Cropping is used to select the area of
+interest in an image, typically on an image sensor or a video decoder.
+It can also be used as part of digital zoom implementations to select
+the area of the image that will be scaled up.
+
+Crop settings are defined by a crop rectangle and represented in a
+struct :ref:`v4l2_rect <v4l2-rect>` by the coordinates of the top
+left corner and the rectangle size. Both the coordinates and sizes are
+expressed in pixels.
+
+As for pad formats, drivers store try and active rectangles for the
+selection targets :ref:`v4l2-selections-common`.
+
+On sink pads, cropping is applied relative to the current pad format.
+The pad format represents the image size as received by the sub-device
+from the previous block in the pipeline, and the crop rectangle
+represents the sub-image that will be transmitted further inside the
+sub-device for processing.
+
+The scaling operation changes the size of the image by scaling it to new
+dimensions. The scaling ratio isn't specified explicitly, but is implied
+from the original and scaled image sizes. Both sizes are represented by
+struct :ref:`v4l2_rect <v4l2-rect>`.
+
+Scaling support is optional. When supported by a subdev, the crop
+rectangle on the subdev's sink pad is scaled to the size configured
+using the
+:ref:`VIDIOC_SUBDEV_S_SELECTION <vidioc-subdev-g-selection>` IOCTL
+using ``V4L2_SEL_TGT_COMPOSE`` selection target on the same pad. If the
+subdev supports scaling but not composing, the top and left values are
+not used and must always be set to zero.
+
+On source pads, cropping is similar to sink pads, with the exception
+that the source size from which the cropping is performed, is the
+COMPOSE rectangle on the sink pad. In both sink and source pads, the
+crop rectangle must be entirely contained inside the source image size
+for the crop operation.
+
+The drivers should always use the closest possible rectangle the user
+requests on all selection targets, unless specifically told otherwise.
+``V4L2_SEL_FLAG_GE`` and ``V4L2_SEL_FLAG_LE`` flags may be used to round
+the image size either up or down. :ref:`v4l2-selection-flags`
+
+
+Types of selection targets
+--------------------------
+
+
+Actual targets
+^^^^^^^^^^^^^^
+
+Actual targets (without a postfix) reflect the actual hardware
+configuration at any point of time. There is a BOUNDS target
+corresponding to every actual target.
+
+
+BOUNDS targets
+^^^^^^^^^^^^^^
+
+BOUNDS targets is the smallest rectangle that contains all valid actual
+rectangles. It may not be possible to set the actual rectangle as large
+as the BOUNDS rectangle, however. This may be because e.g. a sensor's
+pixel array is not rectangular but cross-shaped or round. The maximum
+size may also be smaller than the BOUNDS rectangle.
+
+
+Order of configuration and format propagation
+---------------------------------------------
+
+Inside subdevs, the order of image processing steps will always be from
+the sink pad towards the source pad. This is also reflected in the order
+in which the configuration must be performed by the user: the changes
+made will be propagated to any subsequent stages. If this behaviour is
+not desired, the user must set ``V4L2_SEL_FLAG_KEEP_CONFIG`` flag. This
+flag causes no propagation of the changes are allowed in any
+circumstances. This may also cause the accessed rectangle to be adjusted
+by the driver, depending on the properties of the underlying hardware.
+
+The coordinates to a step always refer to the actual size of the
+previous step. The exception to this rule is the source compose
+rectangle, which refers to the sink compose bounds rectangle --- if it
+is supported by the hardware.
+
+1. Sink pad format. The user configures the sink pad format. This format
+ defines the parameters of the image the entity receives through the
+ pad for further processing.
+
+2. Sink pad actual crop selection. The sink pad crop defines the crop
+ performed to the sink pad format.
+
+3. Sink pad actual compose selection. The size of the sink pad compose
+ rectangle defines the scaling ratio compared to the size of the sink
+ pad crop rectangle. The location of the compose rectangle specifies
+ the location of the actual sink compose rectangle in the sink compose
+ bounds rectangle.
+
+4. Source pad actual crop selection. Crop on the source pad defines crop
+ performed to the image in the sink compose bounds rectangle.
+
+5. Source pad format. The source pad format defines the output pixel
+ format of the subdev, as well as the other parameters with the
+ exception of the image width and height. Width and height are defined
+ by the size of the source pad actual crop selection.
+
+Accessing any of the above rectangles not supported by the subdev will
+return ``EINVAL``. Any rectangle referring to a previous unsupported
+rectangle coordinates will instead refer to the previous supported
+rectangle. For example, if sink crop is not supported, the compose
+selection will refer to the sink pad format dimensions instead.
+
+
+.. _subdev-image-processing-crop:
+
+.. figure:: dev-subdev_files/subdev-image-processing-crop.*
+ :alt: subdev-image-processing-crop.svg
+ :align: center
+
+ Image processing in subdevs: simple crop example
+
+In the above example, the subdev supports cropping on its sink pad. To
+configure it, the user sets the media bus format on the subdev's sink
+pad. Now the actual crop rectangle can be set on the sink pad --- the
+location and size of this rectangle reflect the location and size of a
+rectangle to be cropped from the sink format. The size of the sink crop
+rectangle will also be the size of the format of the subdev's source
+pad.
+
+
+.. _subdev-image-processing-scaling-multi-source:
+
+.. figure:: dev-subdev_files/subdev-image-processing-scaling-multi-source.*
+ :alt: subdev-image-processing-scaling-multi-source.svg
+ :align: center
+
+ Image processing in subdevs: scaling with multiple sources
+
+In this example, the subdev is capable of first cropping, then scaling
+and finally cropping for two source pads individually from the resulting
+scaled image. The location of the scaled image in the cropped image is
+ignored in sink compose target. Both of the locations of the source crop
+rectangles refer to the sink scaling rectangle, independently cropping
+an area at location specified by the source crop rectangle from it.
+
+
+.. _subdev-image-processing-full:
+
+.. figure:: dev-subdev_files/subdev-image-processing-full.*
+ :alt: subdev-image-processing-full.svg
+ :align: center
+
+ Image processing in subdevs: scaling and composition with multiple sinks and sources
+
+The subdev driver supports two sink pads and two source pads. The images
+from both of the sink pads are individually cropped, then scaled and
+further composed on the composition bounds rectangle. From that, two
+independent streams are cropped and sent out of the subdev from the
+source pads.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ subdev-formats
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="43cm" height="10cm" viewBox="-194 128 844 196" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="469.774" height="193"/>
+ <g>
+ <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="63.5" y="211" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="63.5" y="211" width="94" height="77"/>
+ </g>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="74.5" y="227.75">
+ <tspan x="74.5" y="227.75">sink</tspan>
+ <tspan x="74.5" y="243.75">crop</tspan>
+ <tspan x="74.5" y="259.75">selection</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
+ <tspan x="29.5" y="158"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
+ <tspan x="8.53836" y="157.914">sink media</tspan>
+ <tspan x="8.53836" y="173.914">bus format</tspan>
+ </text>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="349.774" y="155">
+ <tspan x="349.774" y="155">source media</tspan>
+ <tspan x="349.774" y="171">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="350.488" y="190.834" width="93.2863" height="75.166"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="350.488" y="190.834" width="93.2863" height="75.166"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="266" x2="63.5" y2="288"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="190.834" x2="63.5" y2="211"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="266" x2="157.5" y2="288"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="190.834" x2="157.5" y2="211"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="481.6" y1="219.984" x2="637.934" y2="220.012"/>
+ <polygon style="fill: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="506.908" y="209.8">
+ <tspan x="506.908" y="209.8">pad 1 (source)</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
+ <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
+ <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
+ </text>
+</svg>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="59cm" height="18cm" viewBox="-186 71 1178 346" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <g>
+ <rect style="fill: #ffffff" x="318.9" y="129" width="208.1" height="249"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff765a" x="318.9" y="129" width="208.1" height="249"/>
+ </g>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-2" y="73" width="806" height="343"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <ellipse style="fill: #ffffff" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.5" y1="167" x2="-30.7361" y2="166.729"/>
+ <polygon style="fill: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.732" y1="205.184" x2="980.066" y2="205.212"/>
+ <polygon style="fill: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139.96" y="155">
+ <tspan x="-139.96" y="155">pad 0 (sink)</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.04" y="195">
+ <tspan x="849.04" y="195">pad 2 (source)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="5.5" y="120" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="5.5" y="120" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="62.5" y="136" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="62.5" y="136" width="94" height="77"/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="30.5" y="89">
+ <tspan x="30.5" y="89"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="9.53836" y="88.9138">
+ <tspan x="9.53836" y="88.9138">sink media</tspan>
+ <tspan x="9.53836" y="104.914">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="62.5" y2="213"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="62.5" y2="136"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="156.5" y2="213"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="156.5" y2="136"/>
+ <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
+ <tspan x="334.704" y="149.442">sink compose</tspan>
+ <tspan x="334.704" y="165.442">selection (scaling)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="409.322" y="194.565" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="409.322" y="194.565" width="100.186" height="71.4523"/>
+ </g>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="689.5" y="105.128">
+ <tspan x="689.5" y="105.128">source media</tspan>
+ <tspan x="689.5" y="121.128">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="688.488" y="173.834" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="688.488" y="173.834" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="245.286" x2="409.322" y2="266.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="173.834" x2="409.322" y2="194.565"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="245.286" x2="509.508" y2="266.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="173.834" x2="509.508" y2="194.565"/>
+ <text style="fill: #ff765a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="325" y="103">
+ <tspan x="325" y="103">sink compose</tspan>
+ <tspan x="325" y="119">bounds selection</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.098" y1="341.8" x2="-30.3343" y2="341.529"/>
+ <polygon style="fill: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139" y="329">
+ <tspan x="-139" y="329">pad 1 (sink)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="7.80824" y="292.8" width="112.092" height="82.2"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="7.80824" y="292.8" width="112.092" height="82.2"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="52.9" y="314.8" width="58.1" height="50.2"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="52.9" y="314.8" width="58.1" height="50.2"/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="31.9" y="259.8">
+ <tspan x="31.9" y="259.8"></tspan>
+ </text>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="251.9" x2="52.9" y2="314.8"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="316" x2="52.9" y2="365"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="316" x2="111" y2="365"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="251.9" x2="111" y2="314.8"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="358.9" y="251.9" width="75.1" height="64.1"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="443.262" y="284.466" width="64.738" height="48.534"/>
+ <g>
+ <rect style="fill: #ffffff" x="693.428" y="324.734" width="63.572" height="49.266"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="693.428" y="324.734" width="63.572" height="49.266"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="374" x2="443.262" y2="333"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="324.734" x2="443.262" y2="284.466"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="374" x2="508" y2="333"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="324.734" x2="508" y2="284.466"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.94" y1="343.984" x2="980.274" y2="344.012"/>
+ <polygon style="fill: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.248" y="333.8">
+ <tspan x="849.248" y="333.8">pad 3 (source)</tspan>
+ </text>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="197" y="91">
+ <tspan x="197" y="91">sink</tspan>
+ <tspan x="197" y="107">crop</tspan>
+ <tspan x="197" y="123">selection</tspan>
+ </text>
+ <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="553" y="95">
+ <tspan x="553" y="95">source</tspan>
+ <tspan x="553" y="111">crop</tspan>
+ <tspan x="553" y="127">selection</tspan>
+ </text>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="211" y1="132" x2="166.21" y2="135.287"/>
+ <polygon style="fill: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="209" y1="131" x2="115.581" y2="306.209"/>
+ <polygon style="fill: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.492" y1="133.214" x2="514.916" y2="186.469"/>
+ <polygon style="fill: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.072" y1="133.787" x2="510.618" y2="275.089"/>
+ <polygon style="fill: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
+ </g>
+</svg>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="59cm" height="17cm" viewBox="-194 128 1179 330" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="806" height="327"/>
+ <g>
+ <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="49.5" y="204" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="49.5" y="204" width="94" height="77"/>
+ </g>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="60" y="224">
+ <tspan x="60" y="224">sink</tspan>
+ <tspan x="60" y="240">crop</tspan>
+ <tspan x="60" y="256">selection</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
+ <tspan x="29.5" y="158"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
+ <tspan x="8.53836" y="157.914">sink media</tspan>
+ <tspan x="8.53836" y="173.914">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="49.5" y2="281"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="49.5" y2="204"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="143.5" y2="281"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="143.5" y2="204"/>
+ <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
+ <tspan x="334.704" y="149.442">sink compose</tspan>
+ <tspan x="334.704" y="165.442">selection (scaling)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="382.322" y="199.565" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="382.322" y="199.565" width="100.186" height="71.4523"/>
+ </g>
+ <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="543.322" y="149.442">
+ <tspan x="543.322" y="149.442">source</tspan>
+ <tspan x="543.322" y="165.442">crop</tspan>
+ <tspan x="543.322" y="181.442">selection</tspan>
+ </text>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="691.5" y="157.128">
+ <tspan x="691.5" y="157.128">source media</tspan>
+ <tspan x="691.5" y="173.128">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="690.488" y="225.834" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="690.488" y="225.834" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="297.286" x2="382.322" y2="271.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="225.834" x2="382.322" y2="199.565"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="297.286" x2="482.508" y2="271.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="225.834" x2="482.508" y2="199.565"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="816.6" y1="249.984" x2="972.934" y2="250.012"/>
+ <polygon style="fill: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="841.908" y="239.8">
+ <tspan x="841.908" y="239.8">pad 1 (source)</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
+ <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
+ <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
+ </text>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="389.822" y="276.666" width="100.186" height="71.4523"/>
+ <g>
+ <rect style="fill: #ffffff" x="689.988" y="345.934" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="689.988" y="345.934" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="417.386" x2="389.822" y2="348.118"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="345.934" x2="389.822" y2="276.666"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="417.386" x2="490.008" y2="348.118"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="345.934" x2="490.008" y2="276.666"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="814.1" y1="384.084" x2="970.434" y2="384.112"/>
+ <polygon style="fill: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="839.408" y="373.9">
+ <tspan x="839.408" y="373.9">pad 2 (source)</tspan>
+ </text>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546" y1="191" x2="492.157" y2="198.263"/>
+ <polygon style="fill: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546.908" y1="190.725" x2="495.383" y2="268.548"/>
+ <polygon style="fill: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
+ </g>
+</svg>
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ttx:
+
+******************
+Teletext Interface
+******************
+
+This interface was aimed at devices receiving and demodulating Teletext
+data [:ref:`ets300706`, :ref:`itu653`], evaluating the Teletext
+packages and storing formatted pages in cache memory. Such devices are
+usually implemented as microcontrollers with serial interface
+(I:sup:`2`\ C) and could be found on old TV cards, dedicated Teletext
+decoding cards and home-brew devices connected to the PC parallel port.
+
+The Teletext API was designed by Martin Buck. It was defined in the
+kernel header file ``linux/videotext.h``, the specification is available
+from
+`ftp://ftp.gwdg.de/pub/linux/misc/videotext/ <ftp://ftp.gwdg.de/pub/linux/misc/videotext/>`__.
+(Videotext is the name of the German public television Teletext
+service.)
+
+Eventually the Teletext API was integrated into the V4L API with
+character device file names ``/dev/vtx0`` to ``/dev/vtx31``, device
+major number 81, minor numbers 192 to 223.
+
+However, teletext decoders were quickly replaced by more generic VBI
+demodulators and those dedicated teletext decoders no longer exist. For
+many years the vtx devices were still around, even though nobody used
+them. So the decision was made to finally remove support for the
+Teletext API in kernel 2.6.37.
+
+Modern devices all use the :ref:`raw <raw-vbi>` or
+:ref:`sliced <sliced>` VBI API.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _devices:
+
+**********
+Interfaces
+**********
+
+
+.. toctree::
+ :maxdepth: 1
+
+ dev-capture
+ dev-overlay
+ dev-output
+ dev-osd
+ dev-codec
+ dev-effect
+ dev-raw-vbi
+ dev-sliced-vbi
+ dev-teletext
+ dev-radio
+ dev-rds
+ dev-sdr
+ dev-event
+ dev-subdev
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _diff-v4l:
+
+********************************
+Differences between V4L and V4L2
+********************************
+
+The Video For Linux API was first introduced in Linux 2.1 to unify and
+replace various TV and radio device related interfaces, developed
+independently by driver writers in prior years. Starting with Linux 2.5
+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
+===========================
+
+For compatibility reasons the character device file names recommended
+for V4L2 video capture, overlay, radio and raw vbi capture devices did
+not change from those used by V4L. They are listed in :ref:`devices`
+and below in :ref:`v4l-dev`.
+
+The teletext devices (minor range 192-223) have been removed in V4L2 and
+no longer exist. There is no hardware available anymore for handling
+pure teletext. Instead raw or sliced VBI is used.
+
+The V4L ``videodev`` module automatically assigns minor numbers to
+drivers in load order, depending on the registered device type. We
+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
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Device Type
+
+ - File Name
+
+ - Minor Numbers
+
+ - .. row 2
+
+ - Video capture and overlay
+
+ - ``/dev/video`` and ``/dev/bttv0``\ [1]_, ``/dev/video0`` to
+ ``/dev/video63``
+
+ - 0-63
+
+ - .. row 3
+
+ - Radio receiver
+
+ - ``/dev/radio``\ [2]_, ``/dev/radio0`` to ``/dev/radio63``
+
+ - 64-127
+
+ - .. row 4
+
+ - Raw VBI capture
+
+ - ``/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
+=====================
+
+The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>`.
+
+The ``name`` field in struct :c:type:`struct video_capability` became
+``card`` in struct :ref:`v4l2_capability <v4l2-capability>`, ``type``
+was replaced by ``capabilities``. Note V4L2 does not distinguish between
+device types like this, better think of basic video input, video output
+and radio devices supporting a set of related functions like video
+capturing, video overlay and VBI capturing. See :ref:`open` for an
+introduction.
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_capability` ``type``
+
+ - struct :ref:`v4l2_capability <v4l2-capability>`
+ ``capabilities`` flags
+
+ - Purpose
+
+ - .. row 2
+
+ - ``VID_TYPE_CAPTURE``
+
+ - ``V4L2_CAP_VIDEO_CAPTURE``
+
+ - The :ref:`video capture <capture>` interface is supported.
+
+ - .. row 3
+
+ - ``VID_TYPE_TUNER``
+
+ - ``V4L2_CAP_TUNER``
+
+ - The device has a :ref:`tuner or modulator <tuner>`.
+
+ - .. row 4
+
+ - ``VID_TYPE_TELETEXT``
+
+ - ``V4L2_CAP_VBI_CAPTURE``
+
+ - The :ref:`raw VBI capture <raw-vbi>` interface is supported.
+
+ - .. row 5
+
+ - ``VID_TYPE_OVERLAY``
+
+ - ``V4L2_CAP_VIDEO_OVERLAY``
+
+ - The :ref:`video overlay <overlay>` interface is supported.
+
+ - .. row 6
+
+ - ``VID_TYPE_CHROMAKEY``
+
+ - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
+ :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether chromakey overlay is supported. For more information on
+ overlay see :ref:`overlay`.
+
+ - .. row 7
+
+ - ``VID_TYPE_CLIPPING``
+
+ - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
+ ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
+ struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether clipping the overlaid image is supported, see
+ :ref:`overlay`.
+
+ - .. row 8
+
+ - ``VID_TYPE_FRAMERAM``
+
+ - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
+ of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether overlay overwrites frame buffer memory, see
+ :ref:`overlay`.
+
+ - .. row 9
+
+ - ``VID_TYPE_SCALES``
+
+ - ``-``
+
+ - This flag indicates if the hardware can scale images. The V4L2 API
+ implies the scale factor by setting the cropping dimensions and
+ image size with the :ref:`VIDIOC_S_CROP <vidioc-g-crop>` and
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl, respectively. The
+ driver returns the closest sizes possible. For more information on
+ cropping and scaling see :ref:`crop`.
+
+ - .. row 10
+
+ - ``VID_TYPE_MONOCHROME``
+
+ - ``-``
+
+ - Applications can enumerate the supported image formats with the
+ :ref:`VIDIOC_ENUM_FMT <vidioc-enum-fmt>` ioctl to determine if
+ the device supports grey scale capturing only. For more
+ information on image formats see :ref:`pixfmt`.
+
+ - .. row 11
+
+ - ``VID_TYPE_SUBCAPTURE``
+
+ - ``-``
+
+ - Applications can call the :ref:`VIDIOC_G_CROP <vidioc-g-crop>`
+ ioctl to determine if the device supports capturing a subsection
+ of the full picture ("cropping" in V4L2). If not, the ioctl
+ returns the EINVAL error code. For more information on cropping
+ and scaling see :ref:`crop`.
+
+ - .. row 12
+
+ - ``VID_TYPE_MPEG_DECODER``
+
+ - ``-``
+
+ - Applications can enumerate the supported image formats with the
+ :ref:`VIDIOC_ENUM_FMT <vidioc-enum-fmt>` ioctl to determine if
+ the device supports MPEG streams.
+
+ - .. row 13
+
+ - ``VID_TYPE_MPEG_ENCODER``
+
+ - ``-``
+
+ - See above.
+
+ - .. row 14
+
+ - ``VID_TYPE_MJPEG_DECODER``
+
+ - ``-``
+
+ - See above.
+
+ - .. row 15
+
+ - ``VID_TYPE_MJPEG_ENCODER``
+
+ - ``-``
+
+ - See above.
+
+
+The ``audios`` field was replaced by ``capabilities`` flag
+``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
+outputs. To determine their number applications can enumerate audio
+inputs with the :ref:`VIDIOC_G_AUDIO <vidioc-g-audio>` ioctl. The
+audio ioctls are described in :ref:`audio`.
+
+The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
+were removed. Calling the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` or
+:ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl with the desired
+dimensions returns the closest size possible, taking into account the
+current video standard, cropping and scaling limitations.
+
+
+Video Sources
+=============
+
+V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
+:c:type:`struct video_channel` to enumerate the video inputs of a V4L
+device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>`,
+:ref:`VIDIOC_G_INPUT <vidioc-g-input>` and
+:ref:`VIDIOC_S_INPUT <vidioc-g-input>` using struct
+:ref:`v4l2_input <v4l2-input>` as discussed in :ref:`video`.
+
+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
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_channel` ``type``
+
+ - struct :ref:`v4l2_input <v4l2-input>` ``type``
+
+ - .. row 2
+
+ - ``VIDEO_TYPE_TV``
+
+ - ``V4L2_INPUT_TYPE_TUNER``
+
+ - .. row 3
+
+ - ``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
+device can have multiple tuners. The index number of the tuner
+associated with the input, if any, is stored in field ``tuner`` of
+struct :ref:`v4l2_input <v4l2-input>`. Enumeration of tuners is
+discussed in :ref:`tuner`.
+
+The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
+associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
+``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
+considers devices with up to 32 audio inputs. Each set bit in the
+``audioset`` field represents one audio input this video input combines
+with. For information about audio inputs and how to switch between them
+see :ref:`audio`.
+
+The ``norm`` field describing the supported video standards was replaced
+by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
+indicating whether the standard can be changed. This flag was a later
+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
+======
+
+The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
+:c:type:`struct video_tuner` can be used to enumerate the tuners of a
+V4L TV or radio device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_TUNER <vidioc-g-tuner>` and
+:ref:`VIDIOC_S_TUNER <vidioc-g-tuner>` using struct
+:ref:`v4l2_tuner <v4l2-tuner>`. Tuners are covered in :ref:`tuner`.
+
+The ``tuner`` field counting tuners was renamed to ``index``. The fields
+``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
+
+The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
+flags indicating the supported video standards were dropped. This
+information is now contained in the associated struct
+:ref:`v4l2_input <v4l2-input>`. No replacement exists for the
+``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
+switched. The ``mode`` field to select a different video standard was
+replaced by a whole new set of ioctls and structures described in
+:ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
+driver supports several standards in addition to the regular
+``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
+``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
+Japan with numbers 3-6 (sic).
+
+The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
+``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
+permits the detection of monaural and bilingual audio, see the
+definition of struct :ref:`v4l2_tuner <v4l2-tuner>` for details.
+Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
+``VIDEO_TUNER_MBS_ON`` flags.
+
+The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
+the struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field.
+
+The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
+frequency where renamed to
+:ref:`VIDIOC_G_FREQUENCY <vidioc-g-frequency>` and
+:ref:`VIDIOC_S_FREQUENCY <vidioc-g-frequency>`. They take a pointer
+to a struct :ref:`v4l2_frequency <v4l2-frequency>` instead of an
+unsigned long integer.
+
+
+.. _v4l-image-properties:
+
+Image Properties
+================
+
+V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
+and struct :c:type:`struct video_picture`. The following fields where
+replaced by V4L2 controls accessible with the
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>`,
+:ref:`VIDIOC_G_CTRL <vidioc-g-ctrl>` and
+:ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` ioctls:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_picture`
+
+ - V4L2 Control ID
+
+ - .. row 2
+
+ - ``brightness``
+
+ - ``V4L2_CID_BRIGHTNESS``
+
+ - .. row 3
+
+ - ``hue``
+
+ - ``V4L2_CID_HUE``
+
+ - .. row 4
+
+ - ``colour``
+
+ - ``V4L2_CID_SATURATION``
+
+ - .. row 5
+
+ - ``contrast``
+
+ - ``V4L2_CID_CONTRAST``
+
+ - .. row 6
+
+ - ``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
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` ioctl. For general
+information about controls see :ref:`control`.
+
+The ``depth`` (average number of bits per pixel) of a video image is
+implied by the selected image format. V4L2 does not explicitly provide
+such information assuming applications recognizing the format are aware
+of the image depth and others need not know. The ``palette`` field moved
+into the struct :ref:`v4l2_pix_format <v4l2-pix-format>`:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_picture` ``palette``
+
+ - struct :ref:`v4l2_pix_format <v4l2-pix-format>` ``pixfmt``
+
+ - .. row 2
+
+ - ``VIDEO_PALETTE_GREY``
+
+ - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
+
+ - .. row 3
+
+ - ``VIDEO_PALETTE_HI240``
+
+ - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [3]_
+
+ - .. row 4
+
+ - ``VIDEO_PALETTE_RGB565``
+
+ - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
+
+ - .. row 5
+
+ - ``VIDEO_PALETTE_RGB555``
+
+ - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
+
+ - .. row 6
+
+ - ``VIDEO_PALETTE_RGB24``
+
+ - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
+
+ - .. row 7
+
+ - ``VIDEO_PALETTE_RGB32``
+
+ - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [4]_
+
+ - .. row 8
+
+ - ``VIDEO_PALETTE_YUV422``
+
+ - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
+
+ - .. row 9
+
+ - ``VIDEO_PALETTE_YUYV``\ [5]_
+
+ - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
+
+ - .. row 10
+
+ - ``VIDEO_PALETTE_UYVY``
+
+ - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
+
+ - .. row 11
+
+ - ``VIDEO_PALETTE_YUV420``
+
+ - None
+
+ - .. row 12
+
+ - ``VIDEO_PALETTE_YUV411``
+
+ - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [6]_
+
+ - .. row 13
+
+ - ``VIDEO_PALETTE_RAW``
+
+ - None [7]_
+
+ - .. row 14
+
+ - ``VIDEO_PALETTE_YUV422P``
+
+ - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
+
+ - .. row 15
+
+ - ``VIDEO_PALETTE_YUV411P``
+
+ - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [8]_
+
+ - .. row 16
+
+ - ``VIDEO_PALETTE_YUV420P``
+
+ - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
+
+ - .. row 17
+
+ - ``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
+=====
+
+The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
+:c:type:`struct video_audio` are used to enumerate the audio inputs
+of a V4L device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_AUDIO <vidioc-g-audio>` and
+:ref:`VIDIOC_S_AUDIO <vidioc-g-audio>` using struct
+:ref:`v4l2_audio <v4l2-audio>` as discussed in :ref:`audio`.
+
+The ``audio`` "channel number" field counting audio inputs was renamed
+to ``index``.
+
+On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
+``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
+``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
+standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
+``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
+specification, there is no way to query the selected mode. On
+``VIDIOCGAUDIO`` the driver returns the *actually received* audio
+programmes in this field. In the V4L2 API this information is stored in
+the struct :ref:`v4l2_tuner <v4l2-tuner>` ``rxsubchans`` and
+``audmode`` fields, respectively. See :ref:`tuner` for more
+information on tuners. Related to audio modes struct
+:ref:`v4l2_audio <v4l2-audio>` also reports if this is a mono or
+stereo input, regardless if the source is a tuner.
+
+The following fields where replaced by V4L2 controls accessible with the
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>`,
+:ref:`VIDIOC_G_CTRL <vidioc-g-ctrl>` and
+:ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` ioctls:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_audio`
+
+ - V4L2 Control ID
+
+ - .. row 2
+
+ - ``volume``
+
+ - ``V4L2_CID_AUDIO_VOLUME``
+
+ - .. row 3
+
+ - ``bass``
+
+ - ``V4L2_CID_AUDIO_BASS``
+
+ - .. row 4
+
+ - ``treble``
+
+ - ``V4L2_CID_AUDIO_TREBLE``
+
+ - .. row 5
+
+ - ``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
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` ioctl reports if the
+respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
+and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
+``V4L2_CID_AUDIO_MUTE`` control.
+
+All V4L2 controls have a ``step`` attribute replacing the struct
+:c:type:`struct video_audio` ``step`` field. The V4L audio 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 :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` ioctl. For general
+information about controls see :ref:`control`.
+
+
+Frame Buffer Overlay
+====================
+
+The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
+:ref:`VIDIOC_G_FBUF <vidioc-g-fbuf>` and
+:ref:`VIDIOC_S_FBUF <vidioc-g-fbuf>`. The ``base`` field of struct
+:c:type:`struct video_buffer` remained unchanged, except V4L2 defines
+a flag to indicate non-destructive overlays instead of a ``NULL``
+pointer. All other fields moved into the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``fmt`` substructure of
+struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`. The ``depth``
+field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
+list of RGB formats and their respective color depths.
+
+Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
+uses the general-purpose data format negotiation ioctls
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` and
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>`. They take a pointer to a struct
+:ref:`v4l2_format <v4l2-format>` as argument. Here the ``win`` member
+of the ``fmt`` union is used, a struct
+:ref:`v4l2_window <v4l2-window>`.
+
+The ``x``, ``y``, ``width`` and ``height`` fields of struct
+:c:type:`struct video_window` moved into struct
+:ref:`v4l2_rect <v4l2-rect>` substructure ``w`` of struct
+:c:type:`struct v4l2_window`. The ``chromakey``, ``clips``, and
+``clipcount`` fields remained unchanged. Struct
+:c:type:`struct video_clip` was renamed to struct
+:ref:`v4l2_clip <v4l2-clip>`, also containing a struct
+:c:type:`struct v4l2_rect`, but the semantics are still the same.
+
+The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
+must set the ``field`` field to ``V4L2_FIELD_ANY`` or
+``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
+into struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`, under the new
+name ``V4L2_FBUF_FLAG_CHROMAKEY``.
+
+In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
+to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
+size bitmap of 1024 × 625 bits. Struct :c:type:`struct v4l2_window`
+has a separate ``bitmap`` pointer field for this purpose and the bitmap
+size is determined by ``w.width`` and ``w.height``.
+
+The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
+:ref:`VIDIOC_OVERLAY <vidioc-overlay>`.
+
+
+Cropping
+========
+
+To capture only a subsection of the full picture V4L defines the
+``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
+:c:type:`struct video_capture`. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_CROP <vidioc-g-crop>` and
+:ref:`VIDIOC_S_CROP <vidioc-g-crop>` using struct
+:ref:`v4l2_crop <v4l2-crop>`, and the related
+:ref:`VIDIOC_CROPCAP <vidioc-cropcap>` ioctl. This is a rather
+complex matter, see :ref:`crop` for details.
+
+The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
+:ref:`v4l2_rect <v4l2-rect>` substructure ``c`` of struct
+:c:type:`struct v4l2_crop`. The ``decimation`` field was dropped. In
+the V4L2 API the scaling factor is implied by the size of the cropping
+rectangle and the size of the captured or overlaid image.
+
+The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
+only the odd or even field, respectively, were replaced by
+``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
+``field`` of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_window <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
+drivers are not required to support this I/O method. Applications can
+determine if the function is available with the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. All V4L2 devices
+exchanging data with applications must support the
+:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+functions.
+
+To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
+``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
+negotiation ioctls :ref:`VIDIOC_G_FMT <vidioc-g-fmt>` and
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>`. They take a pointer to a struct
+:ref:`v4l2_format <v4l2-format>` as argument, here the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` named ``pix`` of its
+``fmt`` union is used.
+
+For more information about the V4L2 read interface see :ref:`rw`.
+
+
+Capturing using memory mapping
+------------------------------
+
+Applications can read from V4L devices by mapping buffers in device
+memory, or more often just buffers allocated in DMA-able system memory,
+into their address space. This avoids the data copying overhead of the
+read method. V4L2 supports memory mapping as well, with a few
+differences.
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - V4L
+
+ - V4L2
+
+ - .. row 2
+
+ -
+ - The image format must be selected before buffers are allocated,
+ with the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl. When no
+ format is selected the driver may use the last, possibly by
+ another application requested format.
+
+ - .. row 3
+
+ - Applications cannot change the number of buffers. The it is built
+ into the driver, unless it has a module option to change the
+ number when the driver module is loaded.
+
+ - The :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl allocates the
+ desired number of buffers, this is a required step in the
+ initialization sequence.
+
+ - .. row 4
+
+ - Drivers map all buffers as one contiguous range of memory. The
+ ``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.
+
+ - Buffers are individually mapped. The offset and size of each
+ buffer can be determined with the
+ :ref:`VIDIOC_QUERYBUF <vidioc-querybuf>` ioctl.
+
+ - .. row 5
+
+ - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
+ also determines the image format for this buffer. The ioctl
+ returns immediately, eventually with an EAGAIN error code if no
+ video signal had been detected. When the driver supports more than
+ one buffer applications can call the ioctl multiple times and thus
+ have multiple outstanding capture requests.
+
+ The ``VIDIOCSYNC`` ioctl suspends execution until a particular
+ buffer has been filled.
+
+ - Drivers maintain an incoming and outgoing queue.
+ :ref:`VIDIOC_QBUF <vidioc-qbuf>` enqueues any empty buffer into
+ 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
+ be used. The :ref:`VIDIOC_STREAMON <vidioc-streamon>` ioctl
+ must be called once after enqueuing one or more buffers to start
+ capturing. Its counterpart
+ :ref:`VIDIOC_STREAMOFF <vidioc-streamon>` stops capturing and
+ dequeues all buffers from both queues. Applications can query the
+ signal status, if known, with the
+ :ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` ioctl.
+
+
+For a more in-depth discussion of memory mapping and examples, see
+:ref:`mmap`.
+
+
+Reading Raw VBI Data
+====================
+
+Originally the V4L API did not specify a raw VBI capture interface, only
+the device file ``/dev/vbi`` was reserved for this purpose. The only
+driver supporting this interface was the BTTV driver, de-facto defining
+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
+
+
+ - .. row 1
+
+ - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+
+ - V4L, BTTV driver
+
+ - .. row 2
+
+ - sampling_rate
+
+ - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
+ and SECAM (625-line standards)
+
+ - .. row 3
+
+ - offset
+
+ - ?
+
+ - .. row 4
+
+ - samples_per_line
+
+ - 2048
+
+ - .. row 5
+
+ - sample_format
+
+ - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
+ integer) contain a frame counter.
+
+ - .. row 6
+
+ - start[]
+
+ - 10, 273 NTSC; 22, 335 PAL and SECAM
+
+ - .. row 7
+
+ - count[]
+
+ - 16, 16 [9]_
+
+ - .. row 8
+
+ - flags
+
+ - 0
+
+
+Undocumented in the V4L specification, in Linux 2.3 the
+``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
+:c:type:`struct vbi_format` were added to determine the VBI image
+parameters. These ioctls are only partially compatible with the V4L2 VBI
+interface specified in :ref:`raw-vbi`.
+
+An ``offset`` field does not exist, ``sample_format`` is supposed to be
+``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
+remaining fields are probably equivalent to struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>`.
+
+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
+``VIDIOCSVBIFMT`` always returns an EINVAL error code if the parameters
+are invalid.
+
+
+Miscellaneous
+=============
+
+V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
+find the VBI device associated with a video capture device (or vice
+versa) by reopening the device and requesting VBI data. For details see
+:ref:`open`.
+
+No replacement exists for ``VIDIOCKEY``, and the V4L functions for
+microcode programming. A new interface for MPEG compression and playback
+devices is documented in :ref:`extended-controls`.
+
+.. [1]
+ According to Documentation/devices.txt these should be symbolic links
+ to ``/dev/video0``. Note the original bttv interface is not
+ compatible with V4L or V4L2.
+
+.. [2]
+ According to ``Documentation/devices.txt`` a symbolic link to
+ ``/dev/radio0``.
+
+.. [3]
+ This is a custom format used by the BTTV driver, not one of the V4L2
+ standard formats.
+
+.. [4]
+ Presumably all V4L RGB formats are little-endian, although some
+ drivers might interpret them according to machine endianness. V4L2
+ defines little-endian, big-endian and red/blue swapped variants. For
+ details see :ref:`pixfmt-rgb`.
+
+.. [5]
+ ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
+ formats. Some V4L drivers respond to one, some to the other.
+
+.. [6]
+ Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
+ format.
+
+.. [7]
+ V4L explains this as: "RAW capture (BT848)"
+
+.. [8]
+ Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
+ format.
+
+.. [9]
+ Old driver versions used different values, eventually the custom
+ ``BTTV_VBISIZE`` ioctl was added to query the correct values.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmabuf:
+
+************************************
+Streaming I/O (DMA buffer importing)
+************************************
+
+The DMABUF framework provides a generic method for sharing buffers
+between multiple devices. Device drivers that support DMABUF can export
+a DMA buffer to userspace as a file descriptor (known as the exporter
+role), import a DMA buffer from userspace using a file descriptor
+previously exported for a different or the same device (known as the
+importer role), or both. This section describes the DMABUF importer role
+API in V4L2.
+
+Refer to :ref:`DMABUF exporting <vidioc-expbuf>` for details about
+exporting V4L2 buffers as DMABUF file descriptors.
+
+Input and output devices support the streaming I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl is set. Whether
+importing DMA buffers through DMABUF file descriptors is supported is
+determined by calling the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>`
+ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``.
+
+This I/O method is dedicated to sharing DMA buffers between different
+devices, which may be V4L devices or other video-related devices (e.g.
+DRM). Buffers (planes) are allocated by a driver on behalf of an
+application. Next, these buffers are exported to the application as file
+descriptors using an API which is specific for an allocator driver. Only
+such file descriptor are exchanged. The descriptors and meta-information
+are passed in struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
+:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
+driver must be switched into DMABUF I/O mode by calling the
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` with the desired buffer type.
+
+
+.. code-block:: c
+
+ struct v4l2_requestbuffers reqbuf;
+
+ memset(&reqbuf, 0, sizeof (reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_DMABUF;
+ reqbuf.count = 1;
+
+ if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
+ if (errno == EINVAL)
+ printf("Video capturing or DMABUF streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+The buffer (plane) file descriptor is passed on the fly with the
+:ref:`VIDIOC_QBUF <vidioc-qbuf>` ioctl. In case of multiplanar
+buffers, every plane can be associated with a different DMABUF
+descriptor. Although buffers are commonly cycled, applications can pass
+a different DMABUF descriptor at each ``VIDIOC_QBUF`` call.
+
+
+.. code-block:: c
+
+ int buffer_queue(int v4lfd, int index, int dmafd)
+ {
+ struct v4l2_buffer buf;
+
+ memset(&buf, 0, sizeof buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_DMABUF;
+ buf.index = index;
+ buf.m.fd = dmafd;
+
+ if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
+ perror("VIDIOC_QBUF");
+ return -1;
+ }
+
+ return 0;
+ }
+
+
+.. code-block:: c
+
+ int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
+ {
+ struct v4l2_buffer buf;
+ struct v4l2_plane planes[VIDEO_MAX_PLANES];
+ int i;
+
+ memset(&buf, 0, sizeof buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+ buf.memory = V4L2_MEMORY_DMABUF;
+ buf.index = index;
+ buf.m.planes = planes;
+ buf.length = n_planes;
+
+ memset(&planes, 0, sizeof planes);
+
+ for (i = 0; i < n_planes; ++i)
+ buf.m.planes[i].m.fd = dmafd[i];
+
+ if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
+ perror("VIDIOC_QBUF");
+ return -1;
+ }
+
+ return 0;
+ }
+
+Captured or displayed buffers are dequeued with the
+:ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl. The driver can unlock the
+buffer at any time between the completion of the DMA and this ioctl. The
+memory is also unlocked when
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>` is called,
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>`, or when the device is closed.
+
+For capturing applications it is customary to enqueue a number of empty
+buffers, to start capturing and enter the read loop. Here the
+application waits until a filled buffer can be dequeued, and re-enqueues
+the buffer when the data is no longer needed. Output applications fill
+and enqueue buffers, when enough buffers are stacked up output is
+started. In the write loop, when the application runs out of free
+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 ``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
+immediately with an EAGAIN error code when no buffer is available. The
+:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+functions are always available.
+
+To start and stop capturing or displaying applications call the
+:ref:`VIDIOC_STREAMON <vidioc-streamon>` and
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>` ioctls. Note that
+``VIDIOC_STREAMOFF`` removes all buffers from both queues and unlocks
+all buffers as a side effect. Since there is no notion of doing anything
+"now" on a multitasking system, if an application needs to synchronize
+with another event it should examine the struct
+:ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
+outputted buffers.
+
+Drivers implementing DMABUF importing I/O must support the
+``VIDIOC_REQBUFS``, ``VIDIOC_QBUF``, ``VIDIOC_DQBUF``,
+``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctls, and the
+:c:func:`select()` and :c:func:`poll()` functions.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _driver:
+
+***********************
+V4L2 Driver Programming
+***********************
+
+to do
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dv-timings:
+
+**************************
+Digital Video (DV) Timings
+**************************
+
+The video standards discussed so far have been dealing with Analog TV
+and the corresponding video timings. Today there are many more different
+hardware interfaces such as High Definition TV interfaces (HDMI), VGA,
+DVI connectors etc., that carry video signals and there is a need to
+extend the API to select the video timings for these interfaces. Since
+it is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>`
+due to the limited bits available, a new set of ioctls was added to
+set/get video timings at the input and output.
+
+These ioctls deal with the detailed digital video timings that define
+each video format. This includes parameters such as the active video
+width and height, signal polarities, frontporches, backporches, sync
+widths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get
+the timings of the formats in the :ref:`cea861` and :ref:`vesadmt`
+standards.
+
+To enumerate and query the attributes of the DV timings supported by a
+device applications use the
+:ref:`VIDIOC_ENUM_DV_TIMINGS <vidioc-enum-dv-timings>` and
+:ref:`VIDIOC_DV_TIMINGS_CAP <vidioc-dv-timings-cap>` ioctls. To set
+DV timings for the device applications use the
+:ref:`VIDIOC_S_DV_TIMINGS <vidioc-g-dv-timings>` ioctl and to get
+current DV timings they use the
+:ref:`VIDIOC_G_DV_TIMINGS <vidioc-g-dv-timings>` ioctl. To detect
+the DV timings as seen by the video receiver applications use the
+:ref:`VIDIOC_QUERY_DV_TIMINGS <vidioc-query-dv-timings>` ioctl.
+
+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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _extended-controls:
+
+*****************
+Extended Controls
+*****************
+
+
+Introduction
+============
+
+The control mechanism as originally designed was meant to be used for
+user settings (brightness, saturation, etc). However, it turned out to
+be a very useful model for implementing more complicated driver APIs
+where each driver implements only a subset of a larger API.
+
+The MPEG encoding API was the driving force behind designing and
+implementing this extended control mechanism: the MPEG standard is quite
+large and the currently supported hardware MPEG encoders each only
+implement a subset of this standard. Further more, many parameters
+relating to how the video is encoded into an MPEG stream are specific to
+the MPEG encoding chip since the MPEG standard only defines the format
+of the resulting MPEG stream, not how the video is actually encoded into
+that format.
+
+Unfortunately, the original control API lacked some features needed for
+these new uses and so it was extended into the (not terribly originally
+named) extended control API.
+
+Even though the MPEG encoding API was the first effort to use the
+Extended Control API, nowadays there are also other classes of Extended
+Controls, such as Camera Controls and FM Transmitter Controls. The
+Extended Controls API as well as all Extended Controls classes are
+described in the following text.
+
+
+The Extended Control API
+========================
+
+Three new ioctls are available:
+:ref:`VIDIOC_G_EXT_CTRLS <vidioc-g-ext-ctrls>`,
+:ref:`VIDIOC_S_EXT_CTRLS <vidioc-g-ext-ctrls>` and
+:ref:`VIDIOC_TRY_EXT_CTRLS <vidioc-g-ext-ctrls>`. These ioctls act
+on arrays of controls (as opposed to the
+:ref:`VIDIOC_G_CTRL <vidioc-g-ctrl>` and
+:ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` ioctls that act on a single
+control). This is needed since it is often required to atomically change
+several controls at once.
+
+Each of the new ioctls expects a pointer to a struct
+:ref:`v4l2_ext_controls <v4l2-ext-controls>`. This structure
+contains a pointer to the control array, a count of the number of
+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 ``VIDIOC_S_CTRL`` ioctl). Control
+class ``V4L2_CTRL_CLASS_MPEG`` contains all controls relating to MPEG
+encoding, etc.
+
+All controls in the control array must belong to the specified control
+class. An error is returned if this is not the case.
+
+It is also possible to use an empty control array (count == 0) to check
+whether the specified control class is supported.
+
+The control array is a struct
+:ref:`v4l2_ext_control <v4l2-ext-control>` array. The
+:c:type:`struct v4l2_ext_control` structure is very similar to
+struct :ref:`v4l2_control <v4l2-control>`, except for the fact that
+it also allows for 64-bit values and pointers to be passed.
+
+Since the struct :ref:`v4l2_ext_control <v4l2-ext-control>` supports
+pointers it is now also possible to have controls with compound types
+such as N-dimensional arrays and/or structures. You need to specify the
+``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually
+be able to see such compound controls. In other words, these controls
+with compound types should only be used programmatically.
+
+Since such compound controls need to expose more information about
+themselves than is possible with
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` the
+:ref:`VIDIOC_QUERY_EXT_CTRL <vidioc-queryctrl>` ioctl was added. In
+particular, this ioctl gives the dimensions of the N-dimensional array
+if this control consists of more than one element.
+
+It is important to realize that due to the flexibility of controls it is
+necessary to check whether the control you want to set actually is
+supported in the driver and what the valid range of values is. So use
+the :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` (or
+:ref:`VIDIOC_QUERY_EXT_CTRL <vidioc-queryctrl>`) and
+:ref:`VIDIOC_QUERYMENU <vidioc-queryctrl>` ioctls to check this. Also
+note that it is possible that some of the menu indices in a control of
+type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
+will return an error). A good example is the list of supported MPEG
+audio bitrates. Some drivers only support one or two bitrates, others
+support a wider range.
+
+All controls use machine endianness.
+
+
+Enumerating Extended Controls
+=============================
+
+The recommended way to enumerate over the extended controls is by using
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` in combination with the
+``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:
+
+
+.. code-block:: c
+
+ struct v4l2_queryctrl qctrl;
+
+ qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
+ /* ... */
+ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+
+The initial control ID is set to 0 ORed with the
+``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will
+return the first control with a higher ID than the specified one. When
+no such controls are found an error is returned.
+
+If you want to get all controls within a specific control class, then
+you can set the initial ``qctrl.id`` value to the control class and add
+an extra check to break out of the loop when a control of another
+control class is found:
+
+
+.. code-block:: c
+
+ qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {
+ if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
+ break;
+ /* ... */
+ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+
+The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the
+top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)
+and are not actually part of the ID. The remaining 28 bits form the
+control ID, of which the most significant 12 bits define the control
+class and the least significant 16 bits identify the control within the
+control class. It is guaranteed that these last 16 bits are always
+non-zero for controls. The range of 0x1000 and up are reserved for
+driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns
+the control class ID based on a control ID.
+
+If the driver does not support extended controls, then
+``VIDIOC_QUERYCTRL`` will fail when used in combination with
+``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating
+control should be used (see :ref:`enum_all_controls`). But if it is
+supported, then it is guaranteed to enumerate over all controls,
+including driver-private controls.
+
+
+Creating Control Panels
+=======================
+
+It is possible to create control panels for a graphical user interface
+where the user can select the various controls. Basically you will have
+to iterate over all controls using the method described above. Each
+control class starts with a control of type
+``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name
+of this control class which can be used as the title of a tab page
+within a control panel.
+
+The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
+contains hints on the behavior of the control. See the
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` documentation for more
+details.
+
+
+.. _mpeg-controls:
+
+Codec Control Reference
+=======================
+
+Below all controls within the Codec control class are described. First
+the generic controls, then controls specific for certain hardware.
+
+Note: These controls are applicable to all codecs and not just MPEG. The
+defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
+were originally made for MPEG codecs and later extended to cover all
+encoding formats.
+
+
+Generic Codec Controls
+----------------------
+
+
+.. _mpeg-control-id:
+
+Codec Control IDs
+^^^^^^^^^^^^^^^^^
+
+``V4L2_CID_MPEG_CLASS (class)``
+ The Codec class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` for this control will
+ return a description of this control class. This description can be
+ used as the caption of a Tab page in a GUI, for example.
+
+.. _`v4l2-mpeg-stream-type`:
+
+``V4L2_CID_MPEG_STREAM_TYPE (enum v4l2_mpeg_stream_type)``
+ The MPEG-1, -2 or -4 output stream type. One cannot assume anything
+ here. Each hardware MPEG encoder tends to support different subsets
+ of the available MPEG stream types. This control is specific to
+ multiplexed MPEG streams. The currently defined stream types are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS``
+
+ - MPEG-2 program stream
+
+ - .. row 2
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS``
+
+ - MPEG-2 transport stream
+
+ - .. row 3
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS``
+
+ - MPEG-1 system stream
+
+ - .. row 4
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD``
+
+ - MPEG-2 DVD-compatible stream
+
+ - .. row 5
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD``
+
+ - MPEG-1 VCD-compatible stream
+
+ - .. row 6
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD``
+
+ - MPEG-2 SVCD-compatible stream
+
+
+
+``V4L2_CID_MPEG_STREAM_PID_PMT (integer)``
+ Program Map Table Packet ID for the MPEG transport stream (default
+ 16)
+
+``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)``
+ Audio Packet ID for the MPEG transport stream (default 256)
+
+``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)``
+ Video Packet ID for the MPEG transport stream (default 260)
+
+``V4L2_CID_MPEG_STREAM_PID_PCR (integer)``
+ Packet ID for the MPEG transport stream carrying PCR fields (default
+ 259)
+
+``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)``
+ Audio ID for MPEG PES
+
+``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)``
+ Video ID for MPEG PES
+
+.. _`v4l2-mpeg-stream-vbi-fmt`:
+
+``V4L2_CID_MPEG_STREAM_VBI_FMT (enum v4l2_mpeg_stream_vbi_fmt)``
+ Some cards can embed VBI data (e. g. Closed Caption, Teletext) into
+ the MPEG stream. This control selects whether VBI data should be
+ embedded, and if so, what embedding method should be used. The list
+ of possible VBI formats depends on the driver. The currently defined
+ VBI format types are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_STREAM_VBI_FMT_NONE``
+
+ - No VBI in the MPEG stream
+
+ - .. row 2
+
+ - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
+
+ - VBI in private packets, IVTV format (documented in the kernel
+ sources in the file
+ ``Documentation/video4linux/cx2341x/README.vbi``)
+
+
+
+.. _`v4l2-mpeg-audio-sampling-freq`:
+
+``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (enum v4l2_mpeg_audio_sampling_freq)``
+ MPEG Audio sampling frequency. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100``
+
+ - 44.1 kHz
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000``
+
+ - 48 kHz
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000``
+
+ - 32 kHz
+
+
+
+.. _`v4l2-mpeg-audio-encoding`:
+
+``V4L2_CID_MPEG_AUDIO_ENCODING (enum v4l2_mpeg_audio_encoding)``
+ MPEG Audio encoding. This control is specific to multiplexed MPEG
+ streams. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1``
+
+ - MPEG-1/2 Layer I encoding
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2``
+
+ - MPEG-1/2 Layer II encoding
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3``
+
+ - MPEG-1/2 Layer III encoding
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_AAC``
+
+ - MPEG-2/4 AAC (Advanced Audio Coding)
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_AC3``
+
+ - AC-3 aka ATSC A/52 encoding
+
+
+
+.. _`v4l2-mpeg-audio-l1-bitrate`:
+
+``V4L2_CID_MPEG_AUDIO_L1_BITRATE (enum v4l2_mpeg_audio_l1_bitrate)``
+ MPEG-1/2 Layer I bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K``
+
+ - 288 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K``
+
+ - 352 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K``
+
+ - 384 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K``
+
+ - 416 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K``
+
+ - 448 kbit/s
+
+
+
+.. _`v4l2-mpeg-audio-l2-bitrate`:
+
+``V4L2_CID_MPEG_AUDIO_L2_BITRATE (enum v4l2_mpeg_audio_l2_bitrate)``
+ MPEG-1/2 Layer II bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K``
+
+ - 384 kbit/s
+
+
+
+.. _`v4l2-mpeg-audio-l3-bitrate`:
+
+``V4L2_CID_MPEG_AUDIO_L3_BITRATE (enum v4l2_mpeg_audio_l3_bitrate)``
+ MPEG-1/2 Layer III bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K``
+
+ - 40 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K``
+
+ - 320 kbit/s
+
+
+
+``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)``
+ AAC bitrate in bits per second.
+
+.. _`v4l2-mpeg-audio-ac3-bitrate`:
+
+``V4L2_CID_MPEG_AUDIO_AC3_BITRATE (enum v4l2_mpeg_audio_ac3_bitrate)``
+ AC-3 bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K``
+
+ - 40 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 15
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K``
+
+ - 384 kbit/s
+
+ - .. row 16
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K``
+
+ - 448 kbit/s
+
+ - .. row 17
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K``
+
+ - 512 kbit/s
+
+ - .. row 18
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K``
+
+ - 576 kbit/s
+
+ - .. row 19
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K``
+
+ - 640 kbit/s
+
+
+
+.. _`v4l2-mpeg-audio-mode`:
+
+``V4L2_CID_MPEG_AUDIO_MODE (enum v4l2_mpeg_audio_mode)``
+ MPEG Audio mode. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_MODE_STEREO``
+
+ - Stereo
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO``
+
+ - Joint Stereo
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_MODE_DUAL``
+
+ - Bilingual
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_MODE_MONO``
+
+ - Mono
+
+
+
+.. _`v4l2-mpeg-audio-mode-extension`:
+
+``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (enum v4l2_mpeg_audio_mode_extension)``
+ Joint Stereo audio mode extension. In Layer I and II they indicate
+ which subbands are in intensity stereo. All other subbands are coded
+ in stereo. Layer III is not (yet) supported. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4``
+
+ - Subbands 4-31 in intensity stereo
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8``
+
+ - Subbands 8-31 in intensity stereo
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12``
+
+ - Subbands 12-31 in intensity stereo
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16``
+
+ - Subbands 16-31 in intensity stereo
+
+
+
+.. _`v4l2-mpeg-audio-emphasis`:
+
+``V4L2_CID_MPEG_AUDIO_EMPHASIS (enum v4l2_mpeg_audio_emphasis)``
+ Audio Emphasis. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE``
+
+ - None
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS``
+
+ - 50/15 microsecond emphasis
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17``
+
+ - CCITT J.17
+
+
+
+.. _`v4l2-mpeg-audio-crc`:
+
+``V4L2_CID_MPEG_AUDIO_CRC (enum v4l2_mpeg_audio_crc)``
+ CRC method. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_CRC_NONE``
+
+ - None
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_CRC_CRC16``
+
+ - 16 bit parity check
+
+
+
+``V4L2_CID_MPEG_AUDIO_MUTE (boolean)``
+ Mutes the audio when capturing. This is not done by muting audio
+ hardware, which can still produce a slight hiss, but in the encoder
+ itself, guaranteeing a fixed and reproducible audio bitstream. 0 =
+ unmuted, 1 = muted.
+
+.. _`v4l2-mpeg-audio-dec-playback`:
+
+``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
+ Determines how monolingual audio should be played back. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO``
+
+ - Automatically determines the best playback mode.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO``
+
+ - Stereo playback.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT``
+
+ - Left channel playback.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT``
+
+ - Right channel playback.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO``
+
+ - Mono playback.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO``
+
+ - Stereo playback with swapped left and right channels.
+
+
+
+.. _`v4l2-mpeg-audio-dec-multilingual-playback`:
+
+``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
+ Determines how multilingual audio should be played back.
+
+.. _`v4l2-mpeg-video-encoding`:
+
+``V4L2_CID_MPEG_VIDEO_ENCODING (enum v4l2_mpeg_video_encoding)``
+ MPEG Video encoding method. This control is specific to multiplexed
+ MPEG streams. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1``
+
+ - MPEG-1 Video encoding
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2``
+
+ - MPEG-2 Video encoding
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC``
+
+ - MPEG-4 AVC (H.264) Video encoding
+
+
+
+.. _`v4l2-mpeg-video-aspect`:
+
+``V4L2_CID_MPEG_VIDEO_ASPECT (enum v4l2_mpeg_video_aspect)``
+ Video aspect. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_1x1``
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_4x3``
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_16x9``
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_221x100``
+
+
+
+``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)``
+ Number of B-Frames (default 2)
+
+``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)``
+ GOP size (default 12)
+
+``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)``
+ GOP closure (default 1)
+
+``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)``
+ Enable 3:2 pulldown (default 0)
+
+.. _`v4l2-mpeg-video-bitrate-mode`:
+
+``V4L2_CID_MPEG_VIDEO_BITRATE_MODE (enum v4l2_mpeg_video_bitrate_mode)``
+ Video bitrate mode. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR``
+
+ - Variable bitrate
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR``
+
+ - Constant bitrate
+
+
+
+``V4L2_CID_MPEG_VIDEO_BITRATE (integer)``
+ 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_TEMPORAL_DECIMATION (integer)``
+ For every captured frame, skip this many subsequent frames (default
+ 0).
+
+``V4L2_CID_MPEG_VIDEO_MUTE (boolean)``
+ "Mutes" the video to a fixed color when capturing. This is useful
+ for testing, to produce a fixed video bitstream. 0 = unmuted, 1 =
+ muted.
+
+``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)``
+ Sets the "mute" color of the video. The supplied 32-bit integer is
+ interpreted as follows (bit 0 = least significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:7
+
+ - V chrominance information
+
+ - .. row 2
+
+ - Bit 8:15
+
+ - U chrominance information
+
+ - .. row 3
+
+ - Bit 16:23
+
+ - Y luminance information
+
+ - .. row 4
+
+ - Bit 24:31
+
+ - Must be zero.
+
+
+
+.. _`v4l2-mpeg-video-dec-pts`:
+
+``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)``
+ This read-only control returns the 33-bit video Presentation Time
+ Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the
+ currently displayed frame. This is the same PTS as is used in
+ :ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>`.
+
+.. _`v4l2-mpeg-video-dec-frame`:
+
+``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)``
+ This read-only control returns the frame counter of the frame that
+ is currently displayed (decoded). This value is reset to 0 whenever
+ the decoder is started.
+
+``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_H264_VUI_SAR_ENABLE (boolean)``
+ Enable writing sample aspect ratio in the Video Usability
+ Information. Applicable to the H264 encoder.
+
+.. _`v4l2-mpeg-video-h264-vui-sar-idc`:
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC (enum v4l2_mpeg_video_h264_vui_sar_idc)``
+ VUI sample aspect ratio indicator for H.264 encoding. The value is
+ defined in the table E-1 in the standard. Applicable to the H264
+ encoder.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED``
+
+ - Unspecified
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1``
+
+ - 1x1
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11``
+
+ - 12x11
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11``
+
+ - 10x11
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11``
+
+ - 16x11
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33``
+
+ - 40x33
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11``
+
+ - 24x11
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11``
+
+ - 20x11
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11``
+
+ - 32x11
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33``
+
+ - 80x33
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11``
+
+ - 18x11
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11``
+
+ - 15x11
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33``
+
+ - 64x33
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99``
+
+ - 160x99
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3``
+
+ - 4x3
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2``
+
+ - 3x2
+
+ - .. row 17
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1``
+
+ - 2x1
+
+ - .. row 18
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED``
+
+ - Extended SAR
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)``
+ Extended sample aspect ratio width for H.264 VUI encoding.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)``
+ Extended sample aspect ratio height for H.264 VUI encoding.
+ Applicable to the H264 encoder.
+
+.. _`v4l2-mpeg-video-h264-level`:
+
+``V4L2_CID_MPEG_VIDEO_H264_LEVEL (enum v4l2_mpeg_video_h264_level)``
+ The level information for the H264 video elementary stream.
+ Applicable to the H264 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0``
+
+ - Level 1.0
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B``
+
+ - Level 1B
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1``
+
+ - Level 1.1
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2``
+
+ - Level 1.2
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3``
+
+ - Level 1.3
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0``
+
+ - Level 2.0
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1``
+
+ - Level 2.1
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2``
+
+ - Level 2.2
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0``
+
+ - Level 3.0
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1``
+
+ - Level 3.1
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2``
+
+ - Level 3.2
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0``
+
+ - Level 4.0
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1``
+
+ - Level 4.1
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2``
+
+ - Level 4.2
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0``
+
+ - Level 5.0
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1``
+
+ - Level 5.1
+
+
+
+.. _`v4l2-mpeg-video-mpeg4-level`:
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL (enum v4l2_mpeg_video_mpeg4_level)``
+ The level information for the MPEG4 elementary stream. Applicable to
+ the MPEG4 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_0``
+
+ - Level 0
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_0B``
+
+ - Level 0b
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_1``
+
+ - Level 1
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_2``
+
+ - Level 2
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_3``
+
+ - Level 3
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_3B``
+
+ - Level 3b
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_4``
+
+ - Level 4
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_5``
+
+ - Level 5
+
+
+
+.. _`v4l2-mpeg-video-h264-profile`:
+
+``V4L2_CID_MPEG_VIDEO_H264_PROFILE (enum v4l2_mpeg_video_h264_profile)``
+ The profile information for H264. Applicable to the H264 encoder.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE``
+
+ - Baseline profile
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE``
+
+ - Constrained Baseline profile
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN``
+
+ - Main profile
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED``
+
+ - Extended profile
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH``
+
+ - High profile
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10``
+
+ - High 10 profile
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422``
+
+ - High 422 profile
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE``
+
+ - High 444 Predictive profile
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA``
+
+ - High 10 Intra profile
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA``
+
+ - High 422 Intra profile
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA``
+
+ - High 444 Intra profile
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA``
+
+ - CAVLC 444 Intra profile
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE``
+
+ - Scalable Baseline profile
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH``
+
+ - Scalable High profile
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA``
+
+ - Scalable High Intra profile
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH``
+
+ - Stereo High profile
+
+ - .. row 17
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH``
+
+ - Multiview High profile
+
+
+
+.. _`v4l2-mpeg-video-mpeg4-profile`:
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE (enum v4l2_mpeg_video_mpeg4_profile)``
+ The profile information for MPEG4. Applicable to the MPEG4 encoder.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE``
+
+ - Simple profile
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE``
+
+ - Advanced Simple profile
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_CORE``
+
+ - Core profile
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE``
+
+ - Simple Scalable profile
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY``
+
+ -
+
+
+
+``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)``
+ The maximum number of reference pictures used for encoding.
+ Applicable to the encoder.
+
+.. _`v4l2-mpeg-video-multi-slice-mode`:
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE (enum v4l2_mpeg_video_multi_slice_mode)``
+ Determines how the encoder should handle division of frame into
+ slices. Applicable to the encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE``
+
+ - Single slice per frame.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``
+
+ - Multiple slices with set maximum number of macroblocks per slice.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``
+
+ - Multiple slice with set maximum size in bytes per slice.
+
+
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)``
+ The maximum number of macroblocks in a slice. Used when
+ ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
+ ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)``
+ The maximum size of a slice in bytes. Used when
+ ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
+ ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the
+ encoder.
+
+.. _`v4l2-mpeg-video-h264-loop-filter-mode`:
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE (enum v4l2_mpeg_video_h264_loop_filter_mode)``
+ Loop filter mode for H264 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED``
+
+ - Loop filter is enabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED``
+
+ - Loop filter is disabled.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY``
+
+ - Loop filter is disabled at the slice boundary.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)``
+ Loop filter alpha coefficient, defined in the H264 standard.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)``
+ Loop filter beta coefficient, defined in the H264 standard.
+ Applicable to the H264 encoder.
+
+.. _`v4l2-mpeg-video-h264-entropy-mode`:
+
+``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE (enum v4l2_mpeg_video_h264_entropy_mode)``
+ Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC``
+
+ - Use CAVLC entropy coding.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC``
+
+ - Use CABAC entropy coding.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)``
+ Enable 8X8 transform for H264. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)``
+ 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.
+
+``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)``
+ Frame level rate control enable. If this control is disabled then
+ the quantization parameter for each frame type is constant and set
+ with appropriate controls (e.g.
+ ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is
+ enabled then quantization parameter is adjusted to meet the chosen
+ bitrate. Minimum and maximum value for the quantization parameter
+ can be set with appropriate controls (e.g.
+ ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders.
+
+``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)``
+ Macroblock level rate control enable. Applicable to the MPEG4 and
+ H264 encoders.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)``
+ Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)``
+ Minimum quantization parameter for H263. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)``
+ Maximum quantization parameter for H263. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)``
+ Minimum quantization parameter for H264. Valid range: from 0 to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)``
+ Maximum quantization parameter for H264. Valid range: from 0 to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for MPEG4. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)``
+ Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)``
+ Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for MPEG4. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for MPEG4. Valid range: from 1
+ to 31.
+
+``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
+ mean to verify that the produced stream will be successfully
+ decoded. The standard describes it as "Part of a hypothetical
+ decoder that is conceptually connected to the output of the encoder.
+ Its purpose is to provide a constraint on the variability of the
+ data rate that an encoder or editing process may produce.".
+ Applicable to the MPEG1, MPEG2, MPEG4 encoders.
+
+.. _`v4l2-mpeg-video-vbv-delay`:
+
+``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)``
+ Sets the initial delay in milliseconds for VBV buffer control.
+
+.. _`v4l2-mpeg-video-hor-search-range`:
+
+``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)``
+ Horizontal search range defines maximum horizontal search area in
+ pixels to search and match for the present Macroblock (MB) in the
+ reference picture. This V4L2 control macro is used to set horizontal
+ search range for motion estimation module in video encoder.
+
+.. _`v4l2-mpeg-video-vert-search-range`:
+
+``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)``
+ Vertical search range defines maximum vertical search area in pixels
+ to search and match for the present Macroblock (MB) in the reference
+ picture. This V4L2 control macro is used to set vertical search
+ range for motion estimation module in video encoder.
+
+.. _`v4l2-mpeg-video-force-key-frame`:
+
+``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)``
+ Force a key frame for the next queued buffer. Applicable to
+ encoders. This is a general, codec-agnostic keyframe control.
+
+``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
+ a mean to verify that the produced stream will be successfully
+ decoded. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)``
+ Period between I-frames in the open GOP for H264. In case of an open
+ GOP this is the period between two I-frames. The period between IDR
+ (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE
+ control. An IDR frame, which stands for Instantaneous Decoding
+ Refresh is an I-frame after which no prior frames are referenced.
+ This means that a stream can be restarted from an IDR frame without
+ the need to store or decode any previous frames. Applicable to the
+ H264 encoder.
+
+.. _`v4l2-mpeg-video-header-mode`:
+
+``V4L2_CID_MPEG_VIDEO_HEADER_MODE (enum v4l2_mpeg_video_header_mode)``
+ Determines whether the header is returned as the first buffer or is
+ it returned together with the first frame. Applicable to encoders.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE``
+
+ - The stream header is returned separately in the first buffer.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME``
+
+ - The stream header is returned together with the first encoded
+ frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)``
+ Repeat the video sequence headers. Repeating these headers makes
+ random access to the video stream easier. Applicable to the MPEG1, 2
+ and 4 encoder.
+
+``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)``
+ Enabled the deblocking post processing filter for MPEG4 decoder.
+ Applicable to the MPEG4 decoder.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)``
+ vop_time_increment_resolution value for MPEG4. Applicable to the
+ MPEG4 encoder.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)``
+ vop_time_increment value for MPEG4. Applicable to the MPEG4
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)``
+ Enable generation of frame packing supplemental enhancement
+ information in the encoded bitstream. The frame packing SEI message
+ contains the arrangement of L and R planes for 3D viewing.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)``
+ Sets current frame as frame0 in frame packing SEI. Applicable to the
+ H264 encoder.
+
+.. _`v4l2-mpeg-video-h264-sei-fp-arrangement-type`:
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE (enum v4l2_mpeg_video_h264_sei_fp_arrangement_type)``
+ Frame packing arrangement type for H264 SEI. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD``
+
+ - Pixels are alternatively from L and R.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN``
+
+ - L and R are interlaced by column.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW``
+
+ - L and R are interlaced by row.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE``
+
+ - L is on the left, R on the right.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM``
+
+ - L is on top, R on bottom.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL``
+
+ - One view per frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)``
+ Enables flexible macroblock ordering in the encoded bitstream. It is
+ a technique used for restructuring the ordering of macroblocks in
+ pictures. Applicable to the H264 encoder.
+
+.. _`v4l2-mpeg-video-h264-fmo-map-type`:
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE (enum v4l2_mpeg_video_h264_fmo_map_type)``
+ When using FMO, the map type divides the image in different scan
+ patterns of macroblocks. Applicable to the H264 encoder. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES``
+
+ - Slices are interleaved one after other with macroblocks in run
+ length order.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES``
+
+ - Scatters the macroblocks based on a mathematical function known to
+ both encoder and decoder.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER``
+
+ - Macroblocks arranged in rectangular areas or regions of interest.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT``
+
+ - Slice groups grow in a cyclic way from centre to outwards.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN``
+
+ - Slice groups grow in raster scan pattern from left to right.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN``
+
+ - Slice groups grow in wipe scan pattern from top to bottom.
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT``
+
+ - User defined map type.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)``
+ Number of slice groups in FMO. Applicable to the H264 encoder.
+
+.. _`v4l2-mpeg-video-h264-fmo-change-direction`:
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION (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:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT``
+
+ - Raster scan or wipe right.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT``
+
+ - Reverse raster scan or wipe left.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)``
+ Specifies the size of the first slice group for raster and wipe map.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)``
+ Specifies the number of consecutive macroblocks for the interleaved
+ map. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)``
+ Enables arbitrary slice ordering in encoded bitstream. Applicable to
+ the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)``
+ Specifies the slice order in ASO. Applicable to the H264 encoder.
+ The supplied 32-bit integer is interpreted as follows (bit 0 = least
+ significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:15
+
+ - Slice ID
+
+ - .. row 2
+
+ - Bit 16:32
+
+ - Slice position or order
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)``
+ Enables H264 hierarchical coding. Applicable to the H264 encoder.
+
+.. _`v4l2-mpeg-video-h264-hierarchical-coding-type`:
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE (enum v4l2_mpeg_video_h264_hierarchical_coding_type)``
+ Specifies the hierarchical coding type. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B``
+
+ - Hierarchical B coding.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P``
+
+ - Hierarchical P coding.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)``
+ Specifies the number of hierarchical coding layers. Applicable to
+ the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)``
+ Specifies a user defined QP for each layer. Applicable to the H264
+ encoder. The supplied 32-bit integer is interpreted as follows (bit
+ 0 = least significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:15
+
+ - QP value
+
+ - .. row 2
+
+ - Bit 16:32
+
+ - Layer number
+
+
+
+
+MFC 5.1 MPEG Controls
+---------------------
+
+The following MPEG class controls deal with MPEG decoding and encoding
+settings that are specific to the Multi Format Codec 5.1 device present
+in the S5P family of SoCs by Samsung.
+
+
+.. _mfc51-control-id:
+
+MFC 5.1 Control IDs
+^^^^^^^^^^^^^^^^^^^
+
+``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_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_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This
+ feature can be used for example for generating thumbnails of videos.
+ Applicable to the H264 decoder.
+
+``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
+ frames. If this number is low it may result in frames returned out
+ of dispaly order, in addition the hardware may still be using the
+ returned buffer as a reference picture for subsequent frames.
+
+``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.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)``
+ Padding enable in the encoder - use a color instead of repeating
+ border pixels. Applicable to encoders.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)``
+ Padding color in the encoder. Applicable to encoders. The supplied
+ 32-bit integer is interpreted as follows (bit 0 = least significant
+ bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:7
+
+ - V chrominance information
+
+ - .. row 2
+
+ - Bit 8:15
+
+ - U chrominance information
+
+ - .. row 3
+
+ - Bit 16:23
+
+ - Y luminance information
+
+ - .. row 4
+
+ - Bit 24:31
+
+ - Must be zero.
+
+
+
+``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
+ Reaction coefficient for MFC rate control. Applicable to encoders.
+
+ Note 1: Valid only when the frame level RC is enabled.
+
+ Note 2: For tight CBR, this field must be small (ex. 2 ~ 10). For
+ VBR, this field must be large (ex. 100 ~ 1000).
+
+ Note 3: It is not recommended to use the greater number than
+ FRAME_RATE * (10^9 / BIT_RATE).
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)``
+ Adaptive rate control for dark region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)``
+ Adaptive rate control for smooth region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)``
+ Adaptive rate control for static region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)``
+ Adaptive rate control for activity region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+.. _`v4l2-mpeg-mfc51-video-frame-skip-mode`:
+
+``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE (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
+ chosen data limit then the frame will be skipped. Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED``
+
+ - Frame skip mode is disabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT``
+
+ - Frame skip mode enabled and buffer limit is set by the chosen
+ level and is defined by the standard.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_MFC51_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.
+
+
+
+``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)``
+ Enable rate-control with fixed target bit. If this setting is
+ enabled, then the rate control logic of the encoder will calculate
+ the average bitrate for a GOP and keep it below or equal the set
+ bitrate target. Otherwise the rate control logic calculates the
+ overall average bitrate for the stream and keeps it below or equal
+ to the set bitrate. In the first case the average bitrate for the
+ whole stream will be smaller then the set bitrate. This is caused
+ because the average is calculated for smaller number of frames, on
+ the other hand enabling this setting will ensure that the stream
+ will meet tight bandwidth constraints. Applicable to encoders.
+
+.. _`v4l2-mpeg-mfc51-video-force-frame-type`:
+
+``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE (enum v4l2_mpeg_mfc51_video_force_frame_type)``
+ Force a frame type for the next queued buffer. Applicable to
+ encoders. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED``
+
+ - Forcing a specific frame type disabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME``
+
+ - Force an I-frame.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED``
+
+ - Force a non-coded frame.
+
+
+
+
+CX2341x MPEG Controls
+---------------------
+
+The following MPEG class controls deal with MPEG encoding settings that
+are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.
+
+
+.. _cx2341x-control-id:
+
+CX2341x Control IDs
+^^^^^^^^^^^^^^^^^^^
+
+.. _`v4l2-mpeg-cx2341x-video-spatial-filter-mode`:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_spatial_filter_mode)``
+ Sets the Spatial Filter mode (default ``MANUAL``). Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL``
+
+ - Choose the filter manually
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO``
+
+ - Choose the filter automatically
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))``
+ The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default
+ is 0.)
+
+.. _`luma-spatial-filter-type`:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type)``
+ Select the algorithm to use for the Luma Spatial Filter (default
+ ``1D_HOR``). Possible values:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR``
+
+ - One-dimensional horizontal
+
+ - .. row 3
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT``
+
+ - One-dimensional vertical
+
+ - .. row 4
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE``
+
+ - Two-dimensional separable
+
+ - .. row 5
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE``
+
+ - Two-dimensional symmetrical non-separable
+
+
+
+.. _`chroma-spatial-filter-type`:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type)``
+ Select the algorithm for the Chroma Spatial Filter (default
+ ``1D_HOR``). Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR``
+
+ - One-dimensional horizontal
+
+
+
+.. _`v4l2-mpeg-cx2341x-video-temporal-filter-mode`:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_temporal_filter_mode)``
+ Sets the Temporal Filter mode (default ``MANUAL``). Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL``
+
+ - Choose the filter manually
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO``
+
+ - Choose the filter automatically
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))``
+ The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default
+ is 8 for full-scale capturing and 0 for scaled capturing.)
+
+.. _`v4l2-mpeg-cx2341x-video-median-filter-type`:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_median_filter_type)``
+ Median Filter Type (default ``OFF``). Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR``
+
+ - Horizontal filter
+
+ - .. row 3
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT``
+
+ - Vertical filter
+
+ - .. row 4
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT``
+
+ - Horizontal and vertical filter
+
+ - .. row 5
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG``
+
+ - Diagonal filter
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
+ Threshold above which the luminance median filter is enabled
+ (default 0)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))``
+ Threshold below which the luminance median filter is enabled
+ (default 255)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
+ Threshold above which the chroma median filter is enabled (default
+ 0)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))``
+ Threshold below which the chroma median filter is enabled (default
+ 255)
+
+``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)``
+ The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into
+ the stream between every four video frames. The packet size is 2048
+ bytes, including the packet_start_code_prefix and stream_id
+ fields. The stream_id is 0xBF (private stream 2). The payload
+ consists of 0x00 bytes, to be filled in by the application. 0 = do
+ not insert, 1 = insert packets.
+
+
+VPX Control Reference
+---------------------
+
+The VPX controls include controls for encoding parameters of VPx video
+codec.
+
+
+.. _vpx-control-id:
+
+VPX Control IDs
+^^^^^^^^^^^^^^^
+
+.. _`v4l2-vpx-num-partitions`:
+
+``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS (enum v4l2_vp8_num_partitions)``
+ The number of token partitions to use in VP8 encoder. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION``
+
+ - 1 coefficient partition
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS``
+
+ - 2 coefficient partitions
+
+ - .. row 3
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS``
+
+ - 4 coefficient partitions
+
+ - .. row 4
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS``
+
+ - 8 coefficient partitions
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)``
+ Setting this prevents intra 4x4 mode in the intra mode decision.
+
+.. _`v4l2-vpx-num-ref-frames`:
+
+``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES (enum v4l2_vp8_num_ref_frames)``
+ The number of reference pictures for encoding P frames. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME``
+
+ - Last encoded frame will be searched
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME``
+
+ - Two frames will be searched among the last encoded frame, the
+ golden frame and the alternate reference (altref) frame. The
+ encoder implementation will decide which two are chosen.
+
+ - .. row 3
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME``
+
+ - The last encoded frame, the golden frame and the altref frame will
+ be searched.
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)``
+ Indicates the loop filter level. The adjustment of the loop filter
+ level is done via a delta value against a baseline loop filter
+ value.
+
+``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)``
+ This parameter affects the loop filter. Anything above zero weakens
+ the deblocking effect on the loop filter.
+
+``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)``
+ Sets the refresh period for the golden frame. The period is defined
+ in number of frames. For a value of 'n', every nth frame starting
+ from the first key frame will be taken as a golden frame. For eg.
+ for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden
+ frame refresh period is set as 4, the frames 0, 4, 8 etc will be
+ taken as the golden frames as frame 0 is always a key frame.
+
+.. _`v4l2-vpx-golden-frame-sel`:
+
+``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL (enum v4l2_vp8_golden_frame_sel)``
+ Selects the golden frame for encoding. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV``
+
+ - Use the (n-2)th frame as a golden frame, current frame index being
+ 'n'.
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD``
+
+ - Use the previous specific frame indicated by
+ V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD as a
+ golden frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)``
+ Minimum quantization parameter for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)``
+ Maximum quantization parameter for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)``
+ Quantization parameter for a P frame for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_PROFILE (integer)``
+ Select the desired profile for VPx encoder. Acceptable values are 0,
+ 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.
+
+
+.. _camera-controls:
+
+Camera Control Reference
+========================
+
+The Camera class includes controls for mechanical (or equivalent
+digital) features of a device such as controllable lenses or sensors.
+
+
+.. _camera-control-id:
+
+Camera Control IDs
+------------------
+
+``V4L2_CID_CAMERA_CLASS (class)``
+ The Camera class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` for this control will
+ return a description of this control class.
+
+.. _`v4l2-exposure-auto-type`:
+
+``V4L2_CID_EXPOSURE_AUTO (enum v4l2_exposure_auto_type)``
+ Enables automatic adjustments of the exposure time and/or iris
+ aperture. The effect of manual changes of the exposure time or iris
+ aperture while these features are enabled is undefined, drivers
+ should ignore such requests. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_EXPOSURE_AUTO``
+
+ - Automatic exposure time, automatic iris aperture.
+
+ - .. row 2
+
+ - ``V4L2_EXPOSURE_MANUAL``
+
+ - Manual exposure time, manual iris.
+
+ - .. row 3
+
+ - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
+
+ - Manual exposure time, auto iris.
+
+ - .. row 4
+
+ - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
+
+ - Auto exposure time, manual iris.
+
+
+
+``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
+ Determines the exposure time of the camera sensor. The exposure time
+ is limited by the frame interval. Drivers should interpret the
+ values as 100 µs units, where the value 1 stands for 1/10000th of a
+ second, 10000 for 1 second and 100000 for 10 seconds.
+
+``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
+ When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
+ ``APERTURE_PRIORITY``, this control determines if the device may
+ dynamically vary the frame rate. By default this feature is disabled
+ (0) and the frame rate must remain constant.
+
+``V4L2_CID_EXPOSURE_BIAS (integer menu)``
+ Determines the automatic exposure compensation, it is effective only
+ when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
+ ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
+ terms of EV, drivers should interpret the values as 0.001 EV units,
+ where the value 1000 stands for +1 EV.
+
+ Increasing the exposure compensation value is equivalent to
+ decreasing the exposure value (EV) and will increase the amount of
+ light at the image sensor. The camera performs the exposure
+ compensation by adjusting absolute exposure time and/or aperture.
+
+.. _`v4l2-exposure-metering`:
+
+``V4L2_CID_EXPOSURE_METERING (enum v4l2_exposure_metering)``
+ Determines how the camera measures the amount of light available for
+ the frame exposure. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_EXPOSURE_METERING_AVERAGE``
+
+ - Use the light information coming from the entire frame and average
+ giving no weighting to any particular portion of the metered area.
+
+ - .. row 2
+
+ - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
+
+ - Average the light information coming from the entire frame giving
+ priority to the center of the metered area.
+
+ - .. row 3
+
+ - ``V4L2_EXPOSURE_METERING_SPOT``
+
+ - Measure only very small area at the center of the frame.
+
+ - .. row 4
+
+ - ``V4L2_EXPOSURE_METERING_MATRIX``
+
+ - A multi-zone metering. The light intensity is measured in several
+ points of the frame and the results are combined. The algorithm of
+ the zones selection and their significance in calculating the
+ final value is device dependent.
+
+
+
+``V4L2_CID_PAN_RELATIVE (integer)``
+ This control turns the camera horizontally by the specified amount.
+ The unit is undefined. A positive value moves the camera to the
+ right (clockwise when viewed from above), a negative value to the
+ left. A value of zero does not cause motion. This is a write-only
+ control.
+
+``V4L2_CID_TILT_RELATIVE (integer)``
+ This control turns the camera vertically by the specified amount.
+ The unit is undefined. A positive value moves the camera up, a
+ negative value down. A value of zero does not cause motion. This is
+ a write-only control.
+
+``V4L2_CID_PAN_RESET (button)``
+ When this control is set, the camera moves horizontally to the
+ default position.
+
+``V4L2_CID_TILT_RESET (button)``
+ When this control is set, the camera moves vertically to the default
+ position.
+
+``V4L2_CID_PAN_ABSOLUTE (integer)``
+ This control turns the camera horizontally to the specified
+ position. Positive values move the camera to the right (clockwise
+ when viewed from above), negative values to the left. Drivers should
+ interpret the values as arc seconds, with valid values between -180
+ * 3600 and +180 * 3600 inclusive.
+
+``V4L2_CID_TILT_ABSOLUTE (integer)``
+ This control turns the camera vertically to the specified position.
+ Positive values move the camera up, negative values down. Drivers
+ should interpret the values as arc seconds, with valid values
+ between -180 * 3600 and +180 * 3600 inclusive.
+
+``V4L2_CID_FOCUS_ABSOLUTE (integer)``
+ This control sets the focal point of the camera to the specified
+ position. The unit is undefined. Positive values set the focus
+ closer to the camera, negative values towards infinity.
+
+``V4L2_CID_FOCUS_RELATIVE (integer)``
+ This control moves the focal point of the camera by the specified
+ amount. The unit is undefined. Positive values move the focus closer
+ to the camera, negative values towards infinity. This is a
+ write-only control.
+
+``V4L2_CID_FOCUS_AUTO (boolean)``
+ Enables continuous automatic focus adjustments. The effect of manual
+ focus adjustments while this feature is enabled is undefined,
+ drivers should ignore such requests.
+
+``V4L2_CID_AUTO_FOCUS_START (button)``
+ Starts single auto focus process. The effect of setting this control
+ when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
+ drivers should ignore such requests.
+
+``V4L2_CID_AUTO_FOCUS_STOP (button)``
+ Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
+ control. It is effective only when the continuous autofocus is
+ disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
+ ``FALSE`` (0).
+
+.. _`v4l2-auto-focus-status`:
+
+``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
+ The automatic focus status. This is a read-only control.
+
+ Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
+ control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
+ control value.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
+
+ - Automatic focus is not active.
+
+ - .. row 2
+
+ - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
+
+ - Automatic focusing is in progress.
+
+ - .. row 3
+
+ - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
+
+ - Focus has been reached.
+
+ - .. row 4
+
+ - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
+
+ - Automatic focus has failed, the driver will not transition from
+ this state until another action is performed by an application.
+
+
+
+.. _`v4l2-auto-focus-range`:
+
+``V4L2_CID_AUTO_FOCUS_RANGE (enum v4l2_auto_focus_range)``
+ Determines auto focus distance range for which lens may be adjusted.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
+
+ - The camera automatically selects the focus range.
+
+ - .. row 2
+
+ - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
+
+ - Normal distance range, limited for best automatic focus
+ performance.
+
+ - .. row 3
+
+ - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
+
+ - Macro (close-up) auto focus. The camera will use its minimum
+ possible distance for auto focus.
+
+ - .. row 4
+
+ - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
+
+ - The lens is set to focus on an object at infinite distance.
+
+
+
+``V4L2_CID_ZOOM_ABSOLUTE (integer)``
+ Specify the objective lens focal length as an absolute value. The
+ zoom unit is driver-specific and its value should be a positive
+ integer.
+
+``V4L2_CID_ZOOM_RELATIVE (integer)``
+ Specify the objective lens focal length relatively to the current
+ value. Positive values move the zoom lens group towards the
+ telephoto direction, negative values towards the wide-angle
+ direction. The zoom unit is driver-specific. This is a write-only
+ control.
+
+``V4L2_CID_ZOOM_CONTINUOUS (integer)``
+ Move the objective lens group at the specified speed until it
+ reaches physical device limits or until an explicit request to stop
+ the movement. A positive value moves the zoom lens group towards the
+ telephoto direction. A value of zero stops the zoom lens group
+ movement. A negative value moves the zoom lens group towards the
+ wide-angle direction. The zoom speed unit is driver-specific.
+
+``V4L2_CID_IRIS_ABSOLUTE (integer)``
+ This control sets the camera's aperture to the specified value. The
+ unit is undefined. Larger values open the iris wider, smaller values
+ close it.
+
+``V4L2_CID_IRIS_RELATIVE (integer)``
+ This control modifies the camera's aperture by the specified amount.
+ The unit is undefined. Positive values open the iris one step
+ further, negative values close it one step further. This is a
+ write-only control.
+
+``V4L2_CID_PRIVACY (boolean)``
+ Prevent video from being acquired by the camera. When this control
+ is set to ``TRUE`` (1), no image can be captured by the camera.
+ Common means to enforce privacy are mechanical obturation of the
+ sensor and firmware image processing, but the device is not
+ restricted to these methods. Devices that implement the privacy
+ control must support read access and may support write access.
+
+``V4L2_CID_BAND_STOP_FILTER (integer)``
+ Switch the band-stop filter of a camera sensor on or off, or specify
+ its strength. Such band-stop filters can be used, for example, to
+ filter out the fluorescent light component.
+
+.. _`v4l2-auto-n-preset-white-balance`:
+
+``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE (enum v4l2_auto_n_preset_white_balance)``
+ Sets white balance to automatic, manual or a preset. The presets
+ determine color temperature of the light as a hint to the camera for
+ white balance adjustments resulting in most accurate color
+ representation. The following white balance presets are listed in
+ order of increasing color temperature.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_WHITE_BALANCE_MANUAL``
+
+ - Manual white balance.
+
+ - .. row 2
+
+ - ``V4L2_WHITE_BALANCE_AUTO``
+
+ - Automatic white balance adjustments.
+
+ - .. row 3
+
+ - ``V4L2_WHITE_BALANCE_INCANDESCENT``
+
+ - White balance setting for incandescent (tungsten) lighting. It
+ generally cools down the colors and corresponds approximately to
+ 2500...3500 K color temperature range.
+
+ - .. row 4
+
+ - ``V4L2_WHITE_BALANCE_FLUORESCENT``
+
+ - White balance preset for fluorescent lighting. It corresponds
+ approximately to 4000...5000 K color temperature.
+
+ - .. row 5
+
+ - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
+
+ - With this setting the camera will compensate for fluorescent H
+ lighting.
+
+ - .. row 6
+
+ - ``V4L2_WHITE_BALANCE_HORIZON``
+
+ - White balance setting for horizon daylight. It corresponds
+ approximately to 5000 K color temperature.
+
+ - .. row 7
+
+ - ``V4L2_WHITE_BALANCE_DAYLIGHT``
+
+ - White balance preset for daylight (with clear sky). It corresponds
+ approximately to 5000...6500 K color temperature.
+
+ - .. row 8
+
+ - ``V4L2_WHITE_BALANCE_FLASH``
+
+ - With this setting the camera will compensate for the flash light.
+ It slightly warms up the colors and corresponds roughly to
+ 5000...5500 K color temperature.
+
+ - .. row 9
+
+ - ``V4L2_WHITE_BALANCE_CLOUDY``
+
+ - White balance preset for moderately overcast sky. This option
+ corresponds approximately to 6500...8000 K color temperature
+ range.
+
+ - .. row 10
+
+ - ``V4L2_WHITE_BALANCE_SHADE``
+
+ - White balance preset for shade or heavily overcast sky. It
+ corresponds approximately to 9000...10000 K color temperature.
+
+
+
+.. _`v4l2-wide-dynamic-range`:
+
+``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
+ Enables or disables the camera's wide dynamic range feature. This
+ feature allows to obtain clear images in situations where intensity
+ of the illumination varies significantly throughout the scene, i.e.
+ there are simultaneously very dark and very bright areas. It is most
+ commonly realized in cameras by combining two subsequent frames with
+ different exposure times. [1]_
+
+.. _`v4l2-image-stabilization`:
+
+``V4L2_CID_IMAGE_STABILIZATION (boolean)``
+ Enables or disables image stabilization.
+
+``V4L2_CID_ISO_SENSITIVITY (integer menu)``
+ Determines ISO equivalent of an image sensor indicating the sensor's
+ sensitivity to light. The numbers are expressed in arithmetic scale,
+ as per :ref:`iso12232` standard, where doubling the sensor
+ sensitivity is represented by doubling the numerical ISO value.
+ Applications should interpret the values as standard ISO values
+ multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
+ Drivers will usually support only a subset of standard ISO values.
+ The effect of setting this control while the
+ ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
+ than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
+ should ignore such requests.
+
+.. _`v4l2-iso-sensitivity-auto-type`:
+
+``V4L2_CID_ISO_SENSITIVITY_AUTO (enum v4l2_iso_sensitivity_type)``
+ Enables or disables automatic ISO sensitivity adjustments.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
+
+ - Manual ISO sensitivity.
+
+ - .. row 2
+
+ - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
+
+ - Automatic ISO sensitivity adjustments.
+
+
+
+.. _`v4l2-scene-mode`:
+
+``V4L2_CID_SCENE_MODE (enum v4l2_scene_mode)``
+ This control allows to select scene programs as the camera automatic
+ modes optimized for common shooting scenes. Within these modes the
+ camera determines best exposure, aperture, focusing, light metering,
+ white balance and equivalent sensitivity. The controls of those
+ parameters are influenced by the scene mode control. An exact
+ behavior in each mode is subject to the camera specification.
+
+ When the scene mode feature is not used, this control should be set
+ to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
+ controls are accessible. The following scene programs are defined:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_SCENE_MODE_NONE``
+
+ - The scene mode feature is disabled.
+
+ - .. row 2
+
+ - ``V4L2_SCENE_MODE_BACKLIGHT``
+
+ - Backlight. Compensates for dark shadows when light is coming from
+ behind a subject, also by automatically turning on the flash.
+
+ - .. row 3
+
+ - ``V4L2_SCENE_MODE_BEACH_SNOW``
+
+ - Beach and snow. This mode compensates for all-white or bright
+ scenes, which tend to look gray and low contrast, when camera's
+ automatic exposure is based on an average scene brightness. To
+ compensate, this mode automatically slightly overexposes the
+ frames. The white balance may also be adjusted to compensate for
+ the fact that reflected snow looks bluish rather than white.
+
+ - .. row 4
+
+ - ``V4L2_SCENE_MODE_CANDLELIGHT``
+
+ - Candle light. The camera generally raises the ISO sensitivity and
+ lowers the shutter speed. This mode compensates for relatively
+ close subject in the scene. The flash is disabled in order to
+ preserve the ambiance of the light.
+
+ - .. row 5
+
+ - ``V4L2_SCENE_MODE_DAWN_DUSK``
+
+ - Dawn and dusk. Preserves the colors seen in low natural light
+ before dusk and after down. The camera may turn off the flash, and
+ automatically focus at infinity. It will usually boost saturation
+ and lower the shutter speed.
+
+ - .. row 6
+
+ - ``V4L2_SCENE_MODE_FALL_COLORS``
+
+ - Fall colors. Increases saturation and adjusts white balance for
+ color enhancement. Pictures of autumn leaves get saturated reds
+ and yellows.
+
+ - .. row 7
+
+ - ``V4L2_SCENE_MODE_FIREWORKS``
+
+ - Fireworks. Long exposure times are used to capture the expanding
+ burst of light from a firework. The camera may invoke image
+ stabilization.
+
+ - .. row 8
+
+ - ``V4L2_SCENE_MODE_LANDSCAPE``
+
+ - Landscape. The camera may choose a small aperture to provide deep
+ depth of field and long exposure duration to help capture detail
+ in dim light conditions. The focus is fixed at infinity. Suitable
+ for distant and wide scenery.
+
+ - .. row 9
+
+ - ``V4L2_SCENE_MODE_NIGHT``
+
+ - Night, also known as Night Landscape. Designed for low light
+ conditions, it preserves detail in the dark areas without blowing
+ out bright objects. The camera generally sets itself to a
+ medium-to-high ISO sensitivity, with a relatively long exposure
+ time, and turns flash off. As such, there will be increased image
+ noise and the possibility of blurred image.
+
+ - .. row 10
+
+ - ``V4L2_SCENE_MODE_PARTY_INDOOR``
+
+ - Party and indoor. Designed to capture indoor scenes that are lit
+ by indoor background lighting as well as the flash. The camera
+ usually increases ISO sensitivity, and adjusts exposure for the
+ low light conditions.
+
+ - .. row 11
+
+ - ``V4L2_SCENE_MODE_PORTRAIT``
+
+ - Portrait. The camera adjusts the aperture so that the depth of
+ field is reduced, which helps to isolate the subject against a
+ smooth background. Most cameras recognize the presence of faces in
+ the scene and focus on them. The color hue is adjusted to enhance
+ skin tones. The intensity of the flash is often reduced.
+
+ - .. row 12
+
+ - ``V4L2_SCENE_MODE_SPORTS``
+
+ - Sports. Significantly increases ISO and uses a fast shutter speed
+ to freeze motion of rapidly-moving subjects. Increased image noise
+ may be seen in this mode.
+
+ - .. row 13
+
+ - ``V4L2_SCENE_MODE_SUNSET``
+
+ - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
+ up the saturation.
+
+ - .. row 14
+
+ - ``V4L2_SCENE_MODE_TEXT``
+
+ - Text. It applies extra contrast and sharpness, it is typically a
+ black-and-white mode optimized for readability. Automatic focus
+ may be switched to close-up mode and this setting may also involve
+ some lens-distortion correction.
+
+
+
+``V4L2_CID_3A_LOCK (bitmask)``
+ This control locks or unlocks the automatic focus, exposure and
+ white balance. The automatic adjustments can be paused independently
+ by setting the corresponding lock bit to 1. The camera then retains
+ the settings until the lock bit is cleared. The following lock bits
+ are defined:
+
+ When a given algorithm is not enabled, drivers should ignore
+ requests to lock it and should return no error. An example might be
+ an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
+ ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
+ value of this control may be changed by exposure, white balance or
+ focus controls.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_LOCK_EXPOSURE``
+
+ - Automatic exposure adjustments lock.
+
+ - .. row 2
+
+ - ``V4L2_LOCK_WHITE_BALANCE``
+
+ - Automatic white balance adjustments lock.
+
+ - .. row 3
+
+ - ``V4L2_LOCK_FOCUS``
+
+ - Automatic focus lock.
+
+
+
+``V4L2_CID_PAN_SPEED (integer)``
+ This control turns the camera horizontally at the specific speed.
+ The unit is undefined. A positive value moves the camera to the
+ right (clockwise when viewed from above), a negative value to the
+ left. A value of zero stops the motion if one is in progress and has
+ no effect otherwise.
+
+``V4L2_CID_TILT_SPEED (integer)``
+ This control turns the camera vertically at the specified speed. The
+ unit is undefined. A positive value moves the camera up, a negative
+ value down. A value of zero stops the motion if one is in progress
+ and has no effect otherwise.
+
+
+.. _fm-tx-controls:
+
+FM Transmitter Control Reference
+================================
+
+The FM Transmitter (FM_TX) class includes controls for common features
+of FM transmissions capable devices. Currently this class includes
+parameters for audio compression, pilot tone generation, audio deviation
+limiter, RDS transmission and tuning power features.
+
+
+.. _fm-tx-control-id:
+
+FM_TX Control IDs
+-----------------
+
+``V4L2_CID_FM_TX_CLASS (class)``
+ The FM_TX class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RDS_TX_DEVIATION (integer)``
+ Configures RDS signal frequency deviation level in Hz. The range and
+ step are driver-specific.
+
+``V4L2_CID_RDS_TX_PI (integer)``
+ Sets the RDS Programme Identification field for transmission.
+
+``V4L2_CID_RDS_TX_PTY (integer)``
+ Sets the RDS Programme Type field for transmission. This encodes up
+ to 31 pre-defined programme types.
+
+``V4L2_CID_RDS_TX_PS_NAME (string)``
+ Sets the Programme Service name (PS_NAME) for transmission. It is
+ intended for static display on a receiver. It is the primary aid to
+ listeners in programme service identification and selection. In
+ Annex E of :ref:`iec62106`, the RDS specification, there is a full
+ description of the correct character encoding for Programme Service
+ name strings. Also from RDS specification, PS is usually a single
+ eight character text. However, it is also possible to find receivers
+ which can scroll strings sized as 8 x N characters. So, this control
+ must be configured with steps of 8 characters. The result is it must
+ always contain a string with size multiple of 8.
+
+``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
+ Sets the Radio Text info for transmission. It is a textual
+ description of what is being broadcasted. RDS Radio Text can be
+ applied when broadcaster wishes to transmit longer PS names,
+ programme-related information or any other text. In these cases,
+ RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
+ The encoding for Radio Text strings is also fully described in Annex
+ E of :ref:`iec62106`. The length of Radio Text strings depends on
+ which RDS Block is being used to transmit it, either 32 (2A block)
+ or 64 (2B block). However, it is also possible to find receivers
+ which can scroll strings sized as 32 x N or 64 x N characters. So,
+ this control must be configured with steps of 32 or 64 characters.
+ The result is it must always contain a string with size multiple of
+ 32 or 64.
+
+``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
+ Sets the Mono/Stereo bit of the Decoder Identification code. If set,
+ then the audio was recorded as stereo.
+
+``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
+ Sets the
+ `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
+ bit of the Decoder Identification code. If set, then the audio was
+ recorded using an artificial head.
+
+``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
+ Sets the Compressed bit of the Decoder Identification code. If set,
+ then the audio is compressed.
+
+``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
+ Sets the Dynamic PTY bit of the Decoder Identification code. If set,
+ then the PTY code is dynamically switched.
+
+``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
+ If set, then a traffic announcement is in progress.
+
+``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
+ If set, then the tuned programme carries traffic announcements.
+
+``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
+ If set, then this channel broadcasts music. If cleared, then it
+ broadcasts speech. If the transmitter doesn't make this distinction,
+ then it should be set.
+
+``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
+ If set, then transmit alternate frequencies.
+
+``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
+ The alternate frequencies in kHz units. The RDS standard allows for
+ up to 25 frequencies to be defined. Drivers may support fewer
+ frequencies so check the array size.
+
+``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
+ Enables or disables the audio deviation limiter feature. The limiter
+ is useful when trying to maximize the audio volume, minimize
+ receiver-generated distortion and prevent overmodulation.
+
+``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
+ Sets the audio deviation limiter feature release time. Unit is in
+ useconds. Step and range are driver-specific.
+
+``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
+ Configures audio frequency deviation level in Hz. The range and step
+ are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
+ Enables or disables the audio compression feature. This feature
+ amplifies signals below the threshold by a fixed gain and compresses
+ audio signals above the threshold by the ratio of Threshold/(Gain +
+ Threshold).
+
+``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
+ Sets the gain for audio compression feature. It is a dB value. The
+ range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
+ Sets the threshold level for audio compression freature. It is a dB
+ value. The range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
+ Sets the attack time for audio compression feature. It is a useconds
+ value. The range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
+ Sets the release time for audio compression feature. It is a
+ useconds value. The range and step are driver-specific.
+
+``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
+ Enables or disables the pilot tone generation feature.
+
+``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
+ Configures pilot tone frequency deviation level. Unit is in Hz. The
+ range and step are driver-specific.
+
+``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
+ Configures pilot tone frequency value. Unit is in Hz. The range and
+ step are driver-specific.
+
+``V4L2_CID_TUNE_PREEMPHASIS (enum v4l2_preemphasis)``
+ Configures the pre-emphasis value for broadcasting. A pre-emphasis
+ filter is applied to the broadcast to accentuate the high audio
+ frequencies. Depending on the region, a time constant of either 50
+ or 75 useconds is used. The enum v4l2_preemphasis defines possible
+ values for pre-emphasis. Here they are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_PREEMPHASIS_DISABLED``
+
+ - No pre-emphasis is applied.
+
+ - .. row 2
+
+ - ``V4L2_PREEMPHASIS_50_uS``
+
+ - A pre-emphasis of 50 uS is used.
+
+ - .. row 3
+
+ - ``V4L2_PREEMPHASIS_75_uS``
+
+ - A pre-emphasis of 75 uS is used.
+
+
+
+``V4L2_CID_TUNE_POWER_LEVEL (integer)``
+ Sets the output power level for signal transmission. Unit is in
+ dBuV. Range and step are driver-specific.
+
+``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
+ This selects the value of antenna tuning capacitor manually or
+ automatically if set to zero. Unit, range and step are
+ driver-specific.
+
+For more details about RDS specification, refer to :ref:`iec62106`
+document, from CENELEC.
+
+
+.. _flash-controls:
+
+Flash Control Reference
+=======================
+
+The V4L2 flash controls are intended to provide generic access to flash
+controller devices. Flash controller devices are typically used in
+digital cameras.
+
+The interface can support both LED and xenon flash devices. As of
+writing this, there is no xenon flash driver using this interface.
+
+
+.. _flash-controls-use-cases:
+
+Supported use cases
+-------------------
+
+
+Unsynchronised LED flash (software strobe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unsynchronised LED flash is controlled directly by the host as the
+sensor. The flash must be enabled by the host before the exposure of the
+image starts and disabled once it ends. The host is fully responsible
+for the timing of the flash.
+
+Example of such device: Nokia N900.
+
+
+Synchronised LED flash (hardware strobe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The synchronised LED flash is pre-programmed by the host (power and
+timeout) but controlled by the sensor through a strobe signal from the
+sensor to the flash.
+
+The sensor controls the flash duration and timing. This information
+typically must be made available to the sensor.
+
+
+LED flash as torch
+^^^^^^^^^^^^^^^^^^
+
+LED flash may be used as torch in conjunction with another use case
+involving camera or individually.
+
+
+.. _flash-control-id:
+
+Flash Control IDs
+"""""""""""""""""
+
+``V4L2_CID_FLASH_CLASS (class)``
+ The FLASH class descriptor.
+
+``V4L2_CID_FLASH_LED_MODE (menu)``
+ Defines the mode of the flash LED, the high-power white LED attached
+ to the flash controller. Setting this control may not be possible in
+ presence of some faults. See V4L2_CID_FLASH_FAULT.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_LED_MODE_NONE``
+
+ - Off.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_LED_MODE_FLASH``
+
+ - Flash mode.
+
+ - .. row 3
+
+ - ``V4L2_FLASH_LED_MODE_TORCH``
+
+ - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
+
+
+
+``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
+ Defines the source of the flash LED strobe.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
+
+ - The flash strobe is triggered by using the
+ V4L2_CID_FLASH_STROBE control.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
+
+ - The flash strobe is triggered by an external source. Typically
+ this is a sensor, which makes it possible to synchronises the
+ flash strobe start to exposure start.
+
+
+
+``V4L2_CID_FLASH_STROBE (button)``
+ Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
+ V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
+ is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
+ control may not be possible in presence of some faults. See
+ V4L2_CID_FLASH_FAULT.
+
+``V4L2_CID_FLASH_STROBE_STOP (button)``
+ Stop flash strobe immediately.
+
+``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
+ Strobe status: whether the flash is strobing at the moment or not.
+ This is a read-only control.
+
+``V4L2_CID_FLASH_TIMEOUT (integer)``
+ Hardware timeout for flash. The flash strobe is stopped after this
+ period of time has passed from the start of the strobe.
+
+``V4L2_CID_FLASH_INTENSITY (integer)``
+ Intensity of the flash strobe when the flash LED is in flash mode
+ (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
+ if possible.
+
+``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
+ Intensity of the flash LED in torch mode
+ (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
+ if possible. Setting this control may not be possible in presence of
+ some faults. See V4L2_CID_FLASH_FAULT.
+
+``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
+ Intensity of the indicator LED. The indicator LED may be fully
+ independent of the flash LED. The unit should be microamps (uA) if
+ possible.
+
+``V4L2_CID_FLASH_FAULT (bitmask)``
+ Faults related to the flash. The faults tell about specific problems
+ in the flash chip itself or the LEDs attached to it. Faults may
+ prevent further use of some of the flash controls. In particular,
+ V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
+ if the fault affects the flash LED. Exactly which faults have such
+ an effect is chip dependent. Reading the faults resets the control
+ and returns the chip to a usable state if possible.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
+
+ - Flash controller voltage to the flash LED has exceeded the limit
+ specific to the flash controller.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_FAULT_TIMEOUT``
+
+ - The flash strobe was still on when the timeout set by the user ---
+ V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
+ controllers may set this in all such conditions.
+
+ - .. row 3
+
+ - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
+
+ - The flash controller has overheated.
+
+ - .. row 4
+
+ - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
+
+ - The short circuit protection of the flash controller has been
+ triggered.
+
+ - .. row 5
+
+ - ``V4L2_FLASH_FAULT_OVER_CURRENT``
+
+ - Current in the LED power supply has exceeded the limit specific to
+ the flash controller.
+
+ - .. row 6
+
+ - ``V4L2_FLASH_FAULT_INDICATOR``
+
+ - The flash controller has detected a short or open circuit
+ condition on the indicator LED.
+
+ - .. row 7
+
+ - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
+
+ - Flash controller voltage to the flash LED has been below the
+ minimum limit specific to the flash controller.
+
+ - .. row 8
+
+ - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
+
+ - The input voltage of the flash controller is below the limit under
+ which strobing the flash at full current will not be possible.The
+ condition persists until this flag is no longer set.
+
+ - .. row 9
+
+ - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
+
+ - The temperature of the LED has exceeded its allowed upper limit.
+
+
+
+``V4L2_CID_FLASH_CHARGE (boolean)``
+ Enable or disable charging of the xenon flash capacitor.
+
+``V4L2_CID_FLASH_READY (boolean)``
+ Is the flash ready to strobe? Xenon flashes require their capacitors
+ charged before strobing. LED flashes often require a cooldown period
+ after strobe during which another strobe will not be possible. This
+ is a read-only control.
+
+
+.. _jpeg-controls:
+
+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
+coding.
+
+
+.. _jpeg-control-id:
+
+JPEG Control IDs
+----------------
+
+``V4L2_CID_JPEG_CLASS (class)``
+ The JPEG class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` for this control will
+ return a description of this control class.
+
+``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
+ The chroma subsampling factors describe how each component of an
+ input image is sampled, in respect to maximum sample rate in each
+ spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
+ details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
+ how Cb and Cr components are downsampled after coverting an input
+ image from RGB to Y'CbCr color space.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
+
+ - No chroma subsampling, each pixel has Y, Cr and Cb values.
+
+ - .. row 2
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
+
+ - Horizontally subsample Cr, Cb components by a factor of 2.
+
+ - .. row 3
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
+
+ - Subsample Cr, Cb components horizontally and vertically by 2.
+
+ - .. row 4
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
+
+ - Horizontally subsample Cr, Cb components by a factor of 4.
+
+ - .. row 5
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
+
+ - Subsample Cr, Cb components horizontally by 4 and vertically by 2.
+
+ - .. row 6
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
+
+ - Use only luminance component.
+
+
+
+``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
+ The restart interval determines an interval of inserting RSTm
+ markers (m = 0..7). The purpose of these markers is to additionally
+ reinitialize the encoder process, in order to process blocks of an
+ image independently. For the lossy compression processes the restart
+ interval unit is MCU (Minimum Coded Unit) and its value is contained
+ in DRI (Define Restart Interval) marker. If
+ ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
+ markers will not be inserted.
+
+.. _`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
+ driver to 0.
+
+ The value range of this control is driver-specific. Only positive,
+ non-zero values are meaningful. The recommended range is 1 - 100,
+ where larger values correspond to better image quality.
+
+.. _`jpeg-active-marker-control`:
+
+``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
+ Specify which JPEG markers are included in compressed stream. This
+ control is valid only for encoders.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_APP0``
+
+ - Application data segment APP\ :sub:`0`.
+
+ - .. row 2
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_APP1``
+
+ - Application data segment APP\ :sub:`1`.
+
+ - .. row 3
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_COM``
+
+ - Comment segment.
+
+ - .. row 4
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
+
+ - Quantization tables segment.
+
+ - .. row 5
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
+
+ - Huffman tables segment.
+
+
+
+For more details about JPEG specification, refer to :ref:`itu-t81`,
+:ref:`jfif`, :ref:`w3c-jpeg-jfif`.
+
+
+.. _image-source-controls:
+
+Image Source Control Reference
+==============================
+
+The Image Source control class is intended for low-level control of
+image source devices such as image sensors. The devices feature an
+analogue to digital converter and a bus transmitter to transmit the
+image data out of the device.
+
+
+.. _image-source-control-id:
+
+Image Source Control IDs
+------------------------
+
+``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
+ The IMAGE_SOURCE class descriptor.
+
+``V4L2_CID_VBLANK (integer)``
+ Vertical blanking. The idle period after every frame during which no
+ image data is produced. The unit of vertical blanking is a line.
+ Every line has length of the image width plus horizontal blanking at
+ the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
+ same sub-device.
+
+``V4L2_CID_HBLANK (integer)``
+ Horizontal blanking. The idle period after every line of image data
+ during which no image data is produced. The unit of horizontal
+ blanking is pixels.
+
+``V4L2_CID_ANALOGUE_GAIN (integer)``
+ Analogue gain is gain affecting all colour components in the pixel
+ matrix. The gain operation is performed in the analogue domain
+ before A/D conversion.
+
+``V4L2_CID_TEST_PATTERN_RED (integer)``
+ Test pattern red colour component.
+
+``V4L2_CID_TEST_PATTERN_GREENR (integer)``
+ Test pattern green (next to red) colour component.
+
+``V4L2_CID_TEST_PATTERN_BLUE (integer)``
+ Test pattern blue colour component.
+
+``V4L2_CID_TEST_PATTERN_GREENB (integer)``
+ Test pattern green (next to blue) colour component.
+
+
+.. _image-process-controls:
+
+Image Process Control Reference
+===============================
+
+The Image Process control class is intended for low-level control of
+image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the
+controls in this class affect processing the image, and do not control
+capturing of it.
+
+
+.. _image-process-control-id:
+
+Image Process Control IDs
+-------------------------
+
+``V4L2_CID_IMAGE_PROC_CLASS (class)``
+ The IMAGE_PROC class descriptor.
+
+``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.
+
+``V4L2_CID_PIXEL_RATE (64-bit integer)``
+ Pixel rate in the source pads of the subdev. This control is
+ read-only and its unit is pixels / second.
+
+``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
+ used to test if a device is working properly.
+
+
+.. _dv-controls:
+
+Digital Video Control Reference
+===============================
+
+The Digital Video control class is intended to control receivers and
+transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
+`DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
+(Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
+(:ref:`dp`). These controls are generally expected to be private to
+the receiver or transmitter subdevice that implements them, so they are
+only exposed on the ``/dev/v4l-subdev*`` device node.
+
+Note that these devices can have multiple input or output pads which are
+hooked up to e.g. HDMI connectors. Even though the subdevice will
+receive or transmit video from/to only one of those pads, the other pads
+can still be active when it comes to EDID (Extended Display
+Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
+Content Protection System, :ref:`hdcp`) processing, allowing the
+device to do the fairly slow EDID/HDCP handling in advance. This allows
+for quick switching between connectors.
+
+These pads appear in several of the controls in this section as
+bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
+1, etc. The maximum value of the control is the set of valid pads.
+
+
+.. _dv-control-id:
+
+Digital Video Control IDs
+-------------------------
+
+``V4L2_CID_DV_CLASS (class)``
+ The Digital Video class descriptor.
+
+``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
+ Many connectors have a hotplug pin which is high if EDID information
+ is available from the source. This control shows the state of the
+ hotplug pin as seen by the transmitter. Each bit corresponds to an
+ output pad on the transmitter. If an output pad does not have an
+ associated hotplug pin, then the bit for that pad will be 0. This
+ read-only control is applicable to DVI-D, HDMI and DisplayPort
+ connectors.
+
+``V4L2_CID_DV_TX_RXSENSE (bitmask)``
+ Rx Sense is the detection of pull-ups on the TMDS clock lines. This
+ normally means that the sink has left/entered standby (i.e. the
+ transmitter can sense that the receiver is ready to receive video).
+ Each bit corresponds to an output pad on the transmitter. If an
+ output pad does not have an associated Rx Sense, then the bit for
+ that pad will be 0. This read-only control is applicable to DVI-D
+ and HDMI devices.
+
+``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
+ When the transmitter sees the hotplug signal from the receiver it
+ will attempt to read the EDID. If set, then the transmitter has read
+ at least the first block (= 128 bytes). Each bit corresponds to an
+ output pad on the transmitter. If an output pad does not support
+ EDIDs, then the bit for that pad will be 0. This read-only control
+ is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_TX_MODE (enum v4l2_dv_tx_mode)``
+ HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
+ mode (video + audio + auxiliary data). This control selects which
+ mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
+ This control is applicable to HDMI connectors.
+
+``V4L2_CID_DV_TX_RGB_RANGE (enum v4l2_dv_rgb_range)``
+ Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
+ follows the RGB quantization range specified in the standard for the
+ video interface (ie. :ref:`cea861` for HDMI).
+ V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
+ standard to be compatible with sinks that have not implemented the
+ standard correctly (unfortunately quite common for HDMI and DVI-D).
+ Full range allows all possible values to be used whereas limited
+ range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
+ the number of bits per component. This control is applicable to VGA,
+ DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_TX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
+ Configures the IT Content Type of the transmitted video. This
+ information is sent over HDMI and DisplayPort connectors as part of
+ the AVI InfoFrame. The term 'IT Content' is used for content that
+ originates from a computer as opposed to content from a TV broadcast
+ or an analog source. The enum v4l2_dv_it_content_type defines
+ the possible content types:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
+
+ - Graphics content. Pixel data should be passed unfiltered and
+ without analog reconstruction.
+
+ - .. row 2
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
+
+ - Photo content. The content is derived from digital still pictures.
+ The content should be passed through with minimal scaling and
+ picture enhancements.
+
+ - .. row 3
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
+
+ - Cinema content.
+
+ - .. row 4
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_GAME``
+
+ - Game content. Audio and video latency should be minimized.
+
+ - .. row 5
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
+
+ - No IT Content information is available and the ITC bit in the AVI
+ InfoFrame is set to 0.
+
+
+
+``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
+ Detects whether the receiver receives power from the source (e.g.
+ HDMI carries 5V on one of the pins). This is often used to power an
+ eeprom which contains EDID information, such that the source can
+ read the EDID even if the sink is in standby/power off. Each bit
+ corresponds to an input pad on the transmitter. If an input pad
+ cannot detect whether power is present, then the bit for that pad
+ will be 0. This read-only control is applicable to DVI-D, HDMI and
+ DisplayPort connectors.
+
+``V4L2_CID_DV_RX_RGB_RANGE (enum v4l2_dv_rgb_range)``
+ Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
+ follows the RGB quantization range specified in the standard for the
+ video interface (ie. :ref:`cea861` for HDMI).
+ V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
+ standard to be compatible with sources that have not implemented the
+ standard correctly (unfortunately quite common for HDMI and DVI-D).
+ Full range allows all possible values to be used whereas limited
+ range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
+ the number of bits per component. This control is applicable to VGA,
+ DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_RX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
+ Reads the IT Content Type of the received video. This information is
+ sent over HDMI and DisplayPort connectors as part of the AVI
+ InfoFrame. The term 'IT Content' is used for content that originates
+ from a computer as opposed to content from a TV broadcast or an
+ analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
+ available content types.
+
+
+.. _fm-rx-controls:
+
+FM Receiver Control Reference
+=============================
+
+The FM Receiver (FM_RX) class includes controls for common features of
+FM Reception capable devices.
+
+
+.. _fm-rx-control-id:
+
+FM_RX Control IDs
+-----------------
+
+``V4L2_CID_FM_RX_CLASS (class)``
+ The FM_RX class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RDS_RECEPTION (boolean)``
+ Enables/disables RDS reception by the radio tuner
+
+``V4L2_CID_RDS_RX_PTY (integer)``
+ Gets RDS Programme Type field. This encodes up to 31 pre-defined
+ programme types.
+
+``V4L2_CID_RDS_RX_PS_NAME (string)``
+ Gets the Programme Service name (PS_NAME). It is intended for
+ static display on a receiver. It is the primary aid to listeners in
+ programme service identification and selection. In Annex E of
+ :ref:`iec62106`, the RDS specification, there is a full
+ description of the correct character encoding for Programme Service
+ name strings. Also from RDS specification, PS is usually a single
+ eight character text. However, it is also possible to find receivers
+ which can scroll strings sized as 8 x N characters. So, this control
+ must be configured with steps of 8 characters. The result is it must
+ always contain a string with size multiple of 8.
+
+``V4L2_CID_RDS_RX_RADIO_TEXT (string)``
+ Gets the Radio Text info. It is a textual description of what is
+ being broadcasted. RDS Radio Text can be applied when broadcaster
+ wishes to transmit longer PS names, programme-related information or
+ any other text. In these cases, RadioText can be used in addition to
+ ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is
+ also fully described in Annex E of :ref:`iec62106`. The length of
+ Radio Text strings depends on which RDS Block is being used to
+ transmit it, either 32 (2A block) or 64 (2B block). However, it is
+ also possible to find receivers which can scroll strings sized as 32
+ x N or 64 x N characters. So, this control must be configured with
+ steps of 32 or 64 characters. The result is it must always contain a
+ string with size multiple of 32 or 64.
+
+``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
+ If set, then a traffic announcement is in progress.
+
+``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
+ If set, then the tuned programme carries traffic announcements.
+
+``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)``
+ If set, then this channel broadcasts music. If cleared, then it
+ broadcasts speech. If the transmitter doesn't make this distinction,
+ then it will be set.
+
+``V4L2_CID_TUNE_DEEMPHASIS (enum v4l2_deemphasis)``
+ Configures the de-emphasis value for reception. A de-emphasis filter
+ is applied to the broadcast to accentuate the high audio
+ frequencies. Depending on the region, a time constant of either 50
+ or 75 useconds is used. The enum v4l2_deemphasis defines possible
+ values for de-emphasis. Here they are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DEEMPHASIS_DISABLED``
+
+ - No de-emphasis is applied.
+
+ - .. row 2
+
+ - ``V4L2_DEEMPHASIS_50_uS``
+
+ - A de-emphasis of 50 uS is used.
+
+ - .. row 3
+
+ - ``V4L2_DEEMPHASIS_75_uS``
+
+ - A de-emphasis of 75 uS is used.
+
+
+
+
+.. _detect-controls:
+
+Detect Control Reference
+========================
+
+The Detect class includes controls for common features of various motion
+or object detection capable devices.
+
+
+.. _detect-control-id:
+
+Detect Control IDs
+------------------
+
+``V4L2_CID_DETECT_CLASS (class)``
+ The Detect class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` for this control will
+ return a description of this control class.
+
+``V4L2_CID_DETECT_MD_MODE (menu)``
+ Sets the motion detection mode.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DETECT_MD_MODE_DISABLED``
+
+ - Disable motion detection.
+
+ - .. row 2
+
+ - ``V4L2_DETECT_MD_MODE_GLOBAL``
+
+ - Use a single motion detection threshold.
+
+ - .. row 3
+
+ - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID``
+
+ - The image is divided into a grid, each cell with its own motion
+ detection threshold. These thresholds are set through the
+ ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control.
+
+ - .. row 4
+
+ - ``V4L2_DETECT_MD_MODE_REGION_GRID``
+
+ - The image is divided into a grid, each cell with its own region
+ value that specifies which per-region motion detection thresholds
+ should be used. Each region has its own thresholds. How these
+ per-region thresholds are set up is driver-specific. The region
+ values for the grid are set through the
+ ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control.
+
+
+
+``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)``
+ Sets the global motion detection threshold to be used with the
+ ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode.
+
+``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)``
+ Sets the motion detection thresholds for each cell in the grid. To
+ be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion
+ detection mode. Matrix element (0, 0) represents the cell at the
+ top-left of the grid.
+
+``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)``
+ Sets the motion detection region value for each cell in the grid. To
+ be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion
+ detection mode. Matrix element (0, 0) represents the cell at the
+ top-left of the grid.
+
+
+.. _rf-tuner-controls:
+
+RF Tuner Control Reference
+==========================
+
+The RF Tuner (RF_TUNER) class includes controls for common features of
+devices having RF tuner.
+
+In this context, RF tuner is radio receiver circuit between antenna and
+demodulator. It receives radio frequency (RF) from the antenna and
+converts that received signal to lower intermediate frequency (IF) or
+baseband frequency (BB). Tuners that could do baseband output are often
+called Zero-IF tuners. Older tuners were typically simple PLL tuners
+inside a metal box, whilst newer ones are highly integrated chips
+without a metal box "silicon tuners". These controls are mostly
+applicable for new feature rich silicon tuners, just because older
+tuners does not have much adjustable features.
+
+For more information about RF tuners see
+`Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__
+and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__
+from Wikipedia.
+
+
+.. _rf-tuner-control-id:
+
+RF_TUNER Control IDs
+--------------------
+
+``V4L2_CID_RF_TUNER_CLASS (class)``
+ The RF_TUNER class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)``
+ Enables/disables tuner radio channel bandwidth configuration. In
+ automatic mode bandwidth configuration is performed by the driver.
+
+``V4L2_CID_RF_TUNER_BANDWIDTH (integer)``
+ Filter(s) on tuner signal path are used to filter signal according
+ to receiving party needs. Driver configures filters to fulfill
+ desired bandwidth requirement. Used when
+ V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The
+ range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
+ Enables/disables LNA automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
+ Enables/disables mixer automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
+ Enables/disables IF automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_RF_GAIN (integer)``
+ The RF amplifier is the very first amplifier on the receiver signal
+ path, just right after the antenna input. The difference between the
+ LNA gain and the RF gain in this document is that the LNA gain is
+ integrated in the tuner chip while the RF gain is a separate chip.
+ There may be both RF and LNA gain controls in the same device. The
+ range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_LNA_GAIN (integer)``
+ LNA (low noise amplifier) gain is first gain stage on the RF tuner
+ signal path. It is located very close to tuner antenna input. Used
+ when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See
+ ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain
+ differs from the each others. The range and step are
+ driver-specific.
+
+``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)``
+ Mixer gain is second gain stage on the RF tuner signal path. It is
+ located inside mixer block, where RF signal is down-converted by the
+ mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set.
+ The range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_IF_GAIN (integer)``
+ IF gain is last gain stage on the RF tuner signal path. It is
+ located on output of RF tuner. It controls signal level of
+ intermediate frequency output or baseband output. Used when
+ ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step
+ are driver-specific.
+
+``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)``
+ Is synthesizer PLL locked? RF tuner is receiving given frequency
+ when that control is set. This is a read-only control.
+
+.. [1]
+ This control may be changed to a menu control in the future, if more
+ options are required.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _fdl:
+
+******************************
+GNU Free Documentation License
+******************************
+
+
+.. _fdl-preamble:
+
+0. PREAMBLE
+===========
+
+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
+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
+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.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free program
+should come with manuals providing the same freedoms that the software
+does. But this License is not limited to software manuals; it can be
+used for any textual work, regardless of subject matter or whether it is
+published as a printed book. We recommend this License principally for
+works whose purpose is instruction or reference.
+
+
+.. _fdl-section1:
+
+1. APPLICABILITY AND DEFINITIONS
+================================
+
+
+.. _fdl-document:
+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
+or work. Any member of the public is a licensee, and is addressed as
+“you”.
+
+
+.. _fdl-modified:
+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
+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
+that could fall directly within that overall subject. (For example, if
+the Document is in part a textbook of mathematics, a Secondary Section
+may not explain any mathematics.) The relationship could be a matter of
+historical connection with the subject or with related matters, or of
+legal, commercial, philosophical, ethical or political position
+regarding them.
+
+
+.. _fdl-invariant:
+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.
+
+
+.. _fdl-cover-texts:
+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
+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
+composed of pixels) generic paint programs or (for drawings) some widely
+available drawing editor, and that is suitable for input to text
+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”.
+
+Examples of suitable formats for Transparent copies include plain ASCII
+without markup, Texinfo input format, LaTeX input format, SGML or XML
+using a publicly available DTD, and standard-conforming simple HTML
+designed for human modification. Opaque formats include PostScript, PDF,
+proprietary formats that can be read and edited only by proprietary word
+processors, SGML or XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML produced by some
+word processors for output purposes only.
+
+
+.. _fdl-title-page:
+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
+most prominent appearance of the work's title, preceding the beginning
+of the body of the text.
+
+
+.. _fdl-section2:
+
+2. VERBATIM COPYING
+===================
+
+You may copy and distribute the :ref:`Document <fdl-document>` in any
+medium, either commercially or noncommercially, provided that this
+License, the copyright notices, and the license notice saying this
+License applies to the Document are reproduced in all copies, and that
+you add no other conditions whatsoever to those of this License. You may
+not use technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in
+:ref:`section 3 <fdl-section3>`.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+.. _fdl-section3:
+
+3. COPYING IN QUANTITY
+======================
+
+If you publish printed copies of the :ref:`Document <fdl-document>`
+numbering more than 100, and the Document's license notice requires
+:ref:`Cover Texts <fdl-cover-texts>`, you must enclose the copies in
+covers that carry, clearly and legibly, all these Cover Texts:
+Front-Cover Texts on the front cover, and Back-Cover Texts on the back
+cover. Both covers must also clearly and legibly identify you as the
+publisher of these copies. The front cover must present the full title
+with all words of the title equally prominent and visible. You may add
+other material on the covers in addition. Copying with changes limited
+to the covers, as long as they preserve the title of the
+:ref:`Document <fdl-document>` and satisfy these conditions, can be
+treated as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute :ref:`Opaque <fdl-transparent>` copies of
+the :ref:`Document <fdl-document>` numbering more than 100, you must
+either include a machine-readable :ref:`Transparent <fdl-transparent>`
+copy along with each Opaque copy, or state in or with each Opaque copy a
+publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+:ref:`Document <fdl-document>` well before redistributing any large
+number of copies, to give them a chance to provide you with an updated
+version of the Document.
+
+
+.. _fdl-section4:
+
+4. MODIFICATIONS
+================
+
+You may copy and distribute a :ref:`Modified Version <fdl-modified>`
+of the :ref:`Document <fdl-document>` under the conditions of sections
+:ref:`2 <fdl-section2>` and :ref:`3 <fdl-section3>` above, provided
+that you release the Modified Version under precisely this License, with
+the Modified Version filling the role of the Document, thus licensing
+distribution and modification of the Modified Version to whoever
+possesses a copy of it. In addition, you must do these things in the
+Modified Version:
+
+- **A.**
+
+ Use in the :ref:`Title Page <fdl-title-page>` (and on the covers,
+ if any) a title distinct from that of the
+ :ref:`Document <fdl-document>`, and from those of previous versions
+ (which should, if there were any, be listed in the History section of
+ the Document). You may use the same title as a previous version if
+ the original publisher of that version gives permission.
+
+- **B.**
+
+ List on the :ref:`Title Page <fdl-title-page>`, as authors, one or
+ more persons or entities responsible for authorship of the
+ modifications in the :ref:`Modified Version <fdl-modified>`,
+ together with at least five of the principal authors of the
+ :ref:`Document <fdl-document>` (all of its principal authors, if it
+ has less than five).
+
+- **C.**
+
+ State on the :ref:`Title Page <fdl-title-page>` the name of the
+ publisher of the :ref:`Modified Version <fdl-modified>`, as the
+ publisher.
+
+- **D.**
+
+ Preserve all the copyright notices of the
+ :ref:`Document <fdl-document>`.
+
+- **E.**
+
+ Add an appropriate copyright notice for your modifications adjacent
+ to the other copyright notices.
+
+- **F.**
+
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the
+ :ref:`Modified Version <fdl-modified>` under the terms of this
+ License, in the form shown in the Addendum below.
+
+- **G.**
+
+ Preserve in that license notice the full lists of
+ :ref:`Invariant Sections <fdl-invariant>` and required
+ :ref:`Cover Texts <fdl-cover-texts>` given in the
+ :ref:`Document's <fdl-document>` license notice.
+
+- **H.**
+
+ Include an unaltered copy of this License.
+
+- **I.**
+
+ 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
+ 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.
+
+- **J.**
+
+ Preserve the network location, if any, given in the
+ :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”
+ 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
+ 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.
+
+- **L.**
+
+ Preserve all the :ref:`Invariant Sections <fdl-invariant>` of the
+ :ref:`Document <fdl-document>`, unaltered in their text and in
+ their titles. Section numbers or the equivalent are not considered
+ part of the section titles.
+
+- **M.**
+
+ 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
+ in title with any :ref:`Invariant Section <fdl-invariant>`.
+
+If the :ref:`Modified Version <fdl-modified>` includes new
+front-matter sections or appendices that qualify as
+:ref:`Secondary Sections <fdl-secondary>` and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the list
+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
+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
+an organization as the authoritative definition of a standard.
+
+You may add a passage of up to five words as a
+:ref:`Front-Cover Text <fdl-cover-texts>`, and a passage of up to 25
+words as a :ref:`Back-Cover Text <fdl-cover-texts>`, to the end of the
+list of :ref:`Cover Texts <fdl-cover-texts>` in the
+:ref:`Modified Version <fdl-modified>`. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or through
+arrangements made by) any one entity. If the
+:ref:`Document <fdl-document>` already includes a cover text for the
+same cover, previously added by you or by arrangement made by the same
+entity you are acting on behalf of, you may not add another; but you may
+replace the old one, on explicit permission from the previous publisher
+that added the old one.
+
+The author(s) and publisher(s) of the :ref:`Document <fdl-document>`
+do not by this License give permission to use their names for publicity
+for or to assert or imply endorsement of any
+:ref:`Modified Version <fdl-modified>`.
+
+
+.. _fdl-section5:
+
+5. COMBINING DOCUMENTS
+======================
+
+You may combine the :ref:`Document <fdl-document>` with other
+documents released under this License, under the terms defined in
+:ref:`section 4 <fdl-section4>` above for modified versions, provided
+that you include in the combination all of the
+:ref:`Invariant Sections <fdl-invariant>` of all of the original
+documents, unmodified, and list them all as Invariant Sections of your
+combined work in its license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical :ref:`Invariant Sections <fdl-invariant>` may be
+replaced with a single copy. If there are multiple Invariant Sections
+with the same name but different contents, make the title of each such
+section unique by adding at the end of it, in parentheses, the name of
+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.”
+
+
+.. _fdl-section6:
+
+6. COLLECTIONS OF DOCUMENTS
+===========================
+
+You may make a collection consisting of the
+:ref:`Document <fdl-document>` and other documents released under this
+License, and replace the individual copies of this License in the
+various documents with a single copy that is included in the collection,
+provided that you follow the rules of this License for verbatim copying
+of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and dispbibute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+.. _fdl-section7:
+
+7. AGGREGATION WITH INDEPENDENT WORKS
+=====================================
+
+A compilation of the :ref:`Document <fdl-document>` or its derivatives
+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
+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>`
+requirement of :ref:`section 3 <fdl-section3>` is applicable to these
+copies of the Document, then if the Document is less than one quarter of
+the entire aggregate, the Document's Cover Texts may be placed on covers
+that surround only the Document within the aggregate. Otherwise they
+must appear on covers around the whole aggregate.
+
+
+.. _fdl-section8:
+
+8. TRANSLATION
+==============
+
+Translation is considered a kind of modification, so you may distribute
+translations of the :ref:`Document <fdl-document>` under the terms of
+:ref:`section 4 <fdl-section4>`. Replacing
+:ref:`Invariant Sections <fdl-invariant>` with translations requires
+special permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the original
+English version of this License. In case of a disagreement between the
+translation and the original English version of this License, the
+original English version will prevail.
+
+
+.. _fdl-section9:
+
+9. TERMINATION
+==============
+
+You may not copy, modify, sublicense, or distribute the
+:ref:`Document <fdl-document>` except as expressly provided for under
+this License. Any other attempt to copy, modify, sublicense or
+distribute the Document is void, and will automatically terminate your
+rights under this License. However, parties who have received copies, or
+rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+
+.. _fdl-section10:
+
+10. FUTURE REVISIONS OF THIS LICENSE
+====================================
+
+The `Free Software Foundation <http://www.gnu.org/fsf/fsf.html>`__
+may publish new, revised versions of the GNU Free Documentation License
+from time to time. Such new versions will be similar in spirit to the
+present version, but may differ in detail to address new problems or
+concerns. See
+`http://www.gnu.org/copyleft/ <http://www.gnu.org/copyleft>`__.
+
+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,
+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
+specify a version number of this License, you may choose any version
+ever published (not as a draft) by the Free Software Foundation.
+
+
+.. _fdl-using:
+
+Addendum
+========
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright © YEAR YOUR NAME.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.1 or any later version published by the Free Software
+ Foundation; with the :ref:`Invariant Sections <fdl-invariant>`
+ 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”.
+
+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
+recommend releasing these examples in parallel under your choice of free
+software license, such as the
+`GNU General Public License <http://www.gnu.org/copyleft/gpl.html>`__,
+to permit their use in free software.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _field-order:
+
+***********
+Field Order
+***********
+
+We have to distinguish between progressive and interlaced video.
+Progressive video transmits all lines of a video image sequentially.
+Interlaced video divides an image into two fields, containing only the
+odd and even lines of the image, respectively. Alternating the so called
+odd and even field are transmitted, and due to a small delay between
+fields a cathode ray TV displays the lines interleaved, yielding the
+original frame. This curious technique was invented because at refresh
+rates similar to film the image would fade out too quickly. Transmitting
+fields reduces the flicker without the necessity of doubling the frame
+rate and with it the bandwidth required for each channel.
+
+It is important to understand a video camera does not expose one frame
+at a time, merely transmitting the frames separated into fields. The
+fields are in fact captured at two different instances in time. An
+object on screen may well move between one field and the next. For
+applications analysing motion it is of paramount importance to recognize
+which field of a frame is older, the *temporal order*.
+
+When the driver provides or accepts images field by field rather than
+interleaved, it is also important applications understand how the fields
+combine to frames. We distinguish between top (aka odd) and bottom (aka
+even) fields, the *spatial order*: The first line of the top field is
+the first line of an interlaced frame, the first line of the bottom
+field is the second line of that frame.
+
+However because fields were captured one after the other, arguing
+whether a frame commences with the top or bottom field is pointless. Any
+two successive top and bottom, or bottom and top fields yield a valid
+frame. Only when the source was progressive to begin with, e. g. when
+transferring film to video, two fields may come from the same frame,
+creating a natural order.
+
+Counter to intuition the top field is not necessarily the older field.
+Whether the older field contains the top or bottom lines is a convention
+determined by the video standard. Hence the distinction between temporal
+and spatial order of fields. The diagrams below should make this
+clearer.
+
+All video capture and output devices must report the current field
+order. Some drivers may permit the selection of a different order, to
+this end applications initialize the ``field`` field of struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` before calling the
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl. If this is not desired it
+should have the value ``V4L2_FIELD_ANY`` (0).
+
+
+.. _v4l2-field:
+
+.. flat-table:: enum v4l2_field
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FIELD_ANY``
+
+ - 0
+
+ - Applications request this field order when any one of the
+ ``V4L2_FIELD_NONE``, ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``, or
+ ``V4L2_FIELD_INTERLACED`` formats is acceptable. Drivers choose
+ depending on hardware capabilities or e. g. the requested image
+ size, and return the actual field order. Drivers must never return
+ ``V4L2_FIELD_ANY``. If multiple field orders are possible the
+ driver must choose one of the possible field orders during
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` or
+ :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>`. struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``field`` can never be
+ ``V4L2_FIELD_ANY``.
+
+ - .. row 2
+
+ - ``V4L2_FIELD_NONE``
+
+ - 1
+
+ - Images are in progressive format, not interlaced. The driver may
+ also indicate this order when it cannot distinguish between
+ ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``.
+
+ - .. row 3
+
+ - ``V4L2_FIELD_TOP``
+
+ - 2
+
+ - Images consist of the top (aka odd) field only.
+
+ - .. row 4
+
+ - ``V4L2_FIELD_BOTTOM``
+
+ - 3
+
+ - Images consist of the bottom (aka even) field only. Applications
+ may wish to prevent a device from capturing interlaced images
+ because they will have "comb" or "feathering" artefacts around
+ moving objects.
+
+ - .. row 5
+
+ - ``V4L2_FIELD_INTERLACED``
+
+ - 4
+
+ - Images contain both fields, interleaved line by line. The temporal
+ order of the fields (whether the top or bottom field is first
+ transmitted) depends on the current video standard. M/NTSC
+ transmits the bottom field first, all other standards the top
+ field first.
+
+ - .. row 6
+
+ - ``V4L2_FIELD_SEQ_TB``
+
+ - 5
+
+ - Images contain both fields, the top field lines are stored first
+ in memory, immediately followed by the bottom field lines. Fields
+ are always stored in temporal order, the older one first in
+ memory. Image sizes refer to the frame, not fields.
+
+ - .. row 7
+
+ - ``V4L2_FIELD_SEQ_BT``
+
+ - 6
+
+ - Images contain both fields, the bottom field lines are stored
+ first in memory, immediately followed by the top field lines.
+ Fields are always stored in temporal order, the older one first in
+ memory. Image sizes refer to the frame, not fields.
+
+ - .. row 8
+
+ - ``V4L2_FIELD_ALTERNATE``
+
+ - 7
+
+ - The two fields of a frame are passed in separate buffers, in
+ temporal order, i. e. the older one first. To indicate the field
+ parity (whether the current field is a top or bottom field) the
+ driver or application, depending on data direction, must set
+ struct :ref:`v4l2_buffer <v4l2-buffer>` ``field`` to
+ ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive
+ fields pair to build a frame. If fields are successive, without
+ any dropped fields between them (fields can drop individually),
+ can be determined from the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``sequence`` field. This
+ format cannot be selected when using the read/write I/O method
+ since there is no way to communicate if a field was a top or
+ bottom field.
+
+ - .. row 9
+
+ - ``V4L2_FIELD_INTERLACED_TB``
+
+ - 8
+
+ - Images contain both fields, interleaved line by line, top field
+ first. The top field is transmitted first.
+
+ - .. row 10
+
+ - ``V4L2_FIELD_INTERLACED_BT``
+
+ - 9
+
+ - Images contain both fields, interleaved line by line, top field
+ first. The bottom field is transmitted first.
+
+
+
+.. _fieldseq-tb:
+
+.. figure:: field-order_files/fieldseq_tb.*
+ :alt: fieldseq_tb.pdf / fieldseq_tb.gif
+ :align: center
+
+ Field Order, Top Field First Transmitted
+
+
+.. _fieldseq-bt:
+
+.. figure:: field-order_files/fieldseq_bt.*
+ :alt: fieldseq_bt.pdf / fieldseq_bt.gif
+ :align: center
+
+ Field Order, Bottom Field First Transmitted
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _format:
+
+************
+Data Formats
+************
+
+
+Data Format Negotiation
+=======================
+
+Different devices exchange different kinds of data with applications,
+for example video images, raw or sliced VBI data, RDS datagrams. Even
+within one kind many different formats are possible, in particular an
+abundance of image formats. Although drivers must provide a default and
+the selection persists across closing and reopening a device,
+applications should always negotiate a data format before engaging in
+data exchange. Negotiation means the application asks for a particular
+format and the driver selects and reports the best the hardware can do
+to satisfy the request. Of course applications can also just query the
+current selection.
+
+A single mechanism exists to negotiate all data formats using the
+aggregate struct :ref:`v4l2_format <v4l2-format>` and the
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` and
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctls. Additionally the
+:ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl can be used to examine
+what the hardware *could* do, without actually selecting a new data
+format. The data formats supported by the V4L2 API are covered in the
+respective device section in :ref:`devices`. For a closer look at
+image formats see :ref:`pixfmt`.
+
+The ``VIDIOC_S_FMT`` ioctl is a major turning-point in the
+initialization sequence. Prior to this point multiple panel applications
+can access the same device concurrently to select the current input,
+change controls or modify other properties. The first ``VIDIOC_S_FMT``
+assigns a logical stream (video data, VBI data etc.) exclusively to one
+file descriptor.
+
+Exclusive means no other application, more precisely no other file
+descriptor, can grab this stream or change device properties
+inconsistent with the negotiated parameters. A video standard change for
+example, when the new standard uses a different number of scan lines,
+can invalidate the selected image format. Therefore only the file
+descriptor owning the stream can make invalidating changes. Accordingly
+multiple file descriptors which grabbed different logical streams
+prevent each other from interfering with their settings. When for
+example video overlay is about to start or already in progress,
+simultaneous video capturing may be restricted to the same cropping and
+image size.
+
+When applications omit the ``VIDIOC_S_FMT`` ioctl its locking side
+effects are implied by the next step, the selection of an I/O method
+with the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl or implicit
+with the first :ref:`read() <func-read>` or
+:ref:`write() <func-write>` call.
+
+Generally only one logical stream can be assigned to a file descriptor,
+the exception being drivers permitting simultaneous video capturing and
+overlay using the same file descriptor for compatibility with V4L and
+earlier versions of V4L2. Switching the logical stream or returning into
+"panel mode" is possible by closing and reopening the device. Drivers
+*may* support a switch using ``VIDIOC_S_FMT``.
+
+All drivers exchanging data with applications must support the
+``VIDIOC_G_FMT`` and ``VIDIOC_S_FMT`` ioctl. Implementation of the
+``VIDIOC_TRY_FMT`` is highly recommended but optional.
+
+
+Image Format Enumeration
+========================
+
+Apart of the generic format negotiation functions a special ioctl to
+enumerate all image formats supported by video capture, overlay or
+output devices is available. [1]_
+
+The :ref:`VIDIOC_ENUM_FMT <vidioc-enum-fmt>` ioctl must be supported
+by all drivers exchanging image data with applications.
+
+ **Important**
+
+ Drivers are not supposed to convert image formats in kernel space.
+ They must enumerate only formats directly supported by the hardware.
+ If necessary driver writers should publish an example conversion
+ routine or library for integration into applications.
+
+.. [1]
+ Enumerating formats an application has no a-priori knowledge of
+ (otherwise it could explicitly ask for them and need not enumerate)
+ seems useless, but there are applications serving as proxy between
+ drivers and the actual video applications for which this is useful.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-close:
+
+************
+V4L2 close()
+************
+
+*man v4l2-close(2)*
+
+Close a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. c:function:: int close( int fd )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+
+Description
+===========
+
+Closes the device. Any I/O in progress is terminated and resources
+associated with the file descriptor are freed. However data format
+parameters, current input or output, control values or other properties
+remain unchanged.
+
+
+Return Value
+============
+
+The function returns 0 on success, -1 on failure and the ``errno`` is
+set appropriately. Possible error codes:
+
+EBADF
+ ``fd`` is not a valid open file descriptor.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-ioctl:
+
+************
+V4L2 ioctl()
+************
+
+*man v4l2-ioctl(2)*
+
+Program a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+
+
+.. c:function:: int ioctl( int fd, int request, void *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ V4L2 ioctl request code as defined in the ``videodev2.h`` header
+ file, for example VIDIOC_QUERYCAP.
+
+``argp``
+ Pointer to a function parameter, usually a structure.
+
+
+Description
+===========
+
+The :c:func:`ioctl()` function is used to program V4L2 devices. The
+argument ``fd`` must be an open file descriptor. An ioctl ``request``
+has encoded in it whether the argument is an input, output or read/write
+parameter, and the size of the argument ``argp`` in bytes. Macros and
+defines specifying V4L2 ioctl requests are located in the
+``videodev2.h`` header file. Applications should use their own copy, not
+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
+============
+
+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.
+
+When an ioctl that takes an output or read/write parameter fails, the
+parameter remains unmodified.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-mmap:
+
+***********
+V4L2 mmap()
+***********
+
+*man v4l2-mmap(2)*
+
+Map device memory into application address space
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #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 )
+
+Arguments
+=========
+
+``start``
+ Map the buffer to this address in the application's address space.
+ When the ``MAP_FIXED`` flag is specified, ``start`` must be a
+ multiple of the pagesize and mmap will fail when the specified
+ address cannot be used. Use of this option is discouraged;
+ applications should just specify a ``NULL`` pointer here.
+
+``length``
+ Length of the memory area to map. This must be the same value as
+ returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the
+ single-planar API, and the same value as returned by the driver in
+ the struct :ref:`v4l2_plane <v4l2-plane>` ``length`` field for
+ the multi-planar API.
+
+``prot``
+ The ``prot`` argument describes the desired memory protection.
+ Regardless of the device type and the direction of data exchange it
+ should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
+ and write access to image buffers. Drivers should support at least
+ this combination of flags. Note the Linux ``video-buf`` kernel
+ module, which is used by the bttv, saa7134, saa7146, cx88 and vivi
+ driver supports only ``PROT_READ`` | ``PROT_WRITE``. When the
+ driver does not support the desired protection the
+ :c:func:`mmap()` function fails.
+
+ Note device memory accesses (e. g. the memory on a graphics card
+ with video capturing hardware) may incur a performance penalty
+ compared to main memory accesses, or reads may be significantly
+ slower than writes or vice versa. Other I/O methods may be more
+ efficient in this case.
+
+``flags``
+ The ``flags`` parameter specifies the type of the mapped object,
+ mapping options and whether modifications made to the mapped copy of
+ the page are private to the process or are to be shared with other
+ references.
+
+ ``MAP_FIXED`` requests that the driver selects no other address than
+ the one specified. If the specified address cannot be used,
+ :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified,
+ ``start`` must be a multiple of the pagesize. Use of this option is
+ discouraged.
+
+ One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
+ ``MAP_SHARED`` allows applications to share the mapped memory with
+ other (e. g. child-) processes. Note the Linux ``video-buf`` module
+ which is used by the bttv, saa7134, saa7146, cx88 and vivi driver
+ supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write
+ semantics. V4L2 applications should not set the ``MAP_PRIVATE``,
+ ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` flag.
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``offset``
+ Offset of the buffer in device memory. This must be the same value
+ as returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``m`` union ``offset`` field for
+ the single-planar API, and the same value as returned by the driver
+ in the struct :ref:`v4l2_plane <v4l2-plane>` ``m`` union
+ ``mem_offset`` field for the multi-planar API.
+
+
+Description
+===========
+
+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.
+
+Suitable length and offset parameters are queried with the
+:ref:`VIDIOC_QUERYBUF <vidioc-querybuf>` ioctl. Buffers must be
+allocated with the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl
+before they can be queried.
+
+To unmap buffers the :ref:`munmap() <func-munmap>` function is used.
+
+
+Return Value
+============
+
+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:
+
+EBADF
+ ``fd`` is not a valid file descriptor.
+
+EACCES
+ ``fd`` is not open for reading and writing.
+
+EINVAL
+ The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
+ they are too large, or not aligned on a ``PAGESIZE`` boundary.)
+
+ The ``flags`` or ``prot`` value is not supported.
+
+ No buffers have been allocated with the
+ :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl.
+
+ENOMEM
+ Not enough physical or virtual memory was available to complete the
+ request.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-munmap:
+
+*************
+V4L2 munmap()
+*************
+
+*man v4l2-munmap(2)*
+
+Unmap device memory
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+ #include <sys/mman.h>
+
+
+.. c:function:: int munmap( void *start, size_t length )
+
+Arguments
+=========
+
+``start``
+ Address of the mapped buffer as returned by the
+ :ref:`mmap() <func-mmap>` function.
+
+``length``
+ Length of the mapped buffer. This must be the same value as given to
+ :c:func:`mmap()` and returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the
+ single-planar API and in the struct
+ :ref:`v4l2_plane <v4l2-plane>` ``length`` field for the
+ multi-planar API.
+
+
+Description
+===========
+
+Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped
+buffer and frees it, if possible.
+
+
+Return Value
+============
+
+On success :c:func:`munmap()` returns 0, on failure -1 and the
+``errno`` variable is set appropriately:
+
+EINVAL
+ The ``start`` or ``length`` is incorrect, or no buffers have been
+ mapped yet.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-open:
+
+***********
+V4L2 open()
+***********
+
+*man v4l2-open(2)*
+
+Open a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+
+.. c:function:: int open( const char *device_name, int flags )
+
+Arguments
+=========
+
+``device_name``
+ Device to be opened.
+
+``flags``
+ Open flags. Access mode must be ``O_RDWR``. This is just a
+ technicality, input devices still support only reading and output
+ devices only writing.
+
+ When the ``O_NONBLOCK`` flag is given, the 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 block until data becomes
+ available. All V4L2 drivers exchanging data with applications must
+ support the ``O_NONBLOCK`` flag.
+
+ Other flags have no effect.
+
+
+Description
+===========
+
+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 :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 :c:func:`open()` returns the new file descriptor. On error
+-1 is returned, and the ``errno`` variable is set appropriately.
+Possible error codes are:
+
+EACCES
+ The caller has no permission to access the device.
+
+EBUSY
+ The driver does not support multiple opens and the device is already
+ in use.
+
+ENXIO
+ No device corresponding to this device special file exists.
+
+ENOMEM
+ Not enough kernel memory was available to complete the request.
+
+EMFILE
+ The process already has the maximum number of files open.
+
+ENFILE
+ The limit on the total number of files open on the system has been
+ reached.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-poll:
+
+***********
+V4L2 poll()
+***********
+
+*man v4l2-poll(2)*
+
+Wait for some event on a file descriptor
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/poll.h>
+
+
+.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
+
+Description
+===========
+
+With the :c:func:`poll()` function applications can suspend execution
+until the driver has captured data or is ready to accept data for
+output.
+
+When streaming I/O has been negotiated this function waits until a
+buffer has been filled by the capture device and can be dequeued with
+the :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl. For output devices this
+function waits until the device is ready to accept a new buffer to be
+queued up with the :ref:`VIDIOC_QBUF <vidioc-qbuf>` ioctl for
+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 :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:type:`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 :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
+:c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in
+the ``revents`` field. For output devices this same situation will cause
+: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 <vidioc-dqevent>`)
+then ``POLLPRI`` will be set in the ``revents`` field and
+:c:func:`poll()` will return.
+
+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 :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
+:c:func:`write()` call.
+
+If the caller is only interested in events (just ``POLLPRI`` is set in
+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 :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 :c:func:`poll()` manual page.
+
+
+Return Value
+============
+
+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:
+
+EBADF
+ One or more of the ``ufds`` members specify an invalid file
+ descriptor.
+
+EBUSY
+ The driver does not support multiple read or write streams and the
+ device is already in use.
+
+EFAULT
+ ``ufds`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal.
+
+EINVAL
+ The ``nfds`` argument is greater than ``OPEN_MAX``.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-read:
+
+***********
+V4L2 read()
+***********
+
+*man v4l2-read(2)*
+
+Read from a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. c:function:: ssize_t read( int fd, void *buf, size_t count )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``buf``
+``count``
+
+
+Description
+===========
+
+: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, :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
+:c:func:`read()` call will provide at most one frame (two fields)
+worth of data.
+
+By default :c:func:`read()` blocks until data becomes available. When
+the ``O_NONBLOCK`` flag was given to the :ref:`open() <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
+execution until data becomes available. All drivers supporting the
+: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.
+
+: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 :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 :c:func:`read()` call as soon as it is complete.
+
+A driver discarding the newest frames stops capturing until the next
+: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 :c:func:`read()`
+is called and returning when the DMA finished.
+
+In the multiple buffer model drivers maintain a ring of internal
+buffers, automatically advancing to the next free buffer. This allows
+continuous capturing when the application can empty the buffers fast
+enough. Again, the behavior when the driver runs out of free buffers
+depends on the discarding policy.
+
+Applications can get and set the number of buffers used internally by
+the driver with the :ref:`VIDIOC_G_PARM <vidioc-g-parm>` and
+:ref:`VIDIOC_S_PARM <vidioc-g-parm>` ioctls. They are optional,
+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
+: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:
+
+EAGAIN
+ Non-blocking I/O has been selected using O_NONBLOCK and no data was
+ immediately available for reading.
+
+EBADF
+ ``fd`` is not a valid file descriptor or is not open for reading, or
+ the process already has the maximum number of files open.
+
+EBUSY
+ The driver does not support multiple read streams and the device is
+ already in use.
+
+EFAULT
+ ``buf`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal before any data was read.
+
+EIO
+ I/O error. This indicates some hardware problem or a failure to
+ communicate with a remote device (USB camera etc.).
+
+EINVAL
+ The :c:func:`read()` function is not supported by this driver, not
+ on this device, or generally not on this type of device.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-select:
+
+*************
+V4L2 select()
+*************
+
+*man v4l2-select(2)*
+
+Synchronous I/O multiplexing
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/time.h>
+ #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 )
+
+Description
+===========
+
+With the :c:func:`select()` function applications can suspend
+execution until the driver has captured data or is ready to accept data
+for output.
+
+When streaming I/O has been negotiated this function waits until a
+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 :c:func:`select()` returns the total number of bits set in
+the :c:type:`struct fd_set`s. 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 <vidioc-qbuf>` or
+:ref:`VIDIOC_STREAMON <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. [1]_
+
+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 :c:func:`select()` function returns
+immediately.
+
+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 :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 :c:func:`select()` manual page.
+
+
+Return Value
+============
+
+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
+error codes are:
+
+EBADF
+ One or more of the file descriptor sets specified a file descriptor
+ that is not open.
+
+EBUSY
+ The driver does not support multiple read or write streams and the
+ device is already in use.
+
+EFAULT
+ The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
+ references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal.
+
+EINVAL
+ The ``nfds`` argument is less than zero or greater than
+ ``FD_SETSIZE``.
+
+.. [1]
+ The Linux kernel implements :c:func:`select()` like the
+ :ref:`poll() <func-poll>` function, but :c:func:`select()` cannot
+ return a ``POLLERR``.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-write:
+
+************
+V4L2 write()
+************
+
+*man v4l2-write(2)*
+
+Write to a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. c:function:: ssize_t write( int fd, void *buf, size_t count )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``buf``
+``count``
+
+
+Description
+===========
+
+: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, :c:func:`write()` returns 0
+without any other effect.
+
+When the application does not provide more data in time, the previous
+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
+============
+
+On success, the number of bytes written are returned. Zero indicates
+nothing was written. On error, -1 is returned, and the ``errno``
+variable is set appropriately. In this case the next write will start at
+the beginning of a new frame. Possible error codes are:
+
+EAGAIN
+ Non-blocking I/O has been selected using the
+ :ref:`O_NONBLOCK <func-open>` flag and no buffer space was
+ available to write the data immediately.
+
+EBADF
+ ``fd`` is not a valid file descriptor or is not open for writing.
+
+EBUSY
+ The driver does not support multiple write streams and the device is
+ already in use.
+
+EFAULT
+ ``buf`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal before any data was written.
+
+EIO
+ I/O error. This indicates some hardware problem.
+
+EINVAL
+ The :c:func:`write()` function is not supported by this driver,
+ not on this device, or generally not on this type of device.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _gen_errors:
+
+*******************
+Generic Error Codes
+*******************
+
+
+.. _gen-errors:
+
+.. flat-table:: Generic error codes
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - EAGAIN (aka EWOULDBLOCK)
+
+ - The ioctl can't be handled because the device is in state where it
+ can't perform it. This could happen for example in case where
+ device is sleeping and ioctl is performed to query statistics. It
+ is also returned when the ioctl would need to wait for an event,
+ but the device was opened in non-blocking mode.
+
+ - .. row 2
+
+ - EBADF
+
+ - The file descriptor is not a valid.
+
+ - .. row 3
+
+ - EBUSY
+
+ - The ioctl can't be handled because the device is busy. This is
+ typically return while device is streaming, and an ioctl tried to
+ change something that would affect the stream, or would require
+ the usage of a hardware resource that was already allocated. The
+ ioctl must not be retried without performing another action to fix
+ the problem first (typically: stop the stream before retrying).
+
+ - .. row 4
+
+ - EFAULT
+
+ - There was a failure while copying data from/to userspace, probably
+ caused by an invalid pointer reference.
+
+ - .. row 5
+
+ - EINVAL
+
+ - One or more of the ioctl parameters are invalid or out of the
+ allowed range. This is a widely used error code. See the
+ individual ioctl requests for specific causes.
+
+ - .. row 6
+
+ - ENODEV
+
+ - Device not found or was removed.
+
+ - .. row 7
+
+ - ENOMEM
+
+ - There's not enough memory to handle the desired operation.
+
+ - .. row 8
+
+ - 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.
+
+ - .. row 9
+
+ - ENOSPC
+
+ - On USB devices, the stream ioctl's can return this error, meaning
+ that this request would overcommit the usb bandwidth reserved for
+ periodic transfers (up to 80% of the USB bandwidth).
+
+ - .. row 10
+
+ - EPERM
+
+ - Permission denied. Can be returned if the device needs write
+ permission, or some special capabilities is needed (e. g. root)
+
+
+Note 1: ioctls may return other error codes. Since errors may have side
+effects such as a driver reset, applications should abort on unexpected
+errors.
+
+Note 2: Request-specific error codes are listed in the individual
+requests descriptions.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _hist-v4l2:
+
+***********************
+Changes of the V4L2 API
+***********************
+
+Soon after the V4L API was added to the kernel it was criticised as too
+inflexible. In August 1998 Bill Dirks proposed a number of improvements
+and began to work on documentation, example drivers and applications.
+With the help of other volunteers this eventually became the V4L2 API,
+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-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
+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``
+identifiers are now ordinals instead of flags, and the
+:c:func:`video_std_construct()` helper function takes id and
+transmission arguments.
+
+1998-09-28: Revamped video standard. Made video controls individually
+enumerable.
+
+1998-10-02: The ``id`` field was removed from struct
+:c:type:`struct video_standard` and the color subcarrier fields were
+renamed. The :ref:`VIDIOC_QUERYSTD <vidioc-querystd>` ioctl was
+renamed to :ref:`VIDIOC_ENUMSTD <vidioc-enumstd>`,
+:ref:`VIDIOC_G_INPUT <vidioc-g-input>` to
+:ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>`. A first draft of the
+Codec API was released.
+
+1998-11-08: Many minor changes. Most symbols have been renamed. Some
+material changes to struct :ref:`v4l2_capability <v4l2-capability>`.
+
+1998-11-12: The read/write directon 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
+controls are now accessible with the
+:ref:`VIDIOC_G_CTRL <vidioc-g-ctrl>` and
+:ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` ioctls under names starting
+with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from
+``videodev.h`` since it was only used once in the ``videodev`` kernel
+module. The ``YUV422`` and ``YUV411`` planar image formats were added.
+
+1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video
+output devices were added.
+
+1999-01-14: A raw VBI capture interface was added.
+
+1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed.
+
+
+V4L2 Version 0.16 1999-01-31
+============================
+
+1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
+are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
+digital zoom (cropping) controls.
+
+
+V4L2 Version 0.18 1999-03-16
+============================
+
+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
+============================
+
+1999-03-18: Fill in the category and catname fields of v4l2_queryctrl
+objects before passing them to the driver. Required a minor change to
+the VIDIOC_QUERYCTRL handlers in the sample drivers.
+
+1999-03-31: Better compatibility for v4l memory capture ioctls. Requires
+changes to drivers to fully support new compatibility features, see
+Driver Writer's Guide and v4l2cap.c. Added new control IDs:
+V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
+and _YUV411P to _YUV411P.
+
+1999-04-04: Added a few more control IDs.
+
+1999-04-07: Added the button control type.
+
+1999-05-02: Fixed a typo in videodev.h, and added the
+V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.
+
+1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a
+malfunction of this ioctl.
+
+1999-06-05: Changed the value of V4L2_CID_WHITENESS.
+
+
+V4L2 Version 0.20 (1999-09-10)
+==============================
+
+Version 0.20 introduced a number of changes which were *not backward
+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
+ :ref:`v4l2_clip <v4l2-clip>` was changed for compatibility with
+ v4l. (1999-08-30)
+
+2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05)
+
+3. All ioctl() commands that used an integer argument now take a pointer
+ to an integer. Where it makes sense, ioctls will return the actual
+ new value in the integer pointed to by the argument, a common
+ convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW,
+ 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);
+
+4. All the different get- and set-format commands were swept into one
+ :ref:`VIDIOC_G_FMT <vidioc-g-fmt>` and
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl taking a union and a
+ type field selecting the union member as parameter. Purpose is to
+ simplify the API by eliminating several ioctls and to allow new and
+ driver private data streams without adding new ioctls.
+
+ 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 :c:type:`struct v4l2_format` was renamed to struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`, while struct
+ :ref:`v4l2_format <v4l2-format>` is now the envelopping 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
+ :ref:`v4l2_streamparm <v4l2-streamparm>` selects the respective
+ union member.
+
+ This change obsoletes the ``VIDIOC_G_OUTPARM`` and
+ ``VIDIOC_S_OUTPARM`` ioctls.
+
+6. Control enumeration was simplified, and two new control flags were
+ introduced and one dropped. The ``catname`` field was replaced by a
+ ``group`` field.
+
+ Drivers can now flag unsupported and temporarily unavailable controls
+ with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2_CTRL_FLAG_GRABBED``
+ respectively. The ``group`` name indicates a possibly narrower
+ classification than the ``category``. In other words, there may be
+ multiple groups within a category. Controls within a group would
+ typically be drawn within a group box. Controls in different
+ categories might have a greater separation, or may even appear in
+ separate windows.
+
+7. The struct :ref:`v4l2_buffer <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
+ stream. The data type name for timestamps is stamp_t, defined as a
+ signed 64-bit integer. Output devices should not send a buffer out
+ until the time in the timestamp field has arrived. I would like to
+ follow SGI's lead, and adopt a multimedia timestamping system like
+ their UST (Unadjusted System Time). See
+ http://web.archive.org/web/*/http://reality.sgi.com
+ /cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are
+ 64-bit signed integers (not struct timeval's) and given in nanosecond
+ units. The UST clock starts at zero when the system is booted and
+ runs continuously and uniformly. It takes a little over 292 years for
+ UST to overflow. There is no way to set the UST clock. The regular
+ Linux time-of-day clock can be changed periodically, which would
+ cause errors if it were being used for timestamping a multimedia
+ stream. A real UST style clock will require some support in the
+ kernel that is not there yet. But in anticipation, I will change the
+ timestamp field to a 64-bit integer, and I will change the
+ v4l2_masterclock_gettime() function (used only by drivers) to
+ return a 64-bit integer.
+
+8. A ``sequence`` field was added to struct
+ :ref:`v4l2_buffer <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 :ref:`v4l2_vbi_format <v4l2-vbi-format>` the
+``reserved1`` field became ``offset``. Previously drivers were required
+to clear the ``reserved1`` field.
+
+2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added.
+
+2000-07-31: The ``linux/poll.h`` header is now included by
+``videodev.h`` for compatibility with the original ``videodev.h`` file.
+
+2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were
+added.
+
+2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added.
+
+2000-12-04: A couple typos in symbol names were fixed.
+
+2001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in
+the ``videodev.h`` header file was renamed to ``v4l2_fourcc``.
+
+2001-01-25: A possible driver-level compatibility problem between the
+``videodev.h`` file in Linux 2.4.0 and the ``videodev.h`` file included
+in the ``videodevX`` patch was fixed. Users of an earlier version of
+``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2
+drivers.
+
+2001-01-26: A possible kernel-level incompatibility between the
+``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h``
+file in Linux 2.2.x with devfs patches applied was fixed.
+
+2001-03-02: Certain V4L ioctls which pass data in both direction
+although they are defined with read-only parameter, did not work
+correctly through the backward compatibility layer. [Solution?]
+
+2001-04-13: Big endian 16-bit RGB formats were added.
+
+2001-09-17: New YUV formats and the
+:ref:`VIDIOC_G_FREQUENCY <vidioc-g-frequency>` and
+:ref:`VIDIOC_S_FREQUENCY <vidioc-g-frequency>` ioctls were added.
+(The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take
+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
+:c:type:`struct v4l2_fmt` ``type`` field does not contain
+``V4L2_BUF_TYPE_VBI``. In the documentation of the struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``offset`` field the
+ambiguous phrase "rising edge" was changed to "leading edge".
+
+
+V4L2 Version 0.20 2000-11-23
+============================
+
+A number of changes were made to the raw VBI interface.
+
+1. Figures clarifying the line numbering scheme were added to the V4L2
+ API specification. The ``start``\ [0] and ``start``\ [1] fields no
+ longer count line numbers beginning at zero. Rationale: a) The
+ previous definition was unclear. b) The ``start``\ [] values are
+ ordinal numbers. c) There is no point in inventing a new line
+ numbering scheme. We now use line number as defined by ITU-R, period.
+ Compatibility: Add one to the start values. Applications depending on
+ the previous semantics may not function correctly.
+
+2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to
+ "(count[0] + count[1]) > 0". Rationale: Drivers may allocate
+ resources at scan line granularity and some data services are
+ transmitted only on the first field. The comment that both ``count``
+ values will usually be equal is misleading and pointless and has been
+ removed. This change *breaks compatibility* with earlier versions:
+ Drivers may return EINVAL, applications may not function correctly.
+
+3. Drivers are again permitted to return negative (unknown) start values
+ as proposed earlier. Why this feature was dropped is unclear. This
+ change may *break compatibility* with applications depending on the
+ start values being positive. The use of ``EBUSY`` and ``EINVAL``
+ error codes with the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl was
+ clarified. The EBUSY error code was finally documented, and the
+ ``reserved2`` field which was previously mentioned only in the
+ ``videodev.h`` header file.
+
+4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``V4L2_TYPE_VBI_OUTPUT``
+ 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
+=============================
+
+Around October-November 2002, prior to an announced feature freeze of
+Linux 2.5, the API was revised, drawing from experience with V4L2 0.20.
+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
+ ``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
+ meaningless ``O_TRUNC`` to indicate accesses without data exchange
+ (panel applications) was dropped. Drivers must stay in "panel mode"
+ until the application attempts to initiate a data exchange, see
+ :ref:`open`.
+
+3. The struct :ref:`v4l2_capability <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
+ :ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl.
+
+ 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
+ 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
+ ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and
+ ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``.
+ ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into
+ ``V4L2_CAP_READWRITE``.
+
+ The redundant fields ``inputs``, ``outputs`` and ``audios`` were
+ removed. These properties can be determined as described in
+ :ref:`video` and :ref:`audio`.
+
+ The somewhat volatile and therefore barely useful fields
+ ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``,
+ ``maxframerate`` were removed. This information is available as
+ described in :ref:`format` and :ref:`standard`.
+
+ ``V4L2_FLAG_SELECT`` was removed. We believe the select() function
+ is important enough to require support of it in all V4L2 drivers
+ exchanging data with applications. The redundant
+ ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is
+ available as described in :ref:`format`.
+
+4. In struct :ref:`v4l2_input <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
+ reports all audio inputs this video input combines with.
+
+ New fields are ``tuner`` (reversing the former link from tuners to
+ video inputs), ``std`` and ``status``.
+
+ Accordingly struct :ref:`v4l2_output <v4l2-output>` lost its
+ ``capability`` and ``assoc_audio`` fields. ``audioset``,
+ ``modulator`` and ``std`` where added instead.
+
+5. The struct :ref:`v4l2_audio <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.
+ ``V4L2_AUDCAP_EFFECTS`` and the corresponding ``V4L2_AUDMODE`` flags
+ where removed. This can be easily implemented using controls.
+ (However the same applies to AVL which is still there.)
+
+ Again for consistency the struct
+ :ref:`v4l2_audioout <v4l2-audioout>` field ``audio`` was renamed
+ to ``index``.
+
+6. The struct :ref:`v4l2_tuner <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
+ :ref:`v4l2_input <v4l2-input>`. A ``type`` field was added.
+
+ Accordingly in struct :ref:`v4l2_modulator <v4l2-modulator>` the
+ ``output`` was replaced by an ``index`` field.
+
+ In struct :ref:`v4l2_frequency <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
+ (satellite tuners in particular).
+
+7. The idea of completely transparent video standards was dropped.
+ Experience showed that applications must be able to work with video
+ standards beyond presenting the user a menu. Instead of enumerating
+ supported standards with an ioctl applications can now refer to
+ standards by :ref:`v4l2_std_id <v4l2-std-id>` and symbols
+ defined in the ``videodev2.h`` header file. For details see
+ :ref:`standard`. The :ref:`VIDIOC_G_STD <vidioc-g-std>` and
+ :ref:`VIDIOC_S_STD <vidioc-g-std>` now take a pointer to this
+ type as argument. :ref:`VIDIOC_QUERYSTD <vidioc-querystd>` was
+ added to autodetect the received standard, if the hardware has this
+ capability. In struct :ref:`v4l2_standard <v4l2-standard>` an
+ ``index`` field was added for
+ :ref:`VIDIOC_ENUMSTD <vidioc-enumstd>`. A
+ :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as
+ machine readable identifier, also replacing the ``transmission``
+ field. The misleading ``framerate`` field was renamed to
+ ``frameperiod``. The now obsolete ``colorstandard`` information,
+ originally needed to distguish between variations of standards, were
+ removed.
+
+ Struct :c:type:`struct v4l2_enumstd` ceased to be.
+ :ref:`VIDIOC_ENUMSTD <vidioc-enumstd>` now takes a pointer to a
+ struct :ref:`v4l2_standard <v4l2-standard>` directly. The
+ information which standards are supported by a particular video
+ input or output moved into struct :ref:`v4l2_input <v4l2-input>`
+ and struct :ref:`v4l2_output <v4l2-output>` fields named ``std``,
+ respectively.
+
+8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields
+ ``category`` and ``group`` did not catch on and/or were not
+ implemented as expected and therefore removed.
+
+9. The :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl was added to
+ negotiate data formats as with
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`, but without the overhead of
+ programming the hardware and regardless of I/O in progress.
+
+ In struct :ref:`v4l2_format <v4l2-format>` the ``fmt`` union was
+ extended to contain struct :ref:`v4l2_window <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
+ :ref:`v4l2_buf_type <v4l2-buf-type>` and the buffer type names
+ changed as follows.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Old defines
+
+ - enum :ref:`v4l2_buf_type <v4l2-buf-type>`
+
+ - .. row 2
+
+ - ``V4L2_BUF_TYPE_CAPTURE``
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
+
+ - .. row 3
+
+ - ``V4L2_BUF_TYPE_CODECIN``
+
+ - Omitted for now
+
+ - .. row 4
+
+ - ``V4L2_BUF_TYPE_CODECOUT``
+
+ - Omitted for now
+
+ - .. row 5
+
+ - ``V4L2_BUF_TYPE_EFFECTSIN``
+
+ - Omitted for now
+
+ - .. row 6
+
+ - ``V4L2_BUF_TYPE_EFFECTSIN2``
+
+ - Omitted for now
+
+ - .. row 7
+
+ - ``V4L2_BUF_TYPE_EFFECTSOUT``
+
+ - Omitted for now
+
+ - .. row 8
+
+ - ``V4L2_BUF_TYPE_VIDEOOUT``
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+
+ - .. row 9
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
+
+ - .. row 10
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VBI_CAPTURE``
+
+ - .. row 11
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VBI_OUTPUT``
+
+ - .. row 12
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
+
+ - .. row 13
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
+
+ - .. row 14
+
+ - ``V4L2_BUF_TYPE_PRIVATE_BASE``
+
+ - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated)
+
+
+10. In struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` a enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>` field named ``type`` was
+ added as in struct :ref:`v4l2_format <v4l2-format>`. The
+ ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed.
+ These calls can be replaced by
+ :ref:`VIDIOC_ENUM_FMT <vidioc-enum-fmt>` with type
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
+
+11. In struct :ref:`v4l2_pix_format <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
+ ``V4L2_FMT_FLAG_COMPRESSED`` flag. The
+ ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag was removed because drivers
+ are not supposed to convert images in kernel space. A user library
+ of conversion functions should be provided instead. The
+ ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was redundant. Applications can
+ set the ``bytesperline`` field to zero to get a reasonable default.
+ Since the remaining flags were replaced as well, the ``flags`` field
+ itself was removed.
+
+ The interlace flags were replaced by a enum
+ :ref:`v4l2_field <v4l2-field>` value in a newly added ``field``
+ field.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Old flag
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - .. row 2
+
+ - ``V4L2_FMT_FLAG_NOT_INTERLACED``
+
+ - ?
+
+ - .. row 3
+
+ - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED``
+
+ - ``V4L2_FIELD_INTERLACED``
+
+ - .. row 4
+
+ - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD``
+
+ - ``V4L2_FIELD_TOP``
+
+ - .. row 5
+
+ - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD``
+
+ - ``V4L2_FIELD_BOTTOM``
+
+ - .. row 6
+
+ - ``-``
+
+ - ``V4L2_FIELD_SEQ_TB``
+
+ - .. row 7
+
+ - ``-``
+
+ - ``V4L2_FIELD_SEQ_BT``
+
+ - .. row 8
+
+ - ``-``
+
+ - ``V4L2_FIELD_ALTERNATE``
+
+
+ The color space flags were replaced by a enum
+ :ref:`v4l2_colorspace <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 :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` the
+ ``type`` field was properly defined as enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>`. Buffer types changed as
+ mentioned above. A new ``memory`` field of type enum
+ :ref:`v4l2_memory <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 :ref:`v4l2_buffer <v4l2-buffer>` the ``type`` field was
+ properly defined as enum :ref:`v4l2_buf_type <v4l2-buf-type>`.
+ Buffer types changed as mentioned above. A ``field`` field of type
+ enum :ref:`v4l2_field <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:`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
+ :ref:`v4l2_memory <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
+ layer, after changes to this code it was no longer needed. The
+ ``V4L2_BUF_ATTR_DEVICEMEM`` flag would indicate if the buffer was
+ indeed allocated in device memory rather than DMA-able system
+ memory. It was barely useful and so was removed.
+
+14. In struct :ref:`v4l2_framebuffer <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
+ ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_CAP_SCALEDOWN`` flags were
+ removed. Applications can determine this capability more accurately
+ using the new cropping and scaling interface. The
+ ``V4L2_FBUF_CAP_CLIPPING`` flag was replaced by
+ ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
+ ``V4L2_FBUF_CAP_BITMAP_CLIPPING``.
+
+15. In struct :ref:`v4l2_clip <v4l2-clip>` the ``x``, ``y``,
+ ``width`` and ``height`` field moved into a ``c`` substructure of
+ type struct :ref:`v4l2_rect <v4l2-rect>`. The ``x`` and ``y``
+ fields were renamed to ``left`` and ``top``, i. e. offsets to a
+ context dependent origin.
+
+16. In struct :ref:`v4l2_window <v4l2-window>` the ``x``, ``y``,
+ ``width`` and ``height`` field moved into a ``w`` substructure as
+ above. A ``field`` field of type %v4l2-field; was added to
+ distinguish between field and frame (interlaced) overlay.
+
+17. The digital zoom interface, including struct
+ :c:type:`struct v4l2_zoomcap`, struct
+ :c:type:`struct v4l2_zoom`, ``V4L2_ZOOM_NONCAP`` and
+ ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and
+ scaling interface. The previously unused struct
+ :c:type:`struct v4l2_cropcap` and :c:type:`struct v4l2_crop`
+ where redefined for this purpose. See :ref:`crop` for details.
+
+18. In struct :ref:`v4l2_vbi_format <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 :ref:`v4l2_captureparm <v4l2-captureparm>` the type of
+ the ``timeperframe`` field changed from unsigned long to struct
+ :ref:`v4l2_fract <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
+ :ref:`v4l2_outputparm <v4l2-outputparm>`.
+
+20. The struct :c:type:`struct v4l2_performance` and
+ ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the
+ :ref:`read/write I/O method <rw>`, which is limited anyway, this
+ information is already available to applications.
+
+21. The example transformation from RGB to YCbCr color space in the old
+ V4L2 documentation was inaccurate, this has been corrected in
+ :ref:`pixfmt`.
+
+
+V4L2 2003-06-19
+===============
+
+1. A new capability flag ``V4L2_CAP_RADIO`` was added for radio devices.
+ Prior to this change radio devices would identify solely by having
+ exactly one tuner whose type field reads ``V4L2_TUNER_RADIO``.
+
+2. An optional driver access priority mechanism was added, see
+ :ref:`app-pri` for details.
+
+3. The audio input and output interface was found to be incomplete.
+
+ Previously the :ref:`VIDIOC_G_AUDIO <vidioc-g-audio>` ioctl would
+ enumerate the available audio inputs. An ioctl to determine the
+ current audio input, if more than one combines with the current video
+ input, did not exist. So ``VIDIOC_G_AUDIO`` was renamed to
+ ``VIDIOC_G_AUDIO_OLD``, this ioctl was removed on Kernel 2.6.39. The
+ :ref:`VIDIOC_ENUMAUDIO <vidioc-enumaudio>` ioctl was added to
+ enumerate audio inputs, while
+ :ref:`VIDIOC_G_AUDIO <vidioc-g-audio>` now reports the current
+ audio input.
+
+ The same changes were made to
+ :ref:`VIDIOC_G_AUDOUT <vidioc-g-audioout>` and
+ :ref:`VIDIOC_ENUMAUDOUT <vidioc-enumaudioout>`.
+
+ Until further the "videodev" module will automatically translate
+ between the old and new ioctls, but drivers and applications must be
+ updated to successfully compile again.
+
+4. The :ref:`VIDIOC_OVERLAY <vidioc-overlay>` ioctl was incorrectly
+ defined with write-read parameter. It was changed to write-only,
+ while the write-read version was renamed to ``VIDIOC_OVERLAY_OLD``.
+ The old ioctl was removed on Kernel 2.6.39. Until further the
+ "videodev" kernel module will automatically translate to the new
+ version, so drivers must be recompiled, but not applications.
+
+5. :ref:`overlay` incorrectly stated that clipping rectangles define
+ regions where the video can be seen. Correct is that clipping
+ rectangles define regions where *no* video shall be displayed and so
+ the graphics surface can be seen.
+
+6. The :ref:`VIDIOC_S_PARM <vidioc-g-parm>` and
+ :ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` ioctls were defined with
+ write-only parameter, inconsistent with other ioctls modifying their
+ argument. They were changed to write-read, while a ``_OLD`` suffix
+ was added to the write-only versions. The old ioctls were removed on
+ Kernel 2.6.39. Drivers and applications assuming a constant parameter
+ need an update.
+
+
+V4L2 2003-11-05
+===============
+
+1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly
+ transferred from Bill Dirks' V4L2 specification. Descriptions below
+ refer to bytes in memory, in ascending address order.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Symbol
+
+ - In this document prior to revision 0.5
+
+ - Corrected
+
+ - .. row 2
+
+ - ``V4L2_PIX_FMT_RGB24``
+
+ - B, G, R
+
+ - R, G, B
+
+ - .. row 3
+
+ - ``V4L2_PIX_FMT_BGR24``
+
+ - R, G, B
+
+ - B, G, R
+
+ - .. row 4
+
+ - ``V4L2_PIX_FMT_RGB32``
+
+ - B, G, R, X
+
+ - R, G, B, X
+
+ - .. row 5
+
+ - ``V4L2_PIX_FMT_BGR32``
+
+ - 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
+ ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2
+ pixel formats was accordingly corrected.
+
+2. Unrelated to the fixes above, drivers may still interpret some V4L2
+ 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
+===============================
+
+1. The :ref:`VIDIOC_CROPCAP <vidioc-cropcap>` ioctl was incorrectly
+ defined with read-only parameter. It is now defined as write-read
+ 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 :ref:`v4l2_buffer <v4l2-buffer>` structure. 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
+============================
+
+1. The return value of the :ref:`func-open` function was incorrectly
+ documented.
+
+2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT.
+
+3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took
+ the wrong argument.
+
+4. The documentation of the :ref:`VIDIOC_QBUF <vidioc-qbuf>` and
+ :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctls did not mention the
+ struct :ref:`v4l2_buffer <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
+====================
+
+1. A new sliced VBI interface was added. It is documented in
+ :ref:`sliced` and replaces the interface first proposed in V4L2
+ specification 0.8.
+
+
+V4L2 in Linux 2.6.15
+====================
+
+1. The :ref:`VIDIOC_LOG_STATUS <vidioc-log-status>` ioctl was added.
+
+2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``,
+ ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and
+ ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and
+ ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60``
+ set now includes ``V4L2_STD_NTSC_443``. See also
+ :ref:`v4l2-std-id`.
+
+3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to
+ ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their
+ argument was replaced by a struct
+ :c:type:`struct v4l2_mpeg_compression` pointer. (The
+ ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed
+ in Linux 2.6.25.)
+
+
+V4L2 spec erratum 2005-11-27
+============================
+
+The capture example in :ref:`capture-example` called the
+:ref:`VIDIOC_S_CROP <vidioc-g-crop>` ioctl without checking if
+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
+ :ref:`v4l2_input <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 :ref:`v4l2_captureparm <v4l2-captureparm>` and struct
+ :ref:`v4l2_outputparm <v4l2-outputparm>` the ``timeperframe``
+ field gives the time in seconds, not microseconds.
+
+
+V4L2 spec erratum 2006-02-04
+============================
+
+1. The ``clips`` field in struct :ref:`v4l2_window <v4l2-window>`
+ must point to an array of struct :ref:`v4l2_clip <v4l2-clip>`, not
+ a linked list, because drivers ignore the struct
+ :c:type:`struct v4l2_clip`. ``next`` pointer.
+
+
+V4L2 in Linux 2.6.17
+====================
+
+1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M
+ South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``,
+ ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and
+ ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and
+ ``V4L2_STD_SECAM_LC`` respectively.
+
+2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both
+ languages of a bilingual program. The use of
+ ``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)
+=========================================
+
+1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and
+ ``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` it was clarified that the struct
+ :ref:`v4l2_audio <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` it was clarified that applications
+ must initialize the tuner ``type`` field of struct
+ :ref:`v4l2_frequency <v4l2-frequency>` before calling
+ :ref:`VIDIOC_S_FREQUENCY <vidioc-g-frequency>`.
+
+5. The ``reserved`` array in struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` has 2 elements,
+ not 32.
+
+6. In :ref:`output` and :ref:`raw-vbi` the device file names
+ ``/dev/vout`` which never caught on were replaced by ``/dev/video``.
+
+7. With Linux 2.6.15 the possible range for VBI device minor numbers was
+ 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
+====================
+
+1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <vidioc-g-ext-ctrls>`,
+ :ref:`VIDIOC_S_EXT_CTRLS <vidioc-g-ext-ctrls>` and
+ :ref:`VIDIOC_TRY_EXT_CTRLS <vidioc-g-ext-ctrls>` were added, a
+ flag to skip unsupported controls with
+ :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>`, new control types
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS``
+ (:ref:`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 :ref:`v4l2_sliced_vbi_cap <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
+ :ref:`VIDIOC_G_SLICED_VBI_CAP <vidioc-g-sliced-vbi-cap>` ioctl
+ was redefined from being read-only to write-read. Applications must
+ initialize the type field and clear the reserved fields now. These
+ changes may *break the compatibility* with older drivers and
+ applications.
+
+2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES <vidioc-enum-framesizes>`
+ and
+ :ref:`VIDIOC_ENUM_FRAMEINTERVALS <vidioc-enum-frameintervals>`
+ were added.
+
+3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) 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
+====================
+
+1. The ``videodev2.h`` header file is now dual licensed under GNU
+ 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 :ref:`v4l2-field` for
+ details.
+
+2. Three new clipping/blending methods with a global or straight or
+ inverted local alpha value were added to the video overlay interface.
+ 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
+ :ref:`v4l2_window <v4l2-window>`, extending the structure. This
+ may *break compatibility* with applications using a struct
+ :c:type:`struct v4l2_window` directly. However the
+ :ref:`VIDIOC_G/S/TRY_FMT <vidioc-g-fmt>` ioctls, which take a
+ pointer to a :ref:`v4l2_format <v4l2-format>` parent structure
+ with padding bytes at the end, are not affected.
+
+3. The format of the ``chromakey`` field in struct
+ :ref:`v4l2_window <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
+====================
+
+1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``,
+ ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and
+ ``V4L2_PIX_FMT_YUV32`` were added.
+
+
+V4L2 in Linux 2.6.25
+====================
+
+1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and
+ :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added.
+
+2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``,
+ ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``,
+ ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were
+ added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``,
+ ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated.
+
+3. A :ref:`Camera controls class <camera-controls>` was added, with
+ the new controls ``V4L2_CID_EXPOSURE_AUTO``,
+ ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``,
+ ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``,
+ ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``,
+ ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``,
+ ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and
+ ``V4L2_CID_FOCUS_AUTO``.
+
+4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which
+ were superseded by the :ref:`extended controls <extended-controls>`
+ interface in Linux 2.6.18, where finally removed from the
+ ``videodev2.h`` header file.
+
+
+V4L2 in Linux 2.6.26
+====================
+
+1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16``
+ were added.
+
+2. Added user controls ``V4L2_CID_CHROMA_AGC`` and
+ ``V4L2_CID_COLOR_KILLER``.
+
+
+V4L2 in Linux 2.6.27
+====================
+
+1. The :ref:`VIDIOC_S_HW_FREQ_SEEK <vidioc-s-hw-freq-seek>` ioctl
+ and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added.
+
+2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``,
+ ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``,
+ ``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
+====================
+
+1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and
+ ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings.
+
+2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding.
+
+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
+ :c:type:`struct v4l2_chip_ident` was renamed to
+ :c:type:`struct v4l2_chip_ident_old`.
+
+2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and
+ ``V4L2_PIX_FMT_NV61`` were added.
+
+3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``,
+ ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and
+ ``V4L2_CID_PRIVACY``.
+
+
+V4L2 in Linux 2.6.30
+====================
+
+1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added.
+
+2. New control ``V4L2_CID_COLORFX`` was added.
+
+
+V4L2 in Linux 2.6.32
+====================
+
+1. In order to be easier to compare a V4L2 API and a kernel version, now
+ V4L2 API is numbered using the Linux Kernel version numeration.
+
+2. Finalized the RDS capture API. See :ref:`rds` for more information.
+
+3. Added new capabilities for modulators and RDS encoders.
+
+4. Add description for libv4l API.
+
+5. Added support for string controls via new type
+ ``V4L2_CTRL_TYPE_STRING``.
+
+6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation.
+
+7. Added FM Modulator (FM TX) Extended Control Class:
+ ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs.
+
+8. Added FM Receiver (FM RX) Extended Control Class:
+ ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs.
+
+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
+====================
+
+1. Remove the vtx (videotext/teletext) API. This API was no longer used
+ and no hardware exists to verify the API. Nor were any userspace
+ applications found that used it. It was originally scheduled for
+ removal in 2.6.35.
+
+
+V4L2 in Linux 2.6.39
+====================
+
+1. The old VIDIOC_*_OLD symbols and V4L1 support were removed.
+
+2. Multi-planar API added. Does not affect the compatibility of current
+ drivers and applications. See :ref:`multi-planar API <planar-apis>`
+ for details.
+
+
+V4L2 in Linux 3.1
+=================
+
+1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a
+ per-driver one.
+
+ Standardize an error code for invalid ioctl.
+
+ Added V4L2_CTRL_TYPE_BITMASK.
+
+
+V4L2 in Linux 3.2
+=================
+
+1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to
+ userspace.
+
+2. Add selection API for extended control over cropping and composing.
+ Does not affect the compatibility of current drivers and
+ applications. See :ref:`selection API <selection-api>` for details.
+
+
+V4L2 in Linux 3.3
+=================
+
+1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the
+ :ref:`User controls class <control>`.
+
+2. Added the device_caps field to struct v4l2_capabilities and added
+ the new V4L2_CAP_DEVICE_CAPS capability.
+
+
+V4L2 in Linux 3.4
+=================
+
+1. Added :ref:`JPEG compression control class <jpeg-controls>`.
+
+2. Extended the DV Timings API:
+ :ref:`VIDIOC_ENUM_DV_TIMINGS <vidioc-enum-dv-timings>`,
+ :ref:`VIDIOC_QUERY_DV_TIMINGS <vidioc-query-dv-timings>` and
+ :ref:`VIDIOC_DV_TIMINGS_CAP <vidioc-dv-timings-cap>`.
+
+
+V4L2 in Linux 3.5
+=================
+
+1. Added integer menus, the new type will be
+ V4L2_CTRL_TYPE_INTEGER_MENU.
+
+2. Added selection API for V4L2 subdev interface:
+ :ref:`VIDIOC_SUBDEV_G_SELECTION <vidioc-subdev-g-selection>` and
+ :ref:`VIDIOC_SUBDEV_S_SELECTION <vidioc-subdev-g-selection>`.
+
+3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``,
+ ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``,
+ ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and
+ ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the
+ ``V4L2_CID_COLORFX`` control.
+
+4. Added ``V4L2_CID_COLORFX_CBCR`` control.
+
+5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``,
+ ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``,
+ ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``,
+ ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``,
+ ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``,
+ ``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 :c:type:`struct v4l2_buffer` by
+ ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``.
+
+2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE
+ capabilities.
+
+3. Added support for frequency band enumerations:
+ :ref:`VIDIOC_ENUM_FREQ_BANDS <vidioc-enum-freq-bands>`.
+
+
+V4L2 in Linux 3.9
+=================
+
+1. Added timestamp types to ``flags`` field in
+ :c:type:`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
+==================
+
+1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET,
+ VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
+ VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
+ capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
+
+2. Added new debugging ioctl
+ :ref:`VIDIOC_DBG_G_CHIP_INFO <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:`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 :ref:`v4l2_pix_format <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
+ :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
+ :ref:`v4l2_quantization <v4l2-quantization>` fields to struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`, struct
+ :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and
+ struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
+
+
+V4L2 in Linux 4.4
+=================
+
+1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of
+ ``V4L2_TUNER_ADC`` is deprecated now.
+
+2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control.
+
+3. Added transmitter support for Software Defined Radio (SDR) Interface.
+
+
+.. _other:
+
+Relation of V4L2 to other Linux multimedia APIs
+===============================================
+
+
+.. _xvideo:
+
+X Video Extension
+-----------------
+
+The X Video Extension (abbreviated XVideo or just Xv) is an extension of
+the X Window system, implemented for example by the XFree86 project. Its
+scope is similar to V4L2, an API to video capture and output devices for
+X clients. Xv allows applications to display live video in a window,
+send window contents to a TV output, and capture or output still images
+in XPixmaps [1]_. With their implementation XFree86 makes the extension
+available across many operating systems and architectures.
+
+Because the driver is embedded into the X server Xv has a number of
+advantages over the V4L2 :ref:`video overlay interface <overlay>`. The
+driver can easily determine the overlay target, i. e. visible graphics
+memory or off-screen buffers for a destructive overlay. It can program
+the RAMDAC for a non-destructive overlay, scaling or color-keying, or
+the clipping functions of the video capture hardware, always in sync
+with drawing operations or windows moving or changing their stacking
+order.
+
+To combine the advantages of Xv and V4L a special Xv driver exists in
+XFree86 and XOrg, just programming any overlay capable Video4Linux
+device it finds. To enable it ``/etc/X11/XF86Config`` must contain these
+lines:
+
+
+
+::
+
+ Section "Module"
+ Load "v4l"
+ EndSection
+As of XFree86 4.2 this driver still supports only V4L ioctls, however it
+should work just fine with all V4L2 devices through the V4L2
+backward-compatibility layer. Since V4L2 permits multiple opens it is
+possible (if supported by the V4L2 driver) to capture video while an X
+client requested video overlay. Restrictions of simultaneous capturing
+and overlay are discussed in :ref:`overlay` apply.
+
+Only marginally related to V4L2, XFree86 extended Xv to support hardware
+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
+-------------
+
+V4L2 does not support digital terrestrial, cable or satellite broadcast.
+A separate project aiming at digital receivers exists. You can find its
+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
+=========================
+
+The following V4L2 API elements are currently experimental and may
+change in the future.
+
+- :ref:`VIDIOC_DBG_G_REGISTER <vidioc-dbg-g-register>` and
+ :ref:`VIDIOC_DBG_S_REGISTER <vidioc-dbg-g-register>` ioctls.
+
+- :ref:`VIDIOC_DBG_G_CHIP_INFO <vidioc-dbg-g-chip-info>` ioctl.
+
+
+.. _obsolete:
+
+Obsolete API Elements
+=====================
+
+The following V4L2 API elements were superseded by new interfaces and
+should not be implemented in new drivers.
+
+- ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended
+ Controls, :ref:`extended-controls`.
+
+- VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET,
+ VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use
+ the DV Timings API (:ref:`dv-timings`).
+
+- ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use
+ ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``,
+ :ref:`vidioc-subdev-g-selection`.
+
+.. [1]
+ This is not implemented in XFree86.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _io:
+
+############
+Input/Output
+############
+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 :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 <vidioc-reqbufs>` ioctl. The asynchronous I/O
+method is not defined yet.
+
+Video overlay can be considered another I/O method, although the
+application does not directly receive the image data. It is selected by
+initiating video overlay with the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
+ioctl. For more information see :ref:`overlay`.
+
+Generally exactly one I/O method, including overlay, is associated with
+each file descriptor. The only exceptions are applications not
+exchanging data with a driver ("panel applications", see :ref:`open`)
+and drivers permitting simultaneous video capturing and overlay using
+the same file descriptor, for compatibility with V4L and earlier
+versions of V4L2.
+
+``VIDIOC_S_FMT`` and ``VIDIOC_REQBUFS`` would permit this to some
+degree, but for simplicity drivers need not support switching the I/O
+method (after first switching away from read/write) other than by
+closing and reopening the device.
+
+The following sections describe the various I/O methods in more detail.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ rw
+ mmap
+ userp
+ dmabuf
+ async
+ buffer
+ field-order
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: media/v4l/keytable.c
+==========================
+
+.. code-block:: c
+
+ /* keytable.c - This program allows checking/replacing keys at IR
+
+ Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@infradead.org>
+
+ This program 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 program 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.
+ */
+
+ #include <ctype.h>
+ #include <errno.h>
+ #include <fcntl.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <linux/input.h>
+ #include <sys/ioctl.h>
+
+ #include "parse.h"
+
+ void prtcode (int *codes)
+ {
+ struct parse_key *p;
+
+ for (p=keynames;p->name!=NULL;p++) {
+ if (p->value == (unsigned)codes[1]) {
+ printf("scancode 0x%04x = %s (0x%02x)\\n", codes[0], p->name, codes[1]);
+ return;
+ }
+ }
+
+ if (isprint (codes[1]))
+ printf("scancode %d = '%c' (0x%02x)\\n", codes[0], codes[1], codes[1]);
+ else
+ printf("scancode %d = 0x%02x\\n", codes[0], codes[1]);
+ }
+
+ int parse_code(char *string)
+ {
+ struct parse_key *p;
+
+ for (p=keynames;p->name!=NULL;p++) {
+ if (!strcasecmp(p->name, string)) {
+ return p->value;
+ }
+ }
+ return -1;
+ }
+
+ int main (int argc, char *argv[])
+ {
+ int fd;
+ unsigned int i, j;
+ int codes[2];
+
+ if (argc<2 || argc>4) {
+ printf ("usage: %s <device> to get table; or\\n"
+ " %s <device> <scancode> <keycode>\\n"
+ " %s <device> <keycode_file>n",*argv,*argv,*argv);
+ return -1;
+ }
+
+ if ((fd = open(argv[1], O_RDONLY)) < 0) {
+ perror("Couldn't open input device");
+ return(-1);
+ }
+
+ if (argc==4) {
+ int value;
+
+ value=parse_code(argv[3]);
+
+ if (value==-1) {
+ value = strtol(argv[3], NULL, 0);
+ if (errno)
+ perror("value");
+ }
+
+ codes [0] = (unsigned) strtol(argv[2], NULL, 0);
+ codes [1] = (unsigned) value;
+
+ if(ioctl(fd, EVIOCSKEYCODE, codes))
+ perror ("EVIOCSKEYCODE");
+
+ if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
+ prtcode(codes);
+ return 0;
+ }
+
+ if (argc==3) {
+ FILE *fin;
+ int value;
+ char *scancode, *keycode, s[2048];
+
+ fin=fopen(argv[2],"r");
+ if (fin==NULL) {
+ perror ("opening keycode file");
+ return -1;
+ }
+
+ /* Clears old table */
+ for (j = 0; j < 256; j++) {
+ for (i = 0; i < 256; i++) {
+ codes[0] = (j << 8) | i;
+ codes[1] = KEY_RESERVED;
+ ioctl(fd, EVIOCSKEYCODE, codes);
+ }
+ }
+
+ while (fgets(s,sizeof(s),fin)) {
+ scancode=strtok(s,"\\n\\t =:");
+ if (!scancode) {
+ perror ("parsing input file scancode");
+ return -1;
+ }
+ if (!strcasecmp(scancode, "scancode")) {
+ scancode = strtok(NULL,"\\n\\t =:");
+ if (!scancode) {
+ perror ("parsing input file scancode");
+ return -1;
+ }
+ }
+
+ keycode=strtok(NULL,"\\n\\t =:(");
+ if (!keycode) {
+ perror ("parsing input file keycode");
+ return -1;
+ }
+
+ // printf ("parsing %s=%s:", scancode, keycode);
+ value=parse_code(keycode);
+ // printf ("\\tvalue=%d\\n",value);
+
+ if (value==-1) {
+ value = strtol(keycode, NULL, 0);
+ if (errno)
+ perror("value");
+ }
+
+ codes [0] = (unsigned) strtol(scancode, NULL, 0);
+ codes [1] = (unsigned) value;
+
+ // printf("\\t%04x=%04x\\n",codes[0], codes[1]);
+ if(ioctl(fd, EVIOCSKEYCODE, codes)) {
+ fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]);
+ perror ("EVIOCSKEYCODE");
+ }
+
+ if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
+ prtcode(codes);
+ }
+ return 0;
+ }
+
+ /* Get scancode table */
+ for (j = 0; j < 256; j++) {
+ for (i = 0; i < 256; i++) {
+ codes[0] = (j << 8) | i;
+ if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED)
+ prtcode(codes);
+ }
+ }
+ return 0;
+ }
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _libv4l-introduction:
+
+************
+Introduction
+************
+
+libv4l is a collection of libraries which adds a thin abstraction layer
+on top of video4linux2 devices. The purpose of this (thin) layer is to
+make it easy for application writers to support a wide variety of
+devices without having to write separate code for different devices in
+the same class.
+
+An example of using libv4l is provided by
+:ref:`v4l2grab <v4l2grab-example>`.
+
+libv4l consists of 3 different libraries:
+
+
+libv4lconvert
+=============
+
+libv4lconvert is a library that converts several different pixelformats
+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_JPEG <V4L2-PIX-FMT-JPEG>`,
+:ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`,
+:ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`,
+:ref:`V4L2_PIX_FMT_OV511 <V4L2-PIX-FMT-OV511>`,
+:ref:`V4L2_PIX_FMT_OV518 <V4L2-PIX-FMT-OV518>`,
+:ref:`V4L2_PIX_FMT_PAC207 <V4L2-PIX-FMT-PAC207>`,
+:ref:`V4L2_PIX_FMT_PJPG <V4L2-PIX-FMT-PJPG>`,
+:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
+:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`,
+:ref:`V4L2_PIX_FMT_SGBRG8 <V4L2-PIX-FMT-SGBRG8>`,
+:ref:`V4L2_PIX_FMT_SGRBG8 <V4L2-PIX-FMT-SGRBG8>`,
+:ref:`V4L2_PIX_FMT_SN9C10X <V4L2-PIX-FMT-SN9C10X>`,
+:ref:`V4L2_PIX_FMT_SN9C20X_I420 <V4L2-PIX-FMT-SN9C20X-I420>`,
+:ref:`V4L2_PIX_FMT_SPCA501 <V4L2-PIX-FMT-SPCA501>`,
+:ref:`V4L2_PIX_FMT_SPCA505 <V4L2-PIX-FMT-SPCA505>`,
+:ref:`V4L2_PIX_FMT_SPCA508 <V4L2-PIX-FMT-SPCA508>`,
+:ref:`V4L2_PIX_FMT_SPCA561 <V4L2-PIX-FMT-SPCA561>`,
+:ref:`V4L2_PIX_FMT_SQ905C <V4L2-PIX-FMT-SQ905C>`,
+``V4L2_PIX_FMT_SRGGB8``,
+:ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`,
+:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`,
+:ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`,
+:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, and
+:ref:`V4L2_PIX_FMT_YVYU <V4L2-PIX-FMT-YVYU>`.
+
+Later on libv4lconvert was expanded to also be able to do various video
+processing functions to improve webcam video quality. The video
+processing is split in to 2 parts: libv4lconvert/control and
+libv4lconvert/processing.
+
+The control part is used to offer video controls which can be used to
+control the video processing functions made available by
+libv4lconvert/processing. These controls are stored application wide
+(until reboot) by using a persistent shared memory object.
+
+libv4lconvert/processing offers the actual video processing
+functionality.
+
+
+libv4l1
+=======
+
+This library offers functions that can be used to quickly make v4l1
+applications work with v4l2 devices. These functions work exactly like
+the normal open/close/etc, except that libv4l1 does full emulation of
+the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will
+just pass calls through.
+
+Since those functions are emulations of the old V4L1 API, it shouldn't
+be used for new applications.
+
+
+libv4l2
+=======
+
+This library should be used for all modern V4L2 applications.
+
+It provides handles to call V4L2 open/ioctl/close/poll methods. Instead
+of just providing the raw output of the device, it enhances the calls in
+the sense that it will use libv4lconvert to provide more video formats
+and to enhance the image quality.
+
+In most cases, libv4l2 just passes the calls directly through to the
+v4l2 driver, intercepting the calls to
+:ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>`,
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>`
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
+:ref:`VIDIOC_ENUM_FRAMESIZES <vidioc-enum-framesizes>` and
+:ref:`VIDIOC_ENUM_FRAMEINTERVALS <vidioc-enum-frameintervals>` in
+order to emulate the formats
+:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
+:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
+:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, and
+:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, if they aren't
+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
+-------------------------------
+
+The common file operation methods are provided by libv4l.
+
+Those functions operate just like glibc
+open/close/dup/ioctl/read/mmap/munmap:
+
+- int v4l2_open(const char *file, int oflag, ...) - operates like the
+ standard :ref:`open() <func-open>` function.
+
+- int v4l2_close(int fd) - operates like the standard
+ :ref:`close() <func-close>` function.
+
+- int v4l2_dup(int fd) - operates like the standard dup() function,
+ duplicating a file handler.
+
+- int v4l2_ioctl (int fd, unsigned long int request, ...) - operates
+ like the standard :ref:`ioctl() <func-ioctl>` function.
+
+- int v4l2_read (int fd, void* buffer, size_t n) - operates like the
+ standard :ref:`read() <func-read>` function.
+
+- void v4l2_mmap(void *start, size_t length, int prot, int flags, int
+ fd, int64_t offset); - operates like the standard
+ :ref:`mmap() <func-mmap>` function.
+
+- int v4l2_munmap(void *_start, size_t length); - operates like the
+ standard :ref:`munmap() <func-munmap>` function.
+
+Those functions provide additional control:
+
+- int v4l2_fd_open(int fd, int v4l2_flags) - opens an already opened
+ fd for further use through v4l2lib and possibly modify libv4l2's
+ default behavior through the v4l2_flags argument. Currently,
+ v4l2_flags can be ``V4L2_DISABLE_CONVERSION``, to disable format
+ conversion.
+
+- int v4l2_set_control(int fd, int cid, int value) - This function
+ takes a value of 0 - 65535, and then scales that range to the actual
+ range of the given v4l control id, and then if the cid exists and is
+ not locked sets the cid to the scaled value.
+
+- int v4l2_get_control(int fd, int cid) - This function returns a
+ value of 0 - 65535, scaled to from the actual range 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 open/close/ioctl/mmap/mmunmap
+operations and redirects them to the libv4l counterparts, by using
+LD_PRELOAD=/usr/lib/v4l1compat.so. It also emulates V4L1 calls via V4L2
+API.
+
+It allows usage of binary legacy applications that still don't use
+libv4l.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _libv4l:
+
+************************
+Libv4l Userspace Library
+************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ libv4l-introduction
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_dev_intro:
+
+************
+Introduction
+************
+
+The LIRC device interface is a bi-directional interface for transporting
+raw IR data between userspace and kernelspace. Fundamentally, it is just
+a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard
+struct file_operations defined on it. With respect to transporting raw
+IR data to and fro, the essential fops are read, write and ioctl.
+
+Example dmesg output upon a driver registering w/LIRC:
+
+ $ dmesg |grep lirc_dev
+
+ lirc_dev: IR Remote Control driver registered, major 248
+
+ rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor
+ = 0
+
+What you should see for a chardev:
+
+ $ ls -l /dev/lirc*
+
+ crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_dev:
+
+LIRC Device Interface
+=====================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ lirc_dev_intro
+ lirc_read
+ lirc_write
+ lirc_ioctl
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_ioctl:
+
+**************
+LIRC ioctl fop
+**************
+
+The LIRC device's ioctl definition is bound by the ioctl function
+definition of struct file_operations, leaving us with an unsigned int
+for the ioctl command and an unsigned long for the arg. For the purposes
+of ioctl portability across 32-bit and 64-bit, these values are capped
+to their 32-bit sizes.
+
+The following ioctls can be used to change specific hardware settings.
+In general each driver should have a default set of settings. The driver
+implementation is expected to re-apply the default settings when the
+device is closed by user-space, so that every application opening the
+device can rely on working with the default settings initially.
+
+LIRC_GET_FEATURES
+ Obviously, get the underlying hardware device's features. If a
+ driver does not announce support of certain features, calling of the
+ corresponding ioctls is undefined.
+
+LIRC_GET_SEND_MODE
+ Get supported transmit mode. Only LIRC_MODE_PULSE is supported by
+ lircd.
+
+LIRC_GET_REC_MODE
+ Get supported receive modes. Only LIRC_MODE_MODE2 and
+ LIRC_MODE_LIRCCODE are supported by lircd.
+
+LIRC_GET_SEND_CARRIER
+ Get carrier frequency (in Hz) currently used for transmit.
+
+LIRC_GET_REC_CARRIER
+ Get carrier frequency (in Hz) currently used for IR reception.
+
+LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE
+ Get/set the duty cycle (from 0 to 100) of the carrier signal.
+ 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.
+
+LIRC_GET_REC_RESOLUTION
+ Some receiver have maximum resolution which is defined by internal
+ sample rate or data format limitations. E.g. it's common that
+ signals can only be reported in 50 microsecond steps. This integer
+ value is used by lircd to automatically adjust the aeps tolerance
+ value in the lircd config file.
+
+LIRC_GET_M{IN,AX}_TIMEOUT
+ Some devices have internal timers that can be used to detect when
+ there's no IR activity for a long time. This can help lircd in
+ detecting that a IR signal is finished and can speed up the decoding
+ process. Returns an integer value with the minimum/maximum timeout
+ that can be set. Some devices have a fixed timeout, in that case
+ both ioctls will return the same value even though the timeout
+ cannot be changed.
+
+LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}
+ Some devices are able to filter out spikes in the incoming signal
+ using given filter rules. These ioctls return the hardware
+ capabilities that describe the bounds of the possible filters.
+ Filter settings depend on the IR protocols that are expected. lircd
+ derives the settings from all protocols definitions found in its
+ config file.
+
+LIRC_GET_LENGTH
+ Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
+ Reads on the device must be done in blocks matching the bit count.
+ The bit could should be rounded up so that it matches full bytes.
+
+LIRC_SET_{SEND,REC}_MODE
+ Set send/receive mode. Largely obsolete for send, as only
+ LIRC_MODE_PULSE is supported.
+
+LIRC_SET_{SEND,REC}_CARRIER
+ Set send/receive carrier (in Hz).
+
+LIRC_SET_TRANSMITTER_MASK
+ This enables the given set of transmitters. The first transmitter is
+ encoded by the least significant bit, etc. 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.
+
+LIRC_SET_REC_TIMEOUT
+ Sets the integer value for IR inactivity timeout (cf.
+ LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0
+ (if supported by the hardware) disables all hardware timeouts and
+ data should be reported as soon as possible. If the exact value
+ cannot be set, then the next possible value _greater_ than the
+ given value should be set.
+
+LIRC_SET_REC_TIMEOUT_REPORTS
+ Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
+ default, timeout reports should be turned off.
+
+LIRC_SET_REC_FILTER_{,PULSE,SPACE}
+ Pulses/spaces shorter than this are filtered out by hardware. If
+ filters cannot be set independently for pulse/space, the
+ corresponding ioctls must return an error and LIRC_SET_REC_FILTER
+ shall be used instead.
+
+LIRC_SET_MEASURE_CARRIER_MODE
+ Enable (1)/disable (0) 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.
+
+LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE
+ To set a range use
+ LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
+ with the lower bound first and later
+ LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper
+ bound.
+
+LIRC_NOTIFY_DECODE
+ This ioctl is called by lircd whenever a successful decoding of an
+ incoming IR signal could be done. This can be used by supporting
+ hardware to give visual feedback to the user e.g. by flashing a LED.
+
+LIRC_SETUP_{START,END}
+ Setting of several driver parameters can be optimized by
+ encapsulating the according ioctl calls with
+ LIRC_SETUP_START/LIRC_SETUP_END. When a driver receives a
+ LIRC_SETUP_START ioctl it can choose to not commit further setting
+ changes to the hardware until a LIRC_SETUP_END is received. But
+ this is open to the driver implementation and every driver must also
+ handle parameter changes which are not encapsulated by
+ LIRC_SETUP_START and LIRC_SETUP_END. Drivers can also choose to
+ ignore these ioctls.
+
+LIRC_SET_WIDEBAND_RECEIVER
+ Some receivers are equipped with special wide band receiver which is
+ intended to be used to learn output of existing remote. Calling that
+ ioctl with (1) will enable it, and with (0) disable it. This might
+ be useful of receivers that have otherwise narrow band receiver that
+ prevents them to be used with some remotes. Wide band receiver might
+ also be more precise On the other hand its disadvantage it usually
+ reduced range of reception. Note: wide band receiver might be
+ implictly enabled if you enable carrier reports. In that case it
+ will be disabled as soon as you disable carrier reports. Trying to
+ disable wide band receiver while carrier reports are active will do
+ nothing.
+
+
+.. _lirc_dev_errors:
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_read:
+
+*************
+LIRC read fop
+*************
+
+The lircd userspace daemon reads raw IR data from the LIRC chardev. The
+exact format of the data depends on what modes a driver supports, and
+what mode has been selected. lircd obtains supported modes and sets the
+active mode via the ioctl interface, detailed at :ref:`lirc_ioctl`.
+The generally preferred mode is LIRC_MODE_MODE2, in which packets
+containing an int value describing an IR signal are read from the
+chardev.
+
+See also
+`http://www.lirc.org/html/technical.html <http://www.lirc.org/html/technical.html>`__
+for more info.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_write:
+
+**************
+LIRC write fop
+**************
+
+The data written to the chardev is a pulse/space sequence of integer
+values. Pulses and spaces are only marked implicitly by their position.
+The data must start and end with a pulse, therefore, the data must
+always include an uneven number of samples. The write function must
+block until the data has been transmitted by the hardware. If more data
+is provided than the hardware can send, the driver returns EINVAL.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-controller-intro:
+
+Introduction
+============
+
+Media devices increasingly handle multiple related functions. Many USB
+cameras include microphones, video capture hardware can also output
+video, or SoC camera interfaces also perform memory-to-memory operations
+similar to video codecs.
+
+Independent functions, even when implemented in the same hardware, can
+be modelled as separate devices. A USB camera with a microphone will be
+presented to userspace applications as V4L2 and ALSA capture devices.
+The devices' relationships (when using a webcam, end-users shouldn't
+have to manually select the associated USB microphone), while not made
+available directly to applications by the drivers, can usually be
+retrieved from sysfs.
+
+With more and more advanced SoC devices being introduced, the current
+approach will not scale. Device topologies are getting increasingly
+complex and can't always be represented by a tree structure. Hardware
+blocks are shared between different functions, creating dependencies
+between seemingly unrelated devices.
+
+Kernel abstraction APIs such as V4L2 and ALSA provide means for
+applications to access hardware parameters. As newer hardware expose an
+increasingly high number of those parameters, drivers need to guess what
+applications really require based on limited information, thereby
+implementing policies that belong to userspace.
+
+The media controller API aims at solving those problems.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-controller-model:
+
+Media device model
+==================
+
+Discovering a device internal topology, and configuring it at runtime,
+is one of the goals of the media controller API. To achieve this,
+hardware devices and Linux Kernel interfaces are modelled as graph
+objects on an oriented graph. The object types that constitute the graph
+are:
+
+- An **entity** is a basic media hardware or software building block.
+ It can correspond to a large variety of logical blocks such as
+ physical hardware devices (CMOS sensor for instance), logical
+ hardware devices (a building block in a System-on-Chip image
+ processing pipeline), DMA channels or physical connectors.
+
+- An **interface** is a graph representation of a Linux Kernel
+ userspace API interface, like a device node or a sysfs file that
+ controls one or more entities in the graph.
+
+- A **pad** is a data connection endpoint through which an entity can
+ interact with other entities. Data (not restricted to video) produced
+ by an entity flows from the entity's output to one or more entity
+ inputs. Pads should not be confused with physical pins at chip
+ boundaries.
+
+- A **data link** is a point-to-point oriented connection between two
+ pads, either on the same entity or on different entities. Data flows
+ from a source pad to a sink pad.
+
+- An **interface link** is a point-to-point bidirectional control
+ connection between a Linux Kernel interface and an entity.m
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media_common:
+
+####################
+Media Controller API
+####################
+
+.. _media_controller:
+
+****************
+Media Controller
+****************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ media-controller-intro
+ media-controller-model
+ media-types
+
+
+.. _media-user-func:
+
+******************
+Function Reference
+******************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ media-func-open
+ media-func-close
+ media-func-ioctl
+ media-ioc-device-info
+ media-ioc-g-topology
+ media-ioc-enum-entities
+ media-ioc-enum-links
+ media-ioc-setup-link
+
+
+**********************
+Revision and Copyright
+**********************
+
+
+:author: Pinchart Laurent
+:address: laurent.pinchart@ideasonboard.com
+:contrib: Initial version.
+
+**Copyright** 2010 : Laurent Pinchart
+
+:revision: 1.0.0 / 2010-11-10 (*lp*)
+
+Initial revision
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-close:
+
+*************
+media close()
+*************
+
+*man media-close(2)*
+
+Close a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. c:function:: int close( int fd )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+
+Description
+===========
+
+Closes the media device. Resources associated with the file descriptor
+are freed. The device configuration remain unchanged.
+
+
+Return Value
+============
+
+:c:func:`close()` returns 0 on success. On error, -1 is returned, and
+``errno`` is set appropriately. Possible error codes are:
+
+EBADF
+ ``fd`` is not a valid open file descriptor.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-ioctl:
+
+*************
+media ioctl()
+*************
+
+*man media-ioctl(2)*
+
+Control a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+
+
+.. c:function:: int ioctl( int fd, int request, void *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ Media ioctl request code as defined in the media.h header file, for
+ example MEDIA_IOC_SETUP_LINK.
+
+``argp``
+ Pointer to a request-specific structure.
+
+
+Description
+===========
+
+The :c:func:`ioctl()` function manipulates media device parameters.
+The argument ``fd`` must be an open file descriptor.
+
+The ioctl ``request`` code specifies the media function to be called. It
+has encoded in it whether the argument is an input, output or read/write
+parameter, and the size of the argument ``argp`` in bytes.
+
+Macros and structures definitions specifying media ioctl requests and
+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
+============
+
+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.
+
+Request-specific error codes are listed in the individual requests
+descriptions.
+
+When an ioctl that takes an output or read/write parameter fails, the
+parameter remains unmodified.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-open:
+
+************
+media open()
+************
+
+*man media-open(2)*
+
+Open a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+
+.. c:function:: int open( const char *device_name, int flags )
+
+Arguments
+=========
+
+``device_name``
+ Device to be opened.
+
+``flags``
+ 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 :c:func:`open()` with the
+desired device name. The function has no side effects; the device
+configuration remain unchanged.
+
+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()` returns the new file descriptor on success. On error,
+-1 is returned, and ``errno`` is set appropriately. Possible error codes
+are:
+
+EACCES
+ The requested access to the file is not allowed.
+
+EMFILE
+ The process already has the maximum number of files open.
+
+ENFILE
+ The system limit on the total number of open files has been reached.
+
+ENOMEM
+ Insufficient kernel memory was available.
+
+ENXIO
+ No device corresponding to this device special file exists.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-ioc-device-info:
+
+***************************
+ioctl MEDIA_IOC_DEVICE_INFO
+***************************
+
+*man MEDIA_IOC_DEVICE_INFO(2)*
+
+Query device information
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct media_device_info *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_DEVICE_INFO
+
+``argp``
+
+
+Description
+===========
+
+All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
+query device information, applications call the ioctl with a pointer to
+a struct :ref:`media_device_info <media-device-info>`. The driver
+fills the structure and returns the information to the application. The
+ioctl never fails.
+
+
+.. _media-device-info:
+
+.. flat-table:: struct media_device_info
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - char
+
+ - ``driver``\ [16]
+
+ - Name of the driver implementing the media API as a NUL-terminated
+ ASCII string. The driver version is stored in the
+ ``driver_version`` field.
+
+ Driver specific applications can use this information to verify
+ the driver identity. It is also useful to work around known bugs,
+ or to identify drivers in error reports.
+
+ - .. row 2
+
+ - char
+
+ - ``model``\ [32]
+
+ - Device model name as a NUL-terminated UTF-8 string. The device
+ version is stored in the ``device_version`` field and is not be
+ appended to the model name.
+
+ - .. row 3
+
+ - char
+
+ - ``serial``\ [40]
+
+ - Serial number as a NUL-terminated ASCII string.
+
+ - .. row 4
+
+ - char
+
+ - ``bus_info``\ [32]
+
+ - Location of the device in the system as a NUL-terminated ASCII
+ string. This includes the bus type name (PCI, USB, ...) and a
+ bus-specific identifier.
+
+ - .. row 5
+
+ - __u32
+
+ - ``media_version``
+
+ - Media API version, formatted with the ``KERNEL_VERSION()`` macro.
+
+ - .. row 6
+
+ - __u32
+
+ - ``hw_revision``
+
+ - Hardware device revision in a driver-specific format.
+
+ - .. row 7
+
+ - __u32
+
+ - ``driver_version``
+
+ - Media device driver version, formatted with the
+ ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
+ this identifies a particular driver.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [31]
+
+ - 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.
+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
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-ioc-enum-entities:
+
+*****************************
+ioctl MEDIA_IOC_ENUM_ENTITIES
+*****************************
+
+*man MEDIA_IOC_ENUM_ENTITIES(2)*
+
+Enumerate entities and their properties
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct media_entity_desc *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_ENUM_ENTITIES
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an entity, applications set the id field of a
+struct :ref:`media_entity_desc <media-entity-desc>` structure and
+call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
+structure. The driver fills the rest of the structure or returns an
+EINVAL error code when the id is invalid.
+
+Entities can be enumerated by or'ing the id with the
+``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information
+about the entity with the smallest id strictly larger than the requested
+one ('next entity'), or the EINVAL error code if there is none.
+
+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.
+
+
+.. _media-entity-desc:
+
+.. flat-table:: struct media_entity_desc
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ -
+ - Entity id, set by the application. When the id is or'ed with
+ ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns
+ the first entity with a larger id.
+
+ - .. row 2
+
+ - char
+
+ - ``name``\ [32]
+
+ -
+ -
+ - Entity name as an UTF-8 NULL-terminated string.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ -
+ -
+ - Entity type, see :ref:`media-entity-type` for details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``revision``
+
+ -
+ -
+ - Entity revision. Always zero (obsolete)
+
+ - .. row 5
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Entity flags, see :ref:`media-entity-flag` for details.
+
+ - .. row 6
+
+ - __u32
+
+ - ``group_id``
+
+ -
+ -
+ - Entity group ID. Always zero (obsolete)
+
+ - .. row 7
+
+ - __u16
+
+ - ``pads``
+
+ -
+ -
+ - Number of pads
+
+ - .. row 8
+
+ - __u16
+
+ - ``links``
+
+ -
+ -
+ - Total number of outbound links. Inbound links are not counted in
+ this field.
+
+ - .. row 9
+
+ - union
+
+ - .. row 10
+
+ -
+ - struct
+
+ - ``dev``
+
+ -
+ - Valid for (sub-)devices that create a single device node.
+
+ - .. row 11
+
+ -
+ -
+ - __u32
+
+ - ``major``
+
+ - Device node major number.
+
+ - .. row 12
+
+ -
+ -
+ - __u32
+
+ - ``minor``
+
+ - Device node minor number.
+
+ - .. row 13
+
+ -
+ - __u8
+
+ - ``raw``\ [184]
+
+ -
+ -
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`media_entity_desc <media-entity-desc>` ``id``
+ references a non-existing entity.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-ioc-enum-links:
+
+**************************
+ioctl MEDIA_IOC_ENUM_LINKS
+**************************
+
+*man MEDIA_IOC_ENUM_LINKS(2)*
+
+Enumerate all pads and links for a given entity
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct media_links_enum *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_ENUM_LINKS
+
+``argp``
+
+
+Description
+===========
+
+To enumerate pads and/or links for a given entity, applications set the
+entity field of a struct :ref:`media_links_enum <media-links-enum>`
+structure and initialize the struct
+:ref:`media_pad_desc <media-pad-desc>` and struct
+:ref:`media_link_desc <media-link-desc>` structure arrays pointed by
+the ``pads`` and ``links`` fields. They then call the
+MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
+
+If the ``pads`` field is not NULL, the driver fills the ``pads`` array
+with information about the entity's pads. The array must have enough
+room to store all the entity's pads. The number of pads can be retrieved
+with the :ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>`
+ioctl.
+
+If the ``links`` field is not NULL, the driver fills the ``links`` array
+with information about the entity's outbound links. The array must have
+enough room to store all the entity's outbound links. The number of
+outbound links can be retrieved with the
+:ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>` ioctl.
+
+Only forward links that originate at one of the entity's source pads are
+returned during the enumeration process.
+
+
+.. _media-links-enum:
+
+.. flat-table:: struct media_links_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entity``
+
+ - Entity id, set by the application.
+
+ - .. row 2
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - *\ ``pads``
+
+ - Pointer to a pads array allocated by the application. Ignored if
+ NULL.
+
+ - .. row 3
+
+ - struct :ref:`media_link_desc <media-link-desc>`
+
+ - *\ ``links``
+
+ - Pointer to a links array allocated by the application. Ignored if
+ NULL.
+
+
+
+.. _media-pad-desc:
+
+.. flat-table:: struct media_pad_desc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entity``
+
+ - ID of the entity this pad belongs to.
+
+ - .. row 2
+
+ - __u16
+
+ - ``index``
+
+ - 0-based pad index.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Pad flags, see :ref:`media-pad-flag` for more details.
+
+
+
+.. _media-link-desc:
+
+.. flat-table:: struct media_link_desc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - ``source``
+
+ - Pad at the origin of this link.
+
+ - .. row 2
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - ``sink``
+
+ - Pad at the target of this link.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Link flags, see :ref:`media-link-flag` for more details.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`media_links_enum <media-links-enum>` ``id``
+ references a non-existing entity.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-g-topology:
+
+**************************
+ioctl MEDIA_IOC_G_TOPOLOGY
+**************************
+
+*man MEDIA_IOC_G_TOPOLOGY(2)*
+
+Enumerate the graph topology and graph element properties
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct media_v2_topology *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_G_TOPOLOGY
+
+``argp``
+
+
+Description
+===========
+
+The typical usage of this ioctl is to call it twice. On the first call,
+the structure defined at struct
+:ref:`media_v2_topology <media-v2-topology>` should be zeroed. At
+return, if no errors happen, this ioctl will return the
+``topology_version`` and the total number of entities, interfaces, pads
+and links.
+
+Before the second call, the userspace should allocate arrays to store
+the graph elements that are desired, putting the pointers to them at the
+ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
+other values untouched.
+
+If the ``topology_version`` remains the same, the ioctl should fill the
+desired arrays with the media graph elements.
+
+
+.. _media-v2-topology:
+
+.. flat-table:: struct media_v2_topology
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``topology_version``
+
+ -
+ -
+ - Version of the media graph topology. When the graph is created,
+ this field starts with zero. Every time a graph element is added
+ or removed, this field is incremented.
+
+ - .. row 2
+
+ - __u64
+
+ - ``num_entities``
+
+ -
+ -
+ - Number of entities in the graph
+
+ - .. row 3
+
+ - __u64
+
+ - ``ptr_entities``
+
+ -
+ -
+ - A pointer to a memory area where the entities array will be
+ stored, converted to a 64-bits integer. It can be zero. if zero,
+ the ioctl won't store the entities. It will just update
+ ``num_entities``
+
+ - .. row 4
+
+ - __u64
+
+ - ``num_interfaces``
+
+ -
+ -
+ - Number of interfaces in the graph
+
+ - .. row 5
+
+ - __u64
+
+ - ``ptr_interfaces``
+
+ -
+ -
+ - A pointer to a memory area where the interfaces array will be
+ stored, converted to a 64-bits integer. It can be zero. if zero,
+ the ioctl won't store the interfaces. It will just update
+ ``num_interfaces``
+
+ - .. row 6
+
+ - __u64
+
+ - ``num_pads``
+
+ -
+ -
+ - Total number of pads in the graph
+
+ - .. row 7
+
+ - __u64
+
+ - ``ptr_pads``
+
+ -
+ -
+ - A pointer to a memory area where the pads array will be stored,
+ converted to a 64-bits integer. It can be zero. if zero, the ioctl
+ won't store the pads. It will just update ``num_pads``
+
+ - .. row 8
+
+ - __u64
+
+ - ``num_links``
+
+ -
+ -
+ - Total number of data and interface links in the graph
+
+ - .. row 9
+
+ - __u64
+
+ - ``ptr_links``
+
+ -
+ -
+ - A pointer to a memory area where the links array will be stored,
+ 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``
+
+
+
+.. _media-v2-entity:
+
+.. flat-table:: struct media_v2_entity
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ -
+ - Unique ID for the entity.
+
+ - .. row 2
+
+ - char
+
+ - ``name``\ [64]
+
+ -
+ -
+ - Entity name as an UTF-8 NULL-terminated string.
+
+ - .. row 3
+
+ - __u32
+
+ - ``function``
+
+ -
+ -
+ - Entity main function, see :ref:`media-entity-type` for details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [12]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+
+.. _media-v2-interface:
+
+.. flat-table:: struct media_v2_interface
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ -
+ - Unique ID for the interface.
+
+ - .. row 2
+
+ - __u32
+
+ - ``intf_type``
+
+ -
+ -
+ - Interface type, see :ref:`media-intf-type` for details.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Interface flags. Currently unused.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ -
+ -
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+ - .. row 5
+
+ - struct media_v2_intf_devnode
+
+ - ``devnode``
+
+ -
+ -
+ - Used only for device node interfaces. See
+ :ref:`media-v2-intf-devnode` for details..
+
+
+
+.. _media-v2-intf-devnode:
+
+.. flat-table:: struct media_v2_interface
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``major``
+
+ -
+ -
+ - Device node major number.
+
+ - .. row 2
+
+ - __u32
+
+ - ``minor``
+
+ -
+ -
+ - Device node minor number.
+
+
+
+.. _media-v2-pad:
+
+.. flat-table:: struct media_v2_pad
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ -
+ - Unique ID for the pad.
+
+ - .. row 2
+
+ - __u32
+
+ - ``entity_id``
+
+ -
+ -
+ - Unique ID for the entity where this pad belongs.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Pad flags, see :ref:`media-pad-flag` for more details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ -
+ -
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+
+.. _media-v2-link:
+
+.. flat-table:: struct media_v2_pad
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ -
+ - Unique ID for the pad.
+
+ - .. row 2
+
+ - __u32
+
+ - ``source_id``
+
+ -
+ -
+ - On pad to pad links: unique ID for the source pad.
+
+ On interface to entity links: unique ID for the interface.
+
+ - .. row 3
+
+ - __u32
+
+ - ``sink_id``
+
+ -
+ -
+ - On pad to pad links: unique ID for the sink pad.
+
+ On interface to entity links: unique ID for the entity.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Link flags, see :ref:`media-link-flag` for more details.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ -
+ -
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+
+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
+ This is returned when either one or more of the num_entities,
+ num_interfaces, num_links or num_pads are non-zero and are
+ smaller than the actual number of elements inside the graph. This
+ may happen if the ``topology_version`` changed when compared to the
+ last time this ioctl was called. Userspace should usually free the
+ area for the pointers, zero the struct elements and call this ioctl
+ again.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-ioc-setup-link:
+
+**************************
+ioctl MEDIA_IOC_SETUP_LINK
+**************************
+
+*man MEDIA_IOC_SETUP_LINK(2)*
+
+Modify the properties of a link
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct media_link_desc *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_SETUP_LINK
+
+``argp``
+
+
+Description
+===========
+
+To change link properties applications fill a struct
+:ref:`media_link_desc <media-link-desc>` with link identification
+information (source and sink pad) and the new requested link flags. They
+then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that
+structure.
+
+The only configurable property is the ``ENABLED`` link flag to
+enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can
+not be enabled or disabled.
+
+Link configuration has no side effect on other links. If an enabled link
+at the sink pad prevents the link from being enabled, the driver returns
+with an EBUSY error code.
+
+Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled
+while streaming media data. Attempting to enable or disable a streaming
+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
+============
+
+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.
+
+EINVAL
+ The struct :ref:`media_link_desc <media-link-desc>` references a
+ non-existing link, or the link is immutable and an attempt to modify
+ its configuration was made.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-controller-types:
+
+Types and flags used to represent the media graph elements
+==========================================================
+
+
+.. _media-entity-type:
+
+.. flat-table:: Media entity types
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_ENT_F_UNKNOWN`` and ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN``
+
+ - Unknown entity. That generally indicates that a driver didn't
+ initialize properly the entity, with is a Kernel bug
+
+ - .. row 2
+
+ - ``MEDIA_ENT_F_IO_V4L``
+
+ - Data streaming input and/or output entity.
+
+ - .. row 3
+
+ - ``MEDIA_ENT_F_IO_VBI``
+
+ - V4L VBI streaming input or output entity
+
+ - .. row 4
+
+ - ``MEDIA_ENT_F_IO_SWRADIO``
+
+ - V4L Software Digital Radio (SDR) streaming input or output entity
+
+ - .. row 5
+
+ - ``MEDIA_ENT_F_IO_DTV``
+
+ - DVB Digital TV streaming input or output entity
+
+ - .. row 6
+
+ - ``MEDIA_ENT_F_DTV_DEMOD``
+
+ - Digital TV demodulator entity.
+
+ - .. row 7
+
+ - ``MEDIA_ENT_F_TS_DEMUX``
+
+ - MPEG Transport stream demux entity. Could be implemented on
+ hardware or in Kernelspace by the Linux DVB subsystem.
+
+ - .. row 8
+
+ - ``MEDIA_ENT_F_DTV_CA``
+
+ - Digital TV Conditional Access module (CAM) entity
+
+ - .. row 9
+
+ - ``MEDIA_ENT_F_DTV_NET_DECAP``
+
+ - Digital TV network ULE/MLE desencapsulation entity. Could be
+ implemented on hardware or in Kernelspace
+
+ - .. row 10
+
+ - ``MEDIA_ENT_F_CONN_RF``
+
+ - Connector for a Radio Frequency (RF) signal.
+
+ - .. row 11
+
+ - ``MEDIA_ENT_F_CONN_SVIDEO``
+
+ - Connector for a S-Video signal.
+
+ - .. row 12
+
+ - ``MEDIA_ENT_F_CONN_COMPOSITE``
+
+ - Connector for a RGB composite signal.
+
+ - .. row 13
+
+ - ``MEDIA_ENT_F_CAM_SENSOR``
+
+ - Camera video sensor entity.
+
+ - .. row 14
+
+ - ``MEDIA_ENT_F_FLASH``
+
+ - Flash controller entity.
+
+ - .. row 15
+
+ - ``MEDIA_ENT_F_LENS``
+
+ - Lens controller entity.
+
+ - .. row 16
+
+ - ``MEDIA_ENT_F_ATV_DECODER``
+
+ - Analog video decoder, the basic function of the video decoder is
+ to accept analogue video from a wide variety of sources such as
+ broadcast, DVD players, cameras and video cassette recorders, in
+ either NTSC, PAL, SECAM or HD format, separating the stream into
+ its component parts, luminance and chrominance, and output it in
+ some digital video standard, with appropriate timing signals.
+
+ - .. row 17
+
+ - ``MEDIA_ENT_F_TUNER``
+
+ - Digital TV, analog TV, radio and/or software radio tuner, with
+ consists on a PLL tuning stage that converts radio frequency (RF)
+ signal into an Intermediate Frequency (IF). Modern tuners have
+ internally IF-PLL decoders for audio and video, but older models
+ have those stages implemented on separate entities.
+
+ - .. row 18
+
+ - ``MEDIA_ENT_F_IF_VID_DECODER``
+
+ - IF-PLL video decoder. It receives the IF from a PLL and decodes
+ the analog TV video signal. This is commonly found on some very
+ old analog tuners, like Philips MK3 designs. They all contain a
+ tda9887 (or some software compatible similar chip, like tda9885).
+ Those devices use a different I2C address than the tuner PLL.
+
+ - .. row 19
+
+ - ``MEDIA_ENT_F_IF_AUD_DECODER``
+
+ - IF-PLL sound decoder. It receives the IF from a PLL and decodes
+ the analog TV audio signal. This is commonly found on some very
+ old analog hardware, like Micronas msp3400, Philips tda9840,
+ tda985x, etc. Those devices use a different I2C address than the
+ tuner PLL and should be controlled together with the IF-PLL video
+ decoder.
+
+ - .. row 20
+
+ - ``MEDIA_ENT_F_AUDIO_CAPTURE``
+
+ - Audio Capture Function Entity.
+
+ - .. row 21
+
+ - ``MEDIA_ENT_F_AUDIO_PLAYBACK``
+
+ - Audio Playback Function Entity.
+
+ - .. row 22
+
+ - ``MEDIA_ENT_F_AUDIO_MIXER``
+
+ - Audio Mixer Function Entity.
+
+
+
+.. _media-entity-flag:
+
+.. flat-table:: Media entity flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_ENT_FL_DEFAULT``
+
+ - Default entity for its type. Used to discover the default audio,
+ VBI and video devices, the default camera sensor, ...
+
+ - .. row 2
+
+ - ``MEDIA_ENT_FL_CONNECTOR``
+
+ - The entity represents a data conector
+
+
+
+.. _media-intf-type:
+
+.. flat-table:: Media interface types
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_INTF_T_DVB_FE``
+
+ - Device node interface for the Digital TV frontend
+
+ - typically, /dev/dvb/adapter?/frontend?
+
+ - .. row 2
+
+ - ``MEDIA_INTF_T_DVB_DEMUX``
+
+ - Device node interface for the Digital TV demux
+
+ - typically, /dev/dvb/adapter?/demux?
+
+ - .. row 3
+
+ - ``MEDIA_INTF_T_DVB_DVR``
+
+ - Device node interface for the Digital TV DVR
+
+ - typically, /dev/dvb/adapter?/dvr?
+
+ - .. row 4
+
+ - ``MEDIA_INTF_T_DVB_CA``
+
+ - Device node interface for the Digital TV Conditional Access
+
+ - typically, /dev/dvb/adapter?/ca?
+
+ - .. row 5
+
+ - ``MEDIA_INTF_T_DVB_FE``
+
+ - Device node interface for the Digital TV network control
+
+ - typically, /dev/dvb/adapter?/net?
+
+ - .. row 6
+
+ - ``MEDIA_INTF_T_V4L_VIDEO``
+
+ - Device node interface for video (V4L)
+
+ - typically, /dev/video?
+
+ - .. row 7
+
+ - ``MEDIA_INTF_T_V4L_VBI``
+
+ - Device node interface for VBI (V4L)
+
+ - typically, /dev/vbi?
+
+ - .. row 8
+
+ - ``MEDIA_INTF_T_V4L_RADIO``
+
+ - Device node interface for radio (V4L)
+
+ - typically, /dev/vbi?
+
+ - .. row 9
+
+ - ``MEDIA_INTF_T_V4L_SUBDEV``
+
+ - Device node interface for a V4L subdevice
+
+ - typically, /dev/v4l-subdev?
+
+ - .. row 10
+
+ - ``MEDIA_INTF_T_V4L_SWRADIO``
+
+ - Device node interface for Software Defined Radio (V4L)
+
+ - typically, /dev/swradio?
+
+ - .. row 11
+
+ - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
+
+ - Device node interface for ALSA PCM Capture
+
+ - typically, /dev/snd/pcmC?D?c
+
+ - .. row 12
+
+ - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK``
+
+ - Device node interface for ALSA PCM Playback
+
+ - typically, /dev/snd/pcmC?D?p
+
+ - .. row 13
+
+ - ``MEDIA_INTF_T_ALSA_CONTROL``
+
+ - Device node interface for ALSA Control
+
+ - typically, /dev/snd/controlC?
+
+ - .. row 14
+
+ - ``MEDIA_INTF_T_ALSA_COMPRESS``
+
+ - Device node interface for ALSA Compress
+
+ - typically, /dev/snd/compr?
+
+ - .. row 15
+
+ - ``MEDIA_INTF_T_ALSA_RAWMIDI``
+
+ - Device node interface for ALSA Raw MIDI
+
+ - typically, /dev/snd/midi?
+
+ - .. row 16
+
+ - ``MEDIA_INTF_T_ALSA_HWDEP``
+
+ - Device node interface for ALSA Hardware Dependent
+
+ - typically, /dev/snd/hwC?D?
+
+ - .. row 17
+
+ - ``MEDIA_INTF_T_ALSA_SEQUENCER``
+
+ - Device node interface for ALSA Sequencer
+
+ - typically, /dev/snd/seq
+
+ - .. row 18
+
+ - ``MEDIA_INTF_T_ALSA_TIMER``
+
+ - Device node interface for ALSA Timer
+
+ - typically, /dev/snd/timer
+
+
+
+.. _media-pad-flag:
+
+.. flat-table:: Media pad flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_PAD_FL_SINK``
+
+ - Input pad, relative to the entity. Input pads sink data and are
+ targets of links.
+
+ - .. row 2
+
+ - ``MEDIA_PAD_FL_SOURCE``
+
+ - Output pad, relative to the entity. Output pads source data and
+ are origins of links.
+
+ - .. row 3
+
+ - ``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.
+
+
+One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE``
+must be set for every pad.
+
+
+.. _media-link-flag:
+
+.. flat-table:: Media link flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_LNK_FL_ENABLED``
+
+ - The link is enabled and can be used to transfer media data. When
+ two or more links target a sink pad, only one of them can be
+ enabled at a time.
+
+ - .. row 2
+
+ - ``MEDIA_LNK_FL_IMMUTABLE``
+
+ - The link enabled state can't be modified at runtime. An immutable
+ link is always enabled.
+
+ - .. row 3
+
+ - ``MEDIA_LNK_FL_DYNAMIC``
+
+ - The link enabled state can be modified during streaming. This flag
+ is set by drivers and is read-only for applications.
+
+ - .. row 4
+
+ - ``MEDIA_LNK_FL_LINK_TYPE``
+
+ - This is a bitmask that defines the type of the link. Currently,
+ two types of links are supported:
+
+ ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads
+
+ ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an
+ interface and an entity
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _mmap:
+
+******************************
+Streaming I/O (Memory Mapping)
+******************************
+
+Input and output devices support this I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl is set. There are two
+streaming methods, to determine if the memory mapping flavor is
+supported applications must call the
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl.
+
+Streaming is an I/O method where only pointers to buffers are exchanged
+between application and driver, the data itself is not copied. Memory
+mapping is primarily intended to map buffers in device memory into the
+application's address space. Device memory can be for example the video
+memory on a graphics card with a video capture add-on. However, being
+the most efficient I/O method available for a long time, many other
+drivers support streaming as well, allocating buffers in DMA-able main
+memory.
+
+A driver can support many sets of buffers. Each set is identified by a
+unique buffer type value. The sets are independent and each set can hold
+a different type of data. To access different sets at the same time
+different file descriptors must be used. [1]_
+
+To allocate device buffers applications call the
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl with the desired number
+of buffers and buffer type, for example ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
+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
+location of the buffers in device memory can be determined with the
+:ref:`VIDIOC_QUERYBUF <vidioc-querybuf>` ioctl. In the single-planar
+API case, the ``m.offset`` and ``length`` returned in a struct
+:ref:`v4l2_buffer <v4l2-buffer>` are passed as sixth and second
+parameter to the :c:func:`mmap()` function. When using the
+multi-planar API, struct :ref:`v4l2_buffer <v4l2-buffer>` contains an
+array of struct :ref:`v4l2_plane <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
+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.
+
+
+.. code-block:: c
+
+ struct v4l2_requestbuffers reqbuf;
+ struct {
+ void *start;
+ size_t length;
+ } *buffers;
+ unsigned int i;
+
+ memset(&reqbuf, 0, sizeof(reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_MMAP;
+ reqbuf.count = 20;
+
+ if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqbuf)) {
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+ /* We want at least five buffers. */
+
+ if (reqbuf.count < 5) {
+ /* You may need to free the buffers here. */
+ printf("Not enough buffer memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(reqbuf.count, sizeof(*buffers));
+ assert(buffers != NULL);
+
+ for (i = 0; i < reqbuf.count; i++) {
+ struct v4l2_buffer buffer;
+
+ memset(&buffer, 0, sizeof(buffer));
+ buffer.type = reqbuf.type;
+ buffer.memory = V4L2_MEMORY_MMAP;
+ buffer.index = i;
+
+ if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers[i].length = buffer.length; /* remember for munmap() */
+
+ buffers[i].start = mmap(NULL, buffer.length,
+ PROT_READ | PROT_WRITE, /* recommended */
+ MAP_SHARED, /* recommended */
+ fd, buffer.m.offset);
+
+ if (MAP_FAILED == buffers[i].start) {
+ /* If you do not exit here you should unmap() and free()
+ the buffers mapped so far. */
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ /* Cleanup. */
+
+ for (i = 0; i < reqbuf.count; i++)
+ munmap(buffers[i].start, buffers[i].length);
+
+
+.. code-block:: c
+
+ struct v4l2_requestbuffers reqbuf;
+ /* Our current format uses 3 planes per buffer */
+ #define FMT_NUM_PLANES = 3
+
+ struct {
+ void *start[FMT_NUM_PLANES];
+ size_t length[FMT_NUM_PLANES];
+ } *buffers;
+ unsigned int i, j;
+
+ memset(&reqbuf, 0, sizeof(reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+ reqbuf.memory = V4L2_MEMORY_MMAP;
+ reqbuf.count = 20;
+
+ if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0) {
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+ /* We want at least five buffers. */
+
+ if (reqbuf.count < 5) {
+ /* You may need to free the buffers here. */
+ printf("Not enough buffer memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(reqbuf.count, sizeof(*buffers));
+ assert(buffers != NULL);
+
+ for (i = 0; i < reqbuf.count; i++) {
+ struct v4l2_buffer buffer;
+ struct v4l2_plane planes[FMT_NUM_PLANES];
+
+ memset(&buffer, 0, sizeof(buffer));
+ buffer.type = reqbuf.type;
+ buffer.memory = V4L2_MEMORY_MMAP;
+ buffer.index = i;
+ /* length in struct v4l2_buffer in multi-planar API stores the size
+ * of planes array. */
+ buffer.length = FMT_NUM_PLANES;
+ buffer.m.planes = planes;
+
+ if (ioctl(fd, VIDIOC_QUERYBUF, &buffer) < 0) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Every plane has to be mapped separately */
+ for (j = 0; j < FMT_NUM_PLANES; j++) {
+ buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
+
+ buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
+ PROT_READ | PROT_WRITE, /* recommended */
+ MAP_SHARED, /* recommended */
+ fd, buffer.m.planes[j].m.offset);
+
+ if (MAP_FAILED == buffers[i].start[j]) {
+ /* If you do not exit here you should unmap() and free()
+ the buffers and planes mapped so far. */
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+ }
+
+ /* Cleanup. */
+
+ for (i = 0; i < reqbuf.count; i++)
+ for (j = 0; j < FMT_NUM_PLANES; j++)
+ munmap(buffers[i].start[j], buffers[i].length[j]);
+
+Conceptually streaming drivers maintain two buffer queues, an incoming
+and an outgoing queue. They separate the synchronous capture or output
+operation locked to a video clock from the application which is subject
+to random disk or network delays and preemption by other processes,
+thereby reducing the probability of data loss. The queues are organized
+as FIFOs, buffers will be output in the order enqueued in the incoming
+FIFO, and were captured in the order dequeued from the outgoing FIFO.
+
+The driver may require a minimum number of buffers enqueued at all times
+to function, apart of this no limit exists on the number of buffers
+applications can enqueue in advance, or dequeue and process. They can
+also enqueue in a different order than buffers have been dequeued, and
+the driver can *fill* enqueued *empty* buffers in any order. [2]_ The
+index number of a buffer (struct :ref:`v4l2_buffer <v4l2-buffer>`
+``index``) plays no role here, it only identifies the buffer.
+
+Initially all mapped buffers are in dequeued state, inaccessible by the
+driver. For capturing applications it is customary to first enqueue all
+mapped buffers, then to start capturing and enter the read loop. Here
+the application waits until a filled buffer can be dequeued, and
+re-enqueues the buffer when the data is no longer needed. Output
+applications fill and enqueue buffers, when enough buffers are stacked
+up the output is started with ``VIDIOC_STREAMON``. 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:`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 <vidioc-querybuf>` ioctl. Two methods exist to
+suspend execution of the application until one or more buffers can be
+dequeued. 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
+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.
+
+To start and stop capturing or output applications call the
+:ref:`VIDIOC_STREAMON <vidioc-streamon>` and
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>` ioctl. Note
+``VIDIOC_STREAMOFF`` removes all buffers from both queues as a side
+effect. Since there is no notion of doing anything "now" on a
+multitasking system, if an application needs to synchronize with another
+event it should examine the struct :ref:`v4l2_buffer <v4l2-buffer>`
+``timestamp`` of captured or outputted buffers.
+
+Drivers implementing memory mapping I/O must support the
+``VIDIOC_REQBUFS``, ``VIDIOC_QUERYBUF``, ``VIDIOC_QBUF``,
+``VIDIOC_DQBUF``, ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl,
+the :c:func:`mmap()`, :c:func:`munmap()`, :c:func:`select()` and
+:c:func:`poll()` function. [3]_
+
+[capture example]
+
+.. [1]
+ One could use one file descriptor and set the buffer type field
+ accordingly when calling :ref:`VIDIOC_QBUF <vidioc-qbuf>` etc.,
+ 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.
+
+.. [2]
+ Random enqueue order permits applications processing images out of
+ order (such as video codecs) to return buffers earlier, reducing the
+ probability of data loss. Random fill order allows drivers to reuse
+ buffers on a LIFO-basis, taking advantage of caches holding
+ scatter-gather lists and the like.
+
+.. [3]
+ 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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _open:
+
+***************************
+Opening and Closing Devices
+***************************
+
+
+Device 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
+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.).
+
+Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
+options to select specific video/radio/vbi node numbers. This allows the
+user to request that the device node is named e.g. /dev/video5 instead
+of leaving it to chance. When the driver supports multiple devices of
+the same type more than one device node number can be assigned,
+separated by commas:
+
+
+
+::
+
+ > modprobe mydriver video_nr=0,1 radio_nr=0,1
+In ``/etc/modules.conf`` this may be written as:
+
+
+
+::
+
+ options mydriver video_nr=0,1 radio_nr=0,1
+When no device node number is given as module option the driver supplies
+a default.
+
+Normally udev will create the device nodes in /dev automatically for
+you. If udev is not installed, then you need to enable the
+CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to
+correctly relate a minor number to a device node number. I.e., you need
+to be certain that minor number 5 maps to device node name video5. With
+this kernel option different device types have different minor number
+ranges. These ranges are listed in :ref:`devices`.
+
+The creation of character special files (with mknod) is a privileged
+operation and devices cannot be opened by major and minor number. That
+means applications cannot *reliable* 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
+===============
+
+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 was designed with the idea that one device node could
+support all functions. However, in practice this never worked: this
+'feature' was never used by applications and many drivers did not
+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 read()/write() API.
+
+Today each 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
+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
+towards both Media Controller-based devices and devices that do not use
+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
+==============
+
+V4L2 devices can be opened more than once. [1]_ When this is supported
+by the driver, users can for example start a "panel" application to
+change controls like brightness or audio volume, while another
+application captures video and audio. In other words, panel applications
+are comparable to an ALSA audio mixer application. Just opening a V4L2
+device should not change the state of the device. [2]_
+
+Once an application has allocated the memory buffers needed for
+streaming data (by calling the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>`
+or :ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>` ioctls, or
+implicitly by calling the :ref:`read() <func-read>` or
+:ref:`write() <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
+no longer allowed to allocate buffers or start or stop streaming. The
+EBUSY error code will be returned instead.
+
+Merely opening a V4L2 device does not grant exclusive access. [3]_
+Initiating data exchange however assigns the right to read or write the
+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
+===================
+
+V4L2 drivers should not support multiple applications reading or writing
+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,
+respectively. Devices are programmed using the
+:ref:`ioctl() <func-ioctl>` function as explained in the following
+sections.
+
+.. [1]
+ 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
+ when the device is already in use.
+
+.. [2]
+ Unfortunately, opening a radio device often switches the state of the
+ device to radio mode in many drivers. This behavior should be fixed
+ eventually as it violates the V4L2 specification.
+
+.. [3]
+ Drivers could recognize the ``O_EXCL`` open flag. Presently this is
+ not required, so applications cannot know if it really works.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Single-planar format structure
+******************************
+
+
+.. _v4l2-pix-format:
+
+.. flat-table:: struct v4l2_pix_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
+ ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
+ refers to the number of lines in the field, otherwise it refers to
+ the number of lines in the frame (which is twice the field height
+ for interlaced formats).
+
+ - .. row 3
+
+ - :cspan:`2` Applications set these fields to request an image
+ size, drivers return the closest possible values. In case of
+ planar formats the ``width`` and ``height`` applies to the largest
+ plane. To avoid ambiguities drivers must return values rounded up
+ to a multiple of the scale factor of any smaller planes. For
+ example when the image format is YUV 4:2:0, ``width`` and
+ ``height`` must be multiples of two.
+
+ - .. row 4
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format or type of compression, set by the application.
+ This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
+ RGB formats in :ref:`rgb-formats`, YUV formats in
+ :ref:`yuv-formats`, and reserved codes in
+ :ref:`reserved-formats`
+
+ - .. row 5
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - Video images are typically interlaced. Applications can request to
+ capture or output only the top or bottom field, or both fields
+ interlaced or sequentially stored in one buffer or alternating in
+ separate buffers. Drivers return the actual field order selected.
+ For more details on fields see :ref:`field-order`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines.
+
+ - .. row 7
+
+ - :cspan:`2`
+
+ Both applications and drivers can set this field to request
+ padding bytes at the end of each line. Drivers however may ignore
+ the value requested by the application, 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.
+
+ Video hardware may access padding bytes, therefore they must
+ reside in accessible memory. Consider cases where padding bytes
+ after the last line of an image cross a system page boundary.
+ Input devices may write padding bytes, the value is undefined.
+ Output devices ignore the contents of padding bytes.
+
+ When the image format is planar the ``bytesperline`` value applies
+ to the first plane and is divided by the same factor as the
+ ``width`` field for the other planes. For example the Cb and Cr
+ planes of a YUV 4:2:0 image have half as many padding bytes
+ following each line as the Y plane. To avoid ambiguities drivers
+ must return a ``bytesperline`` value rounded up to a multiple of
+ the scale factor.
+
+ For compressed formats the ``bytesperline`` value makes no sense.
+ Applications and drivers must set this to 0 in that case.
+
+ - .. row 8
+
+ - __u32
+
+ - ``sizeimage``
+
+ - Size in bytes of the buffer to hold a complete image, set by the
+ driver. Usually this is ``bytesperline`` times ``height``. When
+ the image consists of variable length compressed data this is the
+ maximum number of bytes required to hold an image.
+
+ - .. row 9
+
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``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`.
+
+ - .. row 10
+
+ - __u32
+
+ - ``priv``
+
+ - This field indicates whether the remaining fields of the
+ :c:type:`struct v4l2_pix_format` structure, also called the
+ extended fields, are valid. When set to
+ ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
+ have been correctly initialized. When set to any other value it
+ indicates that the extended fields contain undefined values.
+
+ Applications that wish to use the pixel format extended fields
+ must first ensure that the feature is supported by querying the
+ device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
+ capability. If the capability isn't set the pixel format extended
+ fields are not supported and using the extended fields will lead
+ to undefined results.
+
+ To use the extended fields, applications must set the ``priv``
+ field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
+ fields and zero the unused bytes of the
+ :c:type:`struct v4l2_format` ``raw_data`` field.
+
+ When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
+ drivers must act as if all the extended fields were set to zero.
+ On return drivers must set the ``priv`` field to
+ ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
+ applicable values.
+
+ - .. row 11
+
+ - __u32
+
+ - ``flags``
+
+ - Flags set by the application or driver, see :ref:`format-flags`.
+
+ - .. row 12
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - 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`.
+
+ - .. row 13
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``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`.
+
+ - .. row 14
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``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`.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Multi-planar format structures
+******************************
+
+The :c:type:`struct v4l2_plane_pix_format` structures define size
+and layout for each of the planes in a multi-planar format. The
+:c:type:`struct v4l2_pix_format_mplane` structure contains
+information common to all planes (such as image width and height) and an
+array of :c:type:`struct v4l2_plane_pix_format` structures,
+describing all planes of that format.
+
+
+.. _v4l2-plane-pix-format:
+
+.. flat-table:: struct v4l2_plane_pix_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``sizeimage``
+
+ - Maximum size in bytes required for image data in this plane.
+
+ - .. row 2
+
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines. See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 3
+
+ - __u16
+
+ - ``reserved[6]``
+
+ - Reserved for future extensions. Should be zeroed by drivers and
+ applications.
+
+
+
+.. _v4l2-pix-format-mplane:
+
+.. flat-table:: struct v4l2_pix_format_mplane
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width in pixels. See struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height in pixels. See struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format. Both single- and multi-planar four character
+ codes can be used.
+
+ - .. row 4
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 5
+
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``colorspace``
+
+ - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 6
+
+ - struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`
+
+ - ``plane_fmt[VIDEO_MAX_PLANES]``
+
+ - An array of structures describing format of each plane this pixel
+ format consists of. The number of valid entries in this array has
+ to be put in the ``num_planes`` field.
+
+ - .. row 7
+
+ - __u8
+
+ - ``num_planes``
+
+ - Number of planes (i.e. separate memory buffers) for this format
+ and the number of valid entries in the ``plane_fmt`` array.
+
+ - .. row 8
+
+ - __u8
+
+ - ``flags``
+
+ - Flags set by the application or driver, see :ref:`format-flags`.
+
+ - .. row 9
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - 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`.
+
+ - .. row 10
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``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`.
+
+ - .. row 11
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``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`.
+
+ - .. row 12
+
+ - __u8
+
+ - ``reserved[7]``
+
+ - Reserved for future extensions. Should be zeroed by drivers and
+ applications.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+**********************
+Standard Image Formats
+**********************
+
+In order to exchange images between drivers and applications, it is
+necessary to have standard image data formats which both sides will
+interpret the same way. V4L2 includes several such formats, and this
+section is intended to be an unambiguous specification of the standard
+image data formats in V4L2.
+
+V4L2 drivers are not limited to these formats, however. Driver-specific
+formats are possible. In that case the application may depend on a codec
+to convert images to one of the standard formats when needed. But the
+data can still be stored and retrieved in the proprietary format. For
+example, a device may support a proprietary compressed format.
+Applications can still capture and save the data in the compressed
+format, saving much disk space, and later use a codec to convert the
+images to the X Windows screen format when the video is to be displayed.
+
+Even so, ultimately, some standard formats are needed, so the V4L2
+specification would not be complete without well-defined standard
+formats.
+
+The V4L2 standard formats are mainly uncompressed formats. The pixels
+are always arranged in memory from left to right, and from top to
+bottom. The first byte of data in the image buffer is always for the
+leftmost pixel of the topmost row. Following that is the pixel
+immediately to its right, and so on until the end of the top row of
+pixels. Following the rightmost pixel of the row there may be zero or
+more bytes of padding to guarantee that each row of pixel data has a
+certain alignment. Following the pad bytes, if any, is data for the
+leftmost pixel of the second row from the top, and so on. The last row
+has just as many pad bytes after it as the other rows.
+
+In V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``,
+defined in the :ref:`videodev2.h <videodev>` header file. These
+identifiers represent
+:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also
+listed below, however they are not the same as those used in the Windows
+world.
+
+For some formats, data is stored in separate, discontiguous memory
+buffers. Those formats are identified by a separate set of FourCC codes
+and are referred to as "multi-planar formats". For example, a YUV422
+frame is normally stored in one memory buffer, but it can also be placed
+in two or three separate buffers, with Y component in one buffer and
+CbCr components in another in the 2-planar version or with each
+component in its own buffer in the 3-planar case. Those sub-buffers are
+referred to as "planes".
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+****************************
+Defining Colorspaces in V4L2
+****************************
+
+In V4L2 colorspaces are defined by four values. The first is the
+colorspace identifier (enum :ref:`v4l2_colorspace <v4l2-colorspace>`)
+which defines the chromaticities, the default transfer function, the
+default Y'CbCr encoding and the default quantization method. The second
+is the transfer function identifier (enum
+:ref:`v4l2_xfer_func <v4l2-xfer-func>`) to specify non-standard
+transfer functions. The third is the Y'CbCr encoding identifier (enum
+:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`) to specify
+non-standard Y'CbCr encodings and the fourth is the quantization
+identifier (enum :ref:`v4l2_quantization <v4l2-quantization>`) to
+specify non-standard quantization methods. Most of the time only the
+colorspace field of struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+or struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
+needs to be filled in. Note that the default R'G'B' quantization is full
+range for all colorspaces except for BT.2020 which uses limited range
+R'G'B' quantization.
+
+
+.. _v4l2-colorspace:
+
+.. flat-table:: V4L2 Colorspaces
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_COLORSPACE_DEFAULT``
+
+ - The default colorspace. This can be used by applications to let
+ the driver fill in the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_COLORSPACE_SMPTE170M``
+
+ - See :ref:`col-smpte-170m`.
+
+ - .. row 4
+
+ - ``V4L2_COLORSPACE_REC709``
+
+ - See :ref:`col-rec709`.
+
+ - .. row 5
+
+ - ``V4L2_COLORSPACE_SRGB``
+
+ - See :ref:`col-srgb`.
+
+ - .. row 6
+
+ - ``V4L2_COLORSPACE_ADOBERGB``
+
+ - See :ref:`col-adobergb`.
+
+ - .. row 7
+
+ - ``V4L2_COLORSPACE_BT2020``
+
+ - See :ref:`col-bt2020`.
+
+ - .. row 8
+
+ - ``V4L2_COLORSPACE_DCI_P3``
+
+ - See :ref:`col-dcip3`.
+
+ - .. row 9
+
+ - ``V4L2_COLORSPACE_SMPTE240M``
+
+ - See :ref:`col-smpte-240m`.
+
+ - .. row 10
+
+ - ``V4L2_COLORSPACE_470_SYSTEM_M``
+
+ - See :ref:`col-sysm`.
+
+ - .. row 11
+
+ - ``V4L2_COLORSPACE_470_SYSTEM_BG``
+
+ - See :ref:`col-sysbg`.
+
+ - .. row 12
+
+ - ``V4L2_COLORSPACE_JPEG``
+
+ - See :ref:`col-jpeg`.
+
+ - .. row 13
+
+ - ``V4L2_COLORSPACE_RAW``
+
+ - The raw colorspace. This is used for raw image capture where the
+ image is minimally processed and is using the internal colorspace
+ of the device. The software that processes an image using this
+ 'colorspace' will have to know the internals of the capture
+ device.
+
+
+
+.. _v4l2-xfer-func:
+
+.. flat-table:: V4L2 Transfer Function
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_XFER_FUNC_DEFAULT``
+
+ - Use the default transfer function as defined by the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_XFER_FUNC_709``
+
+ - Use the Rec. 709 transfer function.
+
+ - .. row 4
+
+ - ``V4L2_XFER_FUNC_SRGB``
+
+ - Use the sRGB transfer function.
+
+ - .. row 5
+
+ - ``V4L2_XFER_FUNC_ADOBERGB``
+
+ - Use the AdobeRGB transfer function.
+
+ - .. row 6
+
+ - ``V4L2_XFER_FUNC_SMPTE240M``
+
+ - Use the SMPTE 240M transfer function.
+
+ - .. row 7
+
+ - ``V4L2_XFER_FUNC_NONE``
+
+ - Do not use a transfer function (i.e. use linear RGB values).
+
+ - .. row 8
+
+ - ``V4L2_XFER_FUNC_DCI_P3``
+
+ - Use the DCI-P3 transfer function.
+
+ - .. row 9
+
+ - ``V4L2_XFER_FUNC_SMPTE2084``
+
+ - Use the SMPTE 2084 transfer function.
+
+
+
+.. _v4l2-ycbcr-encoding:
+
+.. flat-table:: V4L2 Y'CbCr Encodings
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_YCBCR_ENC_DEFAULT``
+
+ - Use the default Y'CbCr encoding as defined by the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_YCBCR_ENC_601``
+
+ - Use the BT.601 Y'CbCr encoding.
+
+ - .. row 4
+
+ - ``V4L2_YCBCR_ENC_709``
+
+ - Use the Rec. 709 Y'CbCr encoding.
+
+ - .. row 5
+
+ - ``V4L2_YCBCR_ENC_XV601``
+
+ - Use the extended gamut xvYCC BT.601 encoding.
+
+ - .. row 6
+
+ - ``V4L2_YCBCR_ENC_XV709``
+
+ - Use the extended gamut xvYCC Rec. 709 encoding.
+
+ - .. row 7
+
+ - ``V4L2_YCBCR_ENC_SYCC``
+
+ - Use the extended gamut sYCC encoding.
+
+ - .. row 8
+
+ - ``V4L2_YCBCR_ENC_BT2020``
+
+ - Use the default non-constant luminance BT.2020 Y'CbCr encoding.
+
+ - .. row 9
+
+ - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM``
+
+ - Use the constant luminance BT.2020 Yc'CbcCrc encoding.
+
+
+
+.. _v4l2-quantization:
+
+.. flat-table:: V4L2 Quantization Methods
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``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 usually limited range for Y'CbCr.
+
+ - .. row 3
+
+ - ``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
+ 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to
+ [0…255] (with possible clipping to [1…254] to avoid the 0x00 and
+ 0xff values).
+
+ - .. row 4
+
+ - ``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].
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+********************************
+Detailed Colorspace Descriptions
+********************************
+
+
+.. _col-smpte-170m:
+
+Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M)
+=================================================
+
+The :ref:`smpte170m` standard defines the colorspace used by NTSC and
+PAL and by SDTV in general. 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:
+
+
+
+.. flat-table:: SMPTE 170M Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.630
+
+ - 0.340
+
+ - .. row 3
+
+ - Green
+
+ - 0.310
+
+ - 0.595
+
+ - .. row 4
+
+ - Blue
+
+ - 0.155
+
+ - 0.070
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+The red, green and blue chromaticities are also often referred to as the
+SMPTE C set, so this colorspace is sometimes called SMPTE C as well.
+
+The transfer function defined for SMPTE 170M is the same as the one
+defined in Rec. 709.
+ L' = -1.099(-L):sup:`0.45` + 0.099 for L ≤ -0.018
+
+ L' = 4.5L for -0.018 < L < 0.018
+
+ L' = 1.099L\ :sup:`0.45` - 0.099 for L ≥ 0.018
+
+Inverse Transfer function:
+ L = -((L' - 0.099) / -1.099):sup:`1/0.45` for L' ≤ -0.081
+
+ L = L' / 4.5 for -0.081 < L' < 0.081
+
+ L = ((L' + 0.099) / 1.099)\ :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in
+the :ref:`itu601` standard and this colorspace is sometimes called
+BT.601 as well, even though BT.601 does not mention any color primaries.
+
+The default quantization is limited range, but full range is possible
+although rarely seen.
+
+
+.. _col-rec709:
+
+Colorspace Rec. 709 (V4L2_COLORSPACE_REC709)
+============================================
+
+The :ref:`itu709` standard defines the colorspace used by HDTV in
+general. The default transfer function is ``V4L2_XFER_FUNC_709``. The
+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:
+
+
+
+.. flat-table:: Rec. 709 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.640
+
+ - 0.330
+
+ - .. row 3
+
+ - Green
+
+ - 0.300
+
+ - 0.600
+
+ - .. row 4
+
+ - Blue
+
+ - 0.150
+
+ - 0.060
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+The full name of this standard is Rec. ITU-R BT.709-5.
+
+Transfer function. Normally L is in the range [0…1], but for the
+extended gamut xvYCC encoding values outside that range are allowed.
+ L' = -1.099(-L):sup:`0.45` + 0.099 for L ≤ -0.018
+
+ L' = 4.5L for -0.018 < L < 0.018
+
+ L' = 1.099L\ :sup:`0.45` - 0.099 for L ≥ 0.018
+
+Inverse Transfer function:
+ L = -((L' - 0.099) / -1.099):sup:`1/0.45` for L' ≤ -0.081
+
+ L = L' / 4.5 for -0.081 < L' < 0.081
+
+ L = ((L' + 0.099) / 1.099)\ :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_709`` encoding:
+ Y' = 0.2126R' + 0.7152G' + 0.0722B'
+
+ Cb = -0.1146R' - 0.3854G' + 0.5B'
+
+ Cr = 0.5R' - 0.4542G' - 0.0458B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5].
+
+The default quantization is limited range, but full range is possible
+although rarely seen.
+
+The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for
+this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``,
+in which case the BT.601 Y'CbCr encoding is used.
+
+Two additional extended gamut Y'CbCr encodings are also possible with
+this colorspace:
+
+The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is
+similar to the Rec. 709 encoding, but it allows for R', G' and B' values
+that are outside the range [0…1]. The resulting Y', Cb and Cr values are
+scaled and offset:
+ Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256)
+
+ Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B')
+
+ Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B')
+
+The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is
+similar to the BT.601 encoding, but it allows for R', G' and B' values
+that are outside the range [0…1]. The resulting Y', Cb and Cr values are
+scaled and offset:
+ Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256)
+
+ Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B')
+
+ Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B')
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be
+used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``.
+The xvYCC encodings always use full range quantization.
+
+
+.. _col-srgb:
+
+Colorspace sRGB (V4L2_COLORSPACE_SRGB)
+======================================
+
+The :ref:`srgb` standard defines the colorspace used by most webcams
+and computer graphics. The default transfer function is
+``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_SYCC``. The default Y'CbCr quantization is full range.
+The chromaticities of the primary colors and the white reference are:
+
+
+
+.. flat-table:: sRGB Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.640
+
+ - 0.330
+
+ - .. row 3
+
+ - Green
+
+ - 0.300
+
+ - 0.600
+
+ - .. row 4
+
+ - Blue
+
+ - 0.150
+
+ - 0.060
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+These chromaticities are identical to the Rec. 709 colorspace.
+
+Transfer function. Note that negative values for L are only used by the
+Y'CbCr conversion.
+ L' = -1.055(-L):sup:`1/2.4` + 0.055 for L < -0.0031308
+
+ L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308
+
+ L' = 1.055L\ :sup:`1/2.4` - 0.055 for 0.0031308 < L ≤ 1
+
+Inverse Transfer function:
+ L = -((-L' + 0.055) / 1.055)\ :sup:`2.4` for L' < -0.04045
+
+ L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045
+
+ L = ((L' + 0.055) / 1.055)\ :sup:`2.4` for L' > 0.04045
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_SYCC`` encoding as defined by
+:ref:`sycc`:
+ Y' = 0.2990R' + 0.5870G' + 0.1140B'
+
+ Cb = -0.1687R' - 0.3313G' + 0.5B'
+
+ Cr = 0.5R' - 0.4187G' - 0.0813B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The ``V4L2_YCBCR_ENC_SYCC`` quantization is always full
+range. Although this Y'CbCr encoding looks very similar to the
+``V4L2_YCBCR_ENC_XV601`` encoding, it is not. The
+``V4L2_YCBCR_ENC_XV601`` scales and offsets the Y'CbCr values before
+quantization, but this encoding does not do that.
+
+
+.. _col-adobergb:
+
+Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB)
+===============================================
+
+The :ref:`adobergb` standard defines the colorspace used by computer
+graphics that use the AdobeRGB colorspace. This is also known as the
+:ref:`oprgb` standard. The default transfer function is
+``V4L2_XFER_FUNC_ADOBERGB``. 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:
+
+
+
+.. flat-table:: Adobe RGB Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.6400
+
+ - 0.3300
+
+ - .. row 3
+
+ - Green
+
+ - 0.2100
+
+ - 0.7100
+
+ - .. row 4
+
+ - Blue
+
+ - 0.1500
+
+ - 0.0600
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+Transfer function:
+ L' = L\ :sup:`1/2.19921875`
+
+Inverse Transfer function:
+ L = L'\ :sup:`2.19921875`
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This transform is identical to one defined in SMPTE
+170M/BT.601. The Y'CbCr quantization is limited range.
+
+
+.. _col-bt2020:
+
+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:
+
+
+
+.. flat-table:: BT.2020 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.708
+
+ - 0.292
+
+ - .. row 3
+
+ - Green
+
+ - 0.170
+
+ - 0.797
+
+ - .. row 4
+
+ - Blue
+
+ - 0.131
+
+ - 0.046
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+Transfer function (same as Rec. 709):
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L\ :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099)\ :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_BT2020`` encoding:
+ Y' = 0.2627R' + 0.6780G' + 0.0593B'
+
+ Cb = -0.1396R' - 0.3604G' + 0.5B'
+
+ Cr = 0.5R' - 0.4598G' - 0.0402B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range.
+
+There is also an alternate constant luminance R'G'B' to Yc'CbcCrc
+(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding:
+
+Luma:
+ Yc' = (0.2627R + 0.6780G + 0.0593B)'
+
+B' - Yc' ≤ 0:
+ Cbc = (B' - Yc') / 1.9404
+
+B' - Yc' > 0:
+ Cbc = (B' - Yc') / 1.5816
+
+R' - Yc' ≤ 0:
+ Crc = (R' - Y') / 1.7184
+
+R' - Yc' > 0:
+ Crc = (R' - Y') / 0.9936
+
+Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
+range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.
+
+
+.. _col-dcip3:
+
+Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3)
+==========================================
+
+The :ref:`smpte431` standard defines the colorspace used by cinema
+projectors that use the DCI-P3 colorspace. The default transfer function
+is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_709``. Note that this colorspace does not specify a
+Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this
+default Y'CbCr encoding was picked because it is the HDTV encoding. The
+default Y'CbCr quantization is limited range. The chromaticities of the
+primary colors and the white reference are:
+
+
+
+.. flat-table:: DCI-P3 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.6800
+
+ - 0.3200
+
+ - .. row 3
+
+ - Green
+
+ - 0.2650
+
+ - 0.6900
+
+ - .. row 4
+
+ - Blue
+
+ - 0.1500
+
+ - 0.0600
+
+ - .. row 5
+
+ - White Reference
+
+ - 0.3140
+
+ - 0.3510
+
+
+
+Transfer function:
+ L' = L\ :sup:`1/2.6`
+
+Inverse Transfer function:
+ L = L'\ :sup:`2.6`
+
+Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.
+
+
+.. _col-smpte-240m:
+
+Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M)
+=================================================
+
+The :ref:`smpte240m` standard was an interim standard used during the
+early days of HDTV (1988-1998). It has been superseded by Rec. 709. The
+default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default
+Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr
+quantization is limited range. The chromaticities of the primary colors
+and the white reference are:
+
+
+
+.. flat-table:: SMPTE 240M Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.630
+
+ - 0.340
+
+ - .. row 3
+
+ - Green
+
+ - 0.310
+
+ - 0.595
+
+ - .. row 4
+
+ - Blue
+
+ - 0.155
+
+ - 0.070
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+These chromaticities are identical to the SMPTE 170M colorspace.
+
+Transfer function:
+ L' = 4L for 0 ≤ L < 0.0228
+
+ L' = 1.1115L\ :sup:`0.45` - 0.1115 for 0.0228 ≤ L ≤ 1
+
+Inverse Transfer function:
+ L = L' / 4 for 0 ≤ L' < 0.0913
+
+ L = ((L' + 0.1115) / 1.1115)\ :sup:`1/0.45` for L' ≥ 0.0913
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding:
+ Y' = 0.2122R' + 0.7013G' + 0.0865B'
+
+ Cb = -0.1161R' - 0.3839G' + 0.5B'
+
+ Cr = 0.5R' - 0.4451G' - 0.0549B'
+
+Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
+range [-0.5…0.5]. The Y'CbCr quantization is limited range.
+
+
+.. _col-sysm:
+
+Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M)
+===================================================
+
+This standard defines the colorspace used by NTSC in 1953. In practice
+this colorspace is obsolete and SMPTE 170M should be used instead. 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:
+
+
+
+.. flat-table:: NTSC 1953 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.67
+
+ - 0.33
+
+ - .. row 3
+
+ - Green
+
+ - 0.21
+
+ - 0.71
+
+ - .. row 4
+
+ - Blue
+
+ - 0.14
+
+ - 0.08
+
+ - .. row 5
+
+ - White Reference (C)
+
+ - 0.310
+
+ - 0.316
+
+
+Note that this colorspace uses Illuminant C instead of D65 as the white
+reference. To correctly convert an image in this colorspace to another
+that uses D65 you need to apply a chromatic adaptation algorithm such as
+the Bradford method.
+
+The transfer function was never properly defined for NTSC 1953. The Rec.
+709 transfer function is recommended in the literature:
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L\ :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099)\ :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
+identical to one defined in SMPTE 170M/BT.601.
+
+
+.. _col-sysbg:
+
+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
+``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:
+
+
+
+.. flat-table:: EBU Tech. 3213 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.64
+
+ - 0.33
+
+ - .. row 3
+
+ - Green
+
+ - 0.29
+
+ - 0.60
+
+ - .. row 4
+
+ - Blue
+
+ - 0.15
+
+ - 0.06
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+The transfer function was never properly defined for this colorspace.
+The Rec. 709 transfer function is recommended in the literature:
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L\ :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099)\ :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
+identical to one defined in SMPTE 170M/BT.601.
+
+
+.. _col-jpeg:
+
+Colorspace JPEG (V4L2_COLORSPACE_JPEG)
+======================================
+
+This colorspace defines the colorspace used by most (Motion-)JPEG
+formats. The chromaticities of the primary colors and the white
+reference are identical to sRGB. The transfer function use is
+``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``
+with full range quantization where Y' is scaled to [0…255] and Cb/Cr are
+scaled to [-128…128] and then clipped to [-128…127].
+
+Note that the JPEG standard does not actually store colorspace
+information. So if something other than sRGB is used, then the driver
+will have to set that information explicitly. Effectively
+``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
+``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
+``V4L2_QUANTIZATION_FULL_RANGE``.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+***************************************
+Detailed Transfer Function Descriptions
+***************************************
+
+
+.. _xf-smpte-2084:
+
+Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084)
+=======================================================
+
+The :ref:`smpte2084` standard defines the transfer function used by
+High Dynamic Range content.
+
+Constants:
+ m1 = (2610 / 4096) / 4
+
+ m2 = (2523 / 4096) * 128
+
+ c1 = 3424 / 4096
+
+ c2 = (2413 / 4096) * 32
+
+ c3 = (2392 / 4096) * 32
+
+Transfer function:
+ L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2`
+
+Inverse Transfer function:
+ L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 *
+ L'\ :sup:`1/m2`))\ :sup:`1/m1`
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************
+Compressed Formats
+******************
+
+
+.. _compressed-formats:
+
+.. flat-table:: Compressed Image Formats
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Details
+
+ - .. _`V4L2-PIX-FMT-JPEG`:
+
+ - ``V4L2_PIX_FMT_JPEG``
+
+ - 'JPEG'
+
+ - TBD. See also :ref:`VIDIOC_G_JPEGCOMP <vidioc-g-jpegcomp>`,
+ :ref:`VIDIOC_S_JPEGCOMP <vidioc-g-jpegcomp>`.
+
+ - .. _`V4L2-PIX-FMT-MPEG`:
+
+ - ``V4L2_PIX_FMT_MPEG``
+
+ - 'MPEG'
+
+ - MPEG multiplexed stream. The actual format is determined by
+ extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see
+ :ref:`mpeg-control-id`.
+
+ - .. _`V4L2-PIX-FMT-H264`:
+
+ - ``V4L2_PIX_FMT_H264``
+
+ - 'H264'
+
+ - H264 video elementary stream with start codes.
+
+ - .. _`V4L2-PIX-FMT-H264-NO-SC`:
+
+ - ``V4L2_PIX_FMT_H264_NO_SC``
+
+ - 'AVC1'
+
+ - H264 video elementary stream without start codes.
+
+ - .. _`V4L2-PIX-FMT-H264-MVC`:
+
+ - ``V4L2_PIX_FMT_H264_MVC``
+
+ - 'M264'
+
+ - H264 MVC video elementary stream.
+
+ - .. _`V4L2-PIX-FMT-H263`:
+
+ - ``V4L2_PIX_FMT_H263``
+
+ - 'H263'
+
+ - H263 video elementary stream.
+
+ - .. _`V4L2-PIX-FMT-MPEG1`:
+
+ - ``V4L2_PIX_FMT_MPEG1``
+
+ - 'MPG1'
+
+ - MPEG1 video elementary stream.
+
+ - .. _`V4L2-PIX-FMT-MPEG2`:
+
+ - ``V4L2_PIX_FMT_MPEG2``
+
+ - 'MPG2'
+
+ - MPEG2 video elementary stream.
+
+ - .. _`V4L2-PIX-FMT-MPEG4`:
+
+ - ``V4L2_PIX_FMT_MPEG4``
+
+ - 'MPG4'
+
+ - MPEG4 video elementary stream.
+
+ - .. _`V4L2-PIX-FMT-XVID`:
+
+ - ``V4L2_PIX_FMT_XVID``
+
+ - 'XVID'
+
+ - Xvid video elementary stream.
+
+ - .. _`V4L2-PIX-FMT-VC1-ANNEX-G`:
+
+ - ``V4L2_PIX_FMT_VC1_ANNEX_G``
+
+ - 'VC1G'
+
+ - VC1, SMPTE 421M Annex G compliant stream.
+
+ - .. _`V4L2-PIX-FMT-VC1-ANNEX-L`:
+
+ - ``V4L2_PIX_FMT_VC1_ANNEX_L``
+
+ - 'VC1L'
+
+ - VC1, SMPTE 421M Annex L compliant stream.
+
+ - .. _`V4L2-PIX-FMT-VP8`:
+
+ - ``V4L2_PIX_FMT_VP8``
+
+ - 'VP80'
+
+ - VP8 video elementary stream.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-GREY:
+
+**************************
+V4L2_PIX_FMT_GREY ('GREY')
+**************************
+
+*man V4L2_PIX_FMT_GREY(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-indexed:
+
+**************
+Indexed Format
+**************
+
+In this format each pixel is represented by an 8 bit index into a 256
+entry ARGB palette. It is intended for
+:ref:`Video Output Overlays <osd>` only. There are no ioctls to access
+the palette, this must be done with ioctls of the Linux framebuffer API.
+
+
+
+.. flat-table:: Indexed Image Format
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _`V4L2-PIX-FMT-PAL8`:
+
+ - ``V4L2_PIX_FMT_PAL8``
+
+ - 'PAL8'
+
+ -
+ - i\ :sub:`7`
+
+ - i\ :sub:`6`
+
+ - i\ :sub:`5`
+
+ - i\ :sub:`4`
+
+ - i\ :sub:`3`
+
+ - i\ :sub:`2`
+
+ - i\ :sub:`1`
+
+ - i\ :sub:`0`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-M420:
+
+**************************
+V4L2_PIX_FMT_M420 ('M420')
+**************************
+
+*man V4L2_PIX_FMT_M420(2)*
+
+Format with ½ horizontal and vertical chroma resolution, also known as
+YUV 4:2:0. Hybrid plane line-interleaved layout.
+
+
+Description
+===========
+
+M420 is a YUV format with ½ horizontal and vertical chroma subsampling
+(YUV 4:2:0). Pixels are organized as interleaved luma and chroma planes.
+Two lines of luma data are followed by one line of chroma data.
+
+The luma plane has one byte per pixel. The chroma plane contains
+interleaved CbCr pixels subsampled by ½ in the horizontal and vertical
+directions. 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`.
+
+All line lengths are identical: if the Y lines include pad bytes so do
+the CbCr lines.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 4
+
+ - start + 16:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 5
+
+ - start + 20:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 6
+
+ - start + 24:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12:
+
+******************************************************
+V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')
+******************************************************
+
+*man V4L2_PIX_FMT_NV12(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12M:
+
+***********************************************************************************
+V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16
+***********************************************************************************
+
+*man V4L2_PIX_FMT_NV12M(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 7
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12MT:
+
+****************************
+V4L2_PIX_FMT_NV12MT ('TM12')
+****************************
+
+*man V4L2_PIX_FMT_NV12MT(2)*
+
+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:
+
+.. figure:: pixfmt-nv12mt_files/nv12mt.*
+ :alt: nv12mt.gif
+ :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:
+
+.. figure:: pixfmt-nv12mt_files/nv12mt_example.*
+ :alt: nv12mt_example.gif
+ :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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV16:
+
+******************************************************
+V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')
+******************************************************
+
+*man V4L2_PIX_FMT_NV16(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - start + 20:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - .. row 7
+
+ - start + 24:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - .. row 8
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 6
+
+ -
+
+ - .. row 7
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 8
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 9
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 10
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV16M:
+
+********************************************************
+V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61')
+********************************************************
+
+*man V4L2_PIX_FMT_NV16M(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`02`
+
+ - Cr\ :sub:`02`
+
+ - .. row 7
+
+ - start1 + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`12`
+
+ - Cr\ :sub:`12`
+
+ - .. row 8
+
+ - start1 + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`22`
+
+ - Cr\ :sub:`22`
+
+ - .. row 9
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 6
+
+ -
+
+ - .. row 7
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 8
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 9
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 10
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV24:
+
+******************************************************
+V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')
+******************************************************
+
+*man V4L2_PIX_FMT_NV24(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - 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`
+
+ - .. row 6
+
+ - 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`
+
+ - .. row 7
+
+ - 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`
+
+ - .. row 8
+
+ - 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`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _packed-rgb:
+
+******************
+Packed RGB formats
+******************
+
+*man Packed RGB formats(2)*
+
+Packed 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.
+
+
+.. _rgb-formats:
+
+.. flat-table:: Packed RGB Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ - :cspan:`7` Byte 1
+
+ - :cspan:`7` Byte 2
+
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 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-RGB332`:
+
+ - ``V4L2_PIX_FMT_RGB332``
+
+ - 'RGB1'
+
+ -
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`V4L2-PIX-FMT-ARGB444`:
+
+ - ``V4L2_PIX_FMT_ARGB444``
+
+ - 'AR12'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`V4L2-PIX-FMT-XRGB444`:
+
+ - ``V4L2_PIX_FMT_XRGB444``
+
+ - 'XR12'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`V4L2-PIX-FMT-ARGB555`:
+
+ - ``V4L2_PIX_FMT_ARGB555``
+
+ - 'AR15'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _`V4L2-PIX-FMT-XRGB555`:
+
+ - ``V4L2_PIX_FMT_XRGB555``
+
+ - 'XR15'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _`V4L2-PIX-FMT-RGB565`:
+
+ - ``V4L2_PIX_FMT_RGB565``
+
+ - 'RGBP'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _`V4L2-PIX-FMT-ARGB555X`:
+
+ - ``V4L2_PIX_FMT_ARGB555X``
+
+ - 'AR15' | (1 << 31)
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - 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`
+
+ - .. _`V4L2-PIX-FMT-XRGB555X`:
+
+ - ``V4L2_PIX_FMT_XRGB555X``
+
+ - 'XR15' | (1 << 31)
+
+ -
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - 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`
+
+ - .. _`V4L2-PIX-FMT-RGB565X`:
+
+ - ``V4L2_PIX_FMT_RGB565X``
+
+ - 'RGBR'
+
+ -
+ - 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`
+
+ - .. _`V4L2-PIX-FMT-BGR24`:
+
+ - ``V4L2_PIX_FMT_BGR24``
+
+ - 'BGR3'
+
+ -
+ - 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`
+
+ - .. _`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`
+
+ -
+ - 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`
+
+ - .. _`V4L2-PIX-FMT-BGR666`:
+
+ - ``V4L2_PIX_FMT_BGR666``
+
+ - 'BGRH'
+
+ -
+ - 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`
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - .. _`V4L2-PIX-FMT-ABGR32`:
+
+ - ``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`
+
+ -
+ - 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`
+
+ -
+ - 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_XBGR32``
+
+ - 'XR24'
+
+ -
+ - 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`
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - .. _`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:`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:`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`
+
+
+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 <capture>` and :ref:`output <output>` devices.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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`
+
+
+Formats defined in :ref:`rgb-formats-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 interpreted as in
+either the corresponding ARGB or XRGB format, depending on the driver.
+
+
+.. _rgb-formats-deprecated:
+
+.. flat-table:: Deprecated Packed RGB Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ - :cspan:`7` Byte 1
+
+ - :cspan:`7` Byte 2
+
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 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-RGB444`:
+
+ - ``V4L2_PIX_FMT_RGB444``
+
+ - 'R444'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`V4L2-PIX-FMT-RGB555`:
+
+ - ``V4L2_PIX_FMT_RGB555``
+
+ - 'RGBO'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _`V4L2-PIX-FMT-RGB555X`:
+
+ - ``V4L2_PIX_FMT_RGB555X``
+
+ - 'RGBQ'
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - 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`
+
+ - .. _`V4L2-PIX-FMT-BGR32`:
+
+ - ``V4L2_PIX_FMT_BGR32``
+
+ - 'BGR4'
+
+ -
+ - 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`
+
+ -
+ - 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-RGB32`:
+
+ - ``V4L2_PIX_FMT_RGB32``
+
+ - 'RGB4'
+
+ -
+ - 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:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+
+A test utility to determine which RGB formats a driver actually supports
+is available from the LinuxTV v4l-dvb repository. See
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _packed-yuv:
+
+******************
+Packed YUV formats
+******************
+
+*man Packed YUV formats(2)*
+
+Packed YUV formats
+
+
+Description
+===========
+
+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.
+
+
+
+.. flat-table:: Packed YUV Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ -
+ - :cspan:`7` Byte 1
+
+ -
+ - :cspan:`7` Byte 2
+
+ -
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 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-YUV444`:
+
+ - ``V4L2_PIX_FMT_YUV444``
+
+ - 'Y444'
+
+ -
+ - Cb\ :sub:`3`
+
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - .. _`V4L2-PIX-FMT-YUV555`:
+
+ - ``V4L2_PIX_FMT_YUV555``
+
+ - 'YUVO'
+
+ -
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`4`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - a
+
+ - Y'\ :sub:`4`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - Cb\ :sub:`4`
+
+ - Cb\ :sub:`3`
+
+ - .. _`V4L2-PIX-FMT-YUV565`:
+
+ - ``V4L2_PIX_FMT_YUV565``
+
+ - 'YUVP'
+
+ -
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`4`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - Y'\ :sub:`4`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - Cb\ :sub:`5`
+
+ - Cb\ :sub:`4`
+
+ - Cb\ :sub:`3`
+
+ - .. _`V4L2-PIX-FMT-YUV32`:
+
+ - ``V4L2_PIX_FMT_YUV32``
+
+ - 'YUV4'
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :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`
+
+ -
+ - 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`
+
+
+Bit 7 is the most significant bit. 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>`.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-reserved:
+
+***************************
+Reserved Format Identifiers
+***************************
+
+These formats are not defined by this specification, they are just
+listed for reference and to avoid naming conflicts. If you want to
+register your own format, send an e-mail to the linux-media mailing list
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__
+for inclusion in the ``videodev2.h`` file. If you want to share your
+format with other developers add a link to your documentation and send a
+copy to the linux-media mailing list for inclusion in this section. If
+you think your format should be listed in a standard format section
+please make a proposal on the linux-media mailing list.
+
+
+.. _reserved-formats:
+
+.. flat-table:: Reserved Image Formats
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Details
+
+ - .. _`V4L2-PIX-FMT-DV`:
+
+ - ``V4L2_PIX_FMT_DV``
+
+ - 'dvsd'
+
+ - unknown
+
+ - .. _`V4L2-PIX-FMT-ET61X251`:
+
+ - ``V4L2_PIX_FMT_ET61X251``
+
+ - 'E625'
+
+ - Compressed format of the ET61X251 driver.
+
+ - .. _`V4L2-PIX-FMT-HI240`:
+
+ - ``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,
+ `http://www.ivtvdriver.org/ <http://www.ivtvdriver.org/>`__
+
+ The format is documented in the kernel sources in the file
+ ``Documentation/video4linux/cx2341x/README.hm12``
+
+ - .. _`V4L2-PIX-FMT-CPIA1`:
+
+ - ``V4L2_PIX_FMT_CPIA1``
+
+ - 'CPIA'
+
+ - YUV format used by the gspca cpia1 driver.
+
+ - .. _`V4L2-PIX-FMT-JPGL`:
+
+ - ``V4L2_PIX_FMT_JPGL``
+
+ - 'JPGL'
+
+ - JPEG-Light format (Pegasus Lossless JPEG) used in Divio webcams NW
+ 80x.
+
+ - .. _`V4L2-PIX-FMT-SPCA501`:
+
+ - ``V4L2_PIX_FMT_SPCA501``
+
+ - 'S501'
+
+ - YUYV per line used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-SPCA505`:
+
+ - ``V4L2_PIX_FMT_SPCA505``
+
+ - 'S505'
+
+ - YYUV per line used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-SPCA508`:
+
+ - ``V4L2_PIX_FMT_SPCA508``
+
+ - 'S508'
+
+ - YUVY per line used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-SPCA561`:
+
+ - ``V4L2_PIX_FMT_SPCA561``
+
+ - 'S561'
+
+ - Compressed GBRG Bayer format used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-PAC207`:
+
+ - ``V4L2_PIX_FMT_PAC207``
+
+ - 'P207'
+
+ - Compressed BGGR Bayer format used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-MR97310A`:
+
+ - ``V4L2_PIX_FMT_MR97310A``
+
+ - 'M310'
+
+ - Compressed BGGR Bayer format used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-JL2005BCD`:
+
+ - ``V4L2_PIX_FMT_JL2005BCD``
+
+ - 'JL20'
+
+ - JPEG compressed RGGB Bayer format used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-OV511`:
+
+ - ``V4L2_PIX_FMT_OV511``
+
+ - 'O511'
+
+ - OV511 JPEG format used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-OV518`:
+
+ - ``V4L2_PIX_FMT_OV518``
+
+ - 'O518'
+
+ - OV518 JPEG format used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-PJPG`:
+
+ - ``V4L2_PIX_FMT_PJPG``
+
+ - 'PJPG'
+
+ - Pixart 73xx JPEG format used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-SE401`:
+
+ - ``V4L2_PIX_FMT_SE401``
+
+ - 'S401'
+
+ - Compressed RGB format used by the gspca se401 driver
+
+ - .. _`V4L2-PIX-FMT-SQ905C`:
+
+ - ``V4L2_PIX_FMT_SQ905C``
+
+ - '905C'
+
+ - Compressed RGGB bayer format used by the gspca driver.
+
+ - .. _`V4L2-PIX-FMT-MJPEG`:
+
+ - ``V4L2_PIX_FMT_MJPEG``
+
+ - 'MJPG'
+
+ - Compressed format used by the Zoran driver
+
+ - .. _`V4L2-PIX-FMT-PWC1`:
+
+ - ``V4L2_PIX_FMT_PWC1``
+
+ - 'PWC1'
+
+ - Compressed format of the PWC driver.
+
+ - .. _`V4L2-PIX-FMT-PWC2`:
+
+ - ``V4L2_PIX_FMT_PWC2``
+
+ - 'PWC2'
+
+ - Compressed format of the PWC driver.
+
+ - .. _`V4L2-PIX-FMT-SN9C10X`:
+
+ - ``V4L2_PIX_FMT_SN9C10X``
+
+ - 'S910'
+
+ - Compressed format of the SN9C102 driver.
+
+ - .. _`V4L2-PIX-FMT-SN9C20X-I420`:
+
+ - ``V4L2_PIX_FMT_SN9C20X_I420``
+
+ - 'S920'
+
+ - YUV 4:2:0 format of the gspca sn9c20x driver.
+
+ - .. _`V4L2-PIX-FMT-SN9C2028`:
+
+ - ``V4L2_PIX_FMT_SN9C2028``
+
+ - 'SONX'
+
+ - Compressed GBRG bayer format of the gspca sn9c2028 driver.
+
+ - .. _`V4L2-PIX-FMT-STV0680`:
+
+ - ``V4L2_PIX_FMT_STV0680``
+
+ - 'S680'
+
+ - Bayer format of the gspca stv0680 driver.
+
+ - .. _`V4L2-PIX-FMT-WNVA`:
+
+ - ``V4L2_PIX_FMT_WNVA``
+
+ - 'WNVA'
+
+ - Used by the Winnov Videum driver,
+ `http://www.thedirks.org/winnov/ <http://www.thedirks.org/winnov/>`__
+
+ - .. _`V4L2-PIX-FMT-TM6000`:
+
+ - ``V4L2_PIX_FMT_TM6000``
+
+ - 'TM60'
+
+ - Used by Trident tm6000
+
+ - .. _`V4L2-PIX-FMT-CIT-YYVYUY`:
+
+ - ``V4L2_PIX_FMT_CIT_YYVYUY``
+
+ - 'CITV'
+
+ - Used by xirlink CIT, found at IBM webcams.
+
+ Uses one line of Y then 1 line of VYUY
+
+ - .. _`V4L2-PIX-FMT-KONICA420`:
+
+ - ``V4L2_PIX_FMT_KONICA420``
+
+ - 'KONI'
+
+ - Used by Konica webcams.
+
+ YUV420 planar in blocks of 256 pixels.
+
+ - .. _`V4L2-PIX-FMT-YYUV`:
+
+ - ``V4L2_PIX_FMT_YYUV``
+
+ - 'YYUV'
+
+ - unknown
+
+ - .. _`V4L2-PIX-FMT-Y4`:
+
+ - ``V4L2_PIX_FMT_Y4``
+
+ - 'Y04 '
+
+ - Old 4-bit greyscale format. Only the most significant 4 bits of
+ each byte are used, the other bits are set to 0.
+
+ - .. _`V4L2-PIX-FMT-Y6`:
+
+ - ``V4L2_PIX_FMT_Y6``
+
+ - 'Y06 '
+
+ - Old 6-bit greyscale format. Only the most significant 6 bits of
+ each byte are used, the other bits are set to 0.
+
+ - .. _`V4L2-PIX-FMT-S5C-UYVY-JPG`:
+
+ - ``V4L2_PIX_FMT_S5C_UYVY_JPG``
+
+ - 'S5CI'
+
+ - Two-planar format used by Samsung S5C73MX cameras. The first plane
+ contains interleaved JPEG and UYVY image data, followed by meta
+ data in form of an array of offsets to the UYVY data blocks. The
+ actual pointer array follows immediately the interleaved JPEG/UYVY
+ data, the number of entries in this array equals the height of the
+ UYVY image. Each entry is a 4-byte unsigned integer in big endian
+ order and it's an offset to a single pixel line of the UYVY image.
+ The first plane can start either with JPEG or UYVY data chunk. The
+ size of a single UYVY block equals the UYVY image's width
+ multiplied by 2. The size of a JPEG chunk depends on the image and
+ can vary with each line.
+
+ The second plane, at an offset of 4084 bytes, contains a 4-byte
+ offset to the pointer array in the first plane. This offset is
+ followed by a 4-byte value indicating size of the pointer array.
+ All numbers in the second plane are also in big endian order.
+ Remaining data in the second plane is undefined. The information
+ in the second plane allows to easily find location of the pointer
+ array, which can be different for each frame. The size of the
+ pointer array is constant for given UYVY image height.
+
+ In order to extract UYVY and JPEG frames an application can
+ initially set a data pointer to the start of first plane and then
+ add an offset from the first entry of the pointers table. Such a
+ pointer indicates start of an UYVY image pixel line. Whole UYVY
+ line can be copied to a separate buffer. These steps should be
+ repeated for each line, i.e. the number of entries in the pointer
+ array. Anything what's in between the UYVY lines is JPEG data and
+ should be concatenated to form the JPEG stream.
+
+
+
+.. _format-flags:
+
+.. flat-table:: Format Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``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)
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-rgb:
+
+***********
+RGB Formats
+***********
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-packed-rgb
+ pixfmt-sbggr8
+ pixfmt-sgbrg8
+ pixfmt-sgrbg8
+ pixfmt-srggb8
+ pixfmt-sbggr16
+ pixfmt-srggb10
+ pixfmt-srggb10p
+ pixfmt-srggb10alaw8
+ pixfmt-srggb10dpcm8
+ pixfmt-srggb12
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR16:
+
+*****************************
+V4L2_PIX_FMT_SBGGR16 ('BYR2')
+*****************************
+
+*man V4L2_PIX_FMT_SBGGR16(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This format is similar to
+:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`, except each pixel
+has a depth of 16 bits. The least significant byte is stored at lower
+memory addresses (little-endian). Note the actual sampling precision may
+be lower than 16 bits, for example 10 bits per pixel with values in
+range 0 to 1023.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR8:
+
+****************************
+V4L2_PIX_FMT_SBGGR8 ('BA81')
+****************************
+
+*man V4L2_PIX_FMT_SBGGR8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+blue and green value, the second row of a green and red value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00`
+
+ - G\ :sub:`01`
+
+ - B\ :sub:`02`
+
+ - G\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - G\ :sub:`10`
+
+ - R\ :sub:`11`
+
+ - G\ :sub:`12`
+
+ - R\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - B\ :sub:`20`
+
+ - G\ :sub:`21`
+
+ - B\ :sub:`22`
+
+ - G\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - G\ :sub:`30`
+
+ - R\ :sub:`31`
+
+ - G\ :sub:`32`
+
+ - R\ :sub:`33`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-CS08:
+
+*************************
+V4L2_SDR_FMT_CS8 ('CS08')
+*************************
+
+*man V4L2_SDR_FMT_CS8(2)*
+
+Complex signed 8-bit IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 8 bit signed number. I value comes first and
+Q value after that.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0`
+
+ - .. row 2
+
+ - start + 1:
+
+ - Q'\ :sub:`0`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-CS14LE:
+
+****************************
+V4L2_SDR_FMT_CS14LE ('CS14')
+****************************
+
+*man V4L2_SDR_FMT_CS14LE(2)*
+
+Complex signed 14-bit little endian IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 14 bit signed little endian number. I value
+comes first and Q value after that. 14 bit value is stored in 16 bit
+space with unused high bits padded with 0.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[13:8]`
+
+ - .. row 2
+
+ - start + 2:
+
+ - Q'\ :sub:`0[7:0]`
+
+ - Q'\ :sub:`0[13:8]`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-CU08:
+
+*************************
+V4L2_SDR_FMT_CU8 ('CU08')
+*************************
+
+*man V4L2_SDR_FMT_CU8(2)*
+
+Complex unsigned 8-bit IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 8 bit unsigned number. I value comes first
+and Q value after that.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0`
+
+ - .. row 2
+
+ - start + 1:
+
+ - Q'\ :sub:`0`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-CU16LE:
+
+****************************
+V4L2_SDR_FMT_CU16LE ('CU16')
+****************************
+
+*man V4L2_SDR_FMT_CU16LE(2)*
+
+Complex unsigned 16-bit little endian IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 16 bit unsigned little endian number. I value
+comes first and Q value after that.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[15:8]`
+
+ - .. row 2
+
+ - start + 2:
+
+ - Q'\ :sub:`0[7:0]`
+
+ - Q'\ :sub:`0[15:8]`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-RU12LE:
+
+****************************
+V4L2_SDR_FMT_RU12LE ('RU12')
+****************************
+
+*man V4L2_SDR_FMT_RU12LE(2)*
+
+Real unsigned 12-bit little endian sample
+
+
+Description
+===========
+
+This format contains sequence of real number samples. Each sample is
+represented as a 12 bit unsigned little endian number. Sample is stored
+in 16 bit space with unused high bits padded with 0.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[11:8]`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SGBRG8:
+
+****************************
+V4L2_PIX_FMT_SGBRG8 ('GBRG')
+****************************
+
+*man V4L2_PIX_FMT_SGBRG8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+green and blue value, the second row of a red and green value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - G\ :sub:`00`
+
+ - B\ :sub:`01`
+
+ - G\ :sub:`02`
+
+ - B\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - R\ :sub:`10`
+
+ - G\ :sub:`11`
+
+ - R\ :sub:`12`
+
+ - G\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - G\ :sub:`20`
+
+ - B\ :sub:`21`
+
+ - G\ :sub:`22`
+
+ - B\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - R\ :sub:`30`
+
+ - G\ :sub:`31`
+
+ - R\ :sub:`32`
+
+ - G\ :sub:`33`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SGRBG8:
+
+****************************
+V4L2_PIX_FMT_SGRBG8 ('GRBG')
+****************************
+
+*man V4L2_PIX_FMT_SGRBG8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+green and blue value, the second row of a red and green value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - G\ :sub:`00`
+
+ - R\ :sub:`01`
+
+ - G\ :sub:`02`
+
+ - R\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - B\ :sub:`10`
+
+ - G\ :sub:`11`
+
+ - B\ :sub:`12`
+
+ - G\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - G\ :sub:`20`
+
+ - R\ :sub:`21`
+
+ - G\ :sub:`22`
+
+ - R\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - B\ :sub:`30`
+
+ - G\ :sub:`31`
+
+ - B\ :sub:`32`
+
+ - G\ :sub:`33`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB10:
+
+***************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB10 ('RG10'), V4L2_PIX_FMT_SGRBG10 ('BA10'), V4L2_PIX_FMT_SGBRG10 ('GB10'), V4L2_PIX_FMT_SBGGR10 ('BG10'),
+***************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB10(2)*
+
+V4L2_PIX_FMT_SGRBG10
+V4L2_PIX_FMT_SGBRG10
+V4L2_PIX_FMT_SBGGR10
+10-bit Bayer formats expanded to 16 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+colour. Each colour component is stored in a 16-bit word, with 6 unused
+high bits filled with zeros. Each n-pixel row contains n/2 green samples
+and n/2 blue or red samples, with alternating red and blue rows. Bytes
+are stored in memory in little endian order. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats
+
+**Byte Order..**
+
+Each cell is one byte, high 6 bits in high bytes are 0.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR10ALAW8:
+
+***********************************************************************************************************************************************
+V4L2_PIX_FMT_SBGGR10ALAW8 ('aBA8'), V4L2_PIX_FMT_SGBRG10ALAW8 ('aGA8'), V4L2_PIX_FMT_SGRBG10ALAW8 ('agA8'), V4L2_PIX_FMT_SRGGB10ALAW8 ('aRA8'),
+***********************************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SBGGR10ALAW8(2)*
+
+V4L2_PIX_FMT_SGBRG10ALAW8
+V4L2_PIX_FMT_SGRBG10ALAW8
+V4L2_PIX_FMT_SRGGB10ALAW8
+10-bit Bayer formats compressed to 8 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+color compressed to 8 bits each, using the A-LAW algorithm. Each color
+component consumes 8 bits of memory. In other respects this format is
+similar to :ref:`V4L2-PIX-FMT-SRGGB8`.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR10DPCM8:
+
+***********************************************************************************************************************************************
+V4L2_PIX_FMT_SBGGR10DPCM8 ('bBA8'), V4L2_PIX_FMT_SGBRG10DPCM8 ('bGA8'), V4L2_PIX_FMT_SGRBG10DPCM8 ('BD10'), V4L2_PIX_FMT_SRGGB10DPCM8 ('bRA8'),
+***********************************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SBGGR10DPCM8(2)*
+
+V4L2_PIX_FMT_SGBRG10DPCM8
+V4L2_PIX_FMT_SGRBG10DPCM8
+V4L2_PIX_FMT_SRGGB10DPCM8
+10-bit Bayer formats compressed to 8 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+colour compressed to 8 bits each, using DPCM compression. DPCM,
+differential pulse-code modulation, is lossy. Each colour component
+consumes 8 bits of memory. In other respects this format is similar to
+:ref:`pixfmt-srggb10`.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB10P:
+
+*******************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB10P ('pRAA'), V4L2_PIX_FMT_SGRBG10P ('pgAA'), V4L2_PIX_FMT_SGBRG10P ('pGAA'), V4L2_PIX_FMT_SBGGR10P ('pBAA'),
+*******************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB10P(2)*
+
+V4L2_PIX_FMT_SGRBG10P
+V4L2_PIX_FMT_SGBRG10P
+V4L2_PIX_FMT_SBGGR10P
+10-bit packed Bayer formats
+
+
+Description
+===========
+
+These four pixel formats are packed raw sRGB / Bayer formats with 10
+bits per colour. Every four consecutive colour components are packed
+into 5 bytes. Each of the first 4 bytes contain the 8 high order bits of
+the pixels, and the fifth byte contains the two least significants bits
+of each pixel, in the same order.
+
+Each n-pixel row contains n/2 green samples and n/2 blue or red samples,
+with alternating green-red and green-blue rows. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats:
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03high`
+
+ - B\ :sub:`00low`\ (bits 7--6) G\ :sub:`01low`\ (bits 5--4)
+ B\ :sub:`02low`\ (bits 3--2) G\ :sub:`03low`\ (bits 1--0)
+
+ - .. row 2
+
+ - start + 5:
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13high`
+
+ - G\ :sub:`10low`\ (bits 7--6) R\ :sub:`11low`\ (bits 5--4)
+ G\ :sub:`12low`\ (bits 3--2) R\ :sub:`13low`\ (bits 1--0)
+
+ - .. row 3
+
+ - start + 10:
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23high`
+
+ - B\ :sub:`20low`\ (bits 7--6) G\ :sub:`21low`\ (bits 5--4)
+ B\ :sub:`22low`\ (bits 3--2) G\ :sub:`23low`\ (bits 1--0)
+
+ - .. row 4
+
+ - start + 15:
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33high`
+
+ - G\ :sub:`30low`\ (bits 7--6) R\ :sub:`31low`\ (bits 5--4)
+ G\ :sub:`32low`\ (bits 3--2) R\ :sub:`33low`\ (bits 1--0)
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB12:
+
+***************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB12 ('RG12'), V4L2_PIX_FMT_SGRBG12 ('BA12'), V4L2_PIX_FMT_SGBRG12 ('GB12'), V4L2_PIX_FMT_SBGGR12 ('BG12'),
+***************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB12(2)*
+
+V4L2_PIX_FMT_SGRBG12
+V4L2_PIX_FMT_SGBRG12
+V4L2_PIX_FMT_SBGGR12
+12-bit Bayer formats expanded to 16 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 12 bits per
+colour. Each colour component is stored in a 16-bit word, with 4 unused
+high bits filled with zeros. Each n-pixel row contains n/2 green samples
+and n/2 blue or red samples, with alternating red and blue rows. Bytes
+are stored in memory in little endian order. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats
+
+**Byte Order..**
+
+Each cell is one byte, high 6 bits in high bytes are 0.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB8:
+
+****************************
+V4L2_PIX_FMT_SRGGB8 ('RGGB')
+****************************
+
+*man V4L2_PIX_FMT_SRGGB8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+red and green value, the second row of a green and blue value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - R\ :sub:`00`
+
+ - G\ :sub:`01`
+
+ - R\ :sub:`02`
+
+ - G\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - G\ :sub:`10`
+
+ - B\ :sub:`11`
+
+ - G\ :sub:`12`
+
+ - B\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - R\ :sub:`20`
+
+ - G\ :sub:`21`
+
+ - R\ :sub:`22`
+
+ - G\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - G\ :sub:`30`
+
+ - B\ :sub:`31`
+
+ - G\ :sub:`32`
+
+ - B\ :sub:`33`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-UV8:
+
+************************
+V4L2_PIX_FMT_UV8 ('UV8')
+************************
+
+*man V4L2_PIX_FMT_UV8(2)*
+
+UV plane interleaved
+
+
+Description
+===========
+
+In this format there is no Y plane, Only CbCr plane. ie (UV interleaved)
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - Cr\ :sub:`31`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-UYVY:
+
+**************************
+V4L2_PIX_FMT_UYVY ('UYVY')
+**************************
+
+*man V4L2_PIX_FMT_UYVY(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-VYUY:
+
+**************************
+V4L2_PIX_FMT_VYUY ('VYUY')
+**************************
+
+*man V4L2_PIX_FMT_VYUY(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y10:
+
+*************************
+V4L2_PIX_FMT_Y10 ('Y10 ')
+*************************
+
+*man V4L2_PIX_FMT_Y10(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y10BPACK:
+
+******************************
+V4L2_PIX_FMT_Y10BPACK ('Y10B')
+******************************
+
+*man V4L2_PIX_FMT_Y10BPACK(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - 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]`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y12:
+
+*************************
+V4L2_PIX_FMT_Y12 ('Y12 ')
+*************************
+
+*man V4L2_PIX_FMT_Y12(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y12I:
+
+**************************
+V4L2_PIX_FMT_Y12I ('Y12I')
+**************************
+
+*man V4L2_PIX_FMT_Y12I(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 12 bits per pixel, but with
+pixels from 2 sources interleaved and bit-packed. Each pixel is stored
+in a 24-bit word in the little-endian order. On a little-endian machine
+these pixels can be deinterlaced using
+
+
+.. code-block:: c
+
+ __u8 *buf;
+ left0 = 0xfff & *(__u16 *)buf;
+ right0 = *(__u16 *)(buf + 1) >> 4;
+
+**Bit-packed representation.**
+
+pixels cross the byte boundary and have a ratio of 3 bytes for each
+interleaved pixel.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - Y'\ :sub:`0left[7:0]`
+
+ - Y'\ :sub:`0right[3:0]`\ Y'\ :sub:`0left[11:8]`
+
+ - Y'\ :sub:`0right[11:4]`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y16-BE:
+
+****************************************
+V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31))
+****************************************
+
+*man V4L2_PIX_FMT_Y16_BE(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y16:
+
+*************************
+V4L2_PIX_FMT_Y16 ('Y16 ')
+*************************
+
+*man V4L2_PIX_FMT_Y16(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y41P:
+
+**************************
+V4L2_PIX_FMT_Y41P ('Y41P')
+**************************
+
+*man V4L2_PIX_FMT_Y41P(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ -
+ - 4
+
+ -
+ - 5
+
+ -
+ - 6
+
+ -
+ - 7
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y8I:
+
+*************************
+V4L2_PIX_FMT_Y8I ('Y8I ')
+*************************
+
+*man V4L2_PIX_FMT_Y8I(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 8 bits per pixel, but with
+pixels from 2 sources interleaved. Each pixel is stored in a 16-bit
+word. E.g. the R200 RealSense camera stores pixel from the left sensor
+in lower and from the right sensor in the higher 8 bits.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00left`
+
+ - Y'\ :sub:`00right`
+
+ - Y'\ :sub:`01left`
+
+ - Y'\ :sub:`01right`
+
+ - Y'\ :sub:`02left`
+
+ - Y'\ :sub:`02right`
+
+ - Y'\ :sub:`03left`
+
+ - Y'\ :sub:`03right`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10left`
+
+ - Y'\ :sub:`10right`
+
+ - Y'\ :sub:`11left`
+
+ - Y'\ :sub:`11right`
+
+ - Y'\ :sub:`12left`
+
+ - Y'\ :sub:`12right`
+
+ - Y'\ :sub:`13left`
+
+ - Y'\ :sub:`13right`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20left`
+
+ - Y'\ :sub:`20right`
+
+ - Y'\ :sub:`21left`
+
+ - Y'\ :sub:`21right`
+
+ - Y'\ :sub:`22left`
+
+ - Y'\ :sub:`22right`
+
+ - Y'\ :sub:`23left`
+
+ - Y'\ :sub:`23right`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30left`
+
+ - Y'\ :sub:`30right`
+
+ - Y'\ :sub:`31left`
+
+ - Y'\ :sub:`31right`
+
+ - Y'\ :sub:`32left`
+
+ - Y'\ :sub:`32right`
+
+ - Y'\ :sub:`33left`
+
+ - Y'\ :sub:`33right`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVU410:
+
+**********************************************************
+V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')
+**********************************************************
+
+*man V4L2_PIX_FMT_YVU410(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cr\ :sub:`00`
+
+ - .. row 6
+
+ - start + 17:
+
+ - Cb\ :sub:`00`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ -
+ -
+ - C
+
+ -
+ -
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV411P:
+
+*****************************
+V4L2_PIX_FMT_YUV411P ('411P')
+*****************************
+
+*man V4L2_PIX_FMT_YUV411P(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - .. row 6
+
+ - start + 17:
+
+ - Cb\ :sub:`10`
+
+ - .. row 7
+
+ - start + 18:
+
+ - Cb\ :sub:`20`
+
+ - .. row 8
+
+ - start + 19:
+
+ - Cb\ :sub:`30`
+
+ - .. row 9
+
+ - start + 20:
+
+ - Cr\ :sub:`00`
+
+ - .. row 10
+
+ - start + 21:
+
+ - Cr\ :sub:`10`
+
+ - .. row 11
+
+ - start + 22:
+
+ - Cr\ :sub:`20`
+
+ - .. row 12
+
+ - start + 23:
+
+ - Cr\ :sub:`30`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVU420:
+
+**********************************************************
+V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')
+**********************************************************
+
+*man V4L2_PIX_FMT_YVU420(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - start + 18:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 7
+
+ - start + 20:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 8
+
+ - start + 22:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV420M:
+
+************************************************************
+V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV420M(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 7
+
+ - start1 + 2:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 8
+
+ -
+
+ - .. row 9
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 10
+
+ - start2 + 2:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV422M:
+
+************************************************************
+V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV422M(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 7
+
+ - start1 + 2:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 8
+
+ - start1 + 4:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - .. row 9
+
+ - start1 + 6:
+
+ - Cb\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 12
+
+ - start2 + 2:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 13
+
+ - start2 + 4:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - .. row 14
+
+ - start2 + 6:
+
+ - Cr\ :sub:`30`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV422P:
+
+*****************************
+V4L2_PIX_FMT_YUV422P ('422P')
+*****************************
+
+*man V4L2_PIX_FMT_YUV422P(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 6
+
+ - start + 18:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 7
+
+ - start + 20:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - .. row 8
+
+ - start + 22:
+
+ - Cb\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - .. row 9
+
+ - start + 24:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 10
+
+ - start + 26:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 11
+
+ - start + 28:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - .. row 12
+
+ - start + 30:
+
+ - Cr\ :sub:`30`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV444M:
+
+************************************************************
+V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV444M(2)*
+
+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
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cb\ :sub:`02`
+
+ - Cb\ :sub:`03`
+
+ - .. row 7
+
+ - start1 + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cb\ :sub:`12`
+
+ - Cb\ :sub:`13`
+
+ - .. row 8
+
+ - start1 + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cb\ :sub:`22`
+
+ - Cb\ :sub:`23`
+
+ - .. row 9
+
+ - start1 + 12:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cb\ :sub:`32`
+
+ - Cb\ :sub:`33`
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - Cr\ :sub:`02`
+
+ - Cr\ :sub:`03`
+
+ - .. row 12
+
+ - start2 + 4:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - Cr\ :sub:`12`
+
+ - Cr\ :sub:`13`
+
+ - .. row 13
+
+ - start2 + 8:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - Cr\ :sub:`22`
+
+ - Cr\ :sub:`23`
+
+ - .. row 14
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - YC
+
+ -
+ - YC
+
+ -
+ - YC
+
+ -
+ - YC
+
+ - .. row 3
+
+ - 1
+
+ - YC
+
+ -
+ - YC
+
+ -
+ - YC
+
+ -
+ - YC
+
+ - .. row 4
+
+ - 2
+
+ - YC
+
+ -
+ - YC
+
+ -
+ - YC
+
+ -
+ - YC
+
+ - .. row 5
+
+ - 3
+
+ - YC
+
+ -
+ - YC
+
+ -
+ - YC
+
+ -
+ - YC
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUYV:
+
+**************************
+V4L2_PIX_FMT_YUYV ('YUYV')
+**************************
+
+*man V4L2_PIX_FMT_YUYV(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVYU:
+
+**************************
+V4L2_PIX_FMT_YVYU ('YVYU')
+**************************
+
+*man V4L2_PIX_FMT_YVYU(2)*
+
+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
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - 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`
+
+ - .. row 2
+
+ - 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`
+
+ - .. row 3
+
+ - 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`
+
+ - .. row 4
+
+ - 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
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Z16:
+
+*************************
+V4L2_PIX_FMT_Z16 ('Z16 ')
+*************************
+
+*man V4L2_PIX_FMT_Z16(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a 16-bit format, representing depth data. Each pixel is a
+distance to the respective point in the image coordinates. Distance unit
+can vary and has to be negotiated with the device separately. Each pixel
+is stored in a 16-bit word in the little endian byte order.
+
+**Byte Order..**
+
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Z\ :sub:`00low`
+
+ - Z\ :sub:`00high`
+
+ - Z\ :sub:`01low`
+
+ - Z\ :sub:`01high`
+
+ - Z\ :sub:`02low`
+
+ - Z\ :sub:`02high`
+
+ - Z\ :sub:`03low`
+
+ - Z\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Z\ :sub:`10low`
+
+ - Z\ :sub:`10high`
+
+ - Z\ :sub:`11low`
+
+ - Z\ :sub:`11high`
+
+ - Z\ :sub:`12low`
+
+ - Z\ :sub:`12high`
+
+ - Z\ :sub:`13low`
+
+ - Z\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Z\ :sub:`20low`
+
+ - Z\ :sub:`20high`
+
+ - Z\ :sub:`21low`
+
+ - Z\ :sub:`21high`
+
+ - Z\ :sub:`22low`
+
+ - Z\ :sub:`22high`
+
+ - Z\ :sub:`23low`
+
+ - Z\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Z\ :sub:`30low`
+
+ - Z\ :sub:`30high`
+
+ - Z\ :sub:`31low`
+
+ - Z\ :sub:`31high`
+
+ - Z\ :sub:`32low`
+
+ - Z\ :sub:`32high`
+
+ - Z\ :sub:`33low`
+
+ - Z\ :sub:`33high`
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt:
+
+#############
+Image Formats
+#############
+The V4L2 API was primarily designed for devices exchanging image data
+with applications. The :c:type:`struct v4l2_pix_format` and
+:c:type:`struct v4l2_pix_format_mplane` structures define the
+format and layout of an image in memory. The former is used with the
+single-planar API, while the latter is used with the multi-planar
+version (see :ref:`planar-apis`). Image formats are negotiated with
+the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl. (The explanations here
+focus on video capturing and output, for overlay frame buffer formats
+see also :ref:`VIDIOC_G_FBUF <vidioc-g-fbuf>`.)
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-002
+ pixfmt-003
+ pixfmt-004
+ colorspaces
+ pixfmt-006
+ pixfmt-007
+ pixfmt-008
+ pixfmt-indexed
+ pixfmt-rgb
+ yuv-formats
+ depth-formats
+ pixfmt-013
+ sdr-formats
+ pixfmt-reserved
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _planar-apis:
+
+*****************************
+Single- and multi-planar APIs
+*****************************
+
+Some devices require data for each input or output video frame to be
+placed in discontiguous memory buffers. In such cases, one video frame
+has to be addressed using more than one memory address, i.e. one pointer
+per "plane". A plane is a sub-buffer of the current frame. For examples
+of such formats see :ref:`pixfmt`.
+
+Initially, V4L2 API did not support multi-planar buffers and a set of
+extensions has been introduced to handle them. Those extensions
+constitute what is being referred to as the "multi-planar API".
+
+Some of the V4L2 API calls and structures are interpreted differently,
+depending on whether single- or multi-planar API is being used. An
+application can choose whether to use one or the other by passing a
+corresponding buffer type to its ioctl calls. Multi-planar versions of
+buffer types are suffixed with an `_MPLANE' string. For a list of
+available multi-planar buffer types see enum
+:ref:`v4l2_buf_type <v4l2-buf-type>`.
+
+
+Multi-planar formats
+====================
+
+Multi-planar API introduces new multi-planar formats. Those formats use
+a separate set of FourCC codes. It is important to distinguish between
+the multi-planar API and a multi-planar format. Multi-planar API calls
+can handle all single-planar formats as well (as long as they are passed
+in multi-planar API structures), while the single-planar API cannot
+handle multi-planar formats.
+
+
+Calls that distinguish between single and multi-planar APIs
+===========================================================
+
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>`
+ Two additional multi-planar capabilities are added. They can be set
+ together with non-multi-planar ones for devices that handle both
+ single- and multi-planar formats.
+
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>`,
+:ref:`VIDIOC_S_FMT <vidioc-g-fmt>`,
+:ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>`
+ New structures for describing multi-planar formats are added: struct
+ :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and
+ struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`.
+ Drivers may define new multi-planar formats, which have distinct
+ FourCC codes from the existing single-planar ones.
+
+:ref:`VIDIOC_QBUF <vidioc-qbuf>`,
+:ref:`VIDIOC_DQBUF <vidioc-qbuf>`,
+:ref:`VIDIOC_QUERYBUF <vidioc-querybuf>`
+ A new struct :ref:`v4l2_plane <v4l2-plane>` structure for
+ describing planes is added. Arrays of this structure are passed in
+ the new ``m.planes`` field of struct
+ :ref:`v4l2_buffer <v4l2-buffer>`.
+
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>`
+ Will allocate multi-planar buffers as requested.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _querycap:
+
+*********************
+Querying Capabilities
+*********************
+
+Because V4L2 covers a wide variety of devices not all aspects of the API
+are equally applicable to all types of devices. Furthermore devices of
+the same type have different capabilities and this specification permits
+the omission of a few complicated and less important parts of the API.
+
+The :ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl is available to
+check if the kernel device is compatible with this specification, and to
+query the :ref:`functions <devices>` and :ref:`I/O methods <io>`
+supported by the device.
+
+Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the V4L2
+API version used by the driver, with generally matches the Kernel
+version. There's no need of using
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` to check if a specific ioctl
+is supported, the V4L2 core now returns ENOTTY if a driver doesn't
+provide support for an ioctl.
+
+Other features can be queried by calling the respective ioctl, for
+example :ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` to learn about the
+number, types and names of video connectors on the device. Although
+abstraction is a major objective of this API, the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl also allows driver
+specific applications to reliably identify the driver.
+
+All V4L2 drivers must support ``VIDIOC_QUERYCAP``. Applications should
+always call this ioctl after opening the device.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _remotes:
+
+#####################
+Remote Controller API
+#####################
+
+.. _remote_controllers:
+
+******************
+Remote Controllers
+******************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ Remote_controllers_Intro
+ remote_controllers_sysfs_nodes
+ Remote_controllers_tables
+ Remote_controllers_table_change
+ lirc_device_interface
+
+
+**********************
+Revision and Copyright
+**********************
+
+
+:author: Chehab Mauro (*Carvalho*)
+:address: m.chehab@samsung.com
+:contrib: Initial version.
+
+**Copyright** 2009-2014 : Mauro Carvalho Chehab
+
+:revision: 3.15 / 2014-02-06 (*mcc*)
+
+Added the interface description and the RC sysfs class description.
+
+
+:revision: 1.0 / 2009-09-06 (*mcc*)
+
+Initial revision
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _remote_controllers_sysfs_nodes:
+
+*******************************
+Remote Controller's sysfs nodes
+*******************************
+
+As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are
+the sysfs nodes that control the Remote Controllers:
+
+
+.. _sys_class_rc:
+
+/sys/class/rc/
+==============
+
+The ``/sys/class/rc/`` class sub-directory belongs to the Remote
+Controller core and provides a sysfs interface for configuring infrared
+remote controller receivers.
+
+
+.. _sys_class_rc_rcN:
+
+/sys/class/rc/rcN/
+==================
+
+A ``/sys/class/rc/rcN`` directory is created for each remote control
+receiver device where N is the number of the receiver.
+
+
+.. _sys_class_rc_rcN_protocols:
+
+/sys/class/rc/rcN/protocols
+===========================
+
+Reading this file returns a list of available protocols, something like:
+
+``rc5 [rc6] nec jvc [sony]``
+
+Enabled protocols are shown in [] brackets.
+
+Writing "+proto" will add a protocol to the list of enabled protocols.
+
+Writing "-proto" will remove a protocol from the list of enabled
+protocols.
+
+Writing "proto" will enable only "proto".
+
+Writing "none" will disable all protocols.
+
+Write fails with EINVAL if an invalid protocol combination or unknown
+protocol name is used.
+
+
+.. _sys_class_rc_rcN_filter:
+
+/sys/class/rc/rcN/filter
+========================
+
+Sets the scancode filter expected value.
+
+Use in combination with ``/sys/class/rc/rcN/filter_mask`` to set the
+expected value of the bits set in the filter mask. If the hardware
+supports it then scancodes which do not match the filter will be
+ignored. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the current protocol is altered.
+
+
+.. _sys_class_rc_rcN_filter_mask:
+
+/sys/class/rc/rcN/filter_mask
+=============================
+
+Sets the scancode filter mask of bits to compare. Use in combination
+with ``/sys/class/rc/rcN/filter`` to set the bits of the scancode which
+should be compared against the expected value. A value of 0 disables the
+filter to allow all valid scancodes to be processed.
+
+If the hardware supports it then scancodes which do not match the filter
+will be ignored. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the current protocol is altered.
+
+
+.. _sys_class_rc_rcN_wakeup_protocols:
+
+/sys/class/rc/rcN/wakeup_protocols
+==================================
+
+Reading this file returns a list of available protocols to use for the
+wakeup filter, something like:
+
+``rc5 rc6 nec jvc [sony]``
+
+The enabled wakeup protocol is shown in [] brackets.
+
+Writing "+proto" will add a protocol to the list of enabled wakeup
+protocols.
+
+Writing "-proto" will remove a protocol from the list of enabled wakeup
+protocols.
+
+Writing "proto" will use "proto" for wakeup events.
+
+Writing "none" will disable wakeup.
+
+Write fails with EINVAL if an invalid protocol combination or unknown
+protocol name is used, or if wakeup is not supported by the hardware.
+
+
+.. _sys_class_rc_rcN_wakeup_filter:
+
+/sys/class/rc/rcN/wakeup_filter
+===============================
+
+Sets the scancode wakeup filter expected value. Use in combination with
+``/sys/class/rc/rcN/wakeup_filter_mask`` to set the expected value of
+the bits set in the wakeup filter mask to trigger a system wake event.
+
+If the hardware supports it and wakeup_filter_mask is not 0 then
+scancodes which match the filter will wake the system from e.g. suspend
+to RAM or power off. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the wakeup protocol is altered.
+
+
+.. _sys_class_rc_rcN_wakeup_filter_mask:
+
+/sys/class/rc/rcN/wakeup_filter_mask
+====================================
+
+Sets the scancode wakeup filter mask of bits to compare. Use in
+combination with ``/sys/class/rc/rcN/wakeup_filter`` to set the bits of
+the scancode which should be compared against the expected value to
+trigger a system wake event.
+
+If the hardware supports it and wakeup_filter_mask is not 0 then
+scancodes which match the filter will wake the system from e.g. suspend
+to RAM or power off. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the wakeup protocol is altered.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _rw:
+
+**********
+Read/Write
+**********
+
+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
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl is set.
+
+Drivers may need the CPU to copy the data, but they may also support DMA
+to or from user memory, so this I/O method is not necessarily less
+efficient than other methods merely exchanging buffer pointers. It is
+considered inferior though because no meta-information like frame
+counters or timestamps are passed. This information is necessary to
+recognize frame dropping and to synchronize with other data streams.
+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):
+
+
+
+::
+
+ > 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
+must implement one I/O method if they exchange data with applications,
+but it need not be this. [1]_ When reading or writing is supported, the
+driver must also support the :ref:`select() <func-select>` and
+:ref:`poll() <func-poll>` function. [2]_
+
+.. [1]
+ It would be desirable if applications could depend on drivers
+ supporting all I/O interfaces, but as much as the complex memory
+ mapping I/O can be inadequate for some devices we have no reason to
+ require this interface, which is most useful for simple applications
+ capturing still images.
+
+.. [2]
+ At the driver level :c:func:`select()` and :c:func:`poll()` are
+ the same, and :c:func:`select()` is too important to be optional.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sdr-formats:
+
+***********
+SDR Formats
+***********
+
+These formats are used for :ref:`SDR <sdr>` interface only.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-sdr-cu08
+ pixfmt-sdr-cu16le
+ pixfmt-sdr-cs08
+ pixfmt-sdr-cs14le
+ pixfmt-sdr-ru12le
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+************
+Introduction
+************
+
+Some video capture devices can sample a subsection of a picture and
+shrink or enlarge it to an image of arbitrary size. Next, the devices
+can insert the image into larger one. Some video output devices can crop
+part of an input image, scale it up or down and insert it at an
+arbitrary scan line and horizontal offset into a video signal. We call
+these abilities cropping, scaling and composing.
+
+On a video *capture* device the source is a video signal, and the
+cropping target determine the area actually sampled. The sink is an
+image stored in a memory buffer. The composing area specifies which part
+of the buffer is actually written to by the hardware.
+
+On a video *output* device the source is an image in a memory buffer,
+and the cropping target is a part of an image to be shown on a display.
+The sink is the display or the graphics screen. The application may
+select the part of display where the image should be displayed. The size
+and position of such a window is controlled by the compose target.
+
+Rectangles for all cropping and composing targets are defined even if
+the device does supports neither cropping nor composing. Their size and
+position will be fixed in such a case. If the device does not support
+scaling then the cropping and composing rectangles have the same size.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+*****************
+Selection targets
+*****************
+
+
+.. _sel-targets-capture:
+
+.. figure:: selection-api-003_files/selection.*
+ :alt: selection.png
+ :align: center
+
+ Cropping and composing targets
+
+ Targets used by a cropping, composing and scaling process
+
+
+
+See :ref:`v4l2-selection-targets` for more information.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+*************
+Configuration
+*************
+
+Applications can use the :ref:`selection API <vidioc-g-selection>` to
+select an area in a video signal or a buffer, and to query for default
+settings and hardware limits.
+
+Video hardware can have various cropping, composing and scaling
+limitations. It may only scale up or down, support only discrete scaling
+factors, or have different scaling abilities in the horizontal and
+vertical directions. Also it may not support scaling at all. At the same
+time the cropping/composing rectangles may have to be aligned, and both
+the source and the sink may have arbitrary upper and lower size limits.
+Therefore, as usual, drivers are expected to adjust the requested
+parameters and return the actual values selected. An application can
+control the rounding behaviour using
+:ref:`constraint flags <v4l2-selection-flags>`.
+
+
+Configuration of video capture
+==============================
+
+See figure :ref:`sel-targets-capture` for examples of the selection
+targets available for a video capture device. It is recommended to
+configure the cropping targets before to the composing targets.
+
+The range of coordinates of the top left corner, width and height of
+areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
+target. It is recommended for the driver developers to put the top/left
+corner at position ``(0,0)``. The rectangle's coordinates are expressed
+in pixels.
+
+The top left corner, width and height of the source rectangle, that is
+the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
+It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
+active cropping area must lie completely inside the capture boundaries.
+The driver may further adjust the requested size and/or position
+according to hardware limitations.
+
+Each capture device has a default source rectangle, given by the
+``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the
+driver writer considers the complete picture. Drivers shall set the
+active crop rectangle to the default when the driver is first loaded,
+but not later.
+
+The composing targets refer to a memory buffer. The limits of composing
+coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
+coordinates are expressed in pixels. The rectangle's top/left corner
+must be located at position ``(0,0)``. The width and height are equal to
+the image size set by ``VIDIOC_S_FMT``.
+
+The part of a buffer into which the image is inserted by the hardware is
+controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
+coordinates are also expressed in the same coordinate system as the
+bounds rectangle. The composing rectangle must lie completely inside
+bounds rectangle. The driver must adjust the composing rectangle to fit
+to the bounding limits. Moreover, the driver can perform other
+adjustments according to hardware limitations. The application can
+control rounding behaviour using
+:ref:`constraint flags <v4l2-selection-flags>`.
+
+For capture devices the default composing rectangle is queried using
+``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
+rectangle.
+
+The part of a buffer that is modified by the hardware is given by
+``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
+``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
+during insertion process. All pixels outside this rectangle *must not*
+be changed by the hardware. The content of pixels that lie inside the
+padded area but outside active area is undefined. The application can
+use the padded and active rectangles to detect where the rubbish pixels
+are located and remove them if needed.
+
+
+Configuration of video output
+=============================
+
+For output devices targets and ioctls are used similarly to the video
+capture case. The *composing* rectangle refers to the insertion of an
+image into a video signal. The cropping rectangles refer to a memory
+buffer. It is recommended to configure the composing targets before to
+the cropping targets.
+
+The cropping targets refer to the memory buffer that contains an image
+to be inserted into a video signal or graphical screen. The limits of
+cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
+All coordinates are expressed in pixels. The top/left corner is always
+point ``(0,0)``. The width and height is equal to the image size
+specified using ``VIDIOC_S_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
+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
+limitations.
+
+For output devices the default cropping rectangle is queried using
+``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
+rectangle.
+
+The part of a video signal or graphics display where the image is
+inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
+target. The rectangle's coordinates are expressed in pixels. The
+composing rectangle must lie completely inside the bounds rectangle. The
+driver must adjust the area to fit to the bounding limits. Moreover, the
+driver can perform other adjustments according to hardware limitations.
+
+The device has a default composing rectangle, given by the
+``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
+the driver writer considers the complete picture. It is recommended for
+the driver developers to put the top/left corner at position ``(0,0)``.
+Drivers shall set the active composing rectangle to the default one when
+the driver is first loaded.
+
+The devices may introduce additional content to video signal other than
+an image from memory buffers. It includes borders around an image.
+However, such a padded area is driver-dependent feature not covered by
+this document. Driver developers are encouraged to keep padded rectangle
+equal to active one. The padded target is accessed by the
+``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
+from the ``V4L2_SEL_TGT_COMPOSE`` target.
+
+
+Scaling control
+===============
+
+An application can detect if scaling is performed by comparing the width
+and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
+``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
+scaling is applied. The application can compute the scaling ratios using
+these values.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+********************************
+Comparison with old cropping API
+********************************
+
+The selection API was introduced to cope with deficiencies of previous
+:ref:`API <crop>`, that was designed to control simple capture
+devices. Later the cropping API was adopted by video output drivers. The
+ioctls are used to select a part of the display were the video signal is
+inserted. It should be considered as an API abuse because the described
+operation is actually the composing. The selection API makes a clear
+distinction between composing and cropping operations by setting the
+appropriate targets. The V4L2 API lacks any support for composing to and
+cropping from an image inside a memory buffer. The application could
+configure a capture device to fill only a part of an image by abusing
+V4L2 API. Cropping a smaller image from a larger one is achieved by
+setting the field struct
+:ref:`v4l2_pix_format <v4l2-pix-format>```::bytesperline``.
+Introducing an image offsets could be done by modifying field struct
+:ref:`v4l2_buffer <v4l2-buffer>```::m_userptr`` before calling
+``VIDIOC_QBUF``. Those operations should be avoided because they are not
+portable (endianness), and do not work for macroblock and Bayer formats
+and mmap buffers. The selection API deals with configuration of buffer
+cropping/composing in a clear, intuitive and portable way. Next, with
+the selection API the concepts of the padded target and constraints
+flags are introduced. Finally, struct :ref:`v4l2_crop <v4l2-crop>`
+and struct :ref:`v4l2_cropcap <v4l2-cropcap>` have no reserved
+fields. Therefore there is no way to extend their functionality. The new
+struct :ref:`v4l2_selection <v4l2-selection>` provides a lot of place
+for future extensions. Driver developers are encouraged to implement
+only selection API. The former cropping API would be simulated using the
+new one.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+********
+Examples
+********
+
+(A video capture device is assumed; change
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to
+``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area)
+
+
+.. code-block:: c
+
+ struct v4l2_selection sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
+ .target = V4L2_SEL_TGT_CROP_DEFAULT,
+ };
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+ sel.target = V4L2_SEL_TGT_CROP;
+ ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+
+Setting a composing area on output of size of *at most* half of limit
+placed at a center of a display.
+
+
+.. code-block:: c
+
+ struct v4l2_selection sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
+ };
+ struct v4l2_rect r;
+
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+ /* setting smaller compose rectangle */
+ r.width = sel.r.width / 2;
+ r.height = sel.r.height / 2;
+ r.left = sel.r.width / 4;
+ r.top = sel.r.height / 4;
+ sel.r = r;
+ sel.target = V4L2_SEL_TGT_COMPOSE;
+ sel.flags = V4L2_SEL_FLAG_LE;
+ ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+
+A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+for other devices
+
+
+.. code-block:: c
+
+ struct v4l2_selection compose = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_COMPOSE,
+ };
+ struct v4l2_selection crop = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_CROP,
+ };
+ double hscale, vscale;
+
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &compose);
+ if (ret)
+ exit(-1);
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &crop);
+ if (ret)
+ exit(-1);
+
+ /* computing scaling factors */
+ hscale = (double)compose.r.width / crop.r.width;
+ vscale = (double)compose.r.height / crop.r.height;
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _selection-api:
+
+API for cropping, composing and scaling
+=======================================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ selection-api-002
+ selection-api-003
+ selection-api-004
+ selection-api-005
+ selection-api-006
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selections-common:
+
+Common selection definitions
+============================
+
+While the :ref:`V4L2 selection API <selection-api>` and
+:ref:`V4L2 subdev selection APIs <v4l2-subdev-selections>` are very
+similar, there's one fundamental difference between the two. On
+sub-device API, the selection rectangle refers to the media bus format,
+and is bound to a sub-device's pad. On the V4L2 interface the selection
+rectangles refer to the in-memory pixel format.
+
+This section defines the common definitions of the selection interfaces
+on the two APIs.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ v4l2-selection-targets
+ v4l2-selection-flags
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _standard:
+
+***************
+Video Standards
+***************
+
+Video devices typically support one or more different video standards or
+variations of standards. Each video input and output may support another
+set of standards. This set is reported by the ``std`` field of struct
+:ref:`v4l2_input <v4l2-input>` and struct
+:ref:`v4l2_output <v4l2-output>` returned by the
+:ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` and
+:ref:`VIDIOC_ENUMOUTPUT <vidioc-enumoutput>` ioctls, respectively.
+
+V4L2 defines one bit for each analog video standard currently in use
+worldwide, and sets aside bits for driver defined standards, e. g.
+hybrid standards to watch NTSC video tapes on PAL TVs and vice versa.
+Applications can use the predefined bits to select a particular
+standard, although presenting the user a menu of supported standards is
+preferred. To enumerate and query the attributes of the supported
+standards applications use the :ref:`VIDIOC_ENUMSTD <vidioc-enumstd>`
+ioctl.
+
+Many of the defined standards are actually just variations of a few
+major standards. The hardware may in fact not distinguish between them,
+or do so internal and switch automatically. Therefore enumerated
+standards also contain sets of one or more standard bits.
+
+Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL
+signals. The first enumerated standard is a set of B and G/PAL, switched
+automatically depending on the selected radio frequency in UHF or VHF
+band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a
+Composite input may collapse standards, enumerating "PAL-B/G/H/I",
+"NTSC-M" and "SECAM-D/K". [1]_
+
+To query and select the standard used by the current video input or
+output applications call the :ref:`VIDIOC_G_STD <vidioc-g-std>` and
+:ref:`VIDIOC_S_STD <vidioc-g-std>` ioctl, respectively. The
+*received* standard can be sensed with the
+:ref:`VIDIOC_QUERYSTD <vidioc-querystd>` ioctl. Note that the
+parameter of all these ioctls is a pointer to a
+:ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
+index into the standard enumeration. Drivers must implement all video
+standard ioctls when the device has one or more video inputs or outputs.
+
+Special rules apply to devices such as USB cameras where the notion of
+video standards makes little sense. More generally for any capture or
+output device which is:
+
+- incapable of capturing fields or frames at the nominal rate of the
+ video standard, or
+
+- that does not support the video standard formats at all.
+
+Here the driver shall set the ``std`` field of struct
+:ref:`v4l2_input <v4l2-input>` and struct
+:ref:`v4l2_output <v4l2-output>` to zero and the ``VIDIOC_G_STD``,
+``VIDIOC_S_STD``, ``VIDIOC_QUERYSTD`` and ``VIDIOC_ENUMSTD`` ioctls
+shall return the ENOTTY error code or the EINVAL error code.
+
+Applications can make use of the :ref:`input-capabilities` and
+:ref:`output-capabilities` flags to determine whether the video
+standard ioctls can be used with the given input or output.
+
+
+.. code-block:: c
+
+ v4l2_std_id std_id;
+ struct v4l2_standard standard;
+
+ if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) {
+ /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
+ is no video device or it falls under the USB exception,
+ and VIDIOC_G_STD returning ENOTTY is no error. */
+
+ perror("VIDIOC_G_STD");
+ exit(EXIT_FAILURE);
+ }
+
+ memset(&standard, 0, sizeof(standard));
+ standard.index = 0;
+
+ while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
+ if (standard.id & std_id) {
+ printf("Current video standard: %s\\n", standard.name);
+ exit(EXIT_SUCCESS);
+ }
+
+ standard.index++;
+ }
+
+ /* EINVAL indicates the end of the enumeration, which cannot be
+ empty unless this device falls under the USB exception. */
+
+ if (errno == EINVAL || standard.index == 0) {
+ perror("VIDIOC_ENUMSTD");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+
+ struct v4l2_input input;
+ struct v4l2_standard standard;
+
+ memset(&input, 0, sizeof(input));
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUM_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input %s supports:\\n", input.name);
+
+ memset(&standard, 0, sizeof(standard));
+ standard.index = 0;
+
+ while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
+ if (standard.id & input.std)
+ printf("%s\\n", standard.name);
+
+ standard.index++;
+ }
+
+ /* EINVAL indicates the end of the enumeration, which cannot be
+ empty unless this device falls under the USB exception. */
+
+ if (errno != EINVAL || standard.index == 0) {
+ perror("VIDIOC_ENUMSTD");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+
+ struct v4l2_input input;
+ v4l2_std_id std_id;
+
+ memset(&input, 0, sizeof(input));
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUM_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (0 == (input.std & V4L2_STD_PAL_BG)) {
+ fprintf(stderr, "Oops. B/G PAL is not supported.\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Note this is also supposed to work when only B
+ or G/PAL is supported. */
+
+ std_id = V4L2_STD_PAL_BG;
+
+ if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {
+ perror("VIDIOC_S_STD");
+ exit(EXIT_FAILURE);
+ }
+
+.. [1]
+ Some users are already confused by technical terms PAL, NTSC and
+ SECAM. There is no point asking them to distinguish between B, G, D,
+ or K when the software or hardware can do that automatically.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _streaming-par:
+
+********************
+Streaming Parameters
+********************
+
+Streaming parameters are intended to optimize the video capture process
+as well as I/O. Presently applications can request a high quality
+capture mode with the :ref:`VIDIOC_S_PARM <vidioc-g-parm>` ioctl.
+
+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.
+
+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.
+
+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 pointer to a struct :ref:`v4l2_streamparm <v4l2-streamparm>`, which
+contains a union holding separate parameters for input and output
+devices.
+
+These ioctls are optional, drivers need not implement them. If so, they
+return the EINVAL error code.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-mbus-format:
+
+Media Bus Formats
+=================
+
+
+.. _v4l2-mbus-framefmt:
+
+.. flat-table:: struct v4l2_mbus_framefmt
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width, in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height, in pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - Format code, from enum
+ :ref:`v4l2_mbus_pixelcode <v4l2-mbus-pixelcode>`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``field``
+
+ - Field order, from enum :ref:`v4l2_field <v4l2-field>`. See
+ :ref:`field-order` for details.
+
+ - .. row 5
+
+ - __u32
+
+ - ``colorspace``
+
+ - Image colorspace, from enum
+ :ref:`v4l2_colorspace <v4l2-colorspace>`. See
+ :ref:`colorspaces` for details.
+
+ - .. row 6
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - 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`.
+
+ - .. row 7
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``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`.
+
+ - .. row 8
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``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`.
+
+ - .. row 9
+
+ - __u16
+
+ - ``reserved``\ [11]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-mbus-pixelcode:
+
+Media Bus Pixel Codes
+---------------------
+
+The media bus pixel codes describe image formats as flowing over
+physical busses (both between separate physical components and inside
+SoC devices). This should not be confused with the V4L2 pixel formats
+that describe, using four character codes, image formats as stored in
+memory.
+
+While there is a relationship between image formats on busses and image
+formats in memory (a raw Bayer image won't be magically converted to
+JPEG just by storing it to memory), there is no one-to-one
+correspondance between them.
+
+
+Packed RGB Formats
+^^^^^^^^^^^^^^^^^^
+
+Those formats transfer pixel data as red, green and blue components. The
+format code is made of the following information.
+
+- The red, green and blue components order code, as encoded in a pixel
+ sample. Possible values are RGB and BGR.
+
+- The number of bits per component, for each component. The values can
+ be different for all components. Common values are 555 and 565.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1 and 2.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO). A "C" prefix is used for
+ component-wise padding in the most high order bits (CPADHI) or low
+ order bits (CPADLO) of each separate component.
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+For instance, a format where pixels are encoded as 5-bits red, 5-bits
+green and 5-bit blue values padded on the high bit, transferred as 2
+8-bit samples per pixel with the most significant bits (padding, red and
+half of the green value) transferred first will be named
+``MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE``.
+
+The following tables list existing packed RGB formats.
+
+
+.. _v4l2-mbus-pixelcode-rgb:
+
+.. flat-table:: RGB formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 20
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _`MEDIA-BUS-FMT-RGB444-1X12`:
+
+ - MEDIA_BUS_FMT_RGB444_1X12
+
+ - 0x1016
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE`:
+
+ - MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE
+
+ - 0x1001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. row 5
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE`:
+
+ - MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE
+
+ - 0x1002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 7
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE`:
+
+ - MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE
+
+ - 0x1003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 9
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE`:
+
+ - MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE
+
+ - 0x1004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _`MEDIA-BUS-FMT-RGB565-1X16`:
+
+ - MEDIA_BUS_FMT_RGB565_1X16
+
+ - 0x1017
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-BGR565-2X8-BE`:
+
+ - MEDIA_BUS_FMT_BGR565_2X8_BE
+
+ - 0x1005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 14
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-BGR565-2X8-LE`:
+
+ - MEDIA_BUS_FMT_BGR565_2X8_LE
+
+ - 0x1006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _`MEDIA-BUS-FMT-RGB565-2X8-BE`:
+
+ - MEDIA_BUS_FMT_RGB565_2X8_BE
+
+ - 0x1007
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 18
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB565-2X8-LE`:
+
+ - MEDIA_BUS_FMT_RGB565_2X8_LE
+
+ - 0x1008
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _`MEDIA-BUS-FMT-RGB666-1X18`:
+
+ - MEDIA_BUS_FMT_RGB666_1X18
+
+ - 0x1009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-RBG888-1X24`:
+
+ - MEDIA_BUS_FMT_RBG888_1X24
+
+ - 0x100e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :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`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB666-1X24_CPADHI`:
+
+ - MEDIA_BUS_FMT_RGB666_1X24_CPADHI
+
+ - 0x1015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`5`
+
+ - 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
+
+ - b\ :sub:`5`
+
+ - 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
+
+ - 0x1013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-GBR888-1X24`:
+
+ - MEDIA_BUS_FMT_GBR888_1X24
+
+ - 0x1014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB888-1X24`:
+
+ - MEDIA_BUS_FMT_RGB888_1X24
+
+ - 0x100a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB888-2X12-BE`:
+
+ - MEDIA_BUS_FMT_RGB888_2X12_BE
+
+ - 0x100b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 28
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-RGB888-2X12-LE`:
+
+ - MEDIA_BUS_FMT_RGB888_2X12_LE
+
+ - 0x100c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 30
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-ARGB888-1X32`:
+
+ - MEDIA_BUS_FMT_ARGB888_1X32
+
+ - 0x100d
+
+ -
+ - 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:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB888-1X32-PADHI`:
+
+ - MEDIA_BUS_FMT_RGB888_1X32_PADHI
+
+ - 0x100f
+
+ -
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 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:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+
+On LVDS buses, usually each sample is transferred serialized in seven
+time slots per pixel clock, on three (18-bit) or four (24-bit)
+differential data pairs at the same time. The remaining bits are used
+for control signals as defined by SPWG/PSWG/VESA or JEIDA standards. The
+24-bit RGB format serialized in seven time slots on four lanes using
+JEIDA defined bit mapping will be named
+``MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA``, for example.
+
+
+.. _v4l2-mbus-pixelcode-rgb-lvds:
+
+.. flat-table:: LVDS RGB formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ -
+ - :cspan:`3` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Timeslot
+
+ - Lane
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _`MEDIA-BUS-FMT-RGB666-1X7X3-SPWG`:
+
+ - MEDIA_BUS_FMT_RGB666_1X7X3_SPWG
+
+ - 0x1010
+
+ - 0
+
+ -
+ - -
+
+ - d
+
+ - b\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. row 4
+
+ -
+ -
+ - 1
+
+ -
+ - -
+
+ - d
+
+ - b\ :sub:`0`
+
+ - r\ :sub:`5`
+
+ - .. row 5
+
+ -
+ -
+ - 2
+
+ -
+ - -
+
+ - d
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 6
+
+ -
+ -
+ - 3
+
+ -
+ - -
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 7
+
+ -
+ -
+ - 4
+
+ -
+ - -
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - .. row 8
+
+ -
+ -
+ - 5
+
+ -
+ - -
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - .. row 9
+
+ -
+ -
+ - 6
+
+ -
+ - -
+
+ - b\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB888-1X7X4-SPWG`:
+
+ - MEDIA_BUS_FMT_RGB888_1X7X4_SPWG
+
+ - 0x1011
+
+ - 0
+
+ -
+ - d
+
+ - d
+
+ - b\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ - 1
+
+ -
+ - b\ :sub:`7`
+
+ - d
+
+ - b\ :sub:`0`
+
+ - r\ :sub:`5`
+
+ - .. row 12
+
+ -
+ -
+ - 2
+
+ -
+ - b\ :sub:`6`
+
+ - d
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 13
+
+ -
+ -
+ - 3
+
+ -
+ - g\ :sub:`7`
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 14
+
+ -
+ -
+ - 4
+
+ -
+ - g\ :sub:`6`
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - .. row 15
+
+ -
+ -
+ - 5
+
+ -
+ - r\ :sub:`7`
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - .. row 16
+
+ -
+ -
+ - 6
+
+ -
+ - r\ :sub:`6`
+
+ - b\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-RGB888-1X7X4-JEIDA`:
+
+ - MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA
+
+ - 0x1012
+
+ - 0
+
+ -
+ - d
+
+ - d
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - .. row 18
+
+ -
+ -
+ - 1
+
+ -
+ - b\ :sub:`1`
+
+ - d
+
+ - b\ :sub:`2`
+
+ - r\ :sub:`7`
+
+ - .. row 19
+
+ -
+ -
+ - 2
+
+ -
+ - b\ :sub:`0`
+
+ - d
+
+ - g\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - .. row 20
+
+ -
+ -
+ - 3
+
+ -
+ - g\ :sub:`1`
+
+ - b\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - .. row 21
+
+ -
+ -
+ - 4
+
+ -
+ - g\ :sub:`0`
+
+ - b\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 22
+
+ -
+ -
+ - 5
+
+ -
+ - r\ :sub:`1`
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 23
+
+ -
+ -
+ - 6
+
+ -
+ - r\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+
+
+Bayer Formats
+^^^^^^^^^^^^^
+
+Those formats transfer pixel data as red, green and blue components. The
+format code is made of the following information.
+
+- The red, green and blue components order code, as encoded in a pixel
+ sample. The possible values are shown in :ref:`bayer-patterns`.
+
+- The number of bits per pixel component. All components are
+ transferred on the same number of bits. Common values are 8, 10 and
+ 12.
+
+- The compression (optional). If the pixel components are ALAW- or
+ DPCM-compressed, a mention of the compression scheme and the number
+ of bits per compressed pixel component.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1 and 2.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO).
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+For instance, a format with uncompressed 10-bit Bayer components
+arranged in a red, green, green, blue pattern transferred as 2 8-bit
+samples per pixel with the least significant bits transferred first will
+be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
+
+
+.. _bayer-patterns:
+
+.. figure:: subdev-formats_files/bayer.*
+ :alt: bayer.png
+ :align: center
+
+ Bayer Patterns
+
+ Bayer filter color patterns
+
+
+
+The following table lists existing packed Bayer formats. The data
+organization is given as an example for the first pixel only.
+
+
+.. _v4l2-mbus-pixelcode-bayer:
+
+.. flat-table:: Bayer Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`11` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _`MEDIA-BUS-FMT-SBGGR8-1X8`:
+
+ - MEDIA_BUS_FMT_SBGGR8_1X8
+
+ - 0x3001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SGBRG8-1X8`:
+
+ - MEDIA_BUS_FMT_SGBRG8_1X8
+
+ - 0x3013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SGRBG8-1X8`:
+
+ - MEDIA_BUS_FMT_SGRBG8_1X8
+
+ - 0x3002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SRGGB8-1X8`:
+
+ - MEDIA_BUS_FMT_SRGGB8_1X8
+
+ - 0x3014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8`:
+
+ - MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8
+
+ - 0x3015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8`:
+
+ - MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8
+
+ - 0x3016
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8`:
+
+ - MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8
+
+ - 0x3017
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8`:
+
+ - MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8
+
+ - 0x3018
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8`:
+
+ - MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8
+
+ - 0x300b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8`:
+
+ - MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8
+
+ - 0x300c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8`:
+
+ - MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8
+
+ - 0x3009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8`:
+
+ - MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8
+
+ - 0x300d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE`:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE
+
+ - 0x3003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE`:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE
+
+ - 0x3004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 18
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - .. _`MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE`:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE
+
+ - 0x3005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - .. _`MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE`:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE
+
+ - 0x3006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - .. row 22
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - .. _`MEDIA-BUS-FMT-SBGGR10-1X10`:
+
+ - MEDIA_BUS_FMT_SBGGR10_1X10
+
+ - 0x3007
+
+ -
+ - -
+
+ - -
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-SGBRG10-1X10`:
+
+ - MEDIA_BUS_FMT_SGBRG10_1X10
+
+ - 0x300e
+
+ -
+ - -
+
+ - -
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-SGRBG10-1X10`:
+
+ - MEDIA_BUS_FMT_SGRBG10_1X10
+
+ - 0x300a
+
+ -
+ - -
+
+ - -
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-SRGGB10-1X10`:
+
+ - MEDIA_BUS_FMT_SRGGB10_1X10
+
+ - 0x300f
+
+ -
+ - -
+
+ - -
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-SBGGR12-1X12`:
+
+ - MEDIA_BUS_FMT_SBGGR12_1X12
+
+ - 0x3008
+
+ -
+ - b\ :sub:`11`
+
+ - b\ :sub:`10`
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-SGBRG12-1X12`:
+
+ - MEDIA_BUS_FMT_SGBRG12_1X12
+
+ - 0x3010
+
+ -
+ - g\ :sub:`11`
+
+ - g\ :sub:`10`
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-SGRBG12-1X12`:
+
+ - MEDIA_BUS_FMT_SGRBG12_1X12
+
+ - 0x3011
+
+ -
+ - g\ :sub:`11`
+
+ - g\ :sub:`10`
+
+ - 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`
+
+ - .. _`MEDIA-BUS-FMT-SRGGB12-1X12`:
+
+ - MEDIA_BUS_FMT_SRGGB12_1X12
+
+ - 0x3012
+
+ -
+ - r\ :sub:`11`
+
+ - r\ :sub:`10`
+
+ - 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`
+
+
+
+Packed YUV Formats
+^^^^^^^^^^^^^^^^^^
+
+Those data formats transfer pixel data as (possibly downsampled) Y, U
+and V components. Some formats include dummy bits in some of their
+samples and are collectively referred to as "YDYC" (Y-Dummy-Y-Chroma)
+formats. One cannot rely on the values of these dummy bits as those are
+undefined.
+
+The format code is made of the following information.
+
+- The Y, U and V components order code, as transferred on the bus.
+ Possible values are YUYV, UYVY, YVYU and VYUY for formats with no
+ dummy bit, and YDYUYDYV, YDYVYDYU, YUYDYVYD and YVYDYUYD for YDYC
+ formats.
+
+- The number of bits per pixel component. All components are
+ transferred on the same number of bits. Common values are 8, 10 and
+ 12.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1, 1.5 (encoded as 1_5) and 2.
+
+- The bus width. When the bus width is larger than the number of bits
+ per pixel component, several components are packed in a single bus
+ sample. The components are ordered as specified by the order code,
+ with components on the left of the code transferred in the high order
+ bits. Common values are 8 and 16.
+
+For instance, a format where pixels are encoded as 8-bit YUV values
+downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in
+the U, Y, V, Y order will be named ``MEDIA_BUS_FMT_UYVY8_2X8``.
+
+:ref:`v4l2-mbus-pixelcode-yuv8` lists existing packed YUV formats and
+describes the organization of each pixel data in each sample. When a
+format pattern is split across multiple samples each of the samples in
+the pattern is described.
+
+The role of each bit transferred over the bus is identified by one of
+the following codes.
+
+- y\ :sub:`x` for luma component bit number x
+
+- u\ :sub:`x` for blue chroma component bit number x
+
+- v\ :sub:`x` for red chroma component bit number x
+
+- a\ :sub:`x` for alpha component bit number x
+
+- - for non-available bits (for positions higher than the bus width)
+
+- d for dummy bits
+
+
+.. _v4l2-mbus-pixelcode-yuv8:
+
+.. flat-table:: YUV Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 10
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _`MEDIA-BUS-FMT-Y8-1X8`:
+
+ - MEDIA_BUS_FMT_Y8_1X8
+
+ - 0x2001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-UV8-1X8`:
+
+ - MEDIA_BUS_FMT_UV8_1X8
+
+ - 0x2015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 5
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-UYVY8-1_5X8`:
+
+ - MEDIA_BUS_FMT_UYVY8_1_5X8
+
+ - 0x2002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 7
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 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`
+
+ - .. row 9
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 10
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-VYUY8-1_5X8`:
+
+ - MEDIA_BUS_FMT_VYUY8_1_5X8
+
+ - 0x2003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 13
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 14
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 15
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 17
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-YUYV8-1_5X8`:
+
+ - MEDIA_BUS_FMT_YUYV8_1_5X8
+
+ - 0x2004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 19
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 21
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 22
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 23
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YVYU8-1_5X8`:
+
+ - MEDIA_BUS_FMT_YVYU8_1_5X8
+
+ - 0x2005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 25
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 26
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 27
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 28
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 29
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-UYVY8-2X8`:
+
+ - MEDIA_BUS_FMT_UYVY8_2X8
+
+ - 0x2006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 31
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 32
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 33
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-VYUY8-2X8`:
+
+ - MEDIA_BUS_FMT_VYUY8_2X8
+
+ - 0x2007
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 35
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 36
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 37
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-YUYV8-2X8`:
+
+ - MEDIA_BUS_FMT_YUYV8_2X8
+
+ - 0x2008
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 39
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 40
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 41
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YVYU8-2X8`:
+
+ - MEDIA_BUS_FMT_YVYU8_2X8
+
+ - 0x2009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 43
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 44
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 45
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-Y10-1X10`:
+
+ - MEDIA_BUS_FMT_Y10_1X10
+
+ - 0x200a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-UYVY10-2X10`:
+
+ - MEDIA_BUS_FMT_UYVY10_2X10
+
+ - 0x2018
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 48
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 49
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 50
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-VYUY10-2X10`:
+
+ - MEDIA_BUS_FMT_VYUY10_2X10
+
+ - 0x2019
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 52
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 53
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 54
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-YUYV10-2X10`:
+
+ - MEDIA_BUS_FMT_YUYV10_2X10
+
+ - 0x200b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 56
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 57
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 58
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YVYU10-2X10`:
+
+ - MEDIA_BUS_FMT_YVYU10_2X10
+
+ - 0x200c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 60
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 61
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 62
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-Y12-1X12`:
+
+ - MEDIA_BUS_FMT_Y12_1X12
+
+ - 0x2013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-UYVY12-2X12`:
+
+ - MEDIA_BUS_FMT_UYVY12_2X12
+
+ - 0x201c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 65
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 66
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 67
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-VYUY12-2X12`:
+
+ - MEDIA_BUS_FMT_VYUY12_2X12
+
+ - 0x201d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 69
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 70
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 71
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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-YUYV12-2X12`:
+
+ - MEDIA_BUS_FMT_YUYV12_2X12
+
+ - 0x201e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 73
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 74
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 75
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YVYU12-2X12`:
+
+ - MEDIA_BUS_FMT_YVYU12_2X12
+
+ - 0x201f
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 77
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 78
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - .. row 79
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-UYVY8-1X16`:
+
+ - MEDIA_BUS_FMT_UYVY8_1X16
+
+ - 0x200f
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :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`
+
+ - .. row 81
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :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`
+
+ - .. _`MEDIA-BUS-FMT-VYUY8-1X16`:
+
+ - MEDIA_BUS_FMT_VYUY8_1X16
+
+ - 0x2010
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :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`
+
+ - .. row 83
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :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`
+
+ - .. _`MEDIA-BUS-FMT-YUYV8-1X16`:
+
+ - MEDIA_BUS_FMT_YUYV8_1X16
+
+ - 0x2011
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 85
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YVYU8-1X16`:
+
+ - MEDIA_BUS_FMT_YVYU8_1X16
+
+ - 0x2012
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 87
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YDYUYDYV8-1X16`:
+
+ - MEDIA_BUS_FMT_YDYUYDYV8_1X16
+
+ - 0x2014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - .. row 89
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 90
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - .. row 91
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-UYVY10-1X20`:
+
+ - MEDIA_BUS_FMT_UYVY10_1X20
+
+ - 0x201a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - 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`
+
+ - .. row 93
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - 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-VYUY10-1X20`:
+
+ - MEDIA_BUS_FMT_VYUY10_1X20
+
+ - 0x201b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - 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`
+
+ - .. row 95
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - 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-YUYV10-1X20`:
+
+ - MEDIA_BUS_FMT_YUYV10_1X20
+
+ - 0x200d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 97
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YVYU10-1X20`:
+
+ - MEDIA_BUS_FMT_YVYU10_1X20
+
+ - 0x200e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 99
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-VUY8-1X24`:
+
+ - MEDIA_BUS_FMT_VUY8_1X24
+
+ - 0x201a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :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`
+
+ - .. _`MEDIA-BUS-FMT-YUV8-1X24`:
+
+ - MEDIA_BUS_FMT_YUV8_1X24
+
+ - 0x2025
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-UYVY12-1X24`:
+
+ - MEDIA_BUS_FMT_UYVY12_1X24
+
+ - 0x2020
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - 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`
+
+ - .. row 103
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - 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-VYUY12-1X24`:
+
+ - MEDIA_BUS_FMT_VYUY12_1X24
+
+ - 0x2021
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - 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`
+
+ - .. row 105
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - 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-YUYV12-1X24`:
+
+ - MEDIA_BUS_FMT_YUYV12_1X24
+
+ - 0x2022
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 107
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YVYU12-1X24`:
+
+ - MEDIA_BUS_FMT_YVYU12_1X24
+
+ - 0x2023
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 109
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 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`
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-YUV10-1X30`:
+
+ - MEDIA_BUS_FMT_YUV10_1X30
+
+ - 0x2016
+
+ -
+ - -
+
+ - -
+
+ - 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`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _`MEDIA-BUS-FMT-AYUV8-1X32`:
+
+ - MEDIA_BUS_FMT_AYUV8_1X32
+
+ - 0x2017
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :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`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+
+
+HSV/HSL Formats
+^^^^^^^^^^^^^^^
+
+Those formats transfer pixel data as RGB values in a
+cylindrical-coordinate system using Hue-Saturation-Value or
+Hue-Saturation-Lightness components. The format code is made of the
+following information.
+
+- The hue, saturation, value or lightness and optional alpha components
+ order code, as encoded in a pixel sample. The only currently
+ supported value is AHSV.
+
+- The number of bits per component, for each component. The values can
+ be different for all components. The only currently supported value
+ is 8888.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. The only currently
+ supported value is 1.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO).
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+The following table lists existing HSV/HSL formats.
+
+
+.. _v4l2-mbus-pixelcode-hsv:
+
+.. flat-table:: HSV/HSL formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 20
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _`MEDIA-BUS-FMT-AHSV8888-1X32`:
+
+ - MEDIA_BUS_FMT_AHSV8888_1X32
+
+ - 0x6001
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - h\ :sub:`7`
+
+ - h\ :sub:`6`
+
+ - h\ :sub:`5`
+
+ - h\ :sub:`4`
+
+ - h\ :sub:`3`
+
+ - h\ :sub:`2`
+
+ - h\ :sub:`1`
+
+ - h\ :sub:`0`
+
+ - s\ :sub:`7`
+
+ - s\ :sub:`6`
+
+ - s\ :sub:`5`
+
+ - s\ :sub:`4`
+
+ - s\ :sub:`3`
+
+ - s\ :sub:`2`
+
+ - s\ :sub:`1`
+
+ - s\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+
+
+JPEG Compressed Formats
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Those data formats consist of an ordered sequence of 8-bit bytes
+obtained from JPEG compression process. Additionally to the ``_JPEG``
+postfix the format code is made of the following information.
+
+- The number of bus samples per entropy encoded byte.
+
+- The bus width.
+
+For instance, for a JPEG baseline process and an 8-bit bus width the
+format will be named ``MEDIA_BUS_FMT_JPEG_1X8``.
+
+The following table lists existing JPEG compressed formats.
+
+
+.. _v4l2-mbus-pixelcode-jpeg:
+
+.. flat-table:: JPEG Formats
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Remarks
+
+ - .. _`MEDIA-BUS-FMT-JPEG-1X8`:
+
+ - MEDIA_BUS_FMT_JPEG_1X8
+
+ - 0x4001
+
+ - Besides of its usage for the parallel bus this format is
+ recommended for transmission of JPEG data over MIPI CSI bus using
+ the User Defined 8-bit Data types.
+
+
+
+.. _v4l2-mbus-vendor-spec-fmts:
+
+Vendor and Device Specific Formats
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section lists complex data formats that are either vendor or device
+specific.
+
+The following table lists the existing vendor and device specific
+formats.
+
+
+.. _v4l2-mbus-pixelcode-vendor-specific:
+
+.. flat-table:: Vendor and device specific formats
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Comments
+
+ - .. _`MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8`:
+
+ - MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8
+
+ - 0x5001
+
+ - Interleaved raw UYVY and JPEG image format with embedded meta-data
+ used by Samsung S3C73MX camera sensors.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _tuner:
+
+*********************
+Tuners and Modulators
+*********************
+
+
+Tuners
+======
+
+Video input devices can have one or more tuners demodulating a RF
+signal. Each tuner is associated with one or more video inputs,
+depending on the number of RF connectors on the tuner. The ``type``
+field of the respective struct :ref:`v4l2_input <v4l2-input>`
+returned by the :ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` ioctl is
+set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the
+index number of the tuner.
+
+Radio input devices have exactly one tuner with index zero, no video
+inputs.
+
+To query and change tuner properties applications use the
+:ref:`VIDIOC_G_TUNER <vidioc-g-tuner>` and
+:ref:`VIDIOC_S_TUNER <vidioc-g-tuner>` ioctls, respectively. The
+struct :ref:`v4l2_tuner <v4l2-tuner>` returned by ``VIDIOC_G_TUNER``
+also contains signal status information applicable when the tuner of the
+current video or radio input is queried. Note that ``VIDIOC_S_TUNER``
+does not switch the current tuner, when there is more than one at all.
+The tuner is solely determined by the current video input. Drivers must
+support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl when the device has
+one or more tuners.
+
+
+Modulators
+==========
+
+Video output devices can have one or more modulators, uh, modulating a
+video signal for radiation or connection to the antenna input of a TV
+set or video recorder. Each modulator is associated with one or more
+video outputs, depending on the number of RF connectors on the
+modulator. The ``type`` field of the respective struct
+:ref:`v4l2_output <v4l2-output>` returned by the
+:ref:`VIDIOC_ENUMOUTPUT <vidioc-enumoutput>` ioctl is set to
+``V4L2_OUTPUT_TYPE_MODULATOR`` and its ``modulator`` field contains the
+index number of the modulator.
+
+Radio output devices have exactly one modulator with index zero, no
+video outputs.
+
+A video or radio device cannot support both a tuner and a modulator. Two
+separate device nodes will have to be used for such hardware, one that
+supports the tuner functionality and one that supports the modulator
+functionality. The reason is a limitation with the
+:ref:`VIDIOC_S_FREQUENCY <vidioc-g-frequency>` ioctl where you
+cannot specify whether the frequency is for a tuner or a modulator.
+
+To query and change modulator properties applications use the
+:ref:`VIDIOC_G_MODULATOR <vidioc-g-modulator>` and
+:ref:`VIDIOC_S_MODULATOR <vidioc-g-modulator>` ioctl. Note that
+``VIDIOC_S_MODULATOR`` does not switch the current modulator, when there
+is more than one at all. The modulator is solely determined by the
+current video output. Drivers must support both ioctls and set the
+``V4L2_CAP_MODULATOR`` flag in the struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl when the device has
+one or more modulators.
+
+
+Radio Frequency
+===============
+
+To get and set the tuner or modulator radio frequency applications use
+the :ref:`VIDIOC_G_FREQUENCY <vidioc-g-frequency>` and
+:ref:`VIDIOC_S_FREQUENCY <vidioc-g-frequency>` ioctl which both take
+a pointer to a struct :ref:`v4l2_frequency <v4l2-frequency>`. These
+ioctls are used for TV and radio devices alike. Drivers must support
+both ioctls when the tuner or modulator ioctls are supported, or when
+the device is a radio device.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _user-func:
+
+******************
+Function Reference
+******************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ func-close
+ func-ioctl
+ vidioc-create-bufs
+ vidioc-cropcap
+ vidioc-dbg-g-chip-info
+ vidioc-dbg-g-register
+ vidioc-decoder-cmd
+ vidioc-dqevent
+ vidioc-dv-timings-cap
+ vidioc-encoder-cmd
+ vidioc-enumaudio
+ vidioc-enumaudioout
+ vidioc-enum-dv-timings
+ vidioc-enum-fmt
+ vidioc-enum-framesizes
+ vidioc-enum-frameintervals
+ vidioc-enum-freq-bands
+ vidioc-enuminput
+ vidioc-enumoutput
+ vidioc-enumstd
+ vidioc-expbuf
+ vidioc-g-audio
+ vidioc-g-audioout
+ vidioc-g-crop
+ vidioc-g-ctrl
+ vidioc-g-dv-timings
+ vidioc-g-edid
+ vidioc-g-enc-index
+ vidioc-g-ext-ctrls
+ vidioc-g-fbuf
+ vidioc-g-fmt
+ vidioc-g-frequency
+ vidioc-g-input
+ vidioc-g-jpegcomp
+ vidioc-g-modulator
+ vidioc-g-output
+ vidioc-g-parm
+ vidioc-g-priority
+ vidioc-g-selection
+ vidioc-g-sliced-vbi-cap
+ vidioc-g-std
+ vidioc-g-tuner
+ vidioc-log-status
+ vidioc-overlay
+ vidioc-prepare-buf
+ vidioc-qbuf
+ vidioc-querybuf
+ vidioc-querycap
+ vidioc-queryctrl
+ vidioc-query-dv-timings
+ vidioc-querystd
+ vidioc-reqbufs
+ vidioc-s-hw-freq-seek
+ vidioc-streamon
+ vidioc-subdev-enum-frame-interval
+ vidioc-subdev-enum-frame-size
+ vidioc-subdev-enum-mbus-code
+ vidioc-subdev-g-crop
+ vidioc-subdev-g-fmt
+ vidioc-subdev-g-frame-interval
+ vidioc-subdev-g-selection
+ vidioc-subscribe-event
+ func-mmap
+ func-munmap
+ func-open
+ func-poll
+ func-read
+ func-select
+ func-write
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _userp:
+
+*****************************
+Streaming I/O (User Pointers)
+*****************************
+
+Input and output devices support this I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl is set. If the
+particular user pointer method (not only memory mapping) is supported
+must be determined by calling the
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl.
+
+This I/O method combines advantages of the read/write and memory mapping
+methods. Buffers (planes) are allocated by the application itself, and
+can reside for example in virtual or shared memory. Only pointers to
+data are exchanged, these pointers and meta-information are passed in
+struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
+:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
+driver must be switched into user pointer I/O mode by calling the
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` with the desired buffer type.
+No buffers (planes) are allocated beforehand, consequently they are not
+indexed and cannot be queried like mapped buffers with the
+``VIDIOC_QUERYBUF`` ioctl.
+
+
+.. code-block:: c
+
+ struct v4l2_requestbuffers reqbuf;
+
+ memset (&reqbuf, 0, sizeof (reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_USERPTR;
+
+ if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
+ if (errno == EINVAL)
+ printf ("Video capturing or user pointer streaming is not supported\\n");
+ else
+ perror ("VIDIOC_REQBUFS");
+
+ exit (EXIT_FAILURE);
+ }
+
+Buffer (plane) addresses and sizes are passed on the fly with the
+:ref:`VIDIOC_QBUF <vidioc-qbuf>` ioctl. Although buffers are commonly
+cycled, applications can pass different addresses and sizes at each
+``VIDIOC_QBUF`` call. If required by the hardware the driver swaps
+memory pages within physical memory to create a continuous area of
+memory. This happens transparently to the application in the virtual
+memory subsystem of the kernel. When buffer pages have been swapped out
+to disk they are brought back and finally locked in physical memory for
+DMA. [1]_
+
+Filled or displayed buffers are dequeued with the
+:ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl. The driver can unlock the
+memory pages at any time between the completion of the DMA and this
+ioctl. The memory is also unlocked when
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>` is called,
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>`, or when the device is closed.
+Applications must take care not to free buffers without dequeuing. For
+once, the buffers remain locked until further, wasting physical memory.
+Second the driver will not be notified when the memory is returned to
+the application's free list and subsequently reused for other purposes,
+possibly completing the requested DMA and overwriting valuable data.
+
+For capturing applications it is customary to enqueue a number of empty
+buffers, to start capturing and enter the read loop. Here the
+application waits until a filled buffer can be dequeued, and re-enqueues
+the buffer when the data is no longer needed. Output applications fill
+and enqueue buffers, when enough buffers are stacked up output is
+started. In the write loop, when the application runs out of free
+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 ``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
+immediately with an EAGAIN error code when no buffer is available. The
+:ref:`select() <func-select>` or :ref:`poll() <func-poll>` function
+are always available.
+
+To start and stop capturing or output applications call the
+:ref:`VIDIOC_STREAMON <vidioc-streamon>` and
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>` ioctl. Note
+``VIDIOC_STREAMOFF`` removes all buffers from both queues and unlocks
+all buffers as a side effect. Since there is no notion of doing anything
+"now" on a multitasking system, if an application needs to synchronize
+with another event it should examine the struct
+:ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
+outputted buffers.
+
+Drivers implementing user pointer I/O must support the
+``VIDIOC_REQBUFS``, ``VIDIOC_QBUF``, ``VIDIOC_DQBUF``,
+``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl, the
+:c:func:`select()` and :c:func:`poll()` function. [2]_
+
+.. [1]
+ We expect that frequently used buffers are typically not swapped out.
+ Anyway, the process of swapping, locking or generating scatter-gather
+ lists may be time consuming. The delay can be masked by the depth of
+ the incoming buffer queue, and perhaps by maintaining caches assuming
+ a buffer will be soon enqueued again. On the other hand, to optimize
+ memory usage drivers can limit the number of buffers locked in
+ advance and recycle the most recently used buffers first. Of course,
+ the pages of empty buffers in the incoming queue need not be saved to
+ disk. Output buffers must be saved on the incoming and outgoing queue
+ because an application may share them with other processes.
+
+.. [2]
+ 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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selection-flags:
+
+***************
+Selection flags
+***************
+
+
+.. _v4l2-selection-flags-table:
+
+.. flat-table:: Selection flag definitions
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag name
+
+ - id
+
+ - Definition
+
+ - Valid for V4L2
+
+ - Valid for V4L2 subdev
+
+ - .. row 2
+
+ - ``V4L2_SEL_FLAG_GE``
+
+ - (1 << 0)
+
+ - Suggest the driver it should choose greater or equal rectangle (in
+ size) than was requested. Albeit the driver may choose a lesser
+ size, it will only do so due to hardware limitations. Without this
+ flag (and ``V4L2_SEL_FLAG_LE``) the behaviour is to choose the
+ closest possible rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 3
+
+ - ``V4L2_SEL_FLAG_LE``
+
+ - (1 << 1)
+
+ - Suggest the driver it should choose lesser or equal rectangle (in
+ size) than was requested. Albeit the driver may choose a greater
+ size, it will only do so due to hardware limitations.
+
+ - Yes
+
+ - Yes
+
+ - .. row 4
+
+ - ``V4L2_SEL_FLAG_KEEP_CONFIG``
+
+ - (1 << 2)
+
+ - The configuration must not be propagated to any further processing
+ steps. If this flag is not given, the configuration is propagated
+ inside the subdevice to all further processing steps.
+
+ - No
+
+ - Yes
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selection-targets:
+
+*****************
+Selection targets
+*****************
+
+The precise meaning of the selection targets may be dependent on which
+of the two interfaces they are used.
+
+
+.. _v4l2-selection-targets-table:
+
+.. flat-table:: Selection target definitions
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Target name
+
+ - id
+
+ - Definition
+
+ - Valid for V4L2
+
+ - Valid for V4L2 subdev
+
+ - .. row 2
+
+ - ``V4L2_SEL_TGT_CROP``
+
+ - 0x0000
+
+ - Crop rectangle. Defines the cropped area.
+
+ - Yes
+
+ - Yes
+
+ - .. row 3
+
+ - ``V4L2_SEL_TGT_CROP_DEFAULT``
+
+ - 0x0001
+
+ - Suggested cropping rectangle that covers the "whole picture".
+
+ - Yes
+
+ - No
+
+ - .. row 4
+
+ - ``V4L2_SEL_TGT_CROP_BOUNDS``
+
+ - 0x0002
+
+ - Bounds of the crop rectangle. All valid crop rectangles fit inside
+ the crop bounds rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 5
+
+ - ``V4L2_SEL_TGT_NATIVE_SIZE``
+
+ - 0x0003
+
+ - The native size of the device, e.g. a sensor's pixel array.
+ ``left`` and ``top`` fields are zero for this target. Setting the
+ native size will generally only make sense for memory to memory
+ devices where the software can create a canvas of a given size in
+ which for example a video frame can be composed. In that case
+ V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size of
+ that canvas.
+
+ - Yes
+
+ - Yes
+
+ - .. row 6
+
+ - ``V4L2_SEL_TGT_COMPOSE``
+
+ - 0x0100
+
+ - Compose rectangle. Used to configure scaling and composition.
+
+ - Yes
+
+ - Yes
+
+ - .. row 7
+
+ - ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
+
+ - 0x0101
+
+ - Suggested composition rectangle that covers the "whole picture".
+
+ - Yes
+
+ - No
+
+ - .. row 8
+
+ - ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
+
+ - 0x0102
+
+ - Bounds of the compose rectangle. All valid compose rectangles fit
+ inside the compose bounds rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 9
+
+ - ``V4L2_SEL_TGT_COMPOSE_PADDED``
+
+ - 0x0103
+
+ - The active area and all padding pixels that are inserted or
+ modified by hardware.
+
+ - Yes
+
+ - No
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2spec:
+
+#####################################
+Video for Linux Two API Specification
+#####################################
+
+**Revision 4.4**
+
+.. toctree::
+ :maxdepth: 1
+
+ common
+ pixfmt
+ io
+ devices
+ driver
+ libv4l
+ compat
+ user-func
+ common-defs
+ videodev
+ capture-example
+ v4l2grab-example
+ biblio
+
+
+**********************
+Revision and Copyright
+**********************
+
+
+:author: Schimek Michael (*H*)
+:address: mschimek@gmx.at
+
+:author: Dirks Bill
+:contrib: Original author of the V4L2 API and documentation.
+
+:author: Verkuil Hans
+:address: hverkuil@xs4all.nl
+:contrib: Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API.
+
+:author: Rubli Martin
+:contrib: Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.
+
+:author: Walls Andy
+:address: awalls@md.metrocast.net
+:contrib: Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.
+
+:author: Carvalho Chehab Mauro
+:address: m.chehab@samsung.com
+:contrib: Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.
+
+:author: Karicheri Muralidharan
+:address: m-karicheri2@ti.com
+:contrib: Documented the Digital Video timings API.
+
+:author: Osciak Pawel
+:address: pawel AT osciak.com
+:contrib: Designed and documented the multi-planar API.
+
+:author: Ailus Sakari
+:address: sakari.ailus@iki.fi
+:contrib: Subdev selections API.
+
+:author: Palosaari Antti
+:address: crope@iki.fi
+:contrib: SDR API.
+
+**Copyright** 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 : Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak
+
+Except when explicitly stated as GPL, programming examples within this
+part can be used and distributed without restrictions.
+
+
+:revision: 4.5 / 2015-10-29 (*rr*)
+
+Extend vidioc-g-ext-ctrls;. Replace ctrl_class with a new union with
+ctrl_class and which. Which is used to select the current value of the
+control or the default value.
+
+
+:revision: 4.4 / 2015-05-26 (*ap*)
+
+Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added
+V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for
+Software Defined Radio (SDR) Interface.
+
+
+:revision: 4.1 / 2015-02-13 (*mcc*)
+
+Fix documentation for media controller device nodes and add support for
+DVB device nodes. Add support for Tuner sub-device.
+
+
+:revision: 3.19 / 2014-12-05 (*hv*)
+
+Rewrote Colorspace chapter, added new enum
+:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
+:ref:`v4l2_quantization <v4l2-quantization>` fields to struct
+:ref:`v4l2_pix_format <v4l2-pix-format>`, struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and struct
+:ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
+
+
+:revision: 3.17 / 2014-08-04 (*lp, hv*)
+
+Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added
+format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.
+
+
+:revision: 3.15 / 2014-02-03 (*hv, ap*)
+
+Update several sections of "Common API Elements": "Opening and Closing
+Devices" "Querying Capabilities", "Application Priority", "Video Inputs
+and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video
+Standards" and "Digital Video (DV) Timings". Added SDR API.
+
+
+:revision: 3.14 / 2013-11-25 (*rr*)
+
+Set width and height as unsigned on v4l2_rect.
+
+
+:revision: 3.11 / 2013-05-26 (*hv*)
+
+Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.
+
+
+:revision: 3.10 / 2013-03-25 (*hv*)
+
+Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET,
+VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
+VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
+capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
+Added VIDIOC_DBG_G_CHIP_INFO.
+
+
+:revision: 3.9 / 2012-12-03 (*sa, sn*)
+
+Added timestamp types to v4l2_buffer. Added
+V4L2_EVENT_CTRL_CH_RANGE control event changes flag.
+
+
+:revision: 3.6 / 2012-07-02 (*hv*)
+
+Added VIDIOC_ENUM_FREQ_BANDS.
+
+
+:revision: 3.5 / 2012-05-07 (*sa, sn, hv*)
+
+Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API.
+Improved the description of V4L2_CID_COLORFX control, added
+V4L2_CID_COLORFX_CBCR control. Added camera controls
+V4L2_CID_AUTO_EXPOSURE_BIAS,
+V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE,
+V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY,
+V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING,
+V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK,
+V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP,
+V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added
+VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
+VIDIOC_DV_TIMINGS_CAP.
+
+
+:revision: 3.4 / 2012-01-25 (*sn*)
+
+Added :ref:`JPEG compression control class. <jpeg-controls>`
+
+
+:revision: 3.3 / 2012-01-11 (*hv*)
+
+Added device_caps field to struct v4l2_capabilities.
+
+
+:revision: 3.2 / 2011-08-26 (*hv*)
+
+Added V4L2_CTRL_FLAG_VOLATILE.
+
+
+:revision: 3.1 / 2011-06-27 (*mcc, po, hv*)
+
+Documented that VIDIOC_QUERYCAP now returns a per-subsystem version
+instead of a per-driver one. Standardize an error code for invalid
+ioctl. Added V4L2_CTRL_TYPE_BITMASK.
+
+
+:revision: 2.6.39 / 2011-03-01 (*mcc, po*)
+
+Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect
+latest changes. Added the :ref:`multi-planar API <planar-apis>`.
+
+
+:revision: 2.6.37 / 2010-08-06 (*hv*)
+
+Removed obsolete vtx (videotext) API.
+
+
+:revision: 2.6.33 / 2009-12-03 (*mk*)
+
+Added documentation for the Digital Video timings API.
+
+
+:revision: 2.6.32 / 2009-08-31 (*mcc*)
+
+Now, revisions will match the kernel version where the V4L2 API changes
+will be used by the Linux Kernel. Also added Remote Controller chapter.
+
+
+:revision: 0.29 / 2009-08-26 (*ev*)
+
+Added documentation for string controls and for FM Transmitter controls.
+
+
+:revision: 0.28 / 2009-08-26 (*gl*)
+
+Added V4L2_CID_BAND_STOP_FILTER documentation.
+
+
+:revision: 0.27 / 2009-08-15 (*mcc*)
+
+Added libv4l and Remote Controller documentation; added v4l2grab and
+keytable application examples.
+
+
+:revision: 0.26 / 2009-07-23 (*hv*)
+
+Finalized the RDS capture API. Added modulator and RDS encoder
+capabilities. Added support for string controls.
+
+
+:revision: 0.25 / 2009-01-18 (*hv*)
+
+Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls
+VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera
+controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
+V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.
+
+
+:revision: 0.24 / 2008-03-04 (*mhs*)
+
+Added pixel formats Y16 and SBGGR16, new controls and a camera controls
+class. Removed VIDIOC_G/S_MPEGCOMP.
+
+
+:revision: 0.23 / 2007-08-30 (*mhs*)
+
+Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of
+packed pixel formats.
+
+
+:revision: 0.22 / 2007-08-29 (*mhs*)
+
+Added the Video Output Overlay interface, new MPEG controls,
+V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
+VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
+VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
+Clarifications in the cropping chapter, about RGB pixel formats, the
+mmap(), poll(), select(), read() and write() functions. Typographical
+fixes.
+
+
+:revision: 0.21 / 2006-12-19 (*mhs*)
+
+Fixed a link in the VIDIOC_G_EXT_CTRLS section.
+
+
+:revision: 0.20 / 2006-11-24 (*mhs*)
+
+Clarified the purpose of the audioset field in struct v4l2_input and
+v4l2_output.
+
+
+:revision: 0.19 / 2006-10-19 (*mhs*)
+
+Documented V4L2_PIX_FMT_RGB444.
+
+
+:revision: 0.18 / 2006-10-18 (*mhs*)
+
+Added the description of extended controls by Hans Verkuil. Linked
+V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.
+
+
+:revision: 0.17 / 2006-10-12 (*mhs*)
+
+Corrected V4L2_PIX_FMT_HM12 description.
+
+
+:revision: 0.16 / 2006-10-08 (*mhs*)
+
+VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part
+of the API.
+
+
+:revision: 0.15 / 2006-09-23 (*mhs*)
+
+Cleaned up the bibliography, added BT.653 and BT.1119.
+capture.c/start_capturing() for user pointer I/O did not initialize the
+buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and
+V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See
+the history chapter for API changes.
+
+
+:revision: 0.14 / 2006-09-14 (*mr*)
+
+Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal
+for frame format enumeration of digital devices.
+
+
+:revision: 0.13 / 2006-04-07 (*mhs*)
+
+Corrected the description of struct v4l2_window clips. New V4L2_STD_
+and V4L2_TUNER_MODE_LANG1_LANG2 defines.
+
+
+:revision: 0.12 / 2006-02-03 (*mhs*)
+
+Corrected the description of struct v4l2_captureparm and
+v4l2_outputparm.
+
+
+:revision: 0.11 / 2006-01-27 (*mhs*)
+
+Improved the description of struct v4l2_tuner.
+
+
+:revision: 0.10 / 2006-01-10 (*mhs*)
+
+VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.
+
+
+:revision: 0.9 / 2005-11-27 (*mhs*)
+
+Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the
+sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page.
+Fixed VIDIOC_S_STD call in the video standard selection example.
+Various updates.
+
+
+:revision: 0.8 / 2004-10-04 (*mhs*)
+
+Somehow a piece of junk slipped into the capture example, removed.
+
+
+:revision: 0.7 / 2004-09-19 (*mhs*)
+
+Fixed video standard selection, control enumeration, downscaling and
+aspect example. Added read and user pointer i/o to video capture
+example.
+
+
+:revision: 0.6 / 2004-08-01 (*mhs*)
+
+v4l2_buffer changes, added video capture example, various corrections.
+
+
+:revision: 0.5 / 2003-11-05 (*mhs*)
+
+Pixel format erratum.
+
+
+:revision: 0.4 / 2003-09-17 (*mhs*)
+
+Corrected source and Makefile to generate a PDF. SGML fixes. Added
+latest API changes. Closed gaps in the history chapter.
+
+
+:revision: 0.3 / 2003-02-05 (*mhs*)
+
+Another draft, more corrections.
+
+
+:revision: 0.2 / 2003-01-15 (*mhs*)
+
+Second draft, with corrections pointed out by Gerd Knorr.
+
+
+:revision: 0.1 / 2002-12-01 (*mhs*)
+
+First draft, based on documentation by Bill Dirks and discussions on the
+V4L mailing list.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2grab-example:
+
+**********************************
+Video Grabber example using libv4l
+**********************************
+
+This program demonstrates how to grab V4L2 images in ppm format by using
+libv4l handlers. The advantage is that this grabber can potentially work
+with any V4L2 driver.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ v4l2grab.c
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: media/v4l/v4l2grab.c
+==========================
+
+.. code-block:: c
+
+ /* V4L2 video picture grabber
+ Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org>
+
+ This program 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 program 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.
+ */
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <fcntl.h>
+ #include <errno.h>
+ #include <sys/ioctl.h>
+ #include <sys/types.h>
+ #include <sys/time.h>
+ #include <sys/mman.h>
+ #include <linux/videodev2.h>
+ #include "../libv4l/include/libv4l2.h"
+
+ #define CLEAR(x) memset(&(x), 0, sizeof(x))
+
+ struct buffer {
+ void *start;
+ size_t length;
+ };
+
+ static void xioctl(int fh, int request, void *arg)
+ {
+ int r;
+
+ do {
+ r = v4l2_ioctl(fh, request, arg);
+ } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN)));
+
+ if (r == -1) {
+ fprintf(stderr, "error %d, %s\\n", errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ int main(int argc, char **argv)
+ {
+ struct v4l2_format fmt;
+ struct v4l2_buffer buf;
+ struct v4l2_requestbuffers req;
+ enum v4l2_buf_type type;
+ fd_set fds;
+ struct timeval tv;
+ int r, fd = -1;
+ unsigned int i, n_buffers;
+ char *dev_name = "/dev/video0";
+ char out_name[256];
+ FILE *fout;
+ struct buffer *buffers;
+
+ fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0);
+ if (fd < 0) {
+ perror("Cannot open device");
+ exit(EXIT_FAILURE);
+ }
+
+ CLEAR(fmt);
+ fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ fmt.fmt.pix.width = 640;
+ fmt.fmt.pix.height = 480;
+ fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24;
+ 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");
+ exit(EXIT_FAILURE);
+ }
+ if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480))
+ printf("Warning: driver is sending image at %dx%d\\n",
+ fmt.fmt.pix.width, fmt.fmt.pix.height);
+
+ CLEAR(req);
+ req.count = 2;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_MMAP;
+ xioctl(fd, VIDIOC_REQBUFS, &req);
+
+ buffers = calloc(req.count, sizeof(*buffers));
+ for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = n_buffers;
+
+ xioctl(fd, VIDIOC_QUERYBUF, &buf);
+
+ buffers[n_buffers].length = buf.length;
+ buffers[n_buffers].start = v4l2_mmap(NULL, buf.length,
+ PROT_READ | PROT_WRITE, MAP_SHARED,
+ fd, buf.m.offset);
+
+ if (MAP_FAILED == buffers[n_buffers].start) {
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ for (i = 0; i < n_buffers; ++i) {
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = i;
+ xioctl(fd, VIDIOC_QBUF, &buf);
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ xioctl(fd, VIDIOC_STREAMON, &type);
+ for (i = 0; i < 20; i++) {
+ do {
+ FD_ZERO(&fds);
+ FD_SET(fd, &fds);
+
+ /* Timeout. */
+ tv.tv_sec = 2;
+ tv.tv_usec = 0;
+
+ r = select(fd + 1, &fds, NULL, NULL, &tv);
+ } while ((r == -1 && (errno = EINTR)));
+ if (r == -1) {
+ perror("select");
+ return errno;
+ }
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ xioctl(fd, VIDIOC_DQBUF, &buf);
+
+ sprintf(out_name, "out%03d.ppm", i);
+ fout = fopen(out_name, "w");
+ if (!fout) {
+ perror("Cannot open image");
+ exit(EXIT_FAILURE);
+ }
+ 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);
+
+ xioctl(fd, VIDIOC_QBUF, &buf);
+ }
+
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ xioctl(fd, VIDIOC_STREAMOFF, &type);
+ for (i = 0; i < n_buffers; ++i)
+ v4l2_munmap(buffers[i].start, buffers[i].length);
+ v4l2_close(fd);
+
+ return 0;
+ }
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video:
+
+************************
+Video Inputs and Outputs
+************************
+
+Video inputs and outputs are physical connectors of a device. These can
+be for example RF connectors (antenna/cable), CVBS a.k.a. Composite
+Video, S-Video or RGB connectors. Video and VBI capture devices have
+inputs. Video and VBI output devices have outputs, at least one each.
+Radio devices have no video inputs or outputs.
+
+To learn about the number and attributes of the available inputs and
+outputs applications can enumerate them with the
+:ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` and
+:ref:`VIDIOC_ENUMOUTPUT <vidioc-enumoutput>` ioctl, respectively. The
+struct :ref:`v4l2_input <v4l2-input>` returned by the
+``VIDIOC_ENUMINPUT`` ioctl also contains signal status information
+applicable when the current video input is queried.
+
+The :ref:`VIDIOC_G_INPUT <vidioc-g-input>` and
+:ref:`VIDIOC_G_OUTPUT <vidioc-g-output>` ioctls return the index of
+the current video input or output. To select a different input or output
+applications call the :ref:`VIDIOC_S_INPUT <vidioc-g-input>` and
+:ref:`VIDIOC_S_OUTPUT <vidioc-g-output>` ioctls. Drivers must
+implement all the input ioctls when the device has one or more inputs,
+all the output ioctls when the device has one or more outputs.
+
+
+.. code-block:: c
+
+ struct v4l2_input input;
+ int index;
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ memset(&input, 0, sizeof(input));
+ input.index = index;
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUMINPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input: %s\\n", input.name);
+
+
+.. code-block:: c
+
+ int index;
+
+ index = 0;
+
+ if (-1 == ioctl(fd, VIDIOC_S_INPUT, &index)) {
+ perror("VIDIOC_S_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _videodev:
+
+*******************************
+Video For Linux Two Header File
+*******************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ../../videodev2.h
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-create-bufs:
+
+************************
+ioctl VIDIOC_CREATE_BUFS
+************************
+
+*man VIDIOC_CREATE_BUFS(2)*
+
+Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_create_buffers *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_CREATE_BUFS
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
+or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
+can be used as an alternative or in addition to the
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl, when a tighter control
+over buffers is required. This ioctl can be called multiple times to
+create buffers of different sizes.
+
+To allocate the device buffers applications must initialize the relevant
+fields of the :c:type:`struct v4l2_create_buffers` structure. The
+``count`` field must be set to the number of requested buffers, the
+``memory`` field specifies the requested I/O method and the ``reserved``
+array must be zeroed.
+
+The ``format`` field specifies the image format that the buffers must be
+able to handle. The application has to fill in this struct
+:ref:`v4l2_format <v4l2-format>`. Usually this will be done using the
+:ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` or
+:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctls to ensure that the
+requested format is supported by the driver. Based on the format's
+``type`` field the requested buffer size (for single-planar) or plane
+sizes (for multi-planar formats) will be used for the allocated buffers.
+The driver may return an error if the size(s) are not supported by the
+hardware (usually because they are too small).
+
+The buffers created by this ioctl will have as minimum size the size
+defined by the ``format.pix.sizeimage`` field (or the corresponding
+fields for other format types). Usually if the ``format.pix.sizeimage``
+field is less than the minimum required for the given format, then an
+error will be returned since drivers will typically not allow this. If
+it is larger, then the value will be used as-is. In other words, the
+driver may reject the requested size, but if it is accepted the driver
+will use it unchanged.
+
+When the ioctl is called with a pointer to this structure the driver
+will attempt to allocate up to the requested number of buffers and store
+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.
+
+
+.. _v4l2-create-buffers:
+
+.. flat-table:: struct v4l2_create_buffers
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - The starting buffer index, returned by the driver.
+
+ - .. row 2
+
+ - __u32
+
+ - ``count``
+
+ - The number of buffers requested or granted. If count == 0, then
+ ``VIDIOC_CREATE_BUFS`` will set ``index`` to the current number of
+ created buffers, and it will check the validity of ``memory`` and
+ ``format.type``. If those are invalid -1 is returned and errno is
+ set to EINVAL error code, otherwise ``VIDIOC_CREATE_BUFS`` returns
+ 0. It will never set errno to EBUSY error code in this particular
+ case.
+
+ - .. row 3
+
+ - __u32
+
+ - ``memory``
+
+ - Applications set this field to ``V4L2_MEMORY_MMAP``,
+ ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
+ :ref:`v4l2-memory`
+
+ - .. row 4
+
+ - struct :ref:`v4l2_format <v4l2-format>`
+
+ - ``format``
+
+ - Filled in by the application, preserved by the driver.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - A place holder for future extensions. Drivers and applications
+ must set the array to zero.
+
+
+
+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.
+
+ENOMEM
+ No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
+
+EINVAL
+ The buffer type (``format.type`` field), requested I/O method
+ (``memory``) or format (``format`` field) is not valid.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-cropcap:
+
+********************
+ioctl VIDIOC_CROPCAP
+********************
+
+*man VIDIOC_CROPCAP(2)*
+
+Information about the video cropping and scaling abilities
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_cropcap *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_CROPCAP
+
+``argp``
+
+
+Description
+===========
+
+Applications use this function to query the cropping limits, the pixel
+aspect of images and to calculate scale factors. They set the ``type``
+field of a v4l2_cropcap structure to the respective buffer (stream)
+type and call the ``VIDIOC_CROPCAP`` ioctl with a pointer to this
+structure. Drivers fill the rest of the structure. The results are
+constant except when switching the video standard. Remember this switch
+can occur implicit when switching the video input or output.
+
+Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
+
+This ioctl must be implemented for video capture or output devices that
+support cropping and/or scaling and/or have non-square pixels, and for
+overlay devices.
+
+
+.. _v4l2-cropcap:
+
+.. flat-table:: struct v4l2_cropcap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_rect <v4l2-rect-crop>`
+
+ - ``bounds``
+
+ - Defines the window within capturing or output is possible, this
+ may exclude for example the horizontal and vertical blanking
+ areas. The cropping rectangle cannot exceed these limits. Width
+ and height are defined in pixels, the driver writer is free to
+ choose origin and units of the coordinate system in the analog
+ domain.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_rect <v4l2-rect-crop>`
+
+ - ``defrect``
+
+ - 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
+ as for ``bounds`` is used.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``pixelaspect``
+
+ - This is the pixel aspect (y / x) when no scaling is applied, the
+ ratio of the actual sampling frequency and the frequency required
+ to get square pixels.
+
+ When cropping coordinates refer to square pixels, the driver sets
+ ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
+ SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
+
+
+
+.. _v4l2-rect-crop:
+
+.. flat-table:: struct v4l2_rect
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __s32
+
+ - ``left``
+
+ - Horizontal offset of the top, left corner of the rectangle, in
+ pixels.
+
+ - .. row 2
+
+ - __s32
+
+ - ``top``
+
+ - Vertical offset of the top, left corner of the rectangle, in
+ pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``width``
+
+ - Width of the rectangle, in pixels.
+
+ - .. row 4
+
+ - __u32
+
+ - ``height``
+
+ - Height of the rectangle, in pixels.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is
+ invalid.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-dbg-g-chip-info:
+
+****************************
+ioctl VIDIOC_DBG_G_CHIP_INFO
+****************************
+
+*man VIDIOC_DBG_G_CHIP_INFO(2)*
+
+Identify the chips on a TV card
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_dbg_chip_info *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DBG_G_CHIP_INFO
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`experimental <experimental>` interface and may
+ change in the future.
+
+For driver debugging purposes this ioctl allows test applications to
+query the driver about the chips present on the TV card. Regular
+applications must not use it. When you found a chip specific bug, please
+contact the linux-media mailing list
+(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
+so it can be fixed.
+
+Additionally the Linux kernel must be compiled with the
+``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl.
+
+To query the driver applications must initialize the ``match.type`` and
+``match.addr`` or ``match.name`` fields of a struct
+:ref:`v4l2_dbg_chip_info <v4l2-dbg-chip-info>` and call
+``VIDIOC_DBG_G_CHIP_INFO`` with a pointer to this structure. On success
+the driver stores information about the selected chip in the ``name``
+and ``flags`` fields.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
+selects the nth bridge 'chip' on the TV card. You can enumerate all
+chips by starting at zero and incrementing ``match.addr`` by one until
+``VIDIOC_DBG_G_CHIP_INFO`` fails with an EINVAL error code. The number
+zero always selects the bridge chip itself, e. g. the chip connected to
+the PCI or USB bus. Non-zero numbers identify specific parts of the
+bridge chip such as an AC97 register block.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
+selects the nth sub-device. This allows you to enumerate over all
+sub-devices.
+
+On success, the ``name`` field will contain a chip name and the
+``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver
+supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE``
+if the driver supports writing registers to the device.
+
+We recommended the v4l2-dbg utility over calling this ioctl directly. It
+is available from the LinuxTV v4l-dvb repository; see
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
+
+
+.. _name-v4l2-dbg-match:
+
+.. flat-table:: struct v4l2_dbg_match
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - See :ref:`name-chip-match-types` for a list of possible types.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``addr``
+
+ - Match a chip by this number, interpreted according to the ``type``
+ field.
+
+ - .. row 4
+
+ -
+ - char
+
+ - ``name[32]``
+
+ - Match a chip by this name, interpreted according to the ``type``
+ field. Currently unused.
+
+
+
+.. _v4l2-dbg-chip-info:
+
+.. flat-table:: struct v4l2_dbg_chip_info
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct v4l2_dbg_match
+
+ - ``match``
+
+ - How to match the chip, see :ref:`name-v4l2-dbg-match`.
+
+ - .. row 2
+
+ - char
+
+ - ``name[32]``
+
+ - The name of the chip.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the
+ driver supports reading registers from the device. If
+ ``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing
+ registers.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved[8]``
+
+ - Reserved fields, both application and driver must set these to 0.
+
+
+
+.. _name-chip-match-types:
+
+.. flat-table:: Chip Match Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CHIP_MATCH_BRIDGE``
+
+ - 0
+
+ - Match the nth chip on the card, zero for the bridge chip. Does not
+ match sub-devices.
+
+ - .. row 2
+
+ - ``V4L2_CHIP_MATCH_SUBDEV``
+
+ - 4
+
+ - Match the nth sub-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.
+
+EINVAL
+ The ``match_type`` is invalid or no device could be matched.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-dbg-g-register:
+
+**************************************************
+ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
+**************************************************
+
+*man VIDIOC_DBG_G_REGISTER(2)*
+
+VIDIOC_DBG_S_REGISTER
+Read or write hardware registers
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_dbg_register *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_dbg_register *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`experimental <experimental>` interface and may
+ change in the future.
+
+For driver debugging purposes these ioctls allow test applications to
+access hardware registers directly. Regular applications must not use
+them.
+
+Since writing or even reading registers can jeopardize the system
+security, its stability and damage the hardware, both ioctls require
+superuser privileges. Additionally the Linux kernel must be compiled
+with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.
+
+To write a register applications must initialize all fields of a struct
+:ref:`v4l2_dbg_register <v4l2-dbg-register>` except for ``size`` and
+call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
+``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
+on the TV card, the ``reg`` field specifies a register number and the
+``val`` field the value to be written into the register.
+
+To read a register applications must initialize the ``match.type``,
+``match.addr`` or ``match.name`` and ``reg`` fields, and call
+``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success
+the driver stores the register value in the ``val`` field and the size
+(in bytes) of the value in ``size``.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
+selects the nth non-sub-device chip on the TV card. The number zero
+always selects the host chip, e. g. the chip connected to the PCI or USB
+bus. You can find out which chips are present with the
+:ref:`VIDIOC_DBG_G_CHIP_INFO <vidioc-dbg-g-chip-info>` ioctl.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
+selects the nth sub-device.
+
+These ioctls are optional, not all drivers may support them. However
+when a driver supports these ioctls it must also support
+:ref:`VIDIOC_DBG_G_CHIP_INFO <vidioc-dbg-g-chip-info>`. Conversely
+it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.
+
+``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
+in Linux 2.6.21, but their API was changed to the one described here in
+kernel 2.6.29.
+
+We recommended the v4l2-dbg utility over calling these ioctls directly.
+It is available from the LinuxTV v4l-dvb repository; see
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
+
+
+.. _v4l2-dbg-match:
+
+.. flat-table:: struct v4l2_dbg_match
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - See :ref:`chip-match-types` for a list of possible types.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``addr``
+
+ - Match a chip by this number, interpreted according to the ``type``
+ field.
+
+ - .. row 4
+
+ -
+ - char
+
+ - ``name[32]``
+
+ - Match a chip by this name, interpreted according to the ``type``
+ field. Currently unused.
+
+
+
+.. _v4l2-dbg-register:
+
+.. flat-table:: struct v4l2_dbg_register
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct v4l2_dbg_match
+
+ - ``match``
+
+ - How to match the chip, see :ref:`v4l2-dbg-match`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``size``
+
+ - The register size in bytes.
+
+ - .. row 3
+
+ - __u64
+
+ - ``reg``
+
+ - A register number.
+
+ - .. row 4
+
+ - __u64
+
+ - ``val``
+
+ - The value read from, or to be written into the register.
+
+
+
+.. _chip-match-types:
+
+.. flat-table:: Chip Match Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CHIP_MATCH_BRIDGE``
+
+ - 0
+
+ - Match the nth chip on the card, zero for the bridge chip. Does not
+ match sub-devices.
+
+ - .. row 2
+
+ - ``V4L2_CHIP_MATCH_SUBDEV``
+
+ - 4
+
+ - Match the nth sub-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.
+
+EPERM
+ Insufficient permissions. Root privileges are required to execute
+ these ioctls.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-decoder-cmd:
+
+************************************************
+ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
+************************************************
+
+*man VIDIOC_DECODER_CMD(2)*
+
+VIDIOC_TRY_DECODER_CMD
+Execute an decoder command
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_decoder_cmd *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
+
+``argp``
+
+
+Description
+===========
+
+These ioctls control an audio/video (usually MPEG-) decoder.
+``VIDIOC_DECODER_CMD`` sends a command to the decoder,
+``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually
+executing it. To send a command applications must initialize all fields
+of a struct :ref:`v4l2_decoder_cmd <v4l2-decoder-cmd>` and call
+``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to
+this structure.
+
+The ``cmd`` field must contain the command code. Some commands use the
+``flags`` field for additional information.
+
+A :c:func:`write()`() or :ref:`VIDIOC_STREAMON <vidioc-streamon>`
+call sends an implicit START command to the decoder if it has not been
+started yet.
+
+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.
+
+These ioctls are optional, not all drivers may support them. They were
+introduced in Linux 3.3.
+
+
+.. _v4l2-decoder-cmd:
+
+.. flat-table:: struct v4l2_decoder_cmd
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``cmd``
+
+ -
+ -
+ - The decoder command, see :ref:`decoder-cmds`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Flags to go with the command. If no flags are defined for this
+ command, drivers and applications must set this field to zero.
+
+ - .. row 3
+
+ - union
+
+ - (anonymous)
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - struct
+
+ - ``start``
+
+ -
+ - Structure containing additional data for the
+ ``V4L2_DEC_CMD_START`` command.
+
+ - .. row 5
+
+ -
+ -
+ - __s32
+
+ - ``speed``
+
+ - Playback speed and direction. The playback speed is defined as
+ ``speed``/1000 of the normal speed. So 1000 is normal playback.
+ Negative numbers denote reverse playback, so -1000 does reverse
+ playback at normal speed. Speeds -1, 0 and 1 have special
+ meanings: speed 0 is shorthand for 1000 (normal playback). A speed
+ of 1 steps just one frame forward, a speed of -1 steps just one
+ frame back.
+
+ - .. row 6
+
+ -
+ -
+ - __u32
+
+ - ``format``
+
+ - Format restrictions. This field is set by the driver, not the
+ application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if
+ there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if
+ the decoder operates on full GOPs (*Group Of Pictures*). This is
+ usually the case for reverse playback: the decoder needs full
+ GOPs, which it can then play in reverse order. So to implement
+ reverse playback the application must feed the decoder the last
+ GOP in the video file, then the GOP before that, etc. etc.
+
+ - .. row 7
+
+ -
+ - struct
+
+ - ``stop``
+
+ -
+ - Structure containing additional data for the ``V4L2_DEC_CMD_STOP``
+ command.
+
+ - .. row 8
+
+ -
+ -
+ - __u64
+
+ - ``pts``
+
+ - Stop playback at this ``pts`` or immediately if the playback is
+ already past that timestamp. Leave to 0 if you want to stop after
+ the last frame was decoded.
+
+ - .. row 9
+
+ -
+ - struct
+
+ - ``raw``
+
+ -
+ -
+
+ - .. row 10
+
+ -
+ -
+ - __u32
+
+ - ``data``\ [16]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _decoder-cmds:
+
+.. flat-table:: Decoder Commands
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_DEC_CMD_START``
+
+ - 0
+
+ - Start the decoder. When the decoder is already running or paused,
+ this command will just change the playback speed. That means that
+ calling ``V4L2_DEC_CMD_START`` when the decoder was paused will
+ *not* resume the decoder. You have to explicitly call
+ ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag:
+ ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be
+ muted when playing back at a non-standard speed.
+
+ - .. row 2
+
+ - ``V4L2_DEC_CMD_STOP``
+
+ - 1
+
+ - Stop the decoder. When the decoder is already stopped, this
+ command does nothing. This command has two flags: if
+ ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set
+ the picture to black after it stopped decoding. Otherwise the last
+ image will repeat. mem2mem decoders will stop producing new frames
+ altogether. They will send a ``V4L2_EVENT_EOS`` event when the
+ last frame has been decoded 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. If
+ ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops
+ immediately (ignoring the ``pts`` value), otherwise it will keep
+ decoding until timestamp >= pts or until the last of the pending
+ data from its internal buffers was decoded.
+
+ - .. row 3
+
+ - ``V4L2_DEC_CMD_PAUSE``
+
+ - 2
+
+ - Pause the decoder. When the decoder has not been started yet, the
+ driver will return an EPERM error code. When the decoder is
+ already paused, this command does nothing. This command has one
+ flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the
+ decoder output to black when paused.
+
+ - .. row 4
+
+ - ``V4L2_DEC_CMD_RESUME``
+
+ - 3
+
+ - Resume decoding after a PAUSE command. When the decoder has not
+ been started yet, the driver will return an EPERM error code. When
+ the decoder is already running, this command does nothing. No
+ flags are defined for this 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.
+
+EINVAL
+ The ``cmd`` field is invalid.
+
+EPERM
+ The application sent a PAUSE or RESUME command when the decoder was
+ not running.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-dqevent:
+
+********************
+ioctl VIDIOC_DQEVENT
+********************
+
+*man VIDIOC_DQEVENT(2)*
+
+Dequeue event
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_event *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DQEVENT
+
+``argp``
+
+
+Description
+===========
+
+Dequeue an event from a video device. No input is required for this
+ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>`
+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.
+
+
+.. _v4l2-event:
+
+.. flat-table:: struct v4l2_event
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the event, see :ref:`event-type`.
+
+ - .. row 2
+
+ - union
+
+ - ``u``
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_event_vsync <v4l2-event-vsync>`
+
+ - ``vsync``
+
+ - Event data for event ``V4L2_EVENT_VSYNC``.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>`
+
+ - ``ctrl``
+
+ - Event data for event ``V4L2_EVENT_CTRL``.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
+
+ - ``frame_sync``
+
+ - Event data for event ``V4L2_EVENT_FRAME_SYNC``.
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
+
+ - ``motion_det``
+
+ - Event data for event V4L2_EVENT_MOTION_DET.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_event_src_change <v4l2-event-src-change>`
+
+ - ``src_change``
+
+ - Event data for event V4L2_EVENT_SOURCE_CHANGE.
+
+ - .. row 8
+
+ -
+ - __u8
+
+ - ``data``\ [64]
+
+ - Event data. Defined by the event type. The union should be used to
+ define easily accessible type for events.
+
+ - .. row 9
+
+ - __u32
+
+ - ``pending``
+
+ -
+ - Number of pending events excluding this one.
+
+ - .. row 10
+
+ - __u32
+
+ - ``sequence``
+
+ -
+ - Event sequence number. The sequence number is incremented for
+ every subscribed event that takes place. If sequence numbers are
+ not contiguous it means that events have been lost.
+
+ - .. row 11
+
+ - struct timespec
+
+ - ``timestamp``
+
+ -
+ - Event timestamp. The timestamp has been taken from the
+ ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2,
+ use :c:func:`clock_gettime(2)`.
+
+ - .. row 12
+
+ - u32
+
+ - ``id``
+
+ -
+ - The ID associated with the event source. If the event does not
+ have an associated ID (this depends on the event type), then this
+ is 0.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ -
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _event-type:
+
+.. flat-table:: Event Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_ALL``
+
+ - 0
+
+ - All events. V4L2_EVENT_ALL is valid only for
+ VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_VSYNC``
+
+ - 1
+
+ - This event is triggered on the vertical sync. This event has a
+ struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated
+ with it.
+
+ - .. row 3
+
+ - ``V4L2_EVENT_EOS``
+
+ - 2
+
+ - This event is triggered when the end of a stream is reached. This
+ is typically used with MPEG decoders to report to the application
+ when the last of the MPEG stream has been decoded.
+
+ - .. row 4
+
+ - ``V4L2_EVENT_CTRL``
+
+ - 3
+
+ - This event requires that the ``id`` matches the control ID from
+ which you want to receive events. This event is triggered if the
+ control's value changes, if a button control is pressed or if the
+ control's flags change. This event has a struct
+ :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it.
+ This struct contains much of the same information as struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct
+ :ref:`v4l2_control <v4l2-control>`.
+
+ If the event is generated due to a call to
+ :ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` or
+ :ref:`VIDIOC_S_EXT_CTRLS <vidioc-g-ext-ctrls>`, then the
+ event will *not* be sent to the file handle that called the ioctl
+ function. This prevents nasty feedback loops. If you *do* want to
+ get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
+ flag.
+
+ This event type will ensure that no information is lost when more
+ events are raised than there is room internally. In that case the
+ struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the
+ second-oldest event is kept, but the ``changes`` field of the
+ second-oldest event is ORed with the ``changes`` field of the
+ oldest event.
+
+ - .. row 5
+
+ - ``V4L2_EVENT_FRAME_SYNC``
+
+ - 4
+
+ - Triggered immediately when the reception of a frame has begun.
+ This event has a struct
+ :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
+ associated with it.
+
+ If the hardware needs to be stopped in the case of a buffer
+ underrun it might not be able to generate this event. In such
+ cases the ``frame_sequence`` field in struct
+ :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not
+ be incremented. This causes two consecutive frame sequence numbers
+ to have n times frame interval in between them.
+
+ - .. row 6
+
+ - ``V4L2_EVENT_SOURCE_CHANGE``
+
+ - 5
+
+ - This event is triggered when a source parameter change is detected
+ during runtime by the video device. It can be a runtime resolution
+ change triggered by a video decoder or the format change happening
+ on an input connector. This event requires that the ``id`` matches
+ the input index (when used with a video device node) or the pad
+ index (when used with a subdevice node) from which you want to
+ receive events.
+
+ This event has a struct
+ :ref:`v4l2_event_src_change <v4l2-event-src-change>`
+ associated with it. The ``changes`` bitfield denotes what has
+ changed for the subscribed pad. If multiple events occurred before
+ application could dequeue them, then the changes will have the
+ ORed value of all the events generated.
+
+ - .. row 7
+
+ - ``V4L2_EVENT_MOTION_DET``
+
+ - 6
+
+ - Triggered whenever the motion detection state for one or more of
+ the regions changes. This event has a struct
+ :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
+ associated with it.
+
+ - .. row 8
+
+ - ``V4L2_EVENT_PRIVATE_START``
+
+ - 0x08000000
+
+ - Base event number for driver-private events.
+
+
+
+.. _v4l2-event-vsync:
+
+.. flat-table:: struct v4l2_event_vsync
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``field``
+
+ - The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`.
+
+
+
+.. _v4l2-event-ctrl:
+
+.. flat-table:: struct v4l2_event_ctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``changes``
+
+ -
+ - A bitmask that tells what has changed. See
+ :ref:`ctrl-changes-flags`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ -
+ - The type of the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`.
+
+ - .. row 3
+
+ - union (anonymous)
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __s32
+
+ - ``value``
+
+ - The 32-bit value of the control for 32-bit control types. This is
+ 0 for string controls since the value of a string cannot be passed
+ using :ref:`VIDIOC_DQEVENT <vidioc-dqevent>`.
+
+ - .. row 5
+
+ -
+ - __s64
+
+ - ``value64``
+
+ - The 64-bit value of the control for 64-bit control types.
+
+ - .. row 6
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - The control flags. See :ref:`control-flags`.
+
+ - .. row 7
+
+ - __s32
+
+ - ``minimum``
+
+ -
+ - The minimum value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 8
+
+ - __s32
+
+ - ``maximum``
+
+ -
+ - The maximum value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 9
+
+ - __s32
+
+ - ``step``
+
+ -
+ - The step value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 10
+
+ - __s32
+
+ - ``default_value``
+
+ -
+ - The default value value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+
+
+.. _v4l2-event-frame-sync:
+
+.. flat-table:: struct v4l2_event_frame_sync
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``frame_sequence``
+
+ - The sequence number of the frame being received.
+
+
+
+.. _v4l2-event-src-change:
+
+.. flat-table:: struct v4l2_event_src_change
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``changes``
+
+ - A bitmask that tells what has changed. See
+ :ref:`src-changes-flags`.
+
+
+
+.. _v4l2-event-motion-det:
+
+.. flat-table:: struct v4l2_event_motion_det
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``flags``
+
+ - Currently only one flag is available: if
+ ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the
+ ``frame_sequence`` field is valid, otherwise that field should be
+ ignored.
+
+ - .. row 2
+
+ - __u32
+
+ - ``frame_sequence``
+
+ - The sequence number of the frame being received. Only valid if the
+ ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set.
+
+ - .. row 3
+
+ - __u32
+
+ - ``region_mask``
+
+ - The bitmask of the regions that reported motion. There is at least
+ one region. If this field is 0, then no motion was detected at
+ all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control
+ (see :ref:`detect-controls`) to assign a different region to
+ each cell in the motion detection grid, then that all cells are
+ automatically assigned to the default region 0.
+
+
+
+.. _ctrl-changes-flags:
+
+.. flat-table:: Control Changes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_CTRL_CH_VALUE``
+
+ - 0x0001
+
+ - This control event was triggered because the value of the control
+ changed. Special cases: Volatile controls do no generate this
+ event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
+ flag set, then this event is sent as well, regardless its value.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_CTRL_CH_FLAGS``
+
+ - 0x0002
+
+ - This control event was triggered because the control flags
+ changed.
+
+ - .. row 3
+
+ - ``V4L2_EVENT_CTRL_CH_RANGE``
+
+ - 0x0004
+
+ - This control event was triggered because the minimum, maximum,
+ step or the default value of the control changed.
+
+
+
+.. _src-changes-flags:
+
+.. flat-table:: Source Changes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_SRC_CH_RESOLUTION``
+
+ - 0x0001
+
+ - This event gets triggered when a resolution change is detected at
+ an input. This can come from an input connector or from a video
+ 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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-dv-timings-cap:
+
+*********************************************************
+ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
+*********************************************************
+
+*man VIDIOC_DV_TIMINGS_CAP(2)*
+
+VIDIOC_SUBDEV_DV_TIMINGS_CAP
+The capabilities of the Digital Video receiver/transmitter
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_dv_timings_cap *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
+
+``argp``
+
+
+Description
+===========
+
+To query the capabilities of the DV receiver/transmitter applications
+initialize the ``pad`` field to 0, zero the reserved array of struct
+:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` and call the
+``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill
+in the structure. Note that drivers may return different values after
+switching the video input or output.
+
+When implemented by the driver DV capabilities of subdevices can be
+queried by calling the ``VIDIOC_SUBDEV_DV_TIMINGS_CAP`` ioctl directly
+on a subdevice node. The capabilities are specific to inputs (for DV
+receivers) or outputs (for DV transmitters), applications must specify
+the desired pad number in the struct
+:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` ``pad`` field and
+zero the ``reserved`` array. Attempts to query capabilities on a pad
+that doesn't support them will return an EINVAL error code.
+
+
+.. _v4l2-bt-timings-cap:
+
+.. flat-table:: struct v4l2_bt_timings_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum width of the active video in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum width of the active video in pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum height of the active video in lines.
+
+ - .. row 4
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum height of the active video in lines.
+
+ - .. row 5
+
+ - __u64
+
+ - ``min_pixelclock``
+
+ - Minimum pixelclock frequency in Hz.
+
+ - .. row 6
+
+ - __u64
+
+ - ``max_pixelclock``
+
+ - Maximum pixelclock frequency in Hz.
+
+ - .. row 7
+
+ - __u32
+
+ - ``standards``
+
+ - The video standard(s) supported by the hardware. See
+ :ref:`dv-bt-standards` for a list of standards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``capabilities``
+
+ - Several flags giving more information about the capabilities. See
+ :ref:`dv-bt-cap-capabilities` for a description of the flags.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [16]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-dv-timings-cap:
+
+.. flat-table:: struct v4l2_dv_timings_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of DV timings as listed in :ref:`dv-timing-types`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API. This field is
+ only used when operating on a subdevice node. When operating on a
+ video node applications must set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - union
+
+ -
+ -
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_bt_timings_cap <v4l2-bt-timings-cap>`
+
+ - ``bt``
+
+ - BT.656/1120 timings capabilities of the hardware.
+
+ - .. row 6
+
+ -
+ - __u32
+
+ - ``raw_data``\ [32]
+
+ -
+
+
+
+.. _dv-bt-cap-capabilities:
+
+.. flat-table:: DV BT Timing capabilities
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - V4L2_DV_BT_CAP_INTERLACED
+
+ - Interlaced formats are supported.
+
+ - .. row 4
+
+ - V4L2_DV_BT_CAP_PROGRESSIVE
+
+ - Progressive formats are supported.
+
+ - .. row 5
+
+ - V4L2_DV_BT_CAP_REDUCED_BLANKING
+
+ - CVT/GTF specific: the timings can make use of reduced blanking
+ (CVT) or the 'Secondary GTF' curve (GTF).
+
+ - .. row 6
+
+ - V4L2_DV_BT_CAP_CUSTOM
+
+ - Can support non-standard timings, i.e. timings not belonging to
+ the standards set in the ``standards`` field.
+
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-encoder-cmd:
+
+************************************************
+ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
+************************************************
+
+*man VIDIOC_ENCODER_CMD(2)*
+
+VIDIOC_TRY_ENCODER_CMD
+Execute an encoder command
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_encoder_cmd *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
+
+``argp``
+
+
+Description
+===========
+
+These ioctls control an audio/video (usually MPEG-) encoder.
+``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
+``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
+executing it.
+
+To send a command applications must initialize all fields of a struct
+:ref:`v4l2_encoder_cmd <v4l2-encoder-cmd>` and call
+``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.
+
+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. After a STOP command, :c:func:`read()`() calls will read
+the remaining data buffered by the driver. When the buffer is empty,
+:c:func:`read()`() will return zero and the next :c:func:`read()`()
+call will restart the encoder.
+
+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.
+
+These ioctls are optional, not all drivers may support them. They were
+introduced in Linux 2.6.21.
+
+
+.. _v4l2-encoder-cmd:
+
+.. flat-table:: struct v4l2_encoder_cmd
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``cmd``
+
+ - The encoder command, see :ref:`encoder-cmds`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ - Flags to go with the command, see :ref:`encoder-flags`. If no
+ flags are defined for this command, drivers and applications must
+ set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``data``\ [8]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _encoder-cmds:
+
+.. flat-table:: Encoder Commands
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_CMD_START``
+
+ - 0
+
+ - Start the encoder. When the encoder is already running or paused,
+ this command does nothing. No flags are defined for this command.
+
+ - .. row 2
+
+ - ``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.
+
+ - .. row 3
+
+ - ``V4L2_ENC_CMD_PAUSE``
+
+ - 2
+
+ - Pause the encoder. When the encoder has not been started yet, the
+ driver will return an EPERM error code. When the encoder is
+ already paused, this command does nothing. No flags are defined
+ for this command.
+
+ - .. row 4
+
+ - ``V4L2_ENC_CMD_RESUME``
+
+ - 3
+
+ - Resume encoding after a PAUSE command. When the encoder has not
+ been started yet, the driver will return an EPERM error code. When
+ the encoder is already running, this command does nothing. No
+ flags are defined for this command.
+
+
+
+.. _encoder-flags:
+
+.. flat-table:: Encoder Command Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
+
+ - 0x0001
+
+ - Stop encoding at the end of the current *Group Of Pictures*,
+ rather than immediately.
+
+
+
+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.
+
+EINVAL
+ The ``cmd`` field is invalid.
+
+EPERM
+ The application sent a PAUSE or RESUME command when the encoder was
+ not running.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enum-dv-timings:
+
+***********************************************************
+ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+***********************************************************
+
+*man VIDIOC_ENUM_DV_TIMINGS(2)*
+
+VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+Enumerate supported Digital Video timings
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_enum_dv_timings *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+While some DV receivers or transmitters support a wide range of timings,
+others support only a limited number of timings. With this ioctl
+applications can enumerate a list of known supported timings. Call
+:ref:`VIDIOC_DV_TIMINGS_CAP <vidioc-dv-timings-cap>` to check if it
+also supports other standards or even custom timings that are not in
+this list.
+
+To query the available timings, applications initialize the ``index``
+field, set the ``pad`` field to 0, zero the reserved array of struct
+:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` and call the
+``VIDIOC_ENUM_DV_TIMINGS`` ioctl on a video node with a pointer to this
+structure. Drivers fill the rest of the structure or return an EINVAL
+error code when the index is out of bounds. To enumerate all supported
+DV timings, applications shall begin at index zero, incrementing by one
+until the driver returns EINVAL. Note that drivers may enumerate a
+different set of DV timings after switching the video input or output.
+
+When implemented by the driver DV timings of subdevices can be queried
+by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a
+subdevice node. The DV timings are specific to inputs (for DV receivers)
+or outputs (for DV transmitters), applications must specify the desired
+pad number in the struct
+:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` ``pad`` field.
+Attempts to enumerate timings on a pad that doesn't support them will
+return an EINVAL error code.
+
+
+.. _v4l2-enum-dv-timings:
+
+.. flat-table:: struct v4l2_enum_dv_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the DV timings, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API. This field is
+ only used when operating on a subdevice node. When operating on a
+ video node applications must set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
+
+ - ``timings``
+
+ - The timings.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>`
+ ``index`` is out of bounds or the ``pad`` number is invalid.
+
+ENODATA
+ Digital video presets are not supported for this input or output.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enum-fmt:
+
+*********************
+ioctl VIDIOC_ENUM_FMT
+*********************
+
+*man VIDIOC_ENUM_FMT(2)*
+
+Enumerate image formats
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_fmtdesc *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FMT
+
+``argp``
+
+
+Description
+===========
+
+To enumerate image formats applications initialize the ``type`` and
+``index`` field of struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` and call
+the ``VIDIOC_ENUM_FMT`` ioctl with a pointer to this structure. Drivers
+fill the rest of the structure or return an EINVAL error code. All
+formats are enumerable by beginning at index zero and incrementing by
+one until EINVAL is returned.
+
+Note that after switching input or output the list of enumerated image
+formats may be different.
+
+
+.. _v4l2-fmtdesc:
+
+.. flat-table:: struct v4l2_fmtdesc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+ This is in no way related to the ``pixelformat`` field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - See :ref:`fmtdesc-flags`
+
+ - .. row 4
+
+ - __u8
+
+ - ``description``\ [32]
+
+ - Description of the format, a NUL-terminated ASCII string. This
+ information is intended for the user, for example: "YUV 4:2:2".
+
+ - .. row 5
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The image format identifier. This is a four character code as
+ computed by the v4l2_fourcc() macro:
+
+ - .. row 6
+
+ - :cspan:`2`
+
+
+ .. _v4l2-fourcc:
+ .. code-block:: c
+
+ #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
+
+ Several image formats are already defined by this specification in
+ :ref:`pixfmt`. Note these codes are not the same as those used
+ in the Windows world.
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _fmtdesc-flags:
+
+.. flat-table:: Image Format Description Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FMT_FLAG_COMPRESSED``
+
+ - 0x0001
+
+ - This is a compressed format.
+
+ - .. row 2
+
+ - ``V4L2_FMT_FLAG_EMULATED``
+
+ - 0x0002
+
+ - This format is not native to the device but emulated through
+ software (usually libv4l2), where possible try to use a native
+ format instead for better performance.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` ``type`` is not
+ supported or the ``index`` is out of bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enum-frameintervals:
+
+********************************
+ioctl VIDIOC_ENUM_FRAMEINTERVALS
+********************************
+
+*man VIDIOC_ENUM_FRAMEINTERVALS(2)*
+
+Enumerate frame intervals
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_frmivalenum *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FRAMEINTERVALS
+
+``argp``
+ Pointer to a struct :ref:`v4l2_frmivalenum <v4l2-frmivalenum>`
+ structure that contains a pixel format and size and receives a frame
+ interval.
+
+
+Description
+===========
+
+This ioctl allows applications to enumerate all frame intervals that the
+device supports for the given pixel format and frame size.
+
+The supported pixel formats and frame sizes can be obtained by using the
+:ref:`VIDIOC_ENUM_FMT <vidioc-enum-fmt>` and
+:ref:`VIDIOC_ENUM_FRAMESIZES <vidioc-enum-framesizes>` functions.
+
+The return value and the content of the ``v4l2_frmivalenum.type`` field
+depend on the type of frame intervals the device supports. Here are the
+semantics of the function for the different cases:
+
+- **Discrete:** The function returns success if the given index value
+ (zero-based) is valid. The application should increase the index by
+ one for each call until ``EINVAL`` is returned. The
+ `v4l2_frmivalenum.type` field is set to
+ `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only
+ the `discrete` member is valid.
+
+- **Step-wise:** The function returns success if the given index value
+ is zero and ``EINVAL`` for any other index value. The
+ ``v4l2_frmivalenum.type`` field is set to
+ ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the
+ ``stepwise`` member is valid.
+
+- **Continuous:** This is a special case of the step-wise type above.
+ The function returns success if the given index value is zero and
+ ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type``
+ field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of
+ the union only the ``stepwise`` member is valid and the ``step``
+ value is set to 1.
+
+When the application calls the function with index zero, it must check
+the ``type`` field to determine the type of frame interval enumeration
+the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type
+does it make sense to increase the index value to receive more frame
+intervals.
+
+Note that the order in which the frame intervals are returned has no
+special meaning. In particular does it not say anything about potential
+default frame intervals.
+
+Applications can assume that the enumeration data does not change
+without any interaction from the application itself. This means that the
+enumeration data is consistent if the application does not perform any
+other ioctl calls while it runs the frame interval enumeration.
+
+
+Notes
+=====
+
+- **Frame intervals and frame rates:** The V4L2 API uses frame
+ intervals instead of frame rates. Given the frame interval the frame
+ rate can be computed as follows:
+
+
+
+ ::
+
+ frame_rate = 1 / frame_interval
+
+
+Structs
+=======
+
+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.
+
+
+.. _v4l2-frmival-stepwise:
+
+.. flat-table:: struct v4l2_frmival_stepwise
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``min``
+
+ - Minimum frame interval [s].
+
+ - .. row 2
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``max``
+
+ - Maximum frame interval [s].
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``step``
+
+ - Frame interval step size [s].
+
+
+
+.. _v4l2-frmivalenum:
+
+.. flat-table:: struct v4l2_frmivalenum
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - IN: Index of the given frame interval in the enumeration.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pixel_format``
+
+ -
+ - IN: Pixel format for which the frame intervals are enumerated.
+
+ - .. row 3
+
+ - __u32
+
+ - ``width``
+
+ -
+ - IN: Frame width for which the frame intervals are enumerated.
+
+ - .. row 4
+
+ - __u32
+
+ - ``height``
+
+ -
+ - IN: Frame height for which the frame intervals are enumerated.
+
+ - .. row 5
+
+ - __u32
+
+ - ``type``
+
+ -
+ - OUT: Frame interval type the device supports.
+
+ - .. row 6
+
+ - union
+
+ -
+ -
+ - OUT: Frame interval with the given index.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``discrete``
+
+ - Frame interval [s].
+
+ - .. row 8
+
+ -
+ - struct :ref:`v4l2_frmival_stepwise <v4l2-frmival-stepwise>`
+
+ - ``stepwise``
+
+ -
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved[2]``
+
+ -
+ - Reserved space for future use. Must be zeroed by drivers and
+ applications.
+
+
+
+Enums
+=====
+
+
+.. _v4l2-frmivaltypes:
+
+.. flat-table:: enum v4l2_frmivaltypes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FRMIVAL_TYPE_DISCRETE``
+
+ - 1
+
+ - Discrete frame interval.
+
+ - .. row 2
+
+ - ``V4L2_FRMIVAL_TYPE_CONTINUOUS``
+
+ - 2
+
+ - Continuous frame interval.
+
+ - .. row 3
+
+ - ``V4L2_FRMIVAL_TYPE_STEPWISE``
+
+ - 3
+
+ - Step-wise defined frame interval.
+
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enum-framesizes:
+
+****************************
+ioctl VIDIOC_ENUM_FRAMESIZES
+****************************
+
+*man VIDIOC_ENUM_FRAMESIZES(2)*
+
+Enumerate frame sizes
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_frmsizeenum *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FRAMESIZES
+
+``argp``
+ Pointer to a struct :ref:`v4l2_frmsizeenum <v4l2-frmsizeenum>`
+ that contains an index and pixel format and receives a frame width
+ and height.
+
+
+Description
+===========
+
+This ioctl allows applications to enumerate all frame sizes (i. e. width
+and height in pixels) that the device supports for the given pixel
+format.
+
+The supported pixel formats can be obtained by using the
+:ref:`VIDIOC_ENUM_FMT <vidioc-enum-fmt>` function.
+
+The return value and the content of the ``v4l2_frmsizeenum.type`` field
+depend on the type of frame sizes the device supports. Here are the
+semantics of the function for the different cases:
+
+- **Discrete:** The function returns success if the given index value
+ (zero-based) is valid. The application should increase the index by
+ one for each call until ``EINVAL`` is returned. The
+ ``v4l2_frmsizeenum.type`` field is set to
+ ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
+ ``discrete`` member is valid.
+
+- **Step-wise:** The function returns success if the given index value
+ is zero and ``EINVAL`` for any other index value. The
+ ``v4l2_frmsizeenum.type`` field is set to
+ ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
+ ``stepwise`` member is valid.
+
+- **Continuous:** This is a special case of the step-wise type above.
+ The function returns success if the given index value is zero and
+ ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
+ field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
+ the union only the ``stepwise`` member is valid and the
+ ``step_width`` and ``step_height`` values are set to 1.
+
+When the application calls the function with index zero, it must check
+the ``type`` field to determine the type of frame size enumeration the
+device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
+it make sense to increase the index value to receive more frame sizes.
+
+Note that the order in which the frame sizes are returned has no special
+meaning. In particular does it not say anything about potential default
+format sizes.
+
+Applications can assume that the enumeration data does not change
+without any interaction from the application itself. This means that the
+enumeration data is consistent if the application does not perform any
+other ioctl calls while it runs the frame size enumeration.
+
+
+Structs
+=======
+
+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.
+
+
+.. _v4l2-frmsize-discrete:
+
+.. flat-table:: struct v4l2_frmsize_discrete
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Width of the frame [pixel].
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Height of the frame [pixel].
+
+
+
+.. _v4l2-frmsize-stepwise:
+
+.. flat-table:: struct v4l2_frmsize_stepwise
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum frame width [pixel].
+
+ - .. row 2
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum frame width [pixel].
+
+ - .. row 3
+
+ - __u32
+
+ - ``step_width``
+
+ - Frame width step size [pixel].
+
+ - .. row 4
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum frame height [pixel].
+
+ - .. row 5
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum frame height [pixel].
+
+ - .. row 6
+
+ - __u32
+
+ - ``step_height``
+
+ - Frame height step size [pixel].
+
+
+
+.. _v4l2-frmsizeenum:
+
+.. flat-table:: struct v4l2_frmsizeenum
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - IN: Index of the given frame size in the enumeration.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pixel_format``
+
+ -
+ - IN: Pixel format for which the frame sizes are enumerated.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ -
+ - OUT: Frame size type the device supports.
+
+ - .. row 4
+
+ - union
+
+ -
+ -
+ - OUT: Frame size with the given index.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_frmsize_discrete <v4l2-frmsize-discrete>`
+
+ - ``discrete``
+
+ -
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_frmsize_stepwise <v4l2-frmsize-stepwise>`
+
+ - ``stepwise``
+
+ -
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved[2]``
+
+ -
+ - Reserved space for future use. Must be zeroed by drivers and
+ applications.
+
+
+
+Enums
+=====
+
+
+.. _v4l2-frmsizetypes:
+
+.. flat-table:: enum v4l2_frmsizetypes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FRMSIZE_TYPE_DISCRETE``
+
+ - 1
+
+ - Discrete frame size.
+
+ - .. row 2
+
+ - ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
+
+ - 2
+
+ - Continuous frame size.
+
+ - .. row 3
+
+ - ``V4L2_FRMSIZE_TYPE_STEPWISE``
+
+ - 3
+
+ - Step-wise defined frame size.
+
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enum-freq-bands:
+
+****************************
+ioctl VIDIOC_ENUM_FREQ_BANDS
+****************************
+
+*man VIDIOC_ENUM_FREQ_BANDS(2)*
+
+Enumerate supported frequency bands
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_frequency_band *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FREQ_BANDS
+
+``argp``
+
+
+Description
+===========
+
+Enumerates the frequency bands that a tuner or modulator supports. To do
+this applications initialize the ``tuner``, ``type`` and ``index``
+fields, and zero out the ``reserved`` array of a struct
+:ref:`v4l2_frequency_band <v4l2-frequency-band>` and call the
+``VIDIOC_ENUM_FREQ_BANDS`` ioctl with a pointer to this structure.
+
+This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability
+of the corresponding tuner/modulator is set.
+
+
+.. _v4l2-frequency-band:
+
+.. flat-table:: struct v4l2_frequency_band
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner or modulator index number. This is the same value as in
+ the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
+ the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
+ the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
+ and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
+ field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
+ set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
+ to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
+ ``V4L2_TUNER_RADIO`` for modulators (currently only radio
+ modulators are supported). See :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the frequency band, set by the application.
+
+ - .. row 4
+
+ - __u32
+
+ - ``capability``
+
+ - :cspan:`2` The tuner/modulator capability flags for this
+ frequency band, see :ref:`tuner-capability`. The
+ ``V4L2_TUNER_CAP_LOW`` or ``V4L2_TUNER_CAP_1HZ`` capability must
+ be the same for all frequency bands of the selected
+ tuner/modulator. So either all bands have that capability set, or
+ none of them have that capability.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangelow``
+
+ - :cspan:`2` The lowest tunable frequency in units of 62.5 kHz, or
+ if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
+ of 62.5 Hz, for this frequency band. A 1 Hz unit is used when the
+ ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangehigh``
+
+ - :cspan:`2` The highest tunable frequency in units of 62.5 kHz,
+ or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
+ units of 62.5 Hz, for this frequency band. A 1 Hz unit is used
+ when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 7
+
+ - __u32
+
+ - ``modulation``
+
+ - :cspan:`2` The supported modulation systems of this frequency
+ band. See :ref:`band-modulation`. Note that currently only one
+ modulation system per frequency band is supported. More work will
+ need to be done if multiple modulation systems are possible.
+ Contact the linux-media mailing list
+ (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
+ if you need that functionality.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _band-modulation:
+
+.. flat-table:: Band Modulation Systems
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BAND_MODULATION_VSB``
+
+ - 0x02
+
+ - Vestigial Sideband modulation, used for analog TV.
+
+ - .. row 2
+
+ - ``V4L2_BAND_MODULATION_FM``
+
+ - 0x04
+
+ - Frequency Modulation, commonly used for analog radio.
+
+ - .. row 3
+
+ - ``V4L2_BAND_MODULATION_AM``
+
+ - 0x08
+
+ - Amplitude Modulation, commonly used for analog radio.
+
+
+
+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.
+
+EINVAL
+ The ``tuner`` or ``index`` is out of bounds or the ``type`` field is
+ wrong.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enumaudio:
+
+**********************
+ioctl VIDIOC_ENUMAUDIO
+**********************
+
+*man VIDIOC_ENUMAUDIO(2)*
+
+Enumerate audio inputs
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_audio *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMAUDIO
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an audio input applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_audio <v4l2-audio>` and call the ``VIDIOC_ENUMAUDIO``
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an EINVAL error code when the index is out of
+bounds. To enumerate all audio inputs applications shall begin at index
+zero, incrementing by one until the driver returns EINVAL.
+
+See :ref:`vidioc-g-audio` for a description of struct
+:ref:`v4l2_audio <v4l2-audio>`.
+
+
+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.
+
+EINVAL
+ The number of the audio input is out of bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enumaudioout:
+
+***********************
+ioctl VIDIOC_ENUMAUDOUT
+***********************
+
+*man VIDIOC_ENUMAUDOUT(2)*
+
+Enumerate audio outputs
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMAUDOUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an audio output applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_audioout <v4l2-audioout>` and call the ``VIDIOC_G_AUDOUT``
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an EINVAL error code when the index is out of
+bounds. To enumerate all audio outputs applications shall begin at index
+zero, incrementing by one until the driver returns EINVAL.
+
+Note connectors on a TV card to loop back the received audio signal to a
+sound card are not audio outputs in this sense.
+
+See :ref:`vidioc-g-audioout` for a description of struct
+:ref:`v4l2_audioout <v4l2-audioout>`.
+
+
+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.
+
+EINVAL
+ The number of the audio output is out of bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enuminput:
+
+**********************
+ioctl VIDIOC_ENUMINPUT
+**********************
+
+*man VIDIOC_ENUMINPUT(2)*
+
+Enumerate video inputs
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_input *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMINPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video input applications initialize the
+``index`` field of struct :ref:`v4l2_input <v4l2-input>` and call the
+``VIDIOC_ENUMINPUT`` ioctl with a pointer to this structure. Drivers
+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.
+
+
+.. _v4l2-input:
+
+.. flat-table:: struct v4l2_input
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the input, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the video input, a NUL-terminated ASCII string, for
+ example: "Vin (Composite 2)". This information is intended for the
+ user, preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - Type of the input, see :ref:`input-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``audioset``
+
+ - Drivers can enumerate up to 32 video and audio inputs. This field
+ shows which audio inputs were selectable as audio source if this
+ was the currently selected video input. It is a bit mask. The LSB
+ corresponds to audio input 0, the MSB to input 31. Any number of
+ bits can be set, or none.
+
+ When the driver does not enumerate audio inputs no bits must be
+ set. Applications shall not interpret this as lack of audio
+ support. Some drivers automatically select audio sources and do
+ not enumerate them since there is no choice anyway.
+
+ For details on audio inputs and how to select the current input
+ see :ref:`audio`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``tuner``
+
+ - Capture devices can have zero or more tuners (RF demodulators).
+ When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
+ RF connector and this field identifies the tuner. It corresponds
+ to struct :ref:`v4l2_tuner <v4l2-tuner>` field ``index``. For
+ details on tuners see :ref:`tuner`.
+
+ - .. row 6
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``std``
+
+ - Every video input supports one or more different video standards.
+ This field is a set of all supported standards. For details on
+ video standards and how to switch see :ref:`standard`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``status``
+
+ - This field provides status information about the input. See
+ :ref:`input-status` for flags. With the exception of the sensor
+ orientation bits ``status`` is only valid when this is the current
+ input.
+
+ - .. row 8
+
+ - __u32
+
+ - ``capabilities``
+
+ - This field provides capabilities for the input. See
+ :ref:`input-capabilities` for flags.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _input-type:
+
+.. flat-table:: Input Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_INPUT_TYPE_TUNER``
+
+ - 1
+
+ - This input uses a tuner (RF demodulator).
+
+ - .. row 2
+
+ - ``V4L2_INPUT_TYPE_CAMERA``
+
+ - 2
+
+ - Analog baseband input, for example CVBS / Composite Video,
+ S-Video, RGB.
+
+
+
+.. _input-status:
+
+.. flat-table:: Input Status Flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - :cspan:`2` General
+
+ - .. row 2
+
+ - ``V4L2_IN_ST_NO_POWER``
+
+ - 0x00000001
+
+ - Attached device is off.
+
+ - .. row 3
+
+ - ``V4L2_IN_ST_NO_SIGNAL``
+
+ - 0x00000002
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_IN_ST_NO_COLOR``
+
+ - 0x00000004
+
+ - The hardware supports color decoding, but does not detect color
+ modulation in the signal.
+
+ - .. row 5
+
+ - :cspan:`2` Sensor Orientation
+
+ - .. row 6
+
+ - ``V4L2_IN_ST_HFLIP``
+
+ - 0x00000010
+
+ - The input is connected to a device that produces a signal that is
+ flipped horizontally and does not correct this before passing the
+ signal to userspace.
+
+ - .. row 7
+
+ - ``V4L2_IN_ST_VFLIP``
+
+ - 0x00000020
+
+ - The input is connected to a device that produces a signal that is
+ flipped vertically and does not correct this before passing the
+ signal to userspace. Note that a 180 degree rotation is the same
+ as HFLIP | VFLIP
+
+ - .. row 8
+
+ - :cspan:`2` Analog Video
+
+ - .. row 9
+
+ - ``V4L2_IN_ST_NO_H_LOCK``
+
+ - 0x00000100
+
+ - No horizontal sync lock.
+
+ - .. row 10
+
+ - ``V4L2_IN_ST_COLOR_KILL``
+
+ - 0x00000200
+
+ - A color killer circuit automatically disables color decoding when
+ it detects no color modulation. When this flag is set the color
+ killer is enabled *and* has shut off color decoding.
+
+ - .. row 11
+
+ - :cspan:`2` Digital Video
+
+ - .. row 12
+
+ - ``V4L2_IN_ST_NO_SYNC``
+
+ - 0x00010000
+
+ - No synchronization lock.
+
+ - .. row 13
+
+ - ``V4L2_IN_ST_NO_EQU``
+
+ - 0x00020000
+
+ - No equalizer lock.
+
+ - .. row 14
+
+ - ``V4L2_IN_ST_NO_CARRIER``
+
+ - 0x00040000
+
+ - Carrier recovery failed.
+
+ - .. row 15
+
+ - :cspan:`2` VCR and Set-Top Box
+
+ - .. row 16
+
+ - ``V4L2_IN_ST_MACROVISION``
+
+ - 0x01000000
+
+ - Macrovision is an analog copy prevention system mangling the video
+ signal to confuse video recorders. When this flag is set
+ Macrovision has been detected.
+
+ - .. row 17
+
+ - ``V4L2_IN_ST_NO_ACCESS``
+
+ - 0x02000000
+
+ - Conditional access denied.
+
+ - .. row 18
+
+ - ``V4L2_IN_ST_VTR``
+
+ - 0x04000000
+
+ - VTR time constant. [?]
+
+
+
+.. _input-capabilities:
+
+.. flat-table:: Input capabilities
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_IN_CAP_DV_TIMINGS``
+
+ - 0x00000002
+
+ - This input supports setting video timings by using
+ VIDIOC_S_DV_TIMINGS.
+
+ - .. row 2
+
+ - ``V4L2_IN_CAP_STD``
+
+ - 0x00000004
+
+ - This input supports setting the TV standard by using
+ VIDIOC_S_STD.
+
+ - .. row 3
+
+ - ``V4L2_IN_CAP_NATIVE_SIZE``
+
+ - 0x00000008
+
+ - This input supports setting the native size using the
+ ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
+ :ref:`v4l2-selections-common`.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_input <v4l2-input>` ``index`` is out of
+ bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enumoutput:
+
+***********************
+ioctl VIDIOC_ENUMOUTPUT
+***********************
+
+*man VIDIOC_ENUMOUTPUT(2)*
+
+Enumerate video outputs
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_output *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMOUTPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video outputs applications initialize the
+``index`` field of struct :ref:`v4l2_output <v4l2-output>` and call
+the ``VIDIOC_ENUMOUTPUT`` ioctl with a pointer to this structure.
+Drivers fill the rest of the structure or return an EINVAL error code
+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.
+
+
+.. _v4l2-output:
+
+.. flat-table:: struct v4l2_output
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the output, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the video output, a NUL-terminated ASCII string, for
+ example: "Vout". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - Type of the output, see :ref:`output-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``audioset``
+
+ - Drivers can enumerate up to 32 video and audio outputs. This field
+ shows which audio outputs were selectable as the current output if
+ this was the currently selected video output. It is a bit mask.
+ The LSB corresponds to audio output 0, the MSB to output 31. Any
+ number of bits can be set, or none.
+
+ When the driver does not enumerate audio outputs no bits must be
+ set. Applications shall not interpret this as lack of audio
+ support. Drivers may automatically select audio outputs without
+ enumerating them.
+
+ For details on audio outputs and how to select the current output
+ see :ref:`audio`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``modulator``
+
+ - Output devices can have zero or more RF modulators. When the
+ ``type`` is ``V4L2_OUTPUT_TYPE_MODULATOR`` this is an RF connector
+ and this field identifies the modulator. It corresponds to struct
+ :ref:`v4l2_modulator <v4l2-modulator>` field ``index``. For
+ details on modulators see :ref:`tuner`.
+
+ - .. row 6
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``std``
+
+ - Every video output supports one or more different video standards.
+ This field is a set of all supported standards. For details on
+ video standards and how to switch see :ref:`standard`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``capabilities``
+
+ - This field provides capabilities for the output. See
+ :ref:`output-capabilities` for flags.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _output-type:
+
+.. flat-table:: Output Type
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_OUTPUT_TYPE_MODULATOR``
+
+ - 1
+
+ - This output is an analog TV modulator.
+
+ - .. row 2
+
+ - ``V4L2_OUTPUT_TYPE_ANALOG``
+
+ - 2
+
+ - Analog baseband output, for example Composite / CVBS, S-Video,
+ RGB.
+
+ - .. row 3
+
+ - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
+
+ - 3
+
+ - [?]
+
+
+
+.. _output-capabilities:
+
+.. flat-table:: Output capabilities
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_OUT_CAP_DV_TIMINGS``
+
+ - 0x00000002
+
+ - This output supports setting video timings by using
+ VIDIOC_S_DV_TIMINGS.
+
+ - .. row 2
+
+ - ``V4L2_OUT_CAP_STD``
+
+ - 0x00000004
+
+ - This output supports setting the TV standard by using
+ VIDIOC_S_STD.
+
+ - .. row 3
+
+ - ``V4L2_OUT_CAP_NATIVE_SIZE``
+
+ - 0x00000008
+
+ - This output supports setting the native size using the
+ ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
+ :ref:`v4l2-selections-common`.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_output <v4l2-output>` ``index`` is out of
+ bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-enumstd:
+
+********************
+ioctl VIDIOC_ENUMSTD
+********************
+
+*man VIDIOC_ENUMSTD(2)*
+
+Enumerate supported video standards
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_standard *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMSTD
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video standard, especially a custom (driver
+defined) one, applications initialize the ``index`` field of struct
+:ref:`v4l2_standard <v4l2-standard>` and call the ``VIDIOC_ENUMSTD``
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an EINVAL error code when the index is out of
+bounds. To enumerate all standards applications shall begin at index
+zero, incrementing by one until the driver returns EINVAL. Drivers may
+enumerate a different set of standards after switching the video input
+or output. [1]_
+
+
+.. _v4l2-standard:
+
+.. flat-table:: struct v4l2_standard
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the video standard, set by the application.
+
+ - .. row 2
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``id``
+
+ - The bits in this field identify the standard as one of the common
+ standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are
+ set as custom standards. Multiple bits can be set if the hardware
+ does not distinguish between these standards, however separate
+ indices do not indicate the opposite. The ``id`` must be unique.
+ No other enumerated :c:type:`struct v4l2_standard` structure,
+ for this input or output anyway, can contain the same set of bits.
+
+ - .. row 3
+
+ - __u8
+
+ - ``name``\ [24]
+
+ - Name of the standard, a NUL-terminated ASCII string, for example:
+ "PAL-B/G", "NTSC Japan". This information is intended for the
+ user.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``frameperiod``
+
+ - The frame period (not field period) is numerator / denominator.
+ For example M/NTSC has a frame period of 1001 / 30000 seconds.
+
+ - .. row 5
+
+ - __u32
+
+ - ``framelines``
+
+ - Total lines per frame including blanking, e. g. 625 for B/PAL.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-fract:
+
+.. flat-table:: struct v4l2_fract
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``numerator``
+
+ -
+
+ - .. row 2
+
+ - __u32
+
+ - ``denominator``
+
+ -
+
+
+
+.. _v4l2-std-id:
+
+.. flat-table:: typedef v4l2_std_id
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``v4l2_std_id``
+
+ - This type is a set, each bit representing another video standard
+ as listed below and in :ref:`video-standards`. The 32 most
+ significant bits are reserved for custom (driver defined) video
+ standards.
+
+
+
+.. code-block:: c
+
+ #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
+ #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
+ #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
+ #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
+ #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
+ #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
+ #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
+ #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
+
+ #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
+ #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
+ #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
+ #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
+
+``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh
+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)
+ #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
+ #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
+
+``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)
+
+ #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
+ #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
+ #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
+ #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
+ #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
+ #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
+ #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
+ #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
+
+ /* ATSC/HDTV */
+ #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
+ #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
+
+``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S.
+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 |
+ V4L2_STD_PAL_B1 |
+ V4L2_STD_PAL_G)
+ #define V4L2_STD_B (V4L2_STD_PAL_B |
+ V4L2_STD_PAL_B1 |
+ V4L2_STD_SECAM_B)
+ #define V4L2_STD_GH (V4L2_STD_PAL_G |
+ V4L2_STD_PAL_H |
+ V4L2_STD_SECAM_G |
+ V4L2_STD_SECAM_H)
+ #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |
+ V4L2_STD_PAL_D1 |
+ V4L2_STD_PAL_K)
+ #define V4L2_STD_PAL (V4L2_STD_PAL_BG |
+ V4L2_STD_PAL_DK |
+ V4L2_STD_PAL_H |
+ V4L2_STD_PAL_I)
+ #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |
+ V4L2_STD_NTSC_M_JP |
+ V4L2_STD_NTSC_M_KR)
+ #define V4L2_STD_MN (V4L2_STD_PAL_M |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc |
+ V4L2_STD_NTSC)
+ #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |
+ V4L2_STD_SECAM_K |
+ V4L2_STD_SECAM_K1)
+ #define V4L2_STD_DK (V4L2_STD_PAL_DK |
+ V4L2_STD_SECAM_DK)
+
+ #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |
+ V4L2_STD_SECAM_G |
+ V4L2_STD_SECAM_H |
+ V4L2_STD_SECAM_DK |
+ V4L2_STD_SECAM_L |
+ V4L2_STD_SECAM_LC)
+
+ #define V4L2_STD_525_60 (V4L2_STD_PAL_M |
+ V4L2_STD_PAL_60 |
+ V4L2_STD_NTSC |
+ V4L2_STD_NTSC_443)
+ #define V4L2_STD_625_50 (V4L2_STD_PAL |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc |
+ V4L2_STD_SECAM)
+
+ #define V4L2_STD_UNKNOWN 0
+ #define V4L2_STD_ALL (V4L2_STD_525_60 |
+ V4L2_STD_625_50)
+
+
+.. _video-standards:
+
+.. flat-table:: Video Standards (based on [])
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Characteristics
+
+ - M/NTSC [2]_
+
+ - M/PAL
+
+ - N/PAL [3]_
+
+ - B, B1, G/PAL
+
+ - D, D1, K/PAL
+
+ - H/PAL
+
+ - I/PAL
+
+ - B, G/SECAM
+
+ - D, K/SECAM
+
+ - K1/SECAM
+
+ - L/SECAM
+
+ - .. row 2
+
+ - Frame lines
+
+ - :cspan:`1` 525
+
+ - :cspan:`9` 625
+
+ - .. row 3
+
+ - Frame period (s)
+
+ - :cspan:`1` 1001/30000
+
+ - :cspan:`9` 1/25
+
+ - .. row 4
+
+ - Chrominance sub-carrier frequency (Hz)
+
+ - 3579545 ± 10
+
+ - 3579611.49 ± 10
+
+ - 4433618.75 ± 5 (3582056.25 ± 5)
+
+ - :cspan:`3` 4433618.75 ± 5
+
+ - 4433618.75 ± 1
+
+ - :cspan:`3` f :sub:`OR` = 4406250 ± 2000, f :sub:`OB` = 4250000
+ ± 2000
+
+ - .. row 5
+
+ - Nominal radio-frequency channel bandwidth (MHz)
+
+ - 6
+
+ - 6
+
+ - 6
+
+ - B: 7; B1, G: 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - .. row 6
+
+ - Sound carrier relative to vision carrier (MHz)
+
+ - + 4.5
+
+ - + 4.5
+
+ - + 4.5
+
+ - + 5.5 ± 0.001 [4]_ [5]_ [6]_ [7]_
+
+ - + 6.5 ± 0.001
+
+ - + 5.5
+
+ - + 5.9996 ± 0.0005
+
+ - + 5.5 ± 0.001
+
+ - + 6.5 ± 0.001
+
+ - + 6.5
+
+ - + 6.5 [8]_
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_standard <v4l2-standard>` ``index`` is out
+ of bounds.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
+
+.. [1]
+ The supported standards may overlap and we need an unambiguous set to
+ find the current standard returned by ``VIDIOC_G_STD``.
+
+.. [2]
+ Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP).
+
+.. [3]
+ The values in brackets apply to the combination N/PAL a.k.a.
+ N :sub:`C` used in Argentina (V4L2_STD_PAL_Nc).
+
+.. [4]
+ In the Federal Republic of Germany, Austria, Italy, the Netherlands,
+ Slovakia and Switzerland a system of two sound carriers is used, the
+ frequency of the second carrier being 242.1875 kHz above the
+ frequency of the first sound carrier. For stereophonic sound
+ transmissions a similar system is used in Australia.
+
+.. [5]
+ New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from
+ the vision carrier.
+
+.. [6]
+ In Denmark, Finland, New Zealand, Sweden and Spain a system of two
+ sound carriers is used. In Iceland, Norway and Poland the same system
+ is being introduced. The second carrier is 5.85 MHz above the vision
+ carrier and is DQPSK modulated with 728 kbit/s sound and data
+ multiplex. (NICAM system)
+
+.. [7]
+ In the United Kingdom, a system of two sound carriers is used. The
+ second sound carrier is 6.552 MHz above the vision carrier and is
+ DQPSK modulated with a 728 kbit/s sound and data multiplex able to
+ carry two sound channels. (NICAM system)
+
+.. [8]
+ In France, a digital carrier 5.85 MHz away from the vision carrier
+ may be used in addition to the main sound carrier. It is modulated in
+ differentially encoded QPSK with a 728 kbit/s sound and data
+ multiplexer capable of carrying two sound channels. (NICAM system)
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-expbuf:
+
+*******************
+ioctl VIDIOC_EXPBUF
+*******************
+
+*man VIDIOC_EXPBUF(2)*
+
+Export a buffer as a DMABUF file descriptor.
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_exportbuffer *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_EXPBUF
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O
+method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.
+It can be used to export a buffer as a DMABUF file at any time after
+buffers have been allocated with the
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl.
+
+To export a buffer, applications fill struct
+:ref:`v4l2_exportbuffer <v4l2-exportbuffer>`. The ``type`` field is
+set to the same buffer type as was previously used with struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+Applications must also set the ``index`` field. Valid index numbers
+range from zero to the number of buffers allocated with
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. For the multi-planar API, applications set the ``plane`` field to
+the index of the plane to be exported. Valid planes range from zero to
+the maximal number of valid planes for the currently active format. For
+the single-planar API, applications must set ``plane`` to zero.
+Additional flags may be posted in the ``flags`` field. Refer to a manual
+for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
+and O_RDWR are supported. All other fields must be set to zero. In the
+case of multi-planar API, every plane is exported separately using
+multiple ``VIDIOC_EXPBUF`` calls.
+
+After calling ``VIDIOC_EXPBUF`` the ``fd`` field will be set by a
+driver. This is a DMABUF file descriptor. The application may pass it to
+other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`
+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)
+ {
+ struct v4l2_exportbuffer expbuf;
+
+ memset(&expbuf, 0, sizeof(expbuf));
+ expbuf.type = bt;
+ expbuf.index = index;
+ if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
+ perror("VIDIOC_EXPBUF");
+ return -1;
+ }
+
+ *dmafd = expbuf.fd;
+
+ return 0;
+ }
+
+
+.. code-block:: c
+
+ int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
+ int dmafd[], int n_planes)
+ {
+ int i;
+
+ for (i = 0; i < n_planes; ++i) {
+ struct v4l2_exportbuffer expbuf;
+
+ memset(&expbuf, 0, sizeof(expbuf));
+ expbuf.type = bt;
+ expbuf.index = index;
+ expbuf.plane = i;
+ if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
+ perror("VIDIOC_EXPBUF");
+ while (i)
+ close(dmafd[--i]);
+ return -1;
+ }
+ dmafd[i] = expbuf.fd;
+ }
+
+ return 0;
+ }
+
+
+.. _v4l2-exportbuffer:
+
+.. flat-table:: struct v4l2_exportbuffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the buffer, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` or struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
+ by the application. See :ref:`v4l2-buf-type`
+
+ - .. row 2
+
+ - __u32
+
+ - ``index``
+
+ - Number of the buffer, set by the application. This field is only
+ used for :ref:`memory mapping <mmap>` I/O and can range from
+ zero to the number of buffers allocated with the
+ :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and/or
+ :ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>` ioctls.
+
+ - .. row 3
+
+ - __u32
+
+ - ``plane``
+
+ - Index of the plane to be exported when using the multi-planar API.
+ Otherwise this value must be set to zero.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags for the newly created file, currently only ``O_CLOEXEC``,
+ ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to
+ the manual of open() for more details.
+
+ - .. row 5
+
+ - __s32
+
+ - ``fd``
+
+ - The DMABUF file descriptor associated with a buffer. Set by the
+ driver.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved[11]``
+
+ - Reserved field for future use. Drivers and applications must set
+ the array to zero.
+
+
+
+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.
+
+EINVAL
+ A queue is not in MMAP mode or DMABUF exporting is not supported or
+ ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-audio:
+
+************************************
+ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
+************************************
+
+*man VIDIOC_G_AUDIO(2)*
+
+VIDIOC_S_AUDIO
+Query or select the current audio input and its attributes
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_audio *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_audio *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
+
+``argp``
+
+
+Description
+===========
+
+To query the current audio input applications zero out the ``reserved``
+array of a struct :ref:`v4l2_audio <v4l2-audio>` and call the
+``VIDIOC_G_AUDIO`` ioctl with a pointer to this structure. Drivers fill
+the rest of the structure or return an EINVAL error code when the device
+has no audio inputs, or none which combine with the current video input.
+
+Audio inputs have one writable property, the audio mode. To select the
+current audio input *and* change the audio mode, applications initialize
+the ``index`` and ``mode`` fields, and the ``reserved`` array of a
+:c:type:`struct v4l2_audio` structure and call the ``VIDIOC_S_AUDIO``
+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.
+
+
+.. _v4l2-audio:
+
+.. flat-table:: struct v4l2_audio
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the audio input, set by the driver or application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the audio input, a NUL-terminated ASCII string, for
+ example: "Line In". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Audio capability flags, see :ref:`audio-capability`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``mode``
+
+ - Audio mode flags set by drivers and applications (on
+ ``VIDIOC_S_AUDIO`` ioctl), see :ref:`audio-mode`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _audio-capability:
+
+.. flat-table:: Audio Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_AUDCAP_STEREO``
+
+ - 0x00001
+
+ - This is a stereo input. The flag is intended to automatically
+ disable stereo recording etc. when the signal is always monaural.
+ The API provides no means to detect if stereo is *received*,
+ unless the audio input belongs to a tuner.
+
+ - .. row 2
+
+ - ``V4L2_AUDCAP_AVL``
+
+ - 0x00002
+
+ - Automatic Volume Level mode is supported.
+
+
+
+.. _audio-mode:
+
+.. flat-table:: Audio Mode Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_AUDMODE_AVL``
+
+ - 0x00001
+
+ - AVL mode is on.
+
+
+
+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.
+
+EINVAL
+ No audio inputs combine with the current video input, or the number
+ of the selected audio input is out of bounds or it does not combine.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-audioout:
+
+**************************************
+ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
+**************************************
+
+*man VIDIOC_G_AUDOUT(2)*
+
+VIDIOC_S_AUDOUT
+Query or select the current audio output
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_audioout *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current audio output applications zero out the ``reserved``
+array of a struct :ref:`v4l2_audioout <v4l2-audioout>` and call the
+``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
+the rest of the structure or return an EINVAL error code when the device
+has no audio inputs, or none which combine with the current video
+output.
+
+Audio outputs have no writable properties. Nevertheless, to select the
+current audio output applications can initialize the ``index`` field and
+``reserved`` array (which in the future may contain writable properties)
+of a :c:type:`struct v4l2_audioout` structure and call the
+``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
+return the EINVAL error code when the index is out of bounds. This is a
+write-only ioctl, it does not return the current audio output attributes
+as ``VIDIOC_G_AUDOUT`` does.
+
+Note connectors on a TV card to loop back the received audio signal to a
+sound card are not audio outputs in this sense.
+
+
+.. _v4l2-audioout:
+
+.. flat-table:: struct v4l2_audioout
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the audio output, set by the driver or application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the audio output, a NUL-terminated ASCII string, for
+ example: "Line Out". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Audio capability flags, none defined yet. Drivers must set this
+ field to zero.
+
+ - .. row 4
+
+ - __u32
+
+ - ``mode``
+
+ - Audio mode, none defined yet. Drivers and applications (on
+ ``VIDIOC_S_AUDOUT``) must set this field to zero.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+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.
+
+EINVAL
+ No audio outputs combine with the current video output, or the
+ number of the selected audio output is out of bounds or it does not
+ combine.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-crop:
+
+**********************************
+ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
+**********************************
+
+*man VIDIOC_G_CROP(2)*
+
+VIDIOC_S_CROP
+Get or set the current cropping rectangle
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_crop *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_crop *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_CROP, VIDIOC_S_CROP
+
+``argp``
+
+
+Description
+===========
+
+To query the cropping rectangle size and position applications set the
+``type`` field of a :c:type:`struct v4l2_crop` structure to the
+respective buffer (stream) type and call the ``VIDIOC_G_CROP`` ioctl
+with a pointer to this structure. The driver fills the rest of the
+structure or returns the EINVAL error code if cropping is not supported.
+
+To change the cropping rectangle applications initialize the ``type``
+and struct :ref:`v4l2_rect <v4l2-rect>` substructure named ``c`` of a
+v4l2_crop structure and call the ``VIDIOC_S_CROP`` ioctl with a pointer
+to this structure.
+
+Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
+
+The driver first adjusts the requested dimensions against hardware
+limits, i. e. the bounds given by the capture/output window, and it
+rounds to the closest possible values of horizontal and vertical offset,
+width and height. In particular the driver must round the vertical
+offset of the cropping rectangle to frame lines modulo two, such that
+the field order cannot be confused.
+
+Second the driver adjusts the image size (the opposite rectangle of the
+scaling process, source or target depending on the data direction) to
+the closest size possible while maintaining the current horizontal and
+vertical scaling factor.
+
+Finally the driver programs the hardware with the actual cropping and
+image parameters. ``VIDIOC_S_CROP`` is a write-only ioctl, it does not
+return the actual parameters. To query them applications must call
+``VIDIOC_G_CROP`` and :ref:`VIDIOC_G_FMT <vidioc-g-fmt>`. When the
+parameters are unsuitable the application may modify the cropping or
+image parameters and repeat the cycle until satisfactory parameters have
+been negotiated.
+
+When cropping is not supported then no parameters are changed and
+``VIDIOC_S_CROP`` returns the EINVAL error code.
+
+
+.. _v4l2-crop:
+
+.. flat-table:: struct v4l2_crop
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``c``
+
+ - Cropping rectangle. The same co-ordinate system as for struct
+ :ref:`v4l2_cropcap <v4l2-cropcap>` ``bounds`` is 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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-ctrl:
+
+**********************************
+ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
+**********************************
+
+*man VIDIOC_G_CTRL(2)*
+
+VIDIOC_S_CTRL
+Get or set the value of a control
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_control *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_CTRL, VIDIOC_S_CTRL
+
+``argp``
+
+
+Description
+===========
+
+To get the current value of a control applications initialize the ``id``
+field of a struct :c:type:`struct v4l2_control` and call the
+``VIDIOC_G_CTRL`` ioctl with a pointer to this structure. To change the
+value of a control applications initialize the ``id`` and ``value``
+fields of a struct :c:type:`struct v4l2_control` and call the
+``VIDIOC_S_CTRL`` ioctl.
+
+When the ``id`` is invalid drivers return an EINVAL error code. When the
+``value`` is out of bounds drivers can choose to take the closest valid
+value or return an ERANGE error code, whatever seems more appropriate.
+However, ``VIDIOC_S_CTRL`` is a write-only ioctl, it does not return the
+actual new value. If the ``value`` is inappropriate for the control
+(e.g. if it refers to an unsupported menu index of a menu control), then
+EINVAL error code is returned as well.
+
+These ioctls work only with user controls. For other control classes the
+:ref:`VIDIOC_G_EXT_CTRLS <vidioc-g-ext-ctrls>`,
+:ref:`VIDIOC_S_EXT_CTRLS <vidioc-g-ext-ctrls>` or
+:ref:`VIDIOC_TRY_EXT_CTRLS <vidioc-g-ext-ctrls>` must be used.
+
+
+.. _v4l2-control:
+
+.. flat-table:: struct v4l2_control
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application.
+
+ - .. row 2
+
+ - __s32
+
+ - ``value``
+
+ - New value or current value.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_control <v4l2-control>` ``id`` is invalid
+ or the ``value`` is inappropriate for the given control (i.e. if a
+ menu item is selected that is not supported by the driver according
+ to :ref:`VIDIOC_QUERYMENU <vidioc-queryctrl>`).
+
+ERANGE
+ The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of
+ bounds.
+
+EBUSY
+ The control is temporarily not changeable, possibly because another
+ applications took over control of the device function this control
+ belongs to.
+
+EACCES
+ Attempt to set a read-only control or to get a write-only control.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-dv-timings:
+
+**********************************************
+ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS
+**********************************************
+
+*man VIDIOC_G_DV_TIMINGS(2)*
+
+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, int request, struct v4l2_dv_timings *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS,
+ VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+To set DV timings for the input or output, applications use the
+``VIDIOC_S_DV_TIMINGS`` ioctl and to get the current timings,
+applications use the ``VIDIOC_G_DV_TIMINGS`` ioctl. The detailed timing
+information is filled in using the structure struct
+:ref:`v4l2_dv_timings <v4l2-dv-timings>`. These ioctls take a
+pointer to the struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
+structure as argument. If the ioctl is not supported or the timing
+values are not correct, the driver returns EINVAL error code.
+
+The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
+the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
+the current input or output does not support DV timings (e.g. if
+:ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` does not set the
+``V4L2_IN_CAP_DV_TIMINGS`` flag), then ENODATA error code is returned.
+
+
+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.
+
+EINVAL
+ This ioctl is not supported, or the ``VIDIOC_S_DV_TIMINGS``
+ parameter was unsuitable.
+
+ENODATA
+ Digital video timings are not supported for this input or output.
+
+EBUSY
+ The device is busy and therefore can not change the timings.
+
+
+.. _v4l2-bt-timings:
+
+.. flat-table:: struct v4l2_bt_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Width of the active video in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Height of the active video frame in lines. So for interlaced
+ formats the height of the active video in each field is
+ ``height``/2.
+
+ - .. row 3
+
+ - __u32
+
+ - ``interlaced``
+
+ - Progressive (0) or interlaced (1)
+
+ - .. row 4
+
+ - __u32
+
+ - ``polarities``
+
+ - This is a bit mask that defines polarities of sync signals. bit 0
+ (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit
+ 1 (V4L2_DV_HSYNC_POS_POL) is for horizontal sync polarity. If
+ the bit is set (1) it is positive polarity and if is cleared (0),
+ it is negative polarity.
+
+ - .. row 5
+
+ - __u64
+
+ - ``pixelclock``
+
+ - Pixel clock in Hz. Ex. 74.25MHz->74250000
+
+ - .. row 6
+
+ - __u32
+
+ - ``hfrontporch``
+
+ - Horizontal front porch in pixels
+
+ - .. row 7
+
+ - __u32
+
+ - ``hsync``
+
+ - Horizontal sync length in pixels
+
+ - .. row 8
+
+ - __u32
+
+ - ``hbackporch``
+
+ - Horizontal back porch in pixels
+
+ - .. row 9
+
+ - __u32
+
+ - ``vfrontporch``
+
+ - Vertical front porch in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 10
+
+ - __u32
+
+ - ``vsync``
+
+ - Vertical sync length in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 11
+
+ - __u32
+
+ - ``vbackporch``
+
+ - Vertical back porch in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 12
+
+ - __u32
+
+ - ``il_vfrontporch``
+
+ - Vertical front porch in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 13
+
+ - __u32
+
+ - ``il_vsync``
+
+ - Vertical sync length in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 14
+
+ - __u32
+
+ - ``il_vbackporch``
+
+ - Vertical back porch in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 15
+
+ - __u32
+
+ - ``standards``
+
+ - The video standard(s) this format belongs to. This will be filled
+ in by the driver. Applications must set this to 0. See
+ :ref:`dv-bt-standards` for a list of standards.
+
+ - .. row 16
+
+ - __u32
+
+ - ``flags``
+
+ - Several flags giving more information about the format. See
+ :ref:`dv-bt-flags` for a description of the flags.
+
+
+
+.. _v4l2-dv-timings:
+
+.. flat-table:: struct v4l2_dv_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of DV timings as listed in :ref:`dv-timing-types`.
+
+ - .. row 2
+
+ - union
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_bt_timings <v4l2-bt-timings>`
+
+ - ``bt``
+
+ - Timings defined by BT.656/1120 specifications
+
+ - .. row 4
+
+ -
+ - __u32
+
+ - ``reserved``\ [32]
+
+ -
+
+
+
+.. _dv-timing-types:
+
+.. flat-table:: DV Timing types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Timing type
+
+ - value
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+ -
+
+ - .. row 3
+
+ - V4L2_DV_BT_656_1120
+
+ - 0
+
+ - BT.656/1120 timings
+
+
+
+.. _dv-bt-standards:
+
+.. flat-table:: DV BT Timing standards
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Timing standard
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - V4L2_DV_BT_STD_CEA861
+
+ - The timings follow the CEA-861 Digital TV Profile standard
+
+ - .. row 4
+
+ - V4L2_DV_BT_STD_DMT
+
+ - The timings follow the VESA Discrete Monitor Timings standard
+
+ - .. row 5
+
+ - V4L2_DV_BT_STD_CVT
+
+ - The timings follow the VESA Coordinated Video Timings standard
+
+ - .. row 6
+
+ - V4L2_DV_BT_STD_GTF
+
+ - The timings follow the VESA Generalized Timings Formula standard
+
+
+
+.. _dv-bt-flags:
+
+.. flat-table:: DV BT Timing flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - V4L2_DV_FL_REDUCED_BLANKING
+
+ - CVT/GTF specific: the timings use reduced blanking (CVT) or the
+ 'Secondary GTF' curve (GTF). In both cases the horizontal and/or
+ vertical blanking intervals are reduced, allowing a higher
+ resolution over the same bandwidth. This is a read-only flag,
+ applications must not set this.
+
+ - .. row 4
+
+ - V4L2_DV_FL_CAN_REDUCE_FPS
+
+ - CEA-861 specific: set for CEA-861 formats with a framerate that is
+ a multiple of six. These formats can be optionally played at 1 /
+ 1.001 speed to be compatible with 60 Hz based standards such as
+ NTSC and PAL-M that use a framerate of 29.97 frames per second. If
+ the transmitter can't generate such frequencies, then the flag
+ will also be cleared. This is a read-only flag, applications must
+ not set this.
+
+ - .. row 5
+
+ - V4L2_DV_FL_REDUCED_FPS
+
+ - CEA-861 specific: only valid for video transmitters, the flag is
+ cleared by receivers. It is also only valid for formats with the
+ V4L2_DV_FL_CAN_REDUCE_FPS flag set, for other formats the
+ flag will be cleared by the driver. If the application sets this
+ flag, then the pixelclock used to set up the transmitter is
+ divided by 1.001 to make it compatible with NTSC framerates. If
+ the transmitter can't generate such frequencies, then the flag
+ will also be cleared.
+
+ - .. row 6
+
+ - V4L2_DV_FL_HALF_LINE
+
+ - Specific to interlaced formats: if set, then the vertical
+ frontporch of field 1 (aka the odd field) is really one half-line
+ longer and the vertical backporch of field 2 (aka the even field)
+ is really one half-line shorter, so each field has exactly the
+ same number of half-lines. Whether half-lines can be detected or
+ used depends on the hardware.
+
+ - .. row 7
+
+ - V4L2_DV_FL_IS_CE_VIDEO
+
+ - If set, then this is a Consumer Electronics (CE) video format.
+ Such formats differ from other formats (commonly called IT
+ formats) in that if R'G'B' encoding is used then by default the
+ R'G'B' values use limited range (i.e. 16-235) as opposed to full
+ range (i.e. 0-255). All formats defined in CEA-861 except for the
+ 640x480p59.94 format are CE formats.
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-edid:
+
+******************************************************************************
+ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID
+******************************************************************************
+
+*man VIDIOC_G_EDID(2)*
+
+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, int request, struct v4l2_edid *argp )
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_edid *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID,
+ VIDIOC_SUBDEV_S_EDID
+
+``argp``
+
+
+Description
+===========
+
+These ioctls can be used to get or set an EDID associated with an input
+from a receiver or an output of a transmitter device. They can be used
+with subdevice nodes (/dev/v4l-subdevX) or with video nodes
+(/dev/videoX).
+
+When used with video nodes the ``pad`` field represents the input (for
+video capture devices) or output (for video output devices) index as is
+returned by :ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` and
+:ref:`VIDIOC_ENUMOUTPUT <vidioc-enumoutput>` respectively. When used
+with subdevice nodes the ``pad`` field represents the input or output
+pad of the subdevice. If there is no EDID support for the given ``pad``
+value, then the EINVAL error code will be returned.
+
+To get the EDID data the application has to fill in the ``pad``,
+``start_block``, ``blocks`` and ``edid`` fields, zero the ``reserved``
+array and call ``VIDIOC_G_EDID``. The current EDID from block
+``start_block`` and of size ``blocks`` will be placed in the memory
+``edid`` points to. The ``edid`` pointer must point to memory at least
+``blocks`` * 128 bytes large (the size of one block is 128 bytes).
+
+If there are fewer blocks than specified, then the driver will set
+``blocks`` to the actual number of blocks. If there are no EDID blocks
+available at all, then the error code ENODATA is set.
+
+If blocks have to be retrieved from the sink, then this call will block
+until they have been read.
+
+If ``start_block`` and ``blocks`` are both set to 0 when
+``VIDIOC_G_EDID`` is called, then the driver will set ``blocks`` to the
+total number of available EDID blocks and it will return 0 without
+copying any data. This is an easy way to discover how many EDID blocks
+there are. Note that if there are no EDID blocks available at all, then
+the driver will set ``blocks`` to 0 and it returns 0.
+
+To set the EDID blocks of a receiver the application has to fill in the
+``pad``, ``blocks`` and ``edid`` fields, set ``start_block`` to 0 and
+zero the ``reserved`` array. It is not possible to set part of an EDID,
+it is always all or nothing. Setting the EDID data is only valid for
+receivers as it makes no sense for a transmitter.
+
+The driver assumes that the full EDID is passed in. If there are more
+EDID blocks than the hardware can handle then the EDID is not written,
+but instead the error code E2BIG is set and ``blocks`` is set to the
+maximum that the hardware supports. If ``start_block`` is any value
+other than 0 then the error code EINVAL is set.
+
+To disable an EDID you set ``blocks`` to 0. Depending on the hardware
+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.
+
+
+.. _v4l2-edid:
+
+.. flat-table:: struct v4l2_edid
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad for which to get/set the EDID blocks. When used with a video
+ device node the pad represents the input or output index as
+ returned by :ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` and
+ :ref:`VIDIOC_ENUMOUTPUT <vidioc-enumoutput>` respectively.
+
+ - .. row 2
+
+ - __u32
+
+ - ``start_block``
+
+ - Read the EDID from starting with this block. Must be 0 when
+ setting the EDID.
+
+ - .. row 3
+
+ - __u32
+
+ - ``blocks``
+
+ - The number of blocks to get or set. Must be less or equal to 256
+ (the maximum number of blocks as defined by the standard). When
+ you set the EDID and ``blocks`` is 0, then the EDID is disabled or
+ erased.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+ - .. row 5
+
+ - __u8 *
+
+ - ``edid``
+
+ - Pointer to memory that contains the EDID. The minimum size is
+ ``blocks`` * 128.
+
+
+
+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.
+
+ENODATA
+ The EDID data is not available.
+
+E2BIG
+ The EDID data you provided is more than the hardware can handle.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-enc-index:
+
+************************
+ioctl VIDIOC_G_ENC_INDEX
+************************
+
+*man VIDIOC_G_ENC_INDEX(2)*
+
+Get meta data about a compressed video stream
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_enc_idx *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_ENC_INDEX
+
+``argp``
+
+
+Description
+===========
+
+The ``VIDIOC_G_ENC_INDEX`` ioctl provides meta data about a compressed
+video stream the same or another application currently reads from the
+driver, which is useful for random access into the stream without
+decoding it.
+
+To read the data applications must call ``VIDIOC_G_ENC_INDEX`` with a
+pointer to a struct :ref:`v4l2_enc_idx <v4l2-enc-idx>`. On success
+the driver fills the ``entry`` array, stores the number of elements
+written in the ``entries`` field, and initializes the ``entries_cap``
+field.
+
+Each element of the ``entry`` array contains meta data about one
+picture. A ``VIDIOC_G_ENC_INDEX`` call reads up to
+``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up
+to ``entries_cap`` entries. This number can be lower or higher than
+``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to
+read the meta data in time the oldest entries will be lost. When the
+buffer is empty or no capturing/encoding is in progress, ``entries``
+will be zero.
+
+Currently this ioctl is only defined for MPEG-2 program streams and
+video elementary streams.
+
+
+.. _v4l2-enc-idx:
+
+.. flat-table:: struct v4l2_enc_idx
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entries``
+
+ - The number of entries the driver stored in the ``entry`` array.
+
+ - .. row 2
+
+ - __u32
+
+ - ``entries_cap``
+
+ - The number of entries the driver can buffer. Must be greater than
+ zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - :cspan:`2` Reserved for future extensions. Drivers must set the
+ array to zero.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_enc_idx_entry <v4l2-enc-idx-entry>`
+
+ - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
+
+ - Meta data about a compressed video stream. Each element of the
+ array corresponds to one picture, sorted in ascending order by
+ their ``offset``.
+
+
+
+.. _v4l2-enc-idx-entry:
+
+.. flat-table:: struct v4l2_enc_idx_entry
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``offset``
+
+ - The offset in bytes from the beginning of the compressed video
+ stream to the beginning of this picture, that is a *PES packet
+ header* as defined in :ref:`mpeg2part1` or a *picture header* as
+ defined in :ref:`mpeg2part2`. When the encoder is stopped, the
+ driver resets the offset to zero.
+
+ - .. row 2
+
+ - __u64
+
+ - ``pts``
+
+ - The 33 bit *Presentation Time Stamp* of this picture as defined in
+ :ref:`mpeg2part1`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``length``
+
+ - The length of this picture in bytes.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags containing the coding type of this picture, see
+ :ref:`enc-idx-flags`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _enc-idx-flags:
+
+.. flat-table:: Index Entry Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_IDX_FRAME_I``
+
+ - 0x00
+
+ - This is an Intra-coded picture.
+
+ - .. row 2
+
+ - ``V4L2_ENC_IDX_FRAME_P``
+
+ - 0x01
+
+ - This is a Predictive-coded picture.
+
+ - .. row 3
+
+ - ``V4L2_ENC_IDX_FRAME_B``
+
+ - 0x02
+
+ - This is a Bidirectionally predictive-coded picture.
+
+ - .. row 4
+
+ - ``V4L2_ENC_IDX_FRAME_MASK``
+
+ - 0x0F
+
+ - *AND* the flags field with this mask to obtain the picture coding
+ type.
+
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-ext-ctrls:
+
+******************************************************************
+ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS
+******************************************************************
+
+*man VIDIOC_G_EXT_CTRLS(2)*
+
+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, int request, struct v4l2_ext_controls *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
+ VIDIOC_TRY_EXT_CTRLS
+
+``argp``
+
+
+Description
+===========
+
+These ioctls allow the caller to get or set multiple controls
+atomically. Control IDs are grouped into control classes (see
+:ref:`ctrl-class`) and all controls in the control array must belong
+to the same control class.
+
+Applications must always fill in the ``count``, ``which``, ``controls``
+and ``reserved`` fields of struct
+:ref:`v4l2_ext_controls <v4l2-ext-controls>`, and initialize the
+struct :ref:`v4l2_ext_control <v4l2-ext-control>` array pointed to
+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
+:ref:`v4l2_ext_control <v4l2-ext-control>` and call the
+``VIDIOC_G_EXT_CTRLS`` ioctl. String controls controls must also set the
+``string`` field. Controls of compound types
+(``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field.
+
+If the ``size`` is too small to receive the control result (only
+relevant for pointer-type controls like strings), then the driver will
+set ``size`` to a valid value and return an ENOSPC error code. You
+should re-allocate the memory to this new size and try again. For the
+string type it is possible that the same issue occurs again if the
+string has grown in the meantime. It is recommended to call
+:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` first and use
+``maximum``\ +1 as the new ``size`` value. It is guaranteed that that is
+sufficient memory.
+
+N-dimensional arrays are set and retrieved row-by-row. You cannot set a
+partial array, all elements have to be set or retrieved. The total size
+is calculated as ``elems`` * ``elem_size``. These values can be obtained
+by calling :ref:`VIDIOC_QUERY_EXT_CTRL <vidioc-queryctrl>`.
+
+To change the value of a set of controls applications initialize the
+``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields
+of each struct :ref:`v4l2_ext_control <v4l2-ext-control>` and call
+the ``VIDIOC_S_EXT_CTRLS`` ioctl. The controls will only be set if *all*
+control values are valid.
+
+To check if a set of controls have correct values applications
+initialize the ``id``, ``size``, ``reserved2`` and
+``value/value64/string/ptr`` fields of each struct
+:ref:`v4l2_ext_control <v4l2-ext-control>` and call the
+``VIDIOC_TRY_EXT_CTRLS`` ioctl. It is up to the driver whether wrong
+values are automatically adjusted to a valid value or if an error is
+returned.
+
+When the ``id`` or ``which`` is invalid drivers return an EINVAL error
+code. When the value is out of bounds drivers can choose to take the
+closest valid value or return an ERANGE error code, whatever seems more
+appropriate. In the first case the new value is set in struct
+:ref:`v4l2_ext_control <v4l2-ext-control>`. If the new control value
+is inappropriate (e.g. the given menu index is not supported by the menu
+control), then this will also result in an EINVAL error code error.
+
+The driver will only set/get these controls if all control values are
+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.
+
+
+.. _v4l2-ext-control:
+
+.. flat-table:: struct v4l2_ext_control
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ - Identifies the control, set by the application.
+
+ - .. row 2
+
+ - __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 ``VIDIOC_G_EXT_CTRLS`` finds that this value is
+ less than is required to store the payload result, then it is set
+ to a value large enough to store the payload result and ENOSPC is
+ returned. Note that for string controls this ``size`` field should
+ not be confused with the length of the string. This field refers
+ to the size of the memory that contains the string. The actual
+ *length* of the string may well be much smaller.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved2``\ [1]
+
+ -
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - union
+
+ - (anonymous)
+
+ - .. row 5
+
+ -
+ - __s32
+
+ - ``value``
+
+ - New value or current value. Valid if this control is not of type
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
+ not set.
+
+ - .. row 6
+
+ -
+ - __s64
+
+ - ``value64``
+
+ - New value or current value. Valid if this control is of type
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
+ not set.
+
+ - .. row 7
+
+ -
+ - char *
+
+ - ``string``
+
+ - A pointer to a string. Valid if this control is of type
+ ``V4L2_CTRL_TYPE_STRING``.
+
+ - .. row 8
+
+ -
+ - __u8 *
+
+ - ``p_u8``
+
+ - A pointer to a matrix control of unsigned 8-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U8``.
+
+ - .. row 9
+
+ -
+ - __u16 *
+
+ - ``p_u16``
+
+ - A pointer to a matrix control of unsigned 16-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U16``.
+
+ - .. row 10
+
+ -
+ - __u32 *
+
+ - ``p_u32``
+
+ - A pointer to a matrix control of unsigned 32-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U32``.
+
+ - .. row 11
+
+ -
+ - void *
+
+ - ``ptr``
+
+ - A pointer to a compound type which can be an N-dimensional array
+ and/or a compound type (the control's type is >=
+ ``V4L2_CTRL_COMPOUND_TYPES``). Valid if
+ ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control.
+
+
+
+.. _v4l2-ext-controls:
+
+.. flat-table:: struct v4l2_ext_controls
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - union
+
+ - (anonymous)
+
+ - .. row 2
+
+ -
+ - __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 ``VIDIOC_TRY_EXT_CTRLS`` with a ``count`` of 0. If that
+ succeeds, then the driver supports this feature.
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``which``
+
+ - Which value of the control to get/set/try.
+ ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the
+ control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default
+ value of the control. Please note that you can only get the
+ default value of the control, you cannot set or try it.
+
+ For backwards compatibility you can also use a control class here
+ (see :ref:`ctrl-class`). In that case all controls have to
+ belong to that control class. This usage is deprecated, instead
+ 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``.
+
+ - .. row 4
+
+ - __u32
+
+ - ``count``
+
+ - The number of controls in the controls array. May also be zero.
+
+ - .. row 5
+
+ - __u32
+
+ - ``error_idx``
+
+ - Set by the driver in case of an error. 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
+ ``error_idx`` is set to ``count``. The value is undefined if the
+ ioctl returned 0 (success).
+
+ Before controls are read from/written to hardware a validation
+ step takes place: this checks if all controls in the list are
+ valid controls, if no attempt is made to write to a read-only
+ control or read from a write-only control, and any other up-front
+ checks that can be done without accessing the hardware. The exact
+ validations done during this step are driver dependent since some
+ checks might require hardware access for some devices, thus making
+ it impossible to do those checks up-front. However, drivers should
+ make a best-effort to do as many up-front checks as possible.
+
+ This check is done to avoid leaving the hardware in an
+ inconsistent state due to easy-to-avoid problems. But it leads to
+ another problem: the application needs to know whether an error
+ came from the validation step (meaning that the hardware was not
+ touched) or from an error during the actual reading from/writing
+ to hardware.
+
+ The, in hindsight quite poor, solution for that is to set
+ ``error_idx`` to ``count`` if the validation failed. This has the
+ unfortunate side-effect that it is not possible to see which
+ control failed the validation. If the validation was successful
+ and the error happened while accessing the hardware, then
+ ``error_idx`` is less than ``count`` and only the controls up to
+ ``error_idx-1`` were read or written correctly, and the state of
+ the remaining controls is undefined.
+
+ Since ``VIDIOC_TRY_EXT_CTRLS`` does not access hardware there is
+ also no need to handle the validation step in this special way, so
+ ``error_idx`` will just be set to the control that failed the
+ validation step instead of to ``count``. This means that if
+ ``VIDIOC_S_EXT_CTRLS`` fails with ``error_idx`` set to ``count``,
+ then you can call ``VIDIOC_TRY_EXT_CTRLS`` to try to discover the
+ actual control that failed the validation step. Unfortunately,
+ there is no ``TRY`` equivalent for ``VIDIOC_G_EXT_CTRLS``.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 7
+
+ - struct :ref:`v4l2_ext_control <v4l2-ext-control>` *
+
+ - ``controls``
+
+ - Pointer to an array of ``count`` v4l2_ext_control structures.
+ Ignored if ``count`` equals zero.
+
+
+
+.. _ctrl-class:
+
+.. flat-table:: Control classes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CTRL_CLASS_USER``
+
+ - 0x980000
+
+ - The class containing user controls. These controls are described
+ in :ref:`control`. All controls that can be set using the
+ :ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` and
+ :ref:`VIDIOC_G_CTRL <vidioc-g-ctrl>` ioctl belong to this
+ class.
+
+ - .. row 2
+
+ - ``V4L2_CTRL_CLASS_MPEG``
+
+ - 0x990000
+
+ - The class containing MPEG compression controls. These controls are
+ described in :ref:`mpeg-controls`.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_CLASS_CAMERA``
+
+ - 0x9a0000
+
+ - The class containing camera controls. These controls are described
+ in :ref:`camera-controls`.
+
+ - .. row 4
+
+ - ``V4L2_CTRL_CLASS_FM_TX``
+
+ - 0x9b0000
+
+ - The class containing FM Transmitter (FM TX) controls. These
+ controls are described in :ref:`fm-tx-controls`.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_CLASS_FLASH``
+
+ - 0x9c0000
+
+ - The class containing flash device controls. These controls are
+ described in :ref:`flash-controls`.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_CLASS_JPEG``
+
+ - 0x9d0000
+
+ - The class containing JPEG compression controls. These controls are
+ described in :ref:`jpeg-controls`.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_CLASS_IMAGE_SOURCE``
+
+ - 0x9e0000
+
+ - The class containing image source controls. These controls are
+ described in :ref:`image-source-controls`.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_CLASS_IMAGE_PROC``
+
+ - 0x9f0000
+
+ - The class containing image processing controls. These controls are
+ described in :ref:`image-process-controls`.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_CLASS_FM_RX``
+
+ - 0xa10000
+
+ - The class containing FM Receiver (FM RX) controls. These controls
+ are described in :ref:`fm-rx-controls`.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_CLASS_RF_TUNER``
+
+ - 0xa20000
+
+ - The class containing RF tuner controls. These controls are
+ described in :ref:`rf-tuner-controls`.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``id`` is
+ invalid, the struct :ref:`v4l2_ext_controls <v4l2-ext-controls>`
+ ``which`` is invalid, or the struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` was
+ inappropriate (e.g. the given menu index is not supported by the
+ driver). This error code is also returned by the
+ ``VIDIOC_S_EXT_CTRLS`` and ``VIDIOC_TRY_EXT_CTRLS`` ioctls if two or
+ more control values are in conflict.
+
+ERANGE
+ The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``value``
+ is out of bounds.
+
+EBUSY
+ The control is temporarily not changeable, possibly because another
+ applications took over control of the device function this control
+ belongs to.
+
+ENOSPC
+ The space reserved for the control's payload is insufficient. The
+ field ``size`` is set to a value that is enough to store the payload
+ and this error code is returned.
+
+EACCES
+ Attempt to try or set a read-only control or to get a write-only
+ control.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-fbuf:
+
+**********************************
+ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
+**********************************
+
+*man VIDIOC_G_FBUF(2)*
+
+VIDIOC_S_FBUF
+Get or set frame buffer overlay parameters
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_framebuffer *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_framebuffer *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FBUF, VIDIOC_S_FBUF
+
+``argp``
+
+
+Description
+===========
+
+Applications can use the ``VIDIOC_G_FBUF`` and ``VIDIOC_S_FBUF`` ioctl
+to get and set the framebuffer parameters for a
+:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
+(OSD). The type of overlay is implied by the device type (capture or
+output device) and can be determined with the
+:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. One ``/dev/videoN``
+device must not support both kinds of overlay.
+
+The V4L2 API distinguishes destructive and non-destructive overlays. A
+destructive overlay copies captured video images into the video memory
+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.
+
+To get the current parameters applications call the ``VIDIOC_G_FBUF``
+ioctl with a pointer to a :c:type:`struct v4l2_framebuffer`
+structure. The driver fills all fields of the structure or returns an
+EINVAL error code when overlays are not supported.
+
+To set the parameters for a *Video Output Overlay*, applications must
+initialize the ``flags`` field of a struct
+:c:type:`struct v4l2_framebuffer`. Since the framebuffer is
+implemented on the TV card all other parameters are determined by the
+driver. When an application calls ``VIDIOC_S_FBUF`` with a pointer to
+this structure, the driver prepares for the overlay and returns the
+framebuffer parameters as ``VIDIOC_G_FBUF`` does, or it returns an error
+code.
+
+To set the parameters for a *non-destructive Video Overlay*,
+applications must initialize the ``flags`` field, the ``fmt``
+substructure, and call ``VIDIOC_S_FBUF``. Again the driver prepares for
+the overlay and returns the framebuffer parameters as ``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.
+
+
+.. _v4l2-framebuffer:
+
+.. flat-table:: struct v4l2_framebuffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ -
+ - Overlay capability flags set by the driver, see
+ :ref:`framebuffer-cap`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - Overlay control flags set by application and driver, see
+ :ref:`framebuffer-flags`
+
+ - .. row 3
+
+ - void *
+
+ - ``base``
+
+ -
+ - Physical base address of the framebuffer, that is the address of
+ the pixel in the top left corner of the framebuffer. [1]_
+
+ - .. row 4
+
+ -
+ -
+ -
+ - 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
+ find the corresponding Linux framebuffer device (see
+ :ref:`osd`).
+
+ - .. row 5
+
+ - struct
+
+ - ``fmt``
+
+ -
+ - Layout of the frame buffer.
+
+ - .. row 6
+
+ -
+ - __u32
+
+ - ``width``
+
+ - Width of the frame buffer in pixels.
+
+ - .. row 7
+
+ -
+ - __u32
+
+ - ``height``
+
+ - Height of the frame buffer in pixels.
+
+ - .. row 8
+
+ -
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format of the framebuffer.
+
+ - .. row 9
+
+ -
+ -
+ -
+ - For *non-destructive Video Overlays* this field only defines a
+ format for the struct :ref:`v4l2_window <v4l2-window>`
+ ``chromakey`` field.
+
+ - .. row 10
+
+ -
+ -
+ -
+ - For *destructive Video Overlays* applications must initialize this
+ field. For *Video Output Overlays* the driver must return a valid
+ format.
+
+ - .. row 11
+
+ -
+ -
+ -
+ - Usually this is an RGB format (for example
+ :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
+ formats (only packed YUV formats when chroma keying is used, not
+ including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
+ ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
+ the driver when an application requests a compressed format is
+ undefined. See :ref:`pixfmt` for information on pixel formats.
+
+ - .. row 12
+
+ -
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - Drivers and applications shall ignore this field. If applicable,
+ the field order is selected with the
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl, using the ``field``
+ field of struct :ref:`v4l2_window <v4l2-window>`.
+
+ - .. row 13
+
+ -
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines.
+
+ - .. row 14
+
+ - :cspan:`3`
+
+ 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
+ reside in accessible memory. Consider for example the case where
+ padding bytes after the last line of an image cross a system page
+ boundary. Capture devices may write padding bytes, the value is
+ undefined. Output devices ignore the contents of padding bytes.
+
+ When the image format is planar the ``bytesperline`` value applies
+ to the first plane and is divided by the same factor as the
+ ``width`` field for the other planes. For example the Cb and Cr
+ planes of a YUV 4:2:0 image have half as many padding bytes
+ following each line as the Y plane. To avoid ambiguities drivers
+ must return a ``bytesperline`` value rounded up to a multiple of
+ the scale factor.
+
+ - .. row 15
+
+ -
+ - __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
+ format.
+
+ Together with ``base`` it defines the framebuffer memory
+ accessible by the driver.
+
+ - .. row 16
+
+ -
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``colorspace``
+
+ - This information supplements the ``pixelformat`` and must be set
+ by the driver, see :ref:`colorspaces`.
+
+ - .. row 17
+
+ -
+ - __u32
+
+ - ``priv``
+
+ - Reserved. Drivers and applications must set this field to zero.
+
+
+
+.. _framebuffer-cap:
+
+.. flat-table:: Frame Buffer Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
+
+ - 0x0001
+
+ - The device is capable of non-destructive overlays. When the driver
+ clears this flag, only destructive overlays are supported. There
+ are no drivers yet which support both destructive and
+ non-destructive overlays. Video Output Overlays are in practice
+ always non-destructive.
+
+ - .. row 2
+
+ - ``V4L2_FBUF_CAP_CHROMAKEY``
+
+ - 0x0002
+
+ - The device supports clipping by chroma-keying the images. That is,
+ image pixels replace pixels in the VGA or video signal only where
+ the latter assume a certain color. Chroma-keying makes no sense
+ for destructive overlays.
+
+ - .. row 3
+
+ - ``V4L2_FBUF_CAP_LIST_CLIPPING``
+
+ - 0x0004
+
+ - The device supports clipping using a list of clip rectangles.
+
+ - .. row 4
+
+ - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
+
+ - 0x0008
+
+ - The device supports clipping using a bit mask.
+
+ - .. row 5
+
+ - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
+
+ - 0x0010
+
+ - The device supports clipping/blending using the alpha channel of
+ the framebuffer or VGA signal. Alpha blending makes no sense for
+ destructive overlays.
+
+ - .. row 6
+
+ - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
+
+ - 0x0020
+
+ - The device supports alpha blending using a global alpha value.
+ Alpha blending makes no sense for destructive overlays.
+
+ - .. row 7
+
+ - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
+
+ - 0x0040
+
+ - The device supports clipping/blending using the inverted alpha
+ channel of the framebuffer or VGA signal. Alpha blending makes no
+ sense for destructive overlays.
+
+ - .. row 8
+
+ - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
+
+ - 0x0080
+
+ - The device supports Source Chroma-keying. Video pixels with the
+ chroma-key colors are replaced by framebuffer pixels, which is
+ exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
+
+
+
+.. _framebuffer-flags:
+
+.. flat-table:: Frame Buffer Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FBUF_FLAG_PRIMARY``
+
+ - 0x0001
+
+ - The framebuffer is the primary graphics surface. In other words,
+ the overlay is destructive. This flag is typically set by any
+ driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
+ capability and it is cleared otherwise.
+
+ - .. row 2
+
+ - ``V4L2_FBUF_FLAG_OVERLAY``
+
+ - 0x0002
+
+ - If this flag is set for a video capture device, then the driver
+ will set the initial overlay size to cover the full framebuffer
+ size, otherwise the existing overlay size (as set by
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`) will be used. Only one
+ video capture driver (bttv) supports this flag. The use of this
+ flag for capture devices is deprecated. There is no way to detect
+ which drivers support this flag, so the only reliable method of
+ setting the overlay size is through
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`. If this flag is set for a
+ video output device, then the video output overlay window is
+ relative to the top-left corner of the framebuffer and restricted
+ to the size of the framebuffer. If it is cleared, then the video
+ output overlay window is relative to the video output display.
+
+ - .. row 3
+
+ - ``V4L2_FBUF_FLAG_CHROMAKEY``
+
+ - 0x0004
+
+ - Use chroma-keying. The chroma-key color is determined by the
+ ``chromakey`` field of struct :ref:`v4l2_window <v4l2-window>`
+ and negotiated with the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
+ ioctl, see :ref:`overlay` and :ref:`osd`.
+
+ - .. row 4
+
+ - :cspan:`2` There are no flags to enable clipping using a list of
+ clip rectangles or a bitmap. These methods are negotiated with the
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl, see :ref:`overlay`
+ and :ref:`osd`.
+
+ - .. row 5
+
+ - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
+
+ - 0x0008
+
+ - Use the alpha channel of the framebuffer to clip or blend
+ framebuffer pixels with video images. The blend function is:
+ output = framebuffer pixel * alpha + video pixel * (1 - alpha).
+ The actual alpha depth depends on the framebuffer pixel format.
+
+ - .. row 6
+
+ - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
+
+ - 0x0010
+
+ - Use a global alpha value to blend the framebuffer with video
+ images. The blend function is: output = (framebuffer pixel * alpha
+ + video pixel * (255 - alpha)) / 255. The alpha value is
+ determined by the ``global_alpha`` field of struct
+ :ref:`v4l2_window <v4l2-window>` and negotiated with the
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl, see :ref:`overlay`
+ and :ref:`osd`.
+
+ - .. row 7
+
+ - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
+
+ - 0x0020
+
+ - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
+ framebuffer to clip or blend framebuffer pixels with video images,
+ but with an inverted alpha value. The blend function is: output =
+ framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
+ alpha depth depends on the framebuffer pixel format.
+
+ - .. row 8
+
+ - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
+
+ - 0x0040
+
+ - Use source chroma-keying. The source chroma-key color is
+ determined by the ``chromakey`` field of struct
+ :ref:`v4l2_window <v4l2-window>` and negotiated with the
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl, see :ref:`overlay`
+ and :ref:`osd`. Both chroma-keying are mutual exclusive to each
+ other, so same ``chromakey`` field of struct
+ :ref:`v4l2_window <v4l2-window>` is being 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.
+
+EPERM
+ ``VIDIOC_S_FBUF`` can only be called by a privileged user to
+ negotiate the parameters for a destructive overlay.
+
+EINVAL
+ The ``VIDIOC_S_FBUF`` parameters are unsuitable.
+
+.. [1]
+ 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>`__.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-fmt:
+
+************************************************
+ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
+************************************************
+
+*man VIDIOC_G_FMT(2)*
+
+VIDIOC_S_FMT
+VIDIOC_TRY_FMT
+Get or set the data format, try a format
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_format *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to negotiate the format of data (typically image
+format) exchanged between driver and application.
+
+To query the current parameters applications set the ``type`` field of a
+struct :c:type:`struct v4l2_format` to the respective buffer (stream)
+type. For example video capture devices use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the
+``VIDIOC_G_FMT`` ioctl with a pointer to this structure the driver fills
+the respective member of the ``fmt`` union. In case of video capture
+devices that is either the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member. When the requested buffer type is not supported drivers return
+an EINVAL error code.
+
+To change the current format parameters applications initialize the
+``type`` field and all fields of the respective ``fmt`` union member.
+For details see the documentation of the various devices types in
+:ref:`devices`. Good practice is to query the current parameters
+first, and to modify only those parameters not suitable for the
+application. When the application calls the ``VIDIOC_S_FMT`` ioctl with
+a pointer to a :c:type:`struct v4l2_format` structure the driver
+checks and adjusts the parameters against hardware abilities. Drivers
+should not return an error code unless the ``type`` field is invalid,
+this is a mechanism to fathom device capabilities and to approach
+parameters acceptable for both the application and driver. On success
+the driver may program the hardware, allocate resources and generally
+prepare for data exchange. Finally the ``VIDIOC_S_FMT`` ioctl returns
+the current format parameters as ``VIDIOC_G_FMT`` does. Very simple,
+inflexible devices may even ignore all input and always return the
+default parameters. However all V4L2 devices exchanging data with the
+application must implement the ``VIDIOC_G_FMT`` and ``VIDIOC_S_FMT``
+ioctl. When the requested buffer type is not supported drivers return an
+EINVAL error code on a ``VIDIOC_S_FMT`` attempt. When I/O is already in
+progress or the resource is not available for other reasons drivers
+return the EBUSY error code.
+
+The ``VIDIOC_TRY_FMT`` ioctl is equivalent to ``VIDIOC_S_FMT`` with one
+exception: it does not change driver state. It can also be called at any
+time, never returning EBUSY. This function is provided to negotiate
+parameters, to learn about hardware limitations, without disabling I/O
+or possibly time consuming hardware preparations. Although strongly
+recommended drivers are not required to implement this ioctl.
+
+The format as returned by ``VIDIOC_TRY_FMT`` must be identical to what
+``VIDIOC_S_FMT`` returns for the same input or output.
+
+
+.. _v4l2-format:
+
+.. flat-table:: struct v4l2_format
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the data stream, see :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - union
+
+ - ``fmt``
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+
+ - ``pix``
+
+ - Definition of an image format, see :ref:`pixfmt`, used by video
+ capture and output devices.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
+
+ - ``pix_mp``
+
+ - Definition of an image format, see :ref:`pixfmt`, used by video
+ capture and output devices that support the
+ :ref:`multi-planar version of the API <planar-apis>`.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_window <v4l2-window>`
+
+ - ``win``
+
+ - Definition of an overlaid image, see :ref:`overlay`, used by
+ video overlay devices.
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+
+ - ``vbi``
+
+ - Raw VBI capture or output parameters. This is discussed in more
+ detail in :ref:`raw-vbi`. Used by raw VBI capture and output
+ devices.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`
+
+ - ``sliced``
+
+ - Sliced VBI capture or output parameters. See :ref:`sliced` for
+ details. Used by sliced VBI capture and output devices.
+
+ - .. row 8
+
+ -
+ - struct :ref:`v4l2_sdr_format <v4l2-sdr-format>`
+
+ - ``sdr``
+
+ - Definition of a data format, see :ref:`pixfmt`, used by SDR
+ capture and output devices.
+
+ - .. row 9
+
+ -
+ - __u8
+
+ - ``raw_data``\ [200]
+
+ - Place holder for future extensions.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_format <v4l2-format>` ``type`` field is
+ invalid or the requested buffer type not supported.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-frequency:
+
+********************************************
+ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
+********************************************
+
+*man VIDIOC_G_FREQUENCY(2)*
+
+VIDIOC_S_FREQUENCY
+Get or set tuner or modulator radio frequency
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_frequency *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_frequency *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
+
+``argp``
+
+
+Description
+===========
+
+To get the current tuner or modulator radio frequency applications set
+the ``tuner`` field of a struct
+:ref:`v4l2_frequency <v4l2-frequency>` to the respective tuner or
+modulator number (only input devices have tuners, only output devices
+have modulators), zero out the ``reserved`` array and call the
+``VIDIOC_G_FREQUENCY`` ioctl with a pointer to this structure. The
+driver stores the current frequency in the ``frequency`` field.
+
+To change the current tuner or modulator radio frequency applications
+initialize the ``tuner``, ``type`` and ``frequency`` fields, and the
+``reserved`` array of a struct :ref:`v4l2_frequency <v4l2-frequency>`
+and call the ``VIDIOC_S_FREQUENCY`` ioctl with a pointer to this
+structure. When the requested frequency is not possible the driver
+assumes the closest possible value. However ``VIDIOC_S_FREQUENCY`` is a
+write-only ioctl, it does not return the actual new frequency.
+
+
+.. _v4l2-frequency:
+
+.. flat-table:: struct v4l2_frequency
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner or modulator index number. This is the same value as in
+ the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
+ the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
+ the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
+ and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
+ field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
+ set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
+ to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
+ ``V4L2_TUNER_RADIO`` for modulators (currently only radio
+ modulators are supported). See :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``frequency``
+
+ - Tuning frequency in units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` or struct
+ :ref:`v4l2_modulator <v4l2-modulator>` ``capability`` flag
+ ``V4L2_TUNER_CAP_LOW`` is set, in units of 62.5 Hz. A 1 Hz unit is
+ used when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+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.
+
+EINVAL
+ The ``tuner`` index is out of bounds or the value in the ``type``
+ field is wrong.
+
+EBUSY
+ A hardware seek is in progress.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-input:
+
+************************************
+ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT
+************************************
+
+*man VIDIOC_G_INPUT(2)*
+
+VIDIOC_S_INPUT
+Query or select the current video input
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, int *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_INPUT, VIDIOC_S_INPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current video input applications call the
+``VIDIOC_G_INPUT`` ioctl with a pointer to an integer where the driver
+stores the number of the input, as in the struct
+:ref:`v4l2_input <v4l2-input>` ``index`` field. This ioctl will fail
+only when there are no video inputs, returning EINVAL.
+
+To select a video input applications store the number of the desired
+input in an integer and call the ``VIDIOC_S_INPUT`` ioctl with a pointer
+to this integer. Side effects are possible. For example inputs may
+support different video standards, so the driver may implicitly switch
+the current standard. Because of these possible side effects
+applications must select an input before querying or negotiating any
+other parameters.
+
+Information about video inputs is available using the
+:ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` ioctl.
+
+
+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.
+
+EINVAL
+ The number of the video input is out of bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-jpegcomp:
+
+******************************************
+ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
+******************************************
+
+*man VIDIOC_G_JPEGCOMP(2)*
+
+VIDIOC_S_JPEGCOMP
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, v4l2_jpegcompression *argp )
+
+.. c:function:: int ioctl( int fd, int request, const v4l2_jpegcompression *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are **deprecated**. New drivers and applications should use
+:ref:`JPEG class controls <jpeg-controls>` for image quality and JPEG
+markers control.
+
+[to do]
+
+Ronald Bultje elaborates:
+
+APP is some application-specific information. The application can set it
+itself, and it'll be stored in the JPEG-encoded fields (eg; interlacing
+information for in an AVI or so). COM is the same, but it's comments,
+like 'encoded by me' or so.
+
+jpeg_markers describes whether the huffman tables, quantization tables
+and the restart interval information (all JPEG-specific stuff) should be
+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.
+
+
+.. _v4l2-jpegcompression:
+
+.. flat-table:: struct v4l2_jpegcompression
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - int
+
+ - ``quality``
+
+ - Deprecated. If
+ :ref:`V4L2_CID_JPEG_COMPRESSION_QUALITY <jpeg-quality-control>`
+ control is exposed by a driver applications should use it instead
+ and ignore this field.
+
+ - .. row 2
+
+ - int
+
+ - ``APPn``
+
+ -
+
+ - .. row 3
+
+ - int
+
+ - ``APP_len``
+
+ -
+
+ - .. row 4
+
+ - char
+
+ - ``APP_data``\ [60]
+
+ -
+
+ - .. row 5
+
+ - int
+
+ - ``COM_len``
+
+ -
+
+ - .. row 6
+
+ - char
+
+ - ``COM_data``\ [60]
+
+ -
+
+ - .. row 7
+
+ - __u32
+
+ - ``jpeg_markers``
+
+ - See :ref:`jpeg-markers`. Deprecated. If
+ :ref:`V4L2_CID_JPEG_ACTIVE_MARKER <jpeg-active-marker-control>`
+ control is exposed by a driver applications should use it instead
+ and ignore this field.
+
+
+
+.. _jpeg-markers:
+
+.. flat-table:: JPEG Markers Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_MARKER_DHT``
+
+ - (1<<3)
+
+ - Define Huffman Tables
+
+ - .. row 2
+
+ - ``V4L2_JPEG_MARKER_DQT``
+
+ - (1<<4)
+
+ - Define Quantization Tables
+
+ - .. row 3
+
+ - ``V4L2_JPEG_MARKER_DRI``
+
+ - (1<<5)
+
+ - Define Restart Interval
+
+ - .. row 4
+
+ - ``V4L2_JPEG_MARKER_COM``
+
+ - (1<<6)
+
+ - Comment segment
+
+ - .. row 5
+
+ - ``V4L2_JPEG_MARKER_APP``
+
+ - (1<<7)
+
+ - App segment, driver will always use APP0
+
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-modulator:
+
+********************************************
+ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
+********************************************
+
+*man VIDIOC_G_MODULATOR(2)*
+
+VIDIOC_S_MODULATOR
+Get or set modulator attributes
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_modulator *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_modulator *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a modulator applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_modulator <v4l2-modulator>` and call the
+``VIDIOC_G_MODULATOR`` ioctl with a pointer to this structure. Drivers
+fill the rest of the structure or return an EINVAL error code when the
+index is out of bounds. To enumerate all modulators applications shall
+begin at index zero, incrementing by one until the driver returns
+EINVAL.
+
+Modulators have two writable properties, an audio modulation set and the
+radio frequency. To change the modulated audio subprograms, applications
+initialize the ``index`` and ``txsubchans`` fields and the ``reserved``
+array and call the ``VIDIOC_S_MODULATOR`` ioctl. Drivers may choose a
+different audio modulation if the request cannot be satisfied. However
+this is a write-only ioctl, it does not return the actual audio
+modulation selected.
+
+:ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and
+``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be
+initialized to zero. The term 'modulator' means SDR transmitter in this
+context.
+
+To change the radio frequency the
+:ref:`VIDIOC_S_FREQUENCY <vidioc-g-frequency>` ioctl is available.
+
+
+.. _v4l2-modulator:
+
+.. flat-table:: struct v4l2_modulator
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the modulator, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the modulator, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Modulator capability flags. No flags are defined for this field,
+ the tuner flags in struct :ref:`v4l2_tuner <v4l2-tuner>` are
+ used accordingly. The audio flags indicate the ability to encode
+ audio subprograms. They will *not* change for example with the
+ current video standard.
+
+ - .. row 4
+
+ - __u32
+
+ - ``rangelow``
+
+ - The lowest tunable frequency in units of 62.5 KHz, or if the
+ ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
+ 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
+ set, in units of 1 Hz.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangehigh``
+
+ - The highest tunable frequency in units of 62.5 KHz, or if the
+ ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
+ 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
+ set, in units of 1 Hz.
+
+ - .. row 6
+
+ - __u32
+
+ - ``txsubchans``
+
+ - With this field applications can determine how audio sub-carriers
+ shall be modulated. It contains a set of flags as defined in
+ :ref:`modulator-txsubchans`. Note the tuner ``rxsubchans`` flags
+ are reused, but the semantics are different. Video output devices
+ are assumed to have an analog or PCM audio input with 1-3
+ channels. The ``txsubchans`` flags select one or more channels for
+ modulation, together with some audio subprogram indicator, for
+ example a stereo pilot tone.
+
+ - .. row 7
+
+ - __u32
+
+ - ``type``
+
+ - :cspan:`2` Type of the modulator, see :ref:`v4l2-tuner-type`.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _modulator-txsubchans:
+
+.. flat-table:: Modulator Audio Transmission Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - 0x0001
+
+ - Modulate channel 1 as mono audio, when the input has more
+ channels, a down-mix of channel 1 and 2. This flag does not
+ combine with ``V4L2_TUNER_SUB_STEREO`` or
+ ``V4L2_TUNER_SUB_LANG1``.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_SUB_STEREO``
+
+ - 0x0002
+
+ - Modulate channel 1 and 2 as left and right channel of a stereo
+ audio signal. When the input has only one channel or two channels
+ and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as
+ left and right channel. This flag does not combine with
+ ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the
+ driver does not support stereo audio it shall fall back to mono.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SUB_LANG1``
+
+ - 0x0008
+
+ - Modulate channel 1 and 2 as primary and secondary language of a
+ bilingual audio signal. When the input has only one channel it is
+ used for both languages. It is not possible to encode the primary
+ or secondary language only. This flag does not combine with
+ ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or
+ ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the
+ respective audio matrix, or the current video standard does not
+ permit bilingual audio the ``VIDIOC_S_MODULATOR`` ioctl shall
+ return an EINVAL error code and the driver shall fall back to mono
+ or stereo mode.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_SUB_LANG2``
+
+ - 0x0004
+
+ - Same effect as ``V4L2_TUNER_SUB_SAP``.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_SUB_SAP``
+
+ - 0x0004
+
+ - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is
+ encoded as mono audio, the last channel as Second Audio Program.
+ When the input has only one channel it is used for both audio
+ tracks. When the input has three channels the mono track is a
+ down-mix of channel 1 and 2. When combined with
+ ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and
+ right stereo audio, channel 3 as Second Audio Program. When the
+ input has only two channels, the first is encoded as left and
+ right channel and the second as SAP. When the input has only one
+ channel it is used for all audio tracks. It is not possible to
+ encode a Second Audio Program only. This flag must combine with
+ ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the
+ hardware does not support the respective audio matrix, or the
+ current video standard does not permit SAP the
+ ``VIDIOC_S_MODULATOR`` ioctl shall return an EINVAL error code and
+ driver shall fall back to mono or stereo mode.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_SUB_RDS``
+
+ - 0x0010
+
+ - Enable the RDS encoder for a radio FM transmitter.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_modulator <v4l2-modulator>` ``index`` is
+ out of bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-output:
+
+**************************************
+ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
+**************************************
+
+*man VIDIOC_G_OUTPUT(2)*
+
+VIDIOC_S_OUTPUT
+Query or select the current video output
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, int *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current video output applications call the
+``VIDIOC_G_OUTPUT`` ioctl with a pointer to an integer where the driver
+stores the number of the output, as in the struct
+:ref:`v4l2_output <v4l2-output>` ``index`` field. This ioctl will
+fail only when there are no video outputs, returning the EINVAL error
+code.
+
+To select a video output applications store the number of the desired
+output in an integer and call the ``VIDIOC_S_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
+effects applications must select an output before querying or
+negotiating any other parameters.
+
+Information about video outputs is available using the
+:ref:`VIDIOC_ENUMOUTPUT <vidioc-enumoutput>` ioctl.
+
+
+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.
+
+EINVAL
+ The number of the video output is out of bounds, or there are no
+ video outputs at all.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-parm:
+
+**********************************
+ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
+**********************************
+
+*man VIDIOC_G_PARM(2)*
+
+VIDIOC_S_PARM
+Get or set streaming parameters
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, v4l2_streamparm *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_PARM, VIDIOC_S_PARM
+
+``argp``
+
+
+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 :c:func:`read()` or
+:c:func:`write()`, which are not augmented by timestamps or sequence
+counters, and to avoid unnecessary data copying.
+
+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.
+
+To get and set the streaming parameters applications call the
+``VIDIOC_G_PARM`` and ``VIDIOC_S_PARM`` ioctl, respectively. They take a
+pointer to a struct :c:type:`struct v4l2_streamparm` which contains a
+union holding separate parameters for input and output devices.
+
+
+.. _v4l2-streamparm:
+
+.. flat-table:: struct v4l2_streamparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - The buffer (stream) type, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type``, set by the
+ application. See :ref:`v4l2-buf-type`
+
+ - .. row 2
+
+ - union
+
+ - ``parm``
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_captureparm <v4l2-captureparm>`
+
+ - ``capture``
+
+ - Parameters for capture devices, used when ``type`` is
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_outputparm <v4l2-outputparm>`
+
+ - ``output``
+
+ - Parameters for output devices, used when ``type`` is
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT``.
+
+ - .. row 5
+
+ -
+ - __u8
+
+ - ``raw_data``\ [200]
+
+ - A place holder for future extensions.
+
+
+
+.. _v4l2-captureparm:
+
+.. flat-table:: struct v4l2_captureparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ - See :ref:`parm-caps`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``capturemode``
+
+ - Set by drivers and applications, see :ref:`parm-flags`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <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.
+
+ 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 :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
+ field). 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.
+
+ Drivers support this function only when they set the
+ ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
+
+ - .. row 4
+
+ - __u32
+
+ - ``extendedmode``
+
+ - Custom (driver specific) streaming parameters. When unused,
+ applications and drivers must set this field to zero. Applications
+ using this field should check the driver name and version, see
+ :ref:`querycap`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``readbuffers``
+
+ - Applications set this field to the desired number of buffers used
+ internally by the driver in :ref:`read() <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
+ :ref:`rw`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _v4l2-outputparm:
+
+.. flat-table:: struct v4l2_outputparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ - See :ref:`parm-caps`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``outputmode``
+
+ - Set by drivers and applications, see :ref:`parm-flags`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``timeperframe``
+
+ - This is the desired period between successive frames output by the
+ driver, in seconds.
+
+ - .. row 4
+
+ - :cspan:`2`
+
+ The field is intended to repeat frames on the driver side in
+ :ref:`write() <func-write>` mode (in streaming mode timestamps
+ can be used to throttle the output), saving I/O bandwidth.
+
+ 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 :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
+ field). 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.
+
+ Drivers support this function only when they set the
+ ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
+
+ - .. row 5
+
+ - __u32
+
+ - ``extendedmode``
+
+ - Custom (driver specific) streaming parameters. When unused,
+ applications and drivers must set this field to zero. Applications
+ using this field should check the driver name and version, see
+ :ref:`querycap`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``writebuffers``
+
+ - Applications set this field to the desired number of buffers used
+ 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
+ :ref:`rw`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _parm-caps:
+
+.. flat-table:: Streaming Parameters Capabilites
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CAP_TIMEPERFRAME``
+
+ - 0x1000
+
+ - The frame skipping/repeating controlled by the ``timeperframe``
+ field is supported.
+
+
+
+.. _parm-flags:
+
+.. flat-table:: Capture Parameters Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_MODE_HIGHQUALITY``
+
+ - 0x0001
+
+ - High quality imaging mode. High quality mode is intended for still
+ imaging applications. The idea is to get the best possible image
+ quality that the hardware can deliver. It is not defined how the
+ driver writer may achieve that; it will depend on the hardware and
+ the ingenuity of the driver writer. High quality mode is a
+ different mode from the regular motion video capture modes. In
+ high quality mode:
+
+ - The driver may be able to capture higher resolutions than for
+ motion capture.
+
+ - The driver may support fewer pixel formats than motion capture
+ (eg; true color).
+
+ - The driver may capture and arithmetically combine multiple
+ successive fields or frames to remove color edge artifacts and
+ reduce the noise in the video data.
+
+ - The driver may capture images in slices like a scanner in order
+ to handle larger format images than would otherwise be
+ possible.
+
+ - An image capture operation may be significantly slower than
+ motion capture.
+
+ - Moving objects in the image might have excessive motion blur.
+
+ - Capture might only work through the :c:func:`read()` 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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-priority:
+
+******************************************
+ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
+******************************************
+
+*man VIDIOC_G_PRIORITY(2)*
+
+VIDIOC_S_PRIORITY
+Query or request the access priority associated with a file descriptor
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, enum v4l2_priority *argp )
+
+.. c:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
+
+``argp``
+ Pointer to an enum v4l2_priority type.
+
+
+Description
+===========
+
+To query the current access priority applications call the
+``VIDIOC_G_PRIORITY`` ioctl with a pointer to an enum v4l2_priority
+variable where the driver stores the current priority.
+
+To request an access priority applications store the desired priority in
+an enum v4l2_priority variable and call ``VIDIOC_S_PRIORITY`` ioctl
+with a pointer to this variable.
+
+
+.. _v4l2-priority:
+
+.. flat-table:: enum v4l2_priority
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_PRIORITY_UNSET``
+
+ - 0
+
+ -
+
+ - .. row 2
+
+ - ``V4L2_PRIORITY_BACKGROUND``
+
+ - 1
+
+ - Lowest priority, usually applications running in background, for
+ example monitoring VBI transmissions. A proxy application running
+ in user space will be necessary if multiple applications want to
+ read from a device at this priority.
+
+ - .. row 3
+
+ - ``V4L2_PRIORITY_INTERACTIVE``
+
+ - 2
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_PRIORITY_DEFAULT``
+
+ - 2
+
+ - Medium priority, usually applications started and interactively
+ controlled by the user. For example TV viewers, Teletext browsers,
+ or just "panel" applications to change the channel or video
+ controls. This is the default priority unless an application
+ requests another.
+
+ - .. row 5
+
+ - ``V4L2_PRIORITY_RECORD``
+
+ - 3
+
+ - Highest priority. Only one file descriptor can have this priority,
+ it blocks any other fd from changing device properties. Usually
+ applications which must not be interrupted, like video recording.
+
+
+
+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.
+
+EINVAL
+ The requested priority value is invalid.
+
+EBUSY
+ Another application already requested higher priority.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-selection:
+
+********************************************
+ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
+********************************************
+
+*man VIDIOC_G_SELECTION(2)*
+
+VIDIOC_S_SELECTION
+Get or set one of the selection rectangles
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_selection *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
+
+``argp``
+
+
+Description
+===========
+
+The ioctls are used to query and configure selection rectangles.
+
+To query the cropping (composing) rectangle set struct
+:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the
+respective buffer type. Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the
+value of struct :ref:`v4l2_selection <v4l2-selection>` ``target``
+field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer
+to table :ref:`v4l2-selections-common` or :ref:`selection-api` for
+additional targets. The ``flags`` and ``reserved`` fields of struct
+:ref:`v4l2_selection <v4l2-selection>` are ignored and they must be
+filled with zeros. The driver fills the rest of the structure or returns
+EINVAL error code if incorrect buffer type or target was used. If
+cropping (composing) is not supported then the active rectangle is not
+mutable and it is always equal to the bounds rectangle. Finally, the
+struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle is filled with
+the current cropping (composing) coordinates. The coordinates are
+expressed in driver-dependent units. The only exception are rectangles
+for images in raw formats, whose coordinates are always expressed in
+pixels.
+
+To change the cropping (composing) rectangle set the struct
+:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the
+respective buffer type. Do not use multiplanar buffers. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. Use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the
+value of struct :ref:`v4l2_selection <v4l2-selection>` ``target`` to
+``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table
+:ref:`v4l2-selections-common` or :ref:`selection-api` for additional
+targets. The struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle need
+to be set to the desired active area. Field struct
+:ref:`v4l2_selection <v4l2-selection>` ``reserved`` is ignored and
+must be filled with zeros. The driver may adjust coordinates of the
+requested rectangle. An application may introduce constraints to control
+rounding behaviour. The struct :ref:`v4l2_selection <v4l2-selection>`
+``flags`` field must be set to one of the following:
+
+- ``0`` - The driver can adjust the rectangle size freely and shall
+ choose a crop/compose rectangle as close as possible to the requested
+ one.
+
+- ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the
+ rectangle. The original rectangle must lay inside the adjusted one.
+
+- ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the
+ rectangle. The adjusted rectangle must lay inside the original one.
+
+- ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the
+ size exactly the same as in the requested rectangle.
+
+Please refer to :ref:`sel-const-adjust`.
+
+The driver may have to adjusts the requested dimensions against hardware
+limits and other parts as the pipeline, i.e. the bounds given by the
+capture/output window or TV display. The closest possible values of
+horizontal and vertical offset and sizes are chosen according to
+following priority:
+
+1. Satisfy constraints from struct
+ :ref:`v4l2_selection <v4l2-selection>` ``flags``.
+
+2. Adjust width, height, left, and top to hardware limits and
+ alignments.
+
+3. Keep center of adjusted rectangle as close as possible to the
+ original one.
+
+4. Keep width and height as close as possible to original ones.
+
+5. Keep horizontal and vertical offset as close as possible to original
+ ones.
+
+On success the struct :ref:`v4l2_rect <v4l2-rect>` ``r`` field
+contains the adjusted rectangle. When the parameters are unsuitable the
+application may modify the cropping (composing) or image parameters and
+repeat the cycle until satisfactory parameters have been negotiated. If
+constraints flags have to be violated at then ERANGE is returned. The
+error indicates that *there exist no rectangle* that satisfies the
+constraints.
+
+Selection targets and flags are documented in
+:ref:`v4l2-selections-common`.
+
+
+.. _sel-const-adjust:
+
+.. figure:: vidioc-g-selection_files/constraints.*
+ :alt: constraints.png
+ :align: center
+
+ Size adjustments with constraint flags.
+
+ Behaviour of rectangle adjustment for different constraint flags.
+
+
+
+
+.. _v4l2-selection:
+
+.. flat-table:: struct v4l2_selection
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the buffer (from enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>`).
+
+ - .. row 2
+
+ - __u32
+
+ - ``target``
+
+ - Used to select between
+ :ref:`cropping and composing rectangles <v4l2-selections-common>`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Flags controlling the selection rectangle adjustments, refer to
+ :ref:`selection flags <v4l2-selection-flags>`.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``r``
+
+ - The selection rectangle.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved[9]``
+
+ - Reserved fields for future use. Drivers and applications must zero
+ this array.
+
+
+
+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.
+
+EINVAL
+ Given buffer type ``type`` or the selection target ``target`` is not
+ supported, or the ``flags`` argument is not valid.
+
+ERANGE
+ It is not possible to adjust struct :ref:`v4l2_rect <v4l2-rect>`
+ ``r`` rectangle to satisfy all constraints given in the ``flags``
+ argument.
+
+EBUSY
+ It is not possible to apply change of the selection rectangle at the
+ moment. Usually because streaming is in progress.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-sliced-vbi-cap:
+
+*****************************
+ioctl VIDIOC_G_SLICED_VBI_CAP
+*****************************
+
+*man VIDIOC_G_SLICED_VBI_CAP(2)*
+
+Query sliced VBI capabilities
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_sliced_vbi_cap *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_SLICED_VBI_CAP
+
+``argp``
+
+
+Description
+===========
+
+To find out which data services are supported by a sliced VBI capture or
+output device, applications initialize the ``type`` field of a struct
+:ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>`, clear the
+``reserved`` array and call the ``VIDIOC_G_SLICED_VBI_CAP`` ioctl. The
+driver fills in the remaining fields or returns an EINVAL error code if
+the sliced VBI API is unsupported or ``type`` is invalid.
+
+Note the ``type`` field was added, and the ioctl changed from read-only
+to write-read, in Linux 2.6.19.
+
+
+.. _v4l2-sliced-vbi-cap:
+
+.. flat-table:: struct v4l2_sliced_vbi_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 3 2 2 2
+
+
+ - .. row 1
+
+ - __u16
+
+ - ``service_set``
+
+ - :cspan:`2` A set of all data services supported by the driver.
+ Equal to the union of all elements of the ``service_lines`` array.
+
+ - .. row 2
+
+ - __u16
+
+ - ``service_lines``\ [2][24]
+
+ - :cspan:`2` Each element of this array contains a set of data
+ services the hardware can look for or insert into a particular
+ scan line. Data services are defined in :ref:`vbi-services`.
+ Array indices map to ITU-R line numbers (see also :ref:`vbi-525`
+ and :ref:`vbi-625`) as follows:
+
+ - .. row 3
+
+ -
+ -
+ - Element
+
+ - 525 line systems
+
+ - 625 line systems
+
+ - .. row 4
+
+ -
+ -
+ - ``service_lines``\ [0][1]
+
+ - 1
+
+ - 1
+
+ - .. row 5
+
+ -
+ -
+ - ``service_lines``\ [0][23]
+
+ - 23
+
+ - 23
+
+ - .. row 6
+
+ -
+ -
+ - ``service_lines``\ [1][1]
+
+ - 264
+
+ - 314
+
+ - .. row 7
+
+ -
+ -
+ - ``service_lines``\ [1][23]
+
+ - 286
+
+ - 336
+
+ - .. row 8
+
+ -
+
+ - .. row 9
+
+ -
+ -
+ - :cspan:`2` The number of VBI lines the hardware can capture or
+ output per frame, or the number of services it can identify on a
+ given line may be limited. For example on PAL line 16 the hardware
+ may be able to look for a VPS or Teletext signal, but not both at
+ the same time. Applications can learn about these limits using the
+ :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl as described in
+ :ref:`sliced`.
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ -
+ -
+ - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
+ ``service_lines``\ [1][0] to zero.
+
+ - .. row 12
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, see :ref:`v4l2-buf-type`. Should be
+ ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
+ ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - :cspan:`2` This array is reserved for future extensions.
+ Applications and drivers must set it to zero.
+
+
+
+.. _vbi-services:
+
+.. flat-table:: Sliced VBI services
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 2 1 1 2 2
+
+
+ - .. row 1
+
+ - Symbol
+
+ - Value
+
+ - Reference
+
+ - Lines, usually
+
+ - Payload
+
+ - .. row 2
+
+ - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
+
+ - 0x0001
+
+ - :ref:`ets300706`, :ref:`itu653`
+
+ - PAL/SECAM line 7-22, 320-335 (second field 7-22)
+
+ - Last 42 of the 45 byte Teletext packet, that is without clock
+ run-in and framing code, lsb first transmitted.
+
+ - .. row 3
+
+ - ``V4L2_SLICED_VPS``
+
+ - 0x0400
+
+ - :ref:`ets300231`
+
+ - PAL line 16
+
+ - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
+ first transmitted.
+
+ - .. row 4
+
+ - ``V4L2_SLICED_CAPTION_525``
+
+ - 0x1000
+
+ - :ref:`cea608`
+
+ - NTSC line 21, 284 (second field 21)
+
+ - Two bytes in transmission order, including parity bit, lsb first
+ transmitted.
+
+ - .. row 5
+
+ - ``V4L2_SLICED_WSS_625``
+
+ - 0x4000
+
+ - :ref:`en300294`, :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
+
+ - .. row 6
+
+ - ``V4L2_SLICED_VBI_525``
+
+ - 0x1000
+
+ - :cspan:`2` Set of services applicable to 525 line systems.
+
+ - .. row 7
+
+ - ``V4L2_SLICED_VBI_625``
+
+ - 0x4401
+
+ - :cspan:`2` Set of services applicable to 625 line systems.
+
+
+
+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.
+
+EINVAL
+ The value in the ``type`` field is wrong.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-std:
+
+********************************
+ioctl VIDIOC_G_STD, VIDIOC_S_STD
+********************************
+
+*man VIDIOC_G_STD(2)*
+
+VIDIOC_S_STD
+Query or select the video standard of the current input
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, v4l2_std_id *argp )
+
+.. c:function:: int ioctl( int fd, int request, const v4l2_std_id *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_STD, VIDIOC_S_STD
+
+``argp``
+
+
+Description
+===========
+
+To query and select the current video standard applications use the
+``VIDIOC_G_STD`` and ``VIDIOC_S_STD`` ioctls which take a pointer to a
+:ref:`v4l2_std_id <v4l2-std-id>` type as argument. ``VIDIOC_G_STD``
+can return a single flag or a set of flags as in struct
+:ref:`v4l2_standard <v4l2-standard>` field ``id``. The flags must be
+unambiguous such that they appear in only one enumerated
+:c:type:`struct v4l2_standard` structure.
+
+``VIDIOC_S_STD`` accepts one or more flags, being a write-only ioctl it
+does not return the actual new standard as ``VIDIOC_G_STD`` does. When
+no flags are given or the current input does not support the requested
+standard the driver returns an EINVAL error code. When the standard set
+is ambiguous drivers may return EINVAL or choose any of the requested
+standards. If the current input or output does not support standard
+video timings (e.g. if :ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>`
+does not set the ``V4L2_IN_CAP_STD`` flag), then ENODATA error code is
+returned.
+
+
+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.
+
+EINVAL
+ The ``VIDIOC_S_STD`` parameter was unsuitable.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-g-tuner:
+
+************************************
+ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
+************************************
+
+*man VIDIOC_G_TUNER(2)*
+
+VIDIOC_S_TUNER
+Get or set tuner attributes
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_tuner *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_tuner *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_TUNER, VIDIOC_S_TUNER
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a tuner applications initialize the ``index``
+field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_tuner <v4l2-tuner>` and call the ``VIDIOC_G_TUNER`` ioctl
+with a pointer to this structure. Drivers fill the rest of the structure
+or return an EINVAL error code when the index is out of bounds. To
+enumerate all tuners applications shall begin at index zero,
+incrementing by one until the driver returns EINVAL.
+
+Tuners have two writable properties, the audio mode and the radio
+frequency. To change the audio mode, applications initialize the
+``index``, ``audmode`` and ``reserved`` fields and call the
+``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
+which is determined by the current video input. Drivers may choose a
+different audio mode if the requested mode is invalid or unsupported.
+Since this is a write-only ioctl, it does not return the actually
+selected audio mode.
+
+:ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
+``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
+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.
+
+
+.. _v4l2-tuner:
+
+.. flat-table:: struct v4l2_tuner
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - :cspan:`1` Identifies the tuner, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - :cspan:`1`
+
+ Name of the tuner, a NUL-terminated ASCII string. This information
+ is intended for the user.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - :cspan:`1` Type of the tuner, see :ref:`v4l2-tuner-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``capability``
+
+ - :cspan:`1`
+
+ Tuner capability flags, see :ref:`tuner-capability`. Audio flags
+ indicate the ability to decode audio subprograms. They will *not*
+ change, for example with the current video standard.
+
+ When the structure refers to a radio tuner the
+ ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
+ ``V4L2_TUNER_CAP_NORM`` flags can't be used.
+
+ If multiple frequency bands are supported, then ``capability`` is
+ the union of all ``capability`` fields of each struct
+ :ref:`v4l2_frequency_band <v4l2-frequency-band>`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangelow``
+
+ - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
+ if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
+ of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
+ is set, in units of 1 Hz. If multiple frequency bands are
+ supported, then ``rangelow`` is the lowest frequency of all the
+ frequency bands.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangehigh``
+
+ - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
+ or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
+ units of 62.5 Hz, or if the ``capability`` flag
+ ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
+ frequency bands are supported, then ``rangehigh`` is the highest
+ frequency of all the frequency bands.
+
+ - .. row 7
+
+ - __u32
+
+ - ``rxsubchans``
+
+ - :cspan:`1`
+
+ Some tuners or audio decoders can determine the received audio
+ subprograms by analyzing audio carriers, pilot tones or other
+ indicators. To pass this information drivers set flags defined in
+ :ref:`tuner-rxsubchans` in this field. For example:
+
+ - .. row 8
+
+ -
+ -
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - receiving mono audio
+
+ - .. row 9
+
+ -
+ -
+ - ``STEREO | SAP``
+
+ - receiving stereo audio and a secondary audio program
+
+ - .. row 10
+
+ -
+ -
+ - ``MONO | STEREO``
+
+ - receiving mono or stereo audio, the hardware cannot distinguish
+
+ - .. row 11
+
+ -
+ -
+ - ``LANG1 | LANG2``
+
+ - receiving bilingual audio
+
+ - .. row 12
+
+ -
+ -
+ - ``MONO | STEREO | LANG1 | LANG2``
+
+ - receiving mono, stereo or bilingual audio
+
+ - .. row 13
+
+ -
+ -
+ - :cspan:`1`
+
+ When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
+ ``_SAP`` flag is cleared in the ``capability`` field, the
+ corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.
+
+ This field is valid only if this is the tuner of the current video
+ input, or when the structure refers to a radio tuner.
+
+ - .. row 14
+
+ - __u32
+
+ - ``audmode``
+
+ - :cspan:`1`
+
+ The selected audio mode, see :ref:`tuner-audmode` for valid
+ values. The audio mode does not affect audio subprogram detection,
+ and like a :ref:`control <control>` it does not automatically
+ change unless the requested mode is invalid or unsupported. See
+ :ref:`tuner-matrix` for possible results when the selected and
+ received audio programs do not match.
+
+ Currently this is the only field of struct
+ :c:type:`struct v4l2_tuner` applications can change.
+
+ - .. row 15
+
+ - __u32
+
+ - ``signal``
+
+ - :cspan:`1` The signal strength if known, ranging from 0 to
+ 65535. Higher values indicate a better signal.
+
+ - .. row 16
+
+ - __s32
+
+ - ``afc``
+
+ - :cspan:`1` Automatic frequency control: When the ``afc`` value
+ is negative, the frequency is too low, when positive too high.
+
+ - .. row 17
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - :cspan:`1` Reserved for future extensions. Drivers and
+ applications must set the array to zero.
+
+
+
+.. _v4l2-tuner-type:
+
+.. flat-table:: enum v4l2_tuner_type
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_RADIO``
+
+ - 1
+
+ -
+
+ - .. row 2
+
+ - ``V4L2_TUNER_ANALOG_TV``
+
+ - 2
+
+ -
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SDR``
+
+ - 4
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_TUNER_RF``
+
+ - 5
+
+ -
+
+
+
+.. _tuner-capability:
+
+.. flat-table:: Tuner and Modulator Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_CAP_LOW``
+
+ - 0x0001
+
+ - When set, tuning frequencies are expressed in units of 62.5 Hz
+ instead of 62.5 kHz.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_CAP_NORM``
+
+ - 0x0002
+
+ - This is a multi-standard tuner; the video standard can or must be
+ switched. (B/G PAL tuners for example are typically not considered
+ multi-standard because the video standard is automatically
+ determined from the frequency band.) The set of supported video
+ standards is available from the struct
+ :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the
+ description of ioctl :ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>`
+ for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
+ capability.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
+
+ - 0x0004
+
+ - If set, then this tuner supports the hardware seek functionality
+ where the seek stops when it reaches the end of the frequency
+ range.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
+
+ - 0x0008
+
+ - If set, then this tuner supports the hardware seek functionality
+ where the seek wraps around when it reaches the end of the
+ frequency range.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_CAP_STEREO``
+
+ - 0x0010
+
+ - Stereo audio reception is supported.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_CAP_LANG1``
+
+ - 0x0040
+
+ - Reception of the primary language of a bilingual audio program is
+ supported. Bilingual audio is a feature of two-channel systems,
+ transmitting the primary language monaural on the main audio
+ carrier and a secondary language monaural on a second carrier.
+ Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
+
+ - .. row 7
+
+ - ``V4L2_TUNER_CAP_LANG2``
+
+ - 0x0020
+
+ - Reception of the secondary language of a bilingual audio program
+ is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
+ capability.
+
+ - .. row 8
+
+ - ``V4L2_TUNER_CAP_SAP``
+
+ - 0x0020
+
+ - Reception of a secondary audio program is supported. This is a
+ feature of the BTSC system which accompanies the NTSC video
+ standard. Two audio carriers are available for mono or stereo
+ transmissions of a primary language, and an independent third
+ carrier for a monaural secondary language. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
+
+ Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags
+ are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
+ supports the ``V4L2_STD_NTSC_M`` video standard.
+
+ - .. row 9
+
+ - ``V4L2_TUNER_CAP_RDS``
+
+ - 0x0080
+
+ - RDS capture is supported. This capability is only valid for radio
+ tuners.
+
+ - .. row 10
+
+ - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
+
+ - 0x0100
+
+ - The RDS data is passed as unparsed RDS blocks.
+
+ - .. row 11
+
+ - ``V4L2_TUNER_CAP_RDS_CONTROLS``
+
+ - 0x0200
+
+ - The RDS data is parsed by the hardware and set via controls.
+
+ - .. row 12
+
+ - ``V4L2_TUNER_CAP_FREQ_BANDS``
+
+ - 0x0400
+
+ - The :ref:`VIDIOC_ENUM_FREQ_BANDS <vidioc-enum-freq-bands>`
+ ioctl can be used to enumerate the available frequency bands.
+
+ - .. row 13
+
+ - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
+
+ - 0x0800
+
+ - The range to search when using the hardware seek functionality is
+ programmable, see
+ :ref:`VIDIOC_S_HW_FREQ_SEEK <vidioc-s-hw-freq-seek>` for
+ details.
+
+ - .. row 14
+
+ - ``V4L2_TUNER_CAP_1HZ``
+
+ - 0x1000
+
+ - When set, tuning frequencies are expressed in units of 1 Hz
+ instead of 62.5 kHz.
+
+
+
+.. _tuner-rxsubchans:
+
+.. flat-table:: Tuner Audio Reception Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - 0x0001
+
+ - The tuner receives a mono audio signal.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_SUB_STEREO``
+
+ - 0x0002
+
+ - The tuner receives a stereo audio signal.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SUB_LANG1``
+
+ - 0x0008
+
+ - The tuner receives the primary language of a bilingual audio
+ signal. Drivers must clear this flag when the current video
+ standard is ``V4L2_STD_NTSC_M``.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_SUB_LANG2``
+
+ - 0x0004
+
+ - The tuner receives the secondary language of a bilingual audio
+ signal (or a second audio program).
+
+ - .. row 5
+
+ - ``V4L2_TUNER_SUB_SAP``
+
+ - 0x0004
+
+ - The tuner receives a Second Audio Program. Note the
+ ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are
+ synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current
+ video standard is ``V4L2_STD_NTSC_M``.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_SUB_RDS``
+
+ - 0x0010
+
+ - The tuner receives an RDS channel.
+
+
+
+.. _tuner-audmode:
+
+.. flat-table:: Tuner Audio Modes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_MODE_MONO``
+
+ - 0
+
+ - Play mono audio. When the tuner receives a stereo signal this a
+ down-mix of the left and right channel. When the tuner receives a
+ bilingual or SAP signal this mode selects the primary language.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_MODE_STEREO``
+
+ - 1
+
+ - Play stereo audio. When the tuner receives bilingual audio it may
+ play different languages on the left and right channel or the
+ primary language is played on both channels.
+
+ Playing different languages in this mode is deprecated. New
+ drivers should do this only in ``MODE_LANG1_LANG2``.
+
+ When the tuner receives no stereo signal or does not support
+ stereo reception the driver shall fall back to ``MODE_MONO``.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_MODE_LANG1``
+
+ - 3
+
+ - Play the primary language, mono or stereo. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_MODE_LANG2``
+
+ - 2
+
+ - Play the secondary language, mono. When the tuner receives no
+ bilingual audio or SAP, or their reception is not supported the
+ driver shall fall back to mono or stereo mode. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_MODE_SAP``
+
+ - 2
+
+ - Play the Second Audio Program. When the tuner receives no
+ bilingual audio or SAP, or their reception is not supported the
+ driver shall fall back to mono or stereo mode. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the
+ ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are
+ synonyms.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_MODE_LANG1_LANG2``
+
+ - 4
+
+ - Play the primary language on the left channel, the secondary
+ language on the right channel. When the tuner receives no
+ bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
+ ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
+ mode.
+
+
+
+.. _tuner-matrix:
+
+.. flat-table:: Tuner Audio Matrix
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - :cspan:`5` Selected ``V4L2_TUNER_MODE_``
+
+ - .. row 2
+
+ - Received ``V4L2_TUNER_SUB_``
+
+ - ``MONO``
+
+ - ``STEREO``
+
+ - ``LANG1``
+
+ - ``LANG2 = SAP``
+
+ - ``LANG1_LANG2``\ [1]_
+
+ - .. row 3
+
+ - ``MONO``
+
+ - Mono
+
+ - Mono/Mono
+
+ - Mono
+
+ - Mono
+
+ - Mono/Mono
+
+ - .. row 4
+
+ - ``MONO | SAP``
+
+ - Mono
+
+ - Mono/Mono
+
+ - Mono
+
+ - SAP
+
+ - Mono/SAP (preferred) or Mono/Mono
+
+ - .. row 5
+
+ - ``STEREO``
+
+ - L+R
+
+ - L/R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - L/R (preferred) or L+R/L+R
+
+ - .. row 6
+
+ - ``STEREO | SAP``
+
+ - L+R
+
+ - L/R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - SAP
+
+ - L+R/SAP (preferred) or L/R or L+R/L+R
+
+ - .. row 7
+
+ - ``LANG1 | LANG2``
+
+ - Language 1
+
+ - Lang1/Lang2 (deprecated [2]_) or Lang1/Lang1
+
+ - Language 1
+
+ - Language 2
+
+ - Lang1/Lang2 (preferred) or Lang1/Lang1
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of
+ bounds.
+
+.. [1]
+ This mode has been added in Linux 2.6.17 and may not be supported by
+ older drivers.
+
+.. [2]
+ Playback of both languages in ``MODE_STEREO`` is deprecated. In the
+ future drivers should produce only the primary language in this mode.
+ Applications should request ``MODE_LANG1_LANG2`` to record both
+ languages or a stereo signal.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-log-status:
+
+***********************
+ioctl VIDIOC_LOG_STATUS
+***********************
+
+*man VIDIOC_LOG_STATUS(2)*
+
+Log driver status information
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request )
+
+Description
+===========
+
+As the video/audio devices become more complicated it becomes harder to
+debug problems. When this ioctl is called the driver will output the
+current device status to the kernel log. This is particular useful when
+dealing with problems like no sound, no video and incorrectly tuned
+channels. Also many modern devices autodetect video and audio standards
+and this ioctl will report what the device thinks what the standard is.
+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
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-overlay:
+
+********************
+ioctl VIDIOC_OVERLAY
+********************
+
+*man VIDIOC_OVERLAY(2)*
+
+Start or stop video overlay
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, const int *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_OVERLAY
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is part of the :ref:`video overlay <overlay>` I/O method.
+Applications call ``VIDIOC_OVERLAY`` to start or stop the overlay. It
+takes a pointer to an integer which must be set to zero by the
+application to stop overlay, to one to start.
+
+Drivers do not support :ref:`VIDIOC_STREAMON <vidioc-streamon>` or
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>` with
+``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
+
+
+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.
+
+EINVAL
+ The overlay parameters have not been set up. See :ref:`overlay`
+ for the necessary steps.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-prepare-buf:
+
+************************
+ioctl VIDIOC_PREPARE_BUF
+************************
+
+*man VIDIOC_PREPARE_BUF(2)*
+
+Prepare a buffer for I/O
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_PREPARE_BUF
+
+``argp``
+
+
+Description
+===========
+
+Applications can optionally call the ``VIDIOC_PREPARE_BUF`` ioctl to
+pass ownership of the buffer to the driver before actually enqueuing it,
+using the ``VIDIOC_QBUF`` ioctl, and to prepare it for future I/O. Such
+preparations may include cache invalidation or cleaning. Performing them
+in advance saves time during the actual I/O. In case such cache
+operations are not required, the application can use one of
+``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` and
+``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` flags to skip the respective step.
+
+The :c:type:`struct v4l2_buffer` structure is specified in
+:ref:`buffer`.
+
+
+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.
+
+EBUSY
+ File I/O is in progress.
+
+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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-qbuf:
+
+*******************************
+ioctl VIDIOC_QBUF, VIDIOC_DQBUF
+*******************************
+
+*man VIDIOC_QBUF(2)*
+
+VIDIOC_DQBUF
+Exchange a buffer with the driver
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QBUF, VIDIOC_DQBUF
+
+``argp``
+
+
+Description
+===========
+
+Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
+(capturing) or filled (output) buffer in the driver's incoming queue.
+The semantics depend on the selected I/O method.
+
+To enqueue a buffer applications set the ``type`` field of a struct
+:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was
+previously used with struct :ref:`v4l2_format <v4l2-format>` ``type``
+and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+Applications must also set the ``index`` field. Valid index numbers
+range from zero to the number of buffers allocated with
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. The contents of the struct :c:type:`struct v4l2_buffer` returned
+by a :ref:`VIDIOC_QUERYBUF <vidioc-querybuf>` ioctl will do as well.
+When the buffer is intended for output (``type`` is
+``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
+or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
+``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
+for details. Applications must also set ``flags`` to 0. The
+``reserved2`` and ``reserved`` fields must be set to 0. When using the
+:ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
+contain a userspace pointer to a filled-in array of struct
+:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field must be set
+to the number of elements in that array.
+
+To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
+with a pointer to this structure the driver sets the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
+the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
+EINVAL error code.
+
+To enqueue a :ref:`user pointer <userp>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
+the address of the buffer and ``length`` to its size. When the
+multi-planar API is used, ``m.userptr`` and ``length`` members of the
+passed array of struct :ref:`v4l2_plane <v4l2-plane>` have to be used
+instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
+the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
+``flags`` field, or it returns an error code. This ioctl locks the
+memory pages of the buffer in physical memory, they cannot be swapped
+out to disk. Buffers remain locked until dequeued, until the
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>` or
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl is called, or until the
+device is closed.
+
+To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
+file descriptor associated with a DMABUF buffer. When the multi-planar
+API is used the ``m.fd`` fields of the passed array of struct
+:ref:`v4l2_plane <v4l2-plane>` have to be used instead. When
+``VIDIOC_QBUF`` is called with a pointer to this structure the driver
+sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
+``flags`` field, or it returns an error code. This ioctl locks the
+buffer. Locking a buffer means passing it to a driver for a hardware
+access (usually DMA). If an application accesses (reads/writes) a locked
+buffer then the result is undefined. Buffers remain locked until
+dequeued, until the :ref:`VIDIOC_STREAMOFF <vidioc-streamon>` or
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl is called, or until the
+device is closed.
+
+Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
+(capturing) or displayed (output) buffer from the driver's outgoing
+queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
+a struct :ref:`v4l2_buffer <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
+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
+buffer might be corrupted. When using the multi-planar API, the planes
+array must be passed in as well.
+
+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
+immediately with an EAGAIN error code when no buffer is available.
+
+The :c:type:`struct v4l2_buffer` structure is specified in
+:ref:`buffer`.
+
+
+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.
+
+EAGAIN
+ Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
+ buffer was in the outgoing queue.
+
+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.
+
+EIO
+ ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
+ temporary problems like signal loss. Note the driver might dequeue
+ an (empty) buffer despite returning an error, or even stop
+ capturing. Reusing such buffer may be unsafe though and its details
+ (e.g. ``index``) may not be returned either. It is recommended that
+ drivers indicate recoverable errors by setting the
+ ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
+ application should be able to safely reuse the buffer and continue
+ streaming.
+
+EPIPE
+ ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
+ codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already
+ dequeued and no new buffers are expected to become available.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-query-dv-timings:
+
+*****************************
+ioctl VIDIOC_QUERY_DV_TIMINGS
+*****************************
+
+*man VIDIOC_QUERY_DV_TIMINGS(2)*
+
+VIDIOC_SUBDEV_QUERY_DV_TIMINGS
+Sense the DV preset received by the current input
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERY_DV_TIMINGS, VIDIOC_SUBDEV_QUERY_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+The hardware may be able to detect the current DV timings automatically,
+similar to sensing the video standard. To do so, applications call
+``VIDIOC_QUERY_DV_TIMINGS`` with a pointer to a struct
+:ref:`v4l2_dv_timings <v4l2-dv-timings>`. Once the hardware detects
+the timings, it will fill in the timings structure.
+
+Please note that drivers shall *not* switch timings automatically if new
+timings are detected. Instead, drivers should send the
+``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
+that userspace will take action by calling ``VIDIOC_QUERY_DV_TIMINGS``.
+The reason is that new timings usually mean different buffer sizes as
+well, and you cannot change buffer sizes on the fly. In general,
+applications that receive the Source Change event will have to call
+``VIDIOC_QUERY_DV_TIMINGS``, and if the detected timings are valid they
+will have to stop streaming, set the new timings, allocate new buffers
+and start streaming again.
+
+If the timings could not be detected because there was no signal, then
+ENOLINK is returned. If a signal was detected, but it was unstable and
+the receiver could not lock to the signal, then ENOLCK is returned. If
+the receiver could lock to the signal, but the format is unsupported
+(e.g. because the pixelclock is out of range of the hardware
+capabilities), then the driver fills in whatever timings it could find
+and returns ERANGE. In that case the application can call
+:ref:`VIDIOC_DV_TIMINGS_CAP <vidioc-dv-timings-cap>` to compare the
+found timings with the hardware's capabilities in order to give more
+precise feedback to the user.
+
+
+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.
+
+ENODATA
+ Digital video timings are not supported for this input or output.
+
+ENOLINK
+ No timings could be detected because no signal was found.
+
+ENOLCK
+ The signal was unstable and the hardware could not lock on to it.
+
+ERANGE
+ Timings were found, but they are out of range of the hardware
+ capabilities.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-querybuf:
+
+*********************
+ioctl VIDIOC_QUERYBUF
+*********************
+
+*man VIDIOC_QUERYBUF(2)*
+
+Query the status of a buffer
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYBUF
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
+be used to query the status of a buffer at any time after buffers have
+been allocated with the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl.
+
+Applications set the ``type`` field of a struct
+:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was
+previously used with struct :ref:`v4l2_format <v4l2-format>` ``type``
+and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``,
+and the ``index`` field. Valid index numbers range from zero to the
+number of buffers allocated with
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
+using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
+field must contain a userspace pointer to an array of struct
+:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field has to be set
+to the number of elements in that array. After calling
+``VIDIOC_QUERYBUF`` with a pointer to this structure drivers return an
+error code or fill the rest of the structure.
+
+In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
+``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
+``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
+set to the current I/O method. For the single-planar API, the
+``m.offset`` contains the offset of the buffer from the start of the
+device memory, the ``length`` field its size. For the multi-planar API,
+fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
+elements will be used instead and the ``length`` field of struct
+:ref:`v4l2_buffer <v4l2-buffer>` is set to the number of filled-in
+array elements. The driver may or may not set the remaining fields and
+flags, they are meaningless in this context.
+
+The :c:type:`struct v4l2_buffer` structure is specified in
+:ref:`buffer`.
+
+
+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.
+
+EINVAL
+ The buffer ``type`` is not supported, or the ``index`` is out of
+ bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-querycap:
+
+*********************
+ioctl VIDIOC_QUERYCAP
+*********************
+
+*man VIDIOC_QUERYCAP(2)*
+
+Query device capabilities
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_capability *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYCAP
+
+``argp``
+
+
+Description
+===========
+
+All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to
+identify kernel devices compatible with this specification and to obtain
+information about driver and hardware capabilities. The ioctl takes a
+pointer to a struct :ref:`v4l2_capability <v4l2-capability>` which is
+filled by the driver. When the driver is not compatible with this
+specification the ioctl returns an EINVAL error code.
+
+
+.. _v4l2-capability:
+
+.. flat-table:: struct v4l2_capability
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``driver``\ [16]
+
+ - Name of the driver, a unique NUL-terminated ASCII string. For
+ example: "bttv". Driver specific applications can use this
+ information to verify the driver identity. It is also useful to
+ work around known bugs, or to identify drivers in error reports.
+
+ Storing strings in fixed sized arrays is bad practice but
+ unavoidable here. Drivers and applications should take precautions
+ to never read or write beyond the end of the array and to make
+ sure the strings are properly NUL-terminated.
+
+ - .. row 2
+
+ - __u8
+
+ - ``card``\ [32]
+
+ - Name of the device, a NUL-terminated UTF-8 string. For example:
+ "Yoyodyne TV/FM". One driver may support different brands or
+ models of video hardware. This information is intended for users,
+ for example in a menu of available devices. Since multiple TV
+ cards of the same brand may be installed which are supported by
+ the same driver, this name should be combined with the character
+ device file name (e. g. ``/dev/video2``) or the ``bus_info``
+ string to avoid ambiguities.
+
+ - .. row 3
+
+ - __u8
+
+ - ``bus_info``\ [32]
+
+ - Location of the device in the system, a NUL-terminated ASCII
+ string. For example: "PCI:0000:05:06.0". This information is
+ intended for users, to distinguish multiple identical devices. If
+ no such information is available the field must simply count the
+ devices controlled by the driver ("platform:vivi-000"). The
+ bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI
+ Express boards, "usb-" for USB devices, "I2C:" for i2c devices,
+ "ISA:" for ISA devices, "parport" for parallel port devices and
+ "platform:" for platform devices.
+
+ - .. row 4
+
+ - __u32
+
+ - ``version``
+
+ - Version number of the driver.
+
+ Starting with kernel 3.1, the version reported is provided by the
+ V4L2 subsystem following the kernel numbering scheme. However, it
+ may not always return the same version as the kernel if, for
+ example, a stable or distribution-modified kernel uses the V4L2
+ stack from a newer kernel.
+
+ The version number is formatted using the ``KERNEL_VERSION()``
+ macro:
+
+ - .. row 5
+
+ - :cspan:`2`
+
+
+ .. code-block:: c
+
+ #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
+
+ __u32 version = KERNEL_VERSION(0, 8, 1);
+
+ printf ("Version: %u.%u.%u\\n",
+ (version >> 16) & 0xFF,
+ (version >> 8) & 0xFF,
+ version & 0xFF);
+
+ - .. row 6
+
+ - __u32
+
+ - ``capabilities``
+
+ - Available capabilities of the physical device as a whole, see
+ :ref:`device-capabilities`. The same physical device can export
+ multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and
+ /dev/radioZ). The ``capabilities`` field should contain a union of
+ all capabilities available around the several V4L2 devices
+ exported to userspace. For all those devices the ``capabilities``
+ field returns the same set of capabilities. This allows
+ applications to open just one of the devices (typically the video
+ device) and discover whether video, vbi and/or radio are also
+ supported.
+
+ - .. row 7
+
+ - __u32
+
+ - ``device_caps``
+
+ - Device capabilities of the opened device, see
+ :ref:`device-capabilities`. Should contain the available
+ capabilities of that specific device node. So, for example,
+ ``device_caps`` of a radio device will only contain radio related
+ capabilities and no video or vbi capabilities. This field is only
+ set if the ``capabilities`` field contains the
+ ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities``
+ field can have the ``V4L2_CAP_DEVICE_CAPS`` capability,
+ ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set this array to
+ zero.
+
+
+
+.. _device-capabilities:
+
+.. flat-table:: Device Capabilities Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CAP_VIDEO_CAPTURE``
+
+ - 0x00000001
+
+ - The device supports the single-planar API through the
+ :ref:`Video Capture <capture>` interface.
+
+ - .. row 2
+
+ - ``V4L2_CAP_VIDEO_CAPTURE_MPLANE``
+
+ - 0x00001000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the :ref:`Video Capture <capture>` interface.
+
+ - .. row 3
+
+ - ``V4L2_CAP_VIDEO_OUTPUT``
+
+ - 0x00000002
+
+ - The device supports the single-planar API through the
+ :ref:`Video Output <output>` interface.
+
+ - .. row 4
+
+ - ``V4L2_CAP_VIDEO_OUTPUT_MPLANE``
+
+ - 0x00002000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the :ref:`Video Output <output>` interface.
+
+ - .. row 5
+
+ - ``V4L2_CAP_VIDEO_M2M``
+
+ - 0x00004000
+
+ - The device supports the single-planar API through the Video
+ Memory-To-Memory interface.
+
+ - .. row 6
+
+ - ``V4L2_CAP_VIDEO_M2M_MPLANE``
+
+ - 0x00008000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the Video Memory-To-Memory interface.
+
+ - .. row 7
+
+ - ``V4L2_CAP_VIDEO_OVERLAY``
+
+ - 0x00000004
+
+ - The device supports the :ref:`Video Overlay <overlay>`
+ interface. A video overlay device typically stores captured images
+ directly in the video memory of a graphics card, with hardware
+ clipping and scaling.
+
+ - .. row 8
+
+ - ``V4L2_CAP_VBI_CAPTURE``
+
+ - 0x00000010
+
+ - The device supports the :ref:`Raw VBI Capture <raw-vbi>`
+ interface, providing Teletext and Closed Caption data.
+
+ - .. row 9
+
+ - ``V4L2_CAP_VBI_OUTPUT``
+
+ - 0x00000020
+
+ - The device supports the :ref:`Raw VBI Output <raw-vbi>`
+ interface.
+
+ - .. row 10
+
+ - ``V4L2_CAP_SLICED_VBI_CAPTURE``
+
+ - 0x00000040
+
+ - The device supports the :ref:`Sliced VBI Capture <sliced>`
+ interface.
+
+ - .. row 11
+
+ - ``V4L2_CAP_SLICED_VBI_OUTPUT``
+
+ - 0x00000080
+
+ - The device supports the :ref:`Sliced VBI Output <sliced>`
+ interface.
+
+ - .. row 12
+
+ - ``V4L2_CAP_RDS_CAPTURE``
+
+ - 0x00000100
+
+ - The device supports the :ref:`RDS <rds>` capture interface.
+
+ - .. row 13
+
+ - ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY``
+
+ - 0x00000200
+
+ - The device supports the :ref:`Video Output Overlay <osd>` (OSD)
+ interface. Unlike the *Video Overlay* interface, this is a
+ secondary function of video output devices and overlays an image
+ onto an outgoing video signal. When the driver sets this flag, it
+ must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice
+ versa. [1]_
+
+ - .. row 14
+
+ - ``V4L2_CAP_HW_FREQ_SEEK``
+
+ - 0x00000400
+
+ - The device supports the
+ :ref:`VIDIOC_S_HW_FREQ_SEEK <vidioc-s-hw-freq-seek>` ioctl
+ for hardware frequency seeking.
+
+ - .. row 15
+
+ - ``V4L2_CAP_RDS_OUTPUT``
+
+ - 0x00000800
+
+ - The device supports the :ref:`RDS <rds>` output interface.
+
+ - .. row 16
+
+ - ``V4L2_CAP_TUNER``
+
+ - 0x00010000
+
+ - The device has some sort of tuner to receive RF-modulated video
+ signals. For more information about tuner programming see
+ :ref:`tuner`.
+
+ - .. row 17
+
+ - ``V4L2_CAP_AUDIO``
+
+ - 0x00020000
+
+ - The device has audio inputs or outputs. It may or may not support
+ audio recording or playback, in PCM or compressed formats. PCM
+ audio support must be implemented as ALSA or OSS interface. For
+ more information on audio inputs and outputs see :ref:`audio`.
+
+ - .. row 18
+
+ - ``V4L2_CAP_RADIO``
+
+ - 0x00040000
+
+ - This is a radio receiver.
+
+ - .. row 19
+
+ - ``V4L2_CAP_MODULATOR``
+
+ - 0x00080000
+
+ - The device has some sort of modulator to emit RF-modulated
+ video/audio signals. For more information about modulator
+ programming see :ref:`tuner`.
+
+ - .. row 20
+
+ - ``V4L2_CAP_SDR_CAPTURE``
+
+ - 0x00100000
+
+ - The device supports the :ref:`SDR Capture <sdr>` interface.
+
+ - .. row 21
+
+ - ``V4L2_CAP_EXT_PIX_FORMAT``
+
+ - 0x00200000
+
+ - The device supports the struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>` extended fields.
+
+ - .. row 22
+
+ - ``V4L2_CAP_SDR_OUTPUT``
+
+ - 0x00400000
+
+ - The device supports the :ref:`SDR Output <sdr>` interface.
+
+ - .. row 23
+
+ - ``V4L2_CAP_READWRITE``
+
+ - 0x01000000
+
+ - The device supports the :ref:`read() <rw>` and/or
+ :ref:`write() <rw>` I/O methods.
+
+ - .. row 24
+
+ - ``V4L2_CAP_ASYNCIO``
+
+ - 0x02000000
+
+ - The device supports the :ref:`asynchronous <async>` I/O methods.
+
+ - .. row 25
+
+ - ``V4L2_CAP_STREAMING``
+
+ - 0x04000000
+
+ - The device supports the :ref:`streaming <mmap>` I/O method.
+
+ - .. row 26
+
+ - ``V4L2_CAP_DEVICE_CAPS``
+
+ - 0x80000000
+
+ - The driver fills the ``device_caps`` field. This capability can
+ only appear in the ``capabilities`` field and never in the
+ ``device_caps`` field.
+
+
+
+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.
+
+.. [1]
+ The struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` lacks an
+ enum :ref:`v4l2_buf_type <v4l2-buf-type>` field, therefore the
+ type of overlay is implied by the driver capabilities.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-queryctrl:
+
+***************************************************************
+ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU
+***************************************************************
+
+*man VIDIOC_QUERYCTRL(2)*
+
+VIDIOC_QUERY_EXT_CTRL
+VIDIOC_QUERYMENU
+Enumerate controls and menu control items
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_queryctrl *argp )
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_query_ext_ctrl *argp )
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_querymenu *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a control applications set the ``id`` field
+of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
+``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
+fills the rest of the structure or returns an EINVAL error code when the
+``id`` is invalid.
+
+It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
+with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
+exclusive ``V4L2_CID_LASTP1``. Drivers may return EINVAL if a control in
+this range is not supported. Further applications can enumerate private
+controls, which are not defined in this specification, by starting at
+``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
+returns EINVAL.
+
+In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
+in the ``flags`` field this control is permanently disabled and should
+be ignored by the application. [1]_
+
+When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
+driver returns the next supported non-compound control, or EINVAL if
+there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
+can be specified to enumerate all compound controls (i.e. controls with
+type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
+controls that contain more than one value). Specify both
+``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
+order to enumerate all controls, compound or not. Drivers which do not
+support these flags yet always return EINVAL.
+
+The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
+support controls that can use compound types, and to expose additional
+control information that cannot be returned in struct
+:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
+
+``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
+``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
+as well.
+
+Additional information is required for menu controls: the names of the
+menu items. To query them applications set the ``id`` and ``index``
+fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
+``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
+fills the rest of the structure or returns an EINVAL error code when the
+``id`` or ``index`` is invalid. Menu items are enumerated by calling
+``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
+:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
+inclusive. Note that it is possible for ``VIDIOC_QUERYMENU`` to return
+an EINVAL error code for some indices between ``minimum`` and
+``maximum``. In that case that particular menu item is not supported by
+this driver. Also note that the ``minimum`` value is not necessarily 0.
+
+See also the examples in :ref:`control`.
+
+
+.. _v4l2-queryctrl:
+
+.. flat-table:: struct v4l2_queryctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application. See
+ :ref:`control-id` for predefined IDs. When the ID is ORed with
+ V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
+ returns the first control with a higher ID. Drivers which do not
+ support this flag yet always return an EINVAL error code.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of control, see :ref:`v4l2-ctrl-type`.
+
+ - .. row 3
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the control, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 4
+
+ - __s32
+
+ - ``minimum``
+
+ - Minimum value, inclusive. This field gives a lower bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the minimum value is to be used for each possible control type.
+ Note that this a signed 32-bit value.
+
+ - .. row 5
+
+ - __s32
+
+ - ``maximum``
+
+ - Maximum value, inclusive. This field gives an upper bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the maximum value is to be used for each possible control type.
+ Note that this a signed 32-bit value.
+
+ - .. row 6
+
+ - __s32
+
+ - ``step``
+
+ - This field gives a step size for the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
+ to be used for each possible control type. Note that this an
+ unsigned 32-bit value.
+
+ Generally drivers should not scale hardware control values. It may
+ be necessary for example when the ``name`` or ``id`` imply a
+ particular unit and the hardware actually accepts only multiples
+ of said unit. If so, drivers must take care values are properly
+ rounded when scaling, such that errors will not accumulate on
+ repeated read-write cycles.
+
+ This field gives the smallest change of an integer control
+ actually affecting hardware. Often the information is needed when
+ the user can change controls by keyboard or GUI buttons, rather
+ than a slider. When for example a hardware register accepts values
+ 0-511 and the driver reports 0-65535, step should be 128.
+
+ Note that although signed, the step value is supposed to be always
+ positive.
+
+ - .. row 7
+
+ - __s32
+
+ - ``default_value``
+
+ - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
+ ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
+ for other types of controls. Note that drivers reset controls to
+ their default value only when the driver is first loaded, never
+ afterwards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - Control flags, see :ref:`control-flags`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-query-ext-ctrl:
+
+.. flat-table:: struct v4l2_query_ext_ctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application. See
+ :ref:`control-id` for predefined IDs. When the ID is ORed with
+ ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
+ returns the first non-compound control with a higher ID. When the
+ ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
+ the flag and returns the first compound control with a higher ID.
+ Set both to get the first control (compound or not) with a higher
+ ID.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of control, see :ref:`v4l2-ctrl-type`.
+
+ - .. row 3
+
+ - char
+
+ - ``name``\ [32]
+
+ - Name of the control, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 4
+
+ - __s64
+
+ - ``minimum``
+
+ - Minimum value, inclusive. This field gives a lower bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the minimum value is to be used for each possible control type.
+ Note that this a signed 64-bit value.
+
+ - .. row 5
+
+ - __s64
+
+ - ``maximum``
+
+ - Maximum value, inclusive. This field gives an upper bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the maximum value is to be used for each possible control type.
+ Note that this a signed 64-bit value.
+
+ - .. row 6
+
+ - __u64
+
+ - ``step``
+
+ - This field gives a step size for the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
+ to be used for each possible control type. Note that this an
+ unsigned 64-bit value.
+
+ Generally drivers should not scale hardware control values. It may
+ be necessary for example when the ``name`` or ``id`` imply a
+ particular unit and the hardware actually accepts only multiples
+ of said unit. If so, drivers must take care values are properly
+ rounded when scaling, such that errors will not accumulate on
+ repeated read-write cycles.
+
+ This field gives the smallest change of an integer control
+ actually affecting hardware. Often the information is needed when
+ the user can change controls by keyboard or GUI buttons, rather
+ than a slider. When for example a hardware register accepts values
+ 0-511 and the driver reports 0-65535, step should be 128.
+
+ - .. row 7
+
+ - __s64
+
+ - ``default_value``
+
+ - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
+ ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
+ or ``_U16`` control. Not valid for other types of controls. Note
+ that drivers reset controls to their default value only when the
+ driver is first loaded, never afterwards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - Control flags, see :ref:`control-flags`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``elem_size``
+
+ - The size in bytes of a single element of the array. Given a char
+ pointer ``p`` to a 3-dimensional array you can find the position
+ of cell ``(z, y, x)`` as follows:
+ ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
+ ``elem_size`` is always valid, also when the control isn't an
+ array. For string controls ``elem_size`` is equal to
+ ``maximum + 1``.
+
+ - .. row 10
+
+ - __u32
+
+ - ``elems``
+
+ - The number of elements in the N-dimensional array. If this control
+ is not an array, then ``elems`` is 1. The ``elems`` field can
+ never be 0.
+
+ - .. row 11
+
+ - __u32
+
+ - ``nr_of_dims``
+
+ - The number of dimension in the N-dimensional array. If this
+ control is not an array, then this field is 0.
+
+ - .. row 12
+
+ - __u32
+
+ - ``dims[V4L2_CTRL_MAX_DIMS]``
+
+ - The size of each dimension. The first ``nr_of_dims`` elements of
+ this array must be non-zero, all remaining elements must be zero.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [32]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-querymenu:
+
+.. flat-table:: struct v4l2_querymenu
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ -
+ - ``id``
+
+ - Identifies the control, set by the application from the respective
+ struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
+
+ - .. row 2
+
+ - __u32
+
+ -
+ - ``index``
+
+ - Index of the menu item, starting at zero, set by the application.
+
+ - .. row 3
+
+ - union
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the menu item, a NUL-terminated ASCII string. This
+ information is intended for the user. This field is valid for
+ ``V4L2_CTRL_FLAG_MENU`` type controls.
+
+ - .. row 5
+
+ -
+ - __s64
+
+ - ``value``
+
+ - Value of the integer menu item. This field is valid for
+ ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls.
+
+ - .. row 6
+
+ - __u32
+
+ -
+ - ``reserved``
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-ctrl-type:
+
+.. flat-table:: enum v4l2_ctrl_type
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 30 5 5 5 55
+
+
+ - .. row 1
+
+ - Type
+
+ - ``minimum``
+
+ - ``step``
+
+ - ``maximum``
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_CTRL_TYPE_INTEGER``
+
+ - any
+
+ - any
+
+ - any
+
+ - An integer-valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_TYPE_BOOLEAN``
+
+ - 0
+
+ - 1
+
+ - 1
+
+ - A boolean-valued control. Zero corresponds to "disabled", and one
+ means "enabled".
+
+ - .. row 4
+
+ - ``V4L2_CTRL_TYPE_MENU``
+
+ - ≥ 0
+
+ - 1
+
+ - N-1
+
+ - The control has a menu of N choices. The names of the menu items
+ can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_TYPE_INTEGER_MENU``
+
+ - ≥ 0
+
+ - 1
+
+ - N-1
+
+ - The control has a menu of N choices. The values of the menu items
+ can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
+ similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
+ the menu items are signed 64-bit integers.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_TYPE_BITMASK``
+
+ - 0
+
+ - n/a
+
+ - any
+
+ - A bitmask field. The maximum value is the set of bits that can be
+ used, all other bits are to be 0. The maximum value is interpreted
+ as a __u32, allowing the use of bit 31 in the bitmask.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_TYPE_BUTTON``
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - A control which performs an action when set. Drivers must ignore
+ the value passed with ``VIDIOC_S_CTRL`` and return an EINVAL error
+ code on a ``VIDIOC_G_CTRL`` attempt.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_TYPE_INTEGER64``
+
+ - any
+
+ - any
+
+ - any
+
+ - A 64-bit integer valued control. Minimum, maximum and step size
+ cannot be queried using ``VIDIOC_QUERYCTRL``. Only
+ ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
+ values, they should be interpreted as n/a when using
+ ``VIDIOC_QUERYCTRL``.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_TYPE_STRING``
+
+ - ≥ 0
+
+ - ≥ 1
+
+ - ≥ 0
+
+ - The minimum and maximum string lengths. The step size means that
+ the string must be (minimum + N * step) characters long for N ≥ 0.
+ These lengths do not include the terminating zero, so in order to
+ pass a string of length 8 to
+ :ref:`VIDIOC_S_EXT_CTRLS <vidioc-g-ext-ctrls>` you need to
+ set the ``size`` field of struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>` to 9. For
+ :ref:`VIDIOC_G_EXT_CTRLS <vidioc-g-ext-ctrls>` you can set
+ the ``size`` field to ``maximum`` + 1. Which character encoding is
+ used will depend on the string control itself and should be part
+ of the control documentation.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_TYPE_CTRL_CLASS``
+
+ - n/a
+
+ - n/a
+
+ - n/a
+
+ - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
+ control ID equal to a control class code (see :ref:`ctrl-class`)
+ + 1, the ioctl returns the name of the control class and this
+ control type. Older drivers which do not support this feature
+ return an EINVAL error code.
+
+ - .. row 11
+
+ - ``V4L2_CTRL_TYPE_U8``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 8-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 12
+
+ - ``V4L2_CTRL_TYPE_U16``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 16-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 13
+
+ - ``V4L2_CTRL_TYPE_U32``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 32-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+
+
+.. _control-flags:
+
+.. flat-table:: Control Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CTRL_FLAG_DISABLED``
+
+ - 0x0001
+
+ - This control is permanently disabled and should be ignored by the
+ application. Any attempt to change the control will result in an
+ EINVAL error code.
+
+ - .. row 2
+
+ - ``V4L2_CTRL_FLAG_GRABBED``
+
+ - 0x0002
+
+ - This control is temporarily unchangeable, for example because
+ another application took over control of the respective resource.
+ Such controls may be displayed specially in a user interface.
+ Attempts to change the control may result in an EBUSY error code.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_FLAG_READ_ONLY``
+
+ - 0x0004
+
+ - This control is permanently readable only. Any attempt to change
+ the control will result in an EINVAL error code.
+
+ - .. row 4
+
+ - ``V4L2_CTRL_FLAG_UPDATE``
+
+ - 0x0008
+
+ - A hint that changing this control may affect the value of other
+ controls within the same control class. Applications should update
+ their user interface accordingly.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_FLAG_INACTIVE``
+
+ - 0x0010
+
+ - This control is not applicable to the current configuration and
+ should be displayed accordingly in a user interface. For example
+ the flag may be set on a MPEG audio level 2 bitrate control when
+ MPEG audio encoding level 1 was selected with another control.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_FLAG_SLIDER``
+
+ - 0x0020
+
+ - A hint that this control is best represented as a slider-like
+ element in a user interface.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_FLAG_WRITE_ONLY``
+
+ - 0x0040
+
+ - This control is permanently writable only. Any attempt to read the
+ control will result in an EACCES error code error code. This flag
+ is typically present for relative controls or action controls
+ where writing a value will cause the device to carry out a given
+ action (e. g. motor control) but no meaningful value can be
+ returned.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_FLAG_VOLATILE``
+
+ - 0x0080
+
+ - This control is volatile, which means that the value of the
+ control changes continuously. A typical example would be the
+ current gain value if the device is in auto-gain mode. In such a
+ case the hardware calculates the gain value based on the lighting
+ conditions which can change over time. Note that setting a new
+ value for a volatile control will have no effect and no
+ ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless the
+ ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is also set.
+ Otherwise the new value will just be ignored.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
+
+ - 0x0100
+
+ - This control has a pointer type, so its value has to be accessed
+ using one of the pointer fields of struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>`. This flag is set
+ for controls that are an array, string, or have a compound type.
+ In all cases you have to set a pointer to memory containing the
+ payload of the control.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
+
+ - 0x0200
+
+ - The value provided to the control will be propagated to the driver
+ even if it remains constant. This is required when the control
+ represents an action on the hardware. For example: clearing an
+ error flag or triggering the flash. All the controls of the type
+ ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
+
+
+
+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.
+
+EINVAL
+ The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
+ invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
+ is invalid or ``index`` is out of range (less than ``minimum`` or
+ greater than ``maximum``) or this particular menu item is not
+ supported by the driver.
+
+EACCES
+ An attempt was made to read a write-only control.
+
+.. [1]
+ ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
+ can skip predefined controls not supported by the hardware (although
+ returning EINVAL would do as well), or disable predefined and private
+ controls after hardware detection without the trouble of reordering
+ control arrays and indices (EINVAL cannot be used to skip private
+ controls because it would prematurely end the enumeration).
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-querystd:
+
+*********************
+ioctl VIDIOC_QUERYSTD
+*********************
+
+*man VIDIOC_QUERYSTD(2)*
+
+Sense the video standard received by the current input
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, v4l2_std_id *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYSTD
+
+``argp``
+
+
+Description
+===========
+
+The hardware may be able to detect the current video standard
+automatically. To do so, applications call ``VIDIOC_QUERYSTD`` with a
+pointer to a :ref:`v4l2_std_id <v4l2-std-id>` type. The driver
+stores here a set of candidates, this can be a single flag or a set of
+supported standards if for example the hardware can only distinguish
+between 50 and 60 Hz systems. If no signal was detected, then the driver
+will return V4L2_STD_UNKNOWN. When detection is not possible or fails,
+the set must contain all standards supported by the current video input
+or output.
+
+Please note that drivers shall *not* switch the video standard
+automatically if a new video standard is detected. Instead, drivers
+should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support
+this) and expect that userspace will take action by calling
+``VIDIOC_QUERYSTD``. The reason is that a new video standard can mean
+different buffer sizes as well, and you cannot change buffer sizes on
+the fly. In general, applications that receive the Source Change event
+will have to call ``VIDIOC_QUERYSTD``, and if the detected video
+standard is valid they will have to stop streaming, set the new
+standard, allocate new buffers and start streaming again.
+
+
+Return Value
+============
+
+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.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-reqbufs:
+
+********************
+ioctl VIDIOC_REQBUFS
+********************
+
+*man VIDIOC_REQBUFS(2)*
+
+Initiate Memory Mapping or User Pointer I/O
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_requestbuffers *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_REQBUFS
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is used to initiate :ref:`memory mapped <mmap>`,
+:ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O.
+Memory mapped buffers are located in device memory and must be allocated
+with this ioctl before they can be mapped into the application's address
+space. User buffers are allocated by applications themselves, and this
+ioctl is merely used to switch the driver into user pointer I/O mode and
+to setup some internal structures. Similarly, DMABUF buffers are
+allocated by applications through a device driver, and this ioctl only
+configures the driver into DMABUF I/O mode without performing any direct
+allocation.
+
+To allocate device buffers applications initialize all fields of the
+:c:type:`struct v4l2_requestbuffers` structure. They set the ``type``
+field to the respective stream or buffer type, the ``count`` field to
+the desired number of buffers, ``memory`` must be set to the requested
+I/O method and the ``reserved`` array must be zeroed. When the ioctl is
+called with a pointer to this structure the driver will attempt to
+allocate the requested number of buffers and it stores the actual number
+allocated in the ``count`` field. It can be smaller than the number
+requested, even zero, when the driver runs out of free memory. A larger
+number is also possible when the driver requires more buffers to
+function correctly. For example video output requires at least two
+buffers, one displayed and one filled by the application.
+
+When the I/O method is not supported the ioctl returns an EINVAL error
+code.
+
+Applications can call ``VIDIOC_REQBUFS`` again to change the number of
+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, an implicit
+:ref:`VIDIOC_STREAMOFF <vidioc-streamon>`.
+
+
+.. _v4l2-requestbuffers:
+
+.. flat-table:: struct v4l2_requestbuffers
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``count``
+
+ - The number of buffers requested or granted.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of the stream or buffers, this is the same as the struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` field. See
+ :ref:`v4l2-buf-type` for valid values.
+
+ - .. row 3
+
+ - __u32
+
+ - ``memory``
+
+ - Applications set this field to ``V4L2_MEMORY_MMAP``,
+ ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
+ :ref:`v4l2-memory`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - A place holder for future extensions. Drivers and applications
+ must set the array to zero.
+
+
+
+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.
+
+EINVAL
+ The buffer type (``type`` field) or the requested I/O method
+ (``memory``) is not supported.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-s-hw-freq-seek:
+
+***************************
+ioctl VIDIOC_S_HW_FREQ_SEEK
+***************************
+
+*man VIDIOC_S_HW_FREQ_SEEK(2)*
+
+Perform a hardware frequency seek
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_hw_freq_seek *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_S_HW_FREQ_SEEK
+
+``argp``
+
+
+Description
+===========
+
+Start a hardware frequency seek from the current frequency. To do this
+applications initialize the ``tuner``, ``type``, ``seek_upward``,
+``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
+zero out the ``reserved`` array of a struct
+:ref:`v4l2_hw_freq_seek <v4l2-hw-freq-seek>` and call the
+``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
+
+The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
+to tell the driver to search a specific band. If the struct
+:ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
+within one of the bands returned by
+:ref:`VIDIOC_ENUM_FREQ_BANDS <vidioc-enum-freq-bands>`. If the
+``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
+must exactly match those of one of the bands returned by
+:ref:`VIDIOC_ENUM_FREQ_BANDS <vidioc-enum-freq-bands>`. If the
+current frequency of the tuner does not fall within the selected band it
+will be clamped to fit in the band before the seek is started.
+
+If an error is returned, then the original frequency will be restored.
+
+This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
+set.
+
+If this ioctl is called from a non-blocking filehandle, then EAGAIN
+error code is returned and no seek takes place.
+
+
+.. _v4l2-hw-freq-seek:
+
+.. flat-table:: struct v4l2_hw_freq_seek
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner index number. This is the same value as in the struct
+ :ref:`v4l2_input <v4l2-input>` ``tuner`` field and the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. See
+ :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``seek_upward``
+
+ - If non-zero, seek upward from the current frequency, else seek
+ downward.
+
+ - .. row 4
+
+ - __u32
+
+ - ``wrap_around``
+
+ - If non-zero, wrap around when at the end of the frequency range,
+ else stop seeking. The struct :ref:`v4l2_tuner <v4l2-tuner>`
+ ``capability`` field will tell you what the hardware supports.
+
+ - .. row 5
+
+ - __u32
+
+ - ``spacing``
+
+ - If non-zero, defines the hardware seek resolution in Hz. The
+ driver selects the nearest value that is supported by the device.
+ If spacing is zero a reasonable default value is used.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangelow``
+
+ - If non-zero, the lowest tunable frequency of the band to search in
+ units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+ ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
+ struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
+ the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
+ ``rangelow`` is zero a reasonable default value is used.
+
+ - .. row 7
+
+ - __u32
+
+ - ``rangehigh``
+
+ - If non-zero, the highest tunable frequency of the band to search
+ in units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+ ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
+ struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
+ the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
+ ``rangehigh`` is zero a reasonable default value is used.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Applications must set the array to
+ zero.
+
+
+
+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.
+
+EINVAL
+ The ``tuner`` index is out of bounds, the ``wrap_around`` value is
+ not supported or one of the values in the ``type``, ``rangelow`` or
+ ``rangehigh`` fields is wrong.
+
+EAGAIN
+ Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
+ non-blocking mode.
+
+ENODATA
+ The hardware seek found no channels.
+
+EBUSY
+ Another hardware seek is already in progress.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-streamon:
+
+***************************************
+ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
+***************************************
+
+*man VIDIOC_STREAMON(2)*
+
+VIDIOC_STREAMOFF
+Start or stop streaming I/O
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, const int *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_STREAMON, VIDIOC_STREAMOFF
+
+``argp``
+
+
+Description
+===========
+
+The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
+the capture or output process during streaming
+(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
+:ref:`DMABUF <dmabuf>`) I/O.
+
+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.
+
+Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
+been called for both the capture and output stream types.
+
+If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
+queued.
+
+The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
+in progress, unlocks any user pointer buffers locked in physical memory,
+and it removes all buffers from the incoming and outgoing queues. That
+means all images captured but not dequeued yet will be lost, likewise
+all images enqueued for output but not transmitted yet. I/O returns to
+the same state as after calling
+:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and can be restarted
+accordingly.
+
+If buffers have been queued with :ref:`VIDIOC_QBUF <vidioc-qbuf>` and
+``VIDIOC_STREAMOFF`` is called without ever having called
+``VIDIOC_STREAMON``, then those queued buffers will also be removed from
+the incoming queue and all are returned to the same state as after
+calling :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and can be restarted
+accordingly.
+
+Both ioctls take a pointer to an integer, the desired buffer or stream
+type. This is the same as struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+
+If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
+or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
+then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
+but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
+state as mentioned above.
+
+Note that applications can be preempted for unknown periods right before
+or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
+no notion of starting or stopping "now". Buffer timestamps can be used
+to synchronize with other events.
+
+
+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.
+
+EINVAL
+ The buffer ``type`` is not supported, or no buffers have been
+ allocated (memory mapping) or enqueued (output) yet.
+
+EPIPE
+ The driver implements
+ :ref:`pad-level format configuration <pad-level-formats>` and the
+ pipeline configuration is invalid.
+
+ENOLINK
+ The driver implements Media Controller interface and the pipeline
+ link configuration is invalid.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-subdev-enum-frame-interval:
+
+***************************************
+ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
+***************************************
+
+*man VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL(2)*
+
+Enumerate frame intervals
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval_enum * argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
+
+``argp``
+
+
+Description
+===========
+
+This ioctl lets applications enumerate available frame intervals on a
+given sub-device pad. Frame intervals only makes sense for sub-devices
+that can control the frame period on their own. This includes, for
+instance, image sensors and TV tuners.
+
+For the common use case of image sensors, the frame intervals available
+on the sub-device output pad depend on the frame format and size on the
+same pad. Applications must thus specify the desired format and size
+when enumerating frame intervals.
+
+To enumerate frame intervals applications initialize the ``index``,
+``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct
+:ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>`
+and call the ``VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL`` ioctl with a pointer
+to this structure. Drivers fill the rest of the structure or return an
+EINVAL error code if one of the input fields is invalid. All frame
+intervals are enumerable by beginning at index zero and incrementing by
+one until EINVAL is returned.
+
+Available frame intervals 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 <vidioc-subdev-g-fmt>` for more
+information about the try formats.
+
+Sub-devices that support the frame interval enumeration ioctl should
+implemented it on a single pad only. Its behaviour when supported on
+multiple pads of the same sub-device is not defined.
+
+
+.. _v4l2-subdev-frame-interval-enum:
+
+.. flat-table:: struct v4l2_subdev_frame_interval_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``width``
+
+ - Frame width, in pixels.
+
+ - .. row 5
+
+ - __u32
+
+ - ``height``
+
+ - Frame height, in pixels.
+
+ - .. row 6
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``interval``
+
+ - Period, in seconds, between consecutive video frames.
+
+ - .. row 7
+
+ - __u32
+
+ - ``which``
+
+ - Frame intervals to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+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.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_interval_enum <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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-subdev-enum-frame-size:
+
+***********************************
+ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+***********************************
+
+*man VIDIOC_SUBDEV_ENUM_FRAME_SIZE(2)*
+
+Enumerate media bus frame sizes
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_size_enum * argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+
+``argp``
+
+
+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
+:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE <vidioc-subdev-enum-mbus-code>`
+ioctl.
+
+To enumerate frame sizes applications initialize the ``pad``, ``which``
+, ``code`` and ``index`` fields of the struct
+:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
+call the ``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.
+
+Sub-devices that only support discrete frame sizes (such as most
+sensors) will return one or more frame sizes with identical minimum and
+maximum values.
+
+Not all possible sizes in given [minimum, maximum] ranges need to be
+supported. For instance, a scaler that uses a fixed-point scaling ratio
+might not be able to produce every frame size between the minimum and
+maximum values. Applications must use the
+:ref:`VIDIOC_SUBDEV_S_FMT <vidioc-subdev-g-fmt>` ioctl to try the
+sub-device for an exact supported frame size.
+
+Available frame sizes may depend on the current 'try' formats at other
+pads of the sub-device, as well as on the current active links and the
+current values of V4L2 controls. See
+:ref:`VIDIOC_SUBDEV_G_FMT <vidioc-subdev-g-fmt>` for more
+information about try formats.
+
+
+.. _v4l2-subdev-frame-size-enum:
+
+.. flat-table:: struct v4l2_subdev_frame_size_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum frame width, in pixels.
+
+ - .. row 5
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum frame width, in pixels.
+
+ - .. row 6
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum frame height, in pixels.
+
+ - .. row 7
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum frame height, in pixels.
+
+ - .. row 8
+
+ - __u32
+
+ - ``which``
+
+ - Frame sizes to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+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.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_size_enum <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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-subdev-enum-mbus-code:
+
+**********************************
+ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE
+**********************************
+
+*man VIDIOC_SUBDEV_ENUM_MBUS_CODE(2)*
+
+Enumerate media bus formats
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_mbus_code_enum * argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_MBUS_CODE
+
+``argp``
+
+
+Description
+===========
+
+To enumerate media bus formats available at a given sub-device pad
+applications initialize the ``pad``, ``which`` and ``index`` fields of
+struct
+:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
+call the ``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.
+
+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 <vidioc-subdev-g-fmt>` for more
+information about the try formats.
+
+
+.. _v4l2-subdev-mbus-code-enum:
+
+.. flat-table:: struct v4l2_subdev_mbus_code_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``which``
+
+ - Media bus format codes to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+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.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>`
+ ``pad`` references a non-existing pad, or the ``index`` field is out
+ of bounds.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-subdev-g-crop:
+
+************************************************
+ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
+************************************************
+
+*man VIDIOC_SUBDEV_G_CROP(2)*
+
+VIDIOC_SUBDEV_S_CROP
+Get or set the crop rectangle on a subdev pad
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_crop *argp )
+
+.. c:function:: int ioctl( int fd, int request, const struct v4l2_subdev_crop *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`obsolete <obsolete>` interface and may be removed
+ in the future. It is superseded by
+ :ref:`the selection API <vidioc-subdev-g-selection>`.
+
+To retrieve the current crop rectangle applications set the ``pad``
+field of a struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` to the
+desired pad number as reported by the media API and the ``which`` field
+to ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the
+``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The
+driver fills the members of the ``rect`` field or returns EINVAL error
+code if the input arguments are invalid, or if cropping is not supported
+on the given pad.
+
+To change the current crop rectangle applications set both the ``pad``
+and ``which`` fields and all members of the ``rect`` field. They then
+call the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this
+structure. The driver verifies the requested crop rectangle, adjusts it
+based on the hardware capabilities and configures the device. Upon
+return the struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>`
+contains the current format as would be returned by a
+``VIDIOC_SUBDEV_G_CROP`` call.
+
+Applications can query the device capabilities by setting the ``which``
+to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not
+applied to the device by the driver, but are mangled exactly as active
+crop rectangles and stored in the sub-device file handle. Two
+applications querying the same sub-device would thus not interact with
+each other.
+
+Drivers must not return an error solely because the requested crop
+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.
+
+
+.. _v4l2-subdev-crop:
+
+.. flat-table:: struct v4l2_subdev_crop
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media framework.
+
+ - .. row 2
+
+ - __u32
+
+ - ``which``
+
+ - Crop rectangle to get or set, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``rect``
+
+ - Crop rectangle boundaries, in pixels.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+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.
+
+EBUSY
+ The crop rectangle can't be changed because the pad is currently
+ busy. This can be caused, for instance, by an active video stream on
+ the pad. The ioctl must not be retried without performing another
+ action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_CROP``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_crop <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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-subdev-g-fmt:
+
+**********************************************
+ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
+**********************************************
+
+*man VIDIOC_SUBDEV_G_FMT(2)*
+
+VIDIOC_SUBDEV_S_FMT
+Get or set the data format on a subdev pad
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_format *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to negotiate the frame format at specific subdev
+pads in the image pipeline.
+
+To retrieve the current format applications set the ``pad`` field of a
+struct :ref:`v4l2_subdev_format <v4l2-subdev-format>` to the desired
+pad number as reported by the media API and the ``which`` field to
+``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the
+``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the
+driver fills the members of the ``format`` field.
+
+To change the current format applications set both the ``pad`` and
+``which`` fields and all members of the ``format`` field. When they call
+the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the
+driver verifies the requested format, adjusts it based on the hardware
+capabilities and configures the device. Upon return the struct
+:ref:`v4l2_subdev_format <v4l2-subdev-format>` contains the current
+format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call.
+
+Applications can query the device capabilities by setting the ``which``
+to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied
+to the device by the driver, but are changed exactly as active formats
+and stored in the sub-device file handle. Two applications querying the
+same sub-device would thus not interact with each other.
+
+For instance, to try a format at the output pad of a sub-device,
+applications would first set the try format at the sub-device input with
+the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the
+default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl,
+or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT``
+ioctl and check the returned value.
+
+Try formats do not depend on active formats, but can depend on the
+current links configuration or sub-device controls value. For instance,
+a low-pass noise filter might crop pixels at the frame boundaries,
+modifying its output frame size.
+
+Drivers must not return an error solely because the requested format
+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.
+
+
+.. _v4l2-subdev-format:
+
+.. flat-table:: struct v4l2_subdev_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - __u32
+
+ - ``which``
+
+ - Format to modified, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`
+
+ - ``format``
+
+ - Definition of an image format, see :ref:`v4l2-mbus-framefmt` for
+ details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-subdev-format-whence:
+
+.. flat-table:: enum v4l2_subdev_format_whence
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - V4L2_SUBDEV_FORMAT_TRY
+
+ - 0
+
+ - Try formats, used for querying device capabilities.
+
+ - .. row 2
+
+ - V4L2_SUBDEV_FORMAT_ACTIVE
+
+ - 1
+
+ - Active formats, applied to the 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.
+
+EBUSY
+ The format can't be changed because the pad is currently busy. This
+ can be caused, for instance, by an active video stream on the pad.
+ The ioctl must not be retried without performing another action to
+ fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_format <v4l2-subdev-format>`
+ ``pad`` references a non-existing pad, or the ``which`` field
+ references a non-existing format.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-subdev-g-frame-interval:
+
+********************************************************************
+ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL
+********************************************************************
+
+*man VIDIOC_SUBDEV_G_FRAME_INTERVAL(2)*
+
+VIDIOC_SUBDEV_S_FRAME_INTERVAL
+Get or set the frame interval on a subdev pad
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_FRAME_INTERVAL,
+ VIDIOC_SUBDEV_S_FRAME_INTERVAL
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to get and set the frame interval at specific
+subdev pads in the image pipeline. The frame interval only makes sense
+for sub-devices that can control the frame period on their own. This
+includes, for instance, image sensors and TV tuners. Sub-devices that
+don't support frame intervals must not implement these ioctls.
+
+To retrieve the current frame interval applications set the ``pad``
+field of a struct
+:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` to
+the desired pad number as reported by the media controller API. When
+they call the ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` ioctl with a pointer to
+this structure the driver fills the members of the ``interval`` field.
+
+To change the current frame interval applications set both the ``pad``
+field and all members of the ``interval`` field. When they call the
+``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl with a pointer to this
+structure the driver verifies the requested interval, adjusts it based
+on the hardware capabilities and configures the device. Upon return the
+struct
+:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>`
+contains the current frame interval as would be returned by a
+``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
+
+Drivers must not return an error solely because the requested interval
+doesn't match the device capabilities. They must instead modify the
+interval to match what the hardware can provide. The modified interval
+should be as close as possible to the original request.
+
+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.
+
+
+.. _v4l2-subdev-frame-interval:
+
+.. flat-table:: struct v4l2_subdev_frame_interval
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``interval``
+
+ - Period, in seconds, between consecutive video frames.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+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.
+
+EBUSY
+ The frame interval can't be changed because the pad is currently
+ busy. This can be caused, for instance, by an active video stream on
+ the pad. The ioctl must not be retried without performing another
+ action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_FRAME_INTERVAL``
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>`
+ ``pad`` references a non-existing pad, or the pad doesn't support
+ frame intervals.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-subdev-g-selection:
+
+**********************************************************
+ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
+**********************************************************
+
+*man VIDIOC_SUBDEV_G_SELECTION(2)*
+
+VIDIOC_SUBDEV_S_SELECTION
+Get or set selection rectangles on a subdev pad
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_selection *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
+
+``argp``
+
+
+Description
+===========
+
+The selections are used to configure various image processing
+functionality performed by the subdevs which affect the image size. This
+currently includes cropping, scaling and composition.
+
+The selection API replaces
+:ref:`the old subdev crop API <vidioc-subdev-g-crop>`. All the
+function of the crop API, and more, are supported by the selections API.
+
+See :ref:`subdev` for more information on how each selection target
+affects the image processing pipeline inside the subdevice.
+
+
+Types of selection targets
+--------------------------
+
+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
+------------------------------
+
+To discover which targets are supported, the user can perform
+``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
+return ``EINVAL``.
+
+Selection targets and flags are documented in
+:ref:`v4l2-selections-common`.
+
+
+.. _v4l2-subdev-selection:
+
+.. flat-table:: struct v4l2_subdev_selection
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``which``
+
+ - Active or try selection, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media framework.
+
+ - .. row 3
+
+ - __u32
+
+ - ``target``
+
+ - Target selection rectangle. See :ref:`v4l2-selections-common`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags. See :ref:`v4l2-selection-flags`.
+
+ - .. row 5
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``r``
+
+ - Selection rectangle, in pixels.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+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.
+
+EBUSY
+ The selection rectangle can't be changed because the pad is
+ currently busy. This can be caused, for instance, by an active video
+ stream on the pad. The ioctl must not be retried without performing
+ another action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_SELECTION``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_selection <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.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-subscribe-event:
+
+******************************************************
+ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
+******************************************************
+
+*man VIDIOC_SUBSCRIBE_EVENT(2)*
+
+VIDIOC_UNSUBSCRIBE_EVENT
+Subscribe or unsubscribe event
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_event_subscription *argp )
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
+
+``argp``
+
+
+Description
+===========
+
+Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
+using the :ref:`VIDIOC_DQEVENT <vidioc-dqevent>` ioctl.
+
+
+.. _v4l2-event-subscription:
+
+.. flat-table:: struct v4l2_event_subscription
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the event, see :ref:`event-type`. Note that
+ ``V4L2_EVENT_ALL`` can be used with VIDIOC_UNSUBSCRIBE_EVENT for
+ unsubscribing all events at once.
+
+ - .. row 2
+
+ - __u32
+
+ - ``id``
+
+ - ID of the event source. If there is no ID associated with the
+ event source, then set this to 0. Whether or not an event needs an
+ ID depends on the event type.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Event flags, see :ref:`event-flags`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _event-flags:
+
+.. flat-table:: Event Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
+
+ - 0x0001
+
+ - When this event is subscribed an initial event will be sent
+ containing the current status. This only makes sense for events
+ that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
+ Other events will ignore this flag.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
+
+ - 0x0002
+
+ - If set, then events directly caused by an ioctl will also be sent
+ to the filehandle that called that ioctl. For example, changing a
+ control using :ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` will cause
+ a V4L2_EVENT_CTRL to be sent back to that same filehandle.
+ Normally such events are suppressed to prevent feedback loops
+ where an application changes a control to a one value and then
+ another, and then receives an event telling it that that control
+ has changed to the first value.
+
+ Since it can't tell whether that event was caused by another
+ application or by the :ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>`
+ call it is hard to decide whether to set the control to the value
+ in the event, or ignore it.
+
+ Think carefully when you set this flag so you won't get into
+ situations like that.
+
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _yuv-formats:
+
+***********
+YUV Formats
+***********
+
+YUV is the format native to TV broadcast and composite video signals. It
+separates the brightness information (Y) from the color information (U
+and V or Cb and Cr). The color information consists of red and blue
+*color difference* signals, this way the green component can be
+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.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-packed-yuv
+ pixfmt-grey
+ pixfmt-y10
+ pixfmt-y12
+ pixfmt-y10b
+ pixfmt-y16
+ pixfmt-y16-be
+ 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
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg stroke-linejoin="round" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://www.w3.org/2000/svg" clip-path="url(#a)" xml:space="preserve" fill-rule="evenodd" height="178.78mm" viewBox="0 0 24285.662 17877.829" width="251.99mm" version="1.2" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" preserveAspectRatio="xMidYMid" stroke-width="28.222"><defs><clipPath id="a" clipPathUnits="userSpaceOnUse"><rect y="0" x="0" width="28000" height="21000"/></clipPath></defs><g transform="matrix(1.004 0 0 1 -2185.6 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#fcf" d="m12231 4800c-516 0-1031 515-1031 1031v4124c0 516 515 1032 1031 1032h8538c516 0 1032-516 1032-1032v-4124c0-516-516-1031-1032-1031h-8538z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ffc" d="m3595 15607c-293 0-585 292-585 585v2340c0 293 292 586 585 586h3275c293 0 586-293 586-586v-2340c0-293-293-585-586-585h-3275z"/></g><g transform="translate(-2197.3 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#e6e6e6" d="m2663 2186c-461 0-922 461-922 922v11169c0 461 461 923 922 923h3692c461 0 922-462 922-923v-11169c0-461-461-922-922-922h-3692z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4461 8602h-2260v-1086h4520v1086h-2260z"/><path fill="none" d="m4461 8602h-2260v-1086h4520v1086h-2260z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="8275" x="2579" class="TextPosition"><tspan fill="#000000">Audio decoder</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4461 11772h-2260v-1270h4520v1270h-2260z"/><path fill="none" d="m4461 11772h-2260v-1270h4520v1270h-2260z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="11353" x="2617" class="TextPosition"><tspan fill="#000000">Video decoder</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4453 10217h-2269v-1224h4537v1224h-2268z"/><path fill="none" d="m4453 10217h-2269v-1224h4537v1224h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="9821" x="2571" class="TextPosition"><tspan fill="#000000">Audio encoder</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.RectangleShape"><path fill="#cfc" d="m15711 12832h-3810v-1281h7620v1281h-3810z"/><path fill="none" d="m15711 12832h-3810v-1281h7620v1281h-3810z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="12407" x="12377" class="TextPosition"><tspan fill="#000000">Button Key/IR input logic</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2411.8)" class="com.sun.star.drawing.RectangleShape"><path fill="#cfe7f5" d="m14169 14572h-2268v-1412h4536v1412h-2268z"/><path fill="none" d="m14169 14572h-2268v-1412h4536v1412h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14082" x="12882" class="TextPosition"><tspan fill="#000000">EEPROM</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#fc9" d="m5140 17662h-1563v-1715h3126v1715h-1563z"/><path fill="none" d="m5140 17662h-1563v-1715h3126v1715h-1563z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="17020" x="4276" class="TextPosition"><tspan fill="#000000">Sensor</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 8030 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 8030 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 9612 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 9612 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6721 11100 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m6721 11100 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2411.8)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 13854 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 13854 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 12163 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 12163 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 17158 670-353v176h2028v-176l671 353-671 354v-177h-2028v177l-670-354z"/><path fill="none" d="m9962 17158 670-353v176h2028v-176l671 353-671 354v-177h-2028v177l-670-354z" stroke="#3465af"/></g><g transform="matrix(0 .83339 -1.0005 0 30268 -5276.3)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m23229 12779 1009-978 1009 978h-505v2959h505l-1009 979-1009-979h504v-2959h-504z"/><path fill="none" d="m23229 12779 1009-978 1009 978h-505v2959h505l-1009 979-1009-979h504v-2959h-504z" stroke="#3465af"/></g><g transform="translate(-9973.6 -666.6)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="706px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15832" x="24341" class="TextPosition" transform="matrix(0,-1,1,0,8509,40173)"><tspan fill="#000000">System Bus</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m13151 9262h-1250v-875h2499v875h-1249z"/><path fill="none" d="m13151 9262h-1250v-875h2499v875h-1249z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="9040" x="12215" class="TextPosition"><tspan fill="#000000">Demux</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9996 8765 373-357v178h1130v-178l374 357-374 358v-179h-1130v179l-373-358z"/><path fill="none" d="m9996 8765 373-357v178h1130v-178l374 357-374 358v-179h-1130v179l-373-358z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9996 7378 373-358v179h1130v-179l374 358-374 358v-179h-1130v179l-373-358z"/><path fill="none" d="m9996 7378 373-358v179h1130v-179l374 358-374 358v-179h-1130v179l-373-358z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m16322 7992h-4421v-1270h8841v1270h-4420z"/><path fill="none" d="m16322 7992h-4421v-1270h8841v1270h-4420z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="7573" x="12786" class="TextPosition"><tspan fill="#000000">Conditional Access Module</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4445 13287h-2269v-1224h4537v1224h-2268z"/><path fill="none" d="m4445 13287h-2269v-1224h4537v1224h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="12891" x="2601" class="TextPosition"><tspan fill="#000000">Video encoder</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6721 12634 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m6721 12634 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m20791 7545 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m20791 7545 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2028 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14478" x="1990" class="TextPosition"><tspan fill="#000000">Radio / Analog TV</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="700" class="TextParagraph"><tspan y="10724" x="14956" class="TextPosition"><tspan fill="#000000">Digital TV</tspan></tspan></tspan></text>
+</g><g transform="translate(-8970.5 -1395.8)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="494px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="19167" x="14724" class="TextPosition"><tspan fill="#000000">PS.: picture is not complete: other blocks may be present</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="18561" x="4199" class="TextPosition"><tspan fill="#000000">Webcam</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.RectangleShape"><path fill="#f90" d="m14552 16372h-2650v-1412h5299v1412h-2649z"/><path fill="none" d="m14552 16372h-2650v-1412h5299v1412h-2649z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15882" x="12265" class="TextPosition"><tspan fill="#000000">Processing blocks</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 15654 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 15654 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6702 16954 397-353v176h1201v-176l398 353-398 354v-177h-1201v177l-397-354z"/><path fill="none" d="m6702 16954 397-353v176h1201v-176l398 353-398 354v-177h-1201v177l-397-354z" stroke="#3465af"/></g><g transform="translate(-2479.5 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="8792" x="22850" class="TextPosition"><tspan fill="#000000">Smartcard</tspan></tspan></tspan></text>
+</g><g transform="matrix(1.0048 0 0 1 -2207.4 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#fcf" d="m2766 2600c-333 0-666 333-666 666v2668c0 333 333 666 666 666h18368c333 0 667-333 667-666v-2668c0-333-334-666-667-666h-18368z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m5121 5155h-1614v-1816h3227v1816h-1613z"/><path fill="none" d="m5121 5155h-1614v-1816h3227v1816h-1613z" stroke="#3465af"/><text font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextShape"><tspan class="TextParagraph"><tspan y="4111" x="4374" class="TextPosition"><tspan fill="#000000">Tuner</tspan></tspan></tspan><tspan class="TextParagraph"><tspan y="4814" x="4151" class="TextPosition"><tspan fill="#000000">FM/TV</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ff8080" d="m2902 3702c0 111 40 202 88 202h530c48 0 89-91 89-202 0-110-41-202-89-202h-530c-48 0-88 92-88 202z"/><path fill="none" d="m2902 3702c0 111 40 202 88 202h530c48 0 89-91 89-202 0-110-41-202-89-202h-530c-48 0-88 92-88 202z" stroke="#3465af"/><path fill="#ffb3b3" d="m2902 3702c0 111 40 202 88 202s88-91 88-202c0-110-40-202-88-202s-88 92-88 202z"/><path fill="none" d="m2902 3702c0 111 40 202 88 202s88-91 88-202c0-110-40-202-88-202s-88 92-88 202z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ff8080" d="m2903 4267c0 110 40 202 88 202h530c48 0 89-92 89-202s-41-203-89-203h-530c-48 0-88 93-88 203z"/><path fill="none" d="m2903 4267c0 110 40 202 88 202h530c48 0 89-92 89-202s-41-203-89-203h-530c-48 0-88 93-88 203z" stroke="#3465af"/><path fill="#ffb3b3" d="m2903 4267c0 110 40 202 88 202s88-92 88-202-40-203-88-203-88 93-88 203z"/><path fill="none" d="m2903 4267c0 110 40 202 88 202s88-92 88-202-40-203-88-203-88 93-88 203z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 4196 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 4196 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9979 4150 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z"/><path fill="none" d="m9979 4150 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m16500 6189h-4500v-1389h9e3v1389h-4500z"/><path fill="none" d="m16500 6189h-4500v-1389h9e3v1389h-4500z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="5710" x="12051" class="TextPosition"><tspan fill="#000000">Satellite Equipment Control (SEC)</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#cff" d="m13400 4600h-1400v-1e3h2800v1e3h-1400z"/><path fill="none" d="m13400 4600h-1400v-1e3h2800v1e3h-1400z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="4316" x="12465" class="TextPosition"><tspan fill="#000000">Demod</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9979 5451 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z"/><path fill="none" d="m9979 5451 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z" stroke="#3465af"/></g><path fill="#ff9" d="m7855.1 9099v7302h-1270v-14605h1270v7303z"/><path fill="none" d="m7855.1 9099v7302h-1270v-14605h1270v7303z" stroke="#3465af"/><text y="-6640.4663" x="-20770.572" transform="rotate(-90)" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="7409.5396" x="-11193.634" class="TextPosition" transform="matrix(0,-1,1,0,-4473,23627)"><tspan fill="#000000">I2C Bus (control bus)</tspan></tspan></tspan></text>
+<g transform="translate(-2197.3 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="3278" x="9391" class="TextPosition"><tspan fill="#000000">Digital TV Frontend</tspan></tspan></tspan></text>
+</g><g transform="matrix(1.015 0 0 .99994 -2233.3 -2185.7)" class="com.sun.star.drawing.CustomShape"><g stroke="#3465af" fill="none"><path d="m3e3 2800c-18 0-35 1-53 3"/><path d="m2915 2808c-17 3-35 7-52 12"/><path d="m2832 2830c-16 6-33 12-49 20"/><path d="m2754 2864c-15 8-31 17-46 27"/><path d="m2681 2909c-14 10-28 21-42 32"/><path d="m2614 2962c-13 12-26 24-38 37"/><path d="m2554 3023c-11 13-22 27-33 41"/><path d="m2502 3091c-10 14-19 29-28 45"/><path d="m2459 3164c-8 16-15 32-22 49"/><path d="m2426 3243c-5 17-10 34-14 51"/><path d="m2406 3326c-3 18-5 35-6 53"/><path d="m2400 3411v53"/><path d="m2400 3497v53"/><path d="m2400 3582v53"/><path d="m2400 3668v53"/><path d="m2400 3753v53"/><path d="m2400 3839v53"/><path d="m2400 3924v53"/><path d="m2400 4009v54"/><path d="m2400 4095v53"/><path d="m2400 4180v53"/><path d="m2400 4266v53"/><path d="m2400 4351v53"/><path d="m2400 4437v53"/><path d="m2400 4522v53"/><path d="m2400 4607v54"/><path d="m2400 4693v53"/><path d="m2400 4778v53"/><path d="m2400 4864v53"/><path d="m2400 4949v53"/><path d="m2400 5035v53"/><path d="m2400 5120v53"/><path d="m2400 5205v54"/><path d="m2400 5291v53"/><path d="m2400 5376v53"/><path d="m2400 5462v53"/><path d="m2400 5547v53"/><path d="m2400 5633v53"/><path d="m2400 5718v53"/><path d="m2400 5803c0 18 1 36 3 53"/><path d="m2408 5888c4 18 8 35 13 52"/><path d="m2431 5971c6 16 13 33 20 49"/><path d="m2466 6049c8 15 17 31 27 46"/><path d="m2511 6122c10 14 21 28 32 42"/><path d="m2564 6188c12 13 25 26 38 38"/><path d="m2626 6248c13 11 27 23 41 33"/><path d="m2694 6300c14 10 29 19 45 27"/><path d="m2768 6343c15 7 32 15 48 21"/><path d="m2847 6375c17 5 34 10 51 14"/><path d="m2930 6395c17 2 35 4 53 5"/><path d="m3015 6400h53"/><path d="m3100 6400h53"/><path d="m3186 6400h53"/><path d="m3271 6400h53"/><path d="m3357 6400h53"/><path d="m3442 6400h53"/><path d="m3527 6400h54"/><path d="m3613 6400h53"/><path d="m3698 6400h53"/><path d="m3784 6400h53"/><path d="m3869 6400h53"/><path d="m3955 6400h53"/><path d="m4040 6400h53"/><path d="m4125 6400h54"/><path d="m4211 6400h53"/><path d="m4296 6400h53"/><path d="m4382 6400h53"/><path d="m4467 6400h53"/><path d="m4553 6400h53"/><path d="m4638 6400h53"/><path d="m4723 6400h54"/><path d="m4809 6400h53"/><path d="m4894 6400h53"/><path d="m4980 6400h53"/><path d="m5065 6400h53"/><path d="m5151 6400h53"/><path d="m5236 6400h53"/><path d="m5322 6400h53"/><path d="m5407 6400h53"/><path d="m5492 6400h53"/><path d="m5578 6400h53"/><path d="m5663 6400h53"/><path d="m5749 6400h53"/><path d="m5834 6400h53"/><path d="m5920 6400h53"/><path d="m6005 6400h53"/><path d="m6090 6400h53"/><path d="m6176 6400h53"/><path d="m6261 6400h53"/><path d="m6347 6400h53"/><path d="m6432 6400h53"/><path d="m6518 6400h53"/><path d="m6603 6400h53"/><path d="m6688 6400h54"/><path d="m6774 6400h53"/><path d="m6859 6400h53"/><path d="m6945 6400h53"/><path d="m7030 6400h53"/><path d="m7116 6400h53"/><path d="m7201 6400h53"/><path d="m7286 6400h54"/><path d="m7372 6400h53"/><path d="m7457 6400h53"/><path d="m7543 6400h53"/><path d="m7628 6400h53"/><path d="m7714 6400h53"/><path d="m7799 6400h53"/><path d="m7884 6400h54"/><path d="m7970 6400h53"/><path d="m8055 6400h53"/><path d="m8141 6400h53"/><path d="m8226 6400h53"/><path d="m8312 6400h53"/><path d="m8397 6400h53"/><path d="m8482 6400h54"/><path d="m8568 6400h53"/><path d="m8653 6400h53"/><path d="m8739 6400h53"/><path d="m8824 6400h53"/><path d="m8910 6400h53"/><path d="m8995 6400h53"/><path d="m9081 6400h53"/><path d="m9166 6400h53"/><path d="m9251 6400h53"/><path d="m9337 6400h53"/><path d="m9422 6400h53"/><path d="m9508 6400h53"/><path d="m9593 6400h53"/><path d="m9679 6400h53"/><path d="m9764 6400h53"/><path d="m9849 6400h53"/><path d="m9935 6400h53"/><path d="m10020 6400h53"/><path d="m10106 6400h53"/><path d="m10191 6400h53"/><path d="m10277 6400h53"/><path d="m10362 6400h53"/><path d="m10447 6400h53"/><path d="m10533 6400h53"/><path d="m10618 6400h53"/><path d="m10704 6400h53"/><path d="m10789 6400h53"/><path d="m10875 6400h53"/><path d="m10960 6400h53"/><path d="m11045 6400h54"/><path d="m11131 6400h53"/><path d="m11216 6400h53"/><path d="m11302 6400h53"/><path d="m11387 6400h53"/><path d="m11473 6400h53"/><path d="m11558 6400h53"/><path d="m11643 6400h54"/><path d="m11729 6400h53"/><path d="m11814 6400h53"/><path d="m11900 6400h53"/><path d="m11985 6400h53"/><path d="m12071 6400h53"/><path d="m12156 6400h53"/><path d="m12241 6400h54"/><path d="m12327 6400h53"/><path d="m12412 6400h53"/><path d="m12498 6400h53"/><path d="m12583 6400h53"/><path d="m12669 6400h53"/><path d="m12754 6400h53"/><path d="m12839 6400h54"/><path d="m12925 6400h53"/><path d="m13010 6400h53"/><path d="m13096 6400h53"/><path d="m13181 6400h53"/><path d="m13267 6400h53"/><path d="m13352 6400h53"/><path d="m13438 6400h53"/><path d="m13523 6400h53"/><path d="m13608 6400h53"/><path d="m13694 6400h53"/><path d="m13779 6400h53"/><path d="m13865 6400h53"/><path d="m13950 6400h53"/><path d="m14036 6400h53"/><path d="m14121 6400h53"/><path d="m14206 6400h53"/><path d="m14292 6400h53"/><path d="m14377 6400h53"/><path d="m14463 6400h53"/><path d="m14548 6400h53"/><path d="m14634 6400h53"/><path d="m14719 6400h53"/><path d="m14804 6400h54"/><path d="m14890 6400h53"/><path d="m14975 6400h53"/><path d="m15061 6400h53"/><path d="m15146 6400h53"/><path d="m15232 6400h53"/><path d="m15317 6400h53"/><path d="m15402 6400h54"/><path d="m15488 6400h53"/><path d="m15573 6400h53"/><path d="m15659 6400h53"/><path d="m15744 6400h53"/><path d="m15830 6400h53"/><path d="m15915 6400h53"/><path d="m16000 6400h54"/><path d="m16086 6400h53"/><path d="m16171 6400h53"/><path d="m16257 6400h53"/><path d="m16342 6400h53"/><path d="m16428 6400h53"/><path d="m16513 6400h53"/><path d="m16598 6400h54"/><path d="m16684 6400h53"/><path d="m16769 6400h53"/><path d="m16855 6400h53"/><path d="m16940 6400h53"/><path d="m17026 6400h53"/><path d="m17111 6400h53"/><path d="m17196 6400h54"/><path d="m17282 6400h53"/><path d="m17367 6400h53"/><path d="m17453 6400h53"/><path d="m17538 6400h53"/><path d="m17624 6400h53"/><path d="m17709 6400h53"/><path d="m17795 6400h53"/><path d="m17880 6400h53"/><path d="m17965 6400h53"/><path d="m18051 6400h53"/><path d="m18136 6400h53"/><path d="m18222 6400h53"/><path d="m18307 6400h53"/><path d="m18393 6400h53"/><path d="m18478 6400h53"/><path d="m18563 6400h53"/><path d="m18649 6400h53"/><path d="m18734 6400h53"/><path d="m18820 6400h53"/><path d="m18905 6400h53"/><path d="m18991 6400h53"/><path d="m19076 6400h53"/><path d="m19161 6400h54"/><path d="m19247 6400h53"/><path d="m19332 6400h53"/><path d="m19418 6400h53"/><path d="m19503 6400h53"/><path d="m19589 6400h53"/><path d="m19674 6400h53"/><path d="m19759 6400h54"/><path d="m19845 6400h53"/><path d="m19930 6400h53"/><path d="m20016 6400h53"/><path d="m20101 6400h53"/><path d="m20187 6400h53"/><path d="m20272 6400h53"/><path d="m20357 6400h54"/><path d="m20443 6400h53"/><path d="m20528 6400h53"/><path d="m20614 6400c17-1 35-2 53-5"/><path d="m20699 6390c17-4 34-9 51-14"/><path d="m20781 6365c16-6 32-13 48-21"/><path d="m20858 6329c15-8 31-17 45-27"/><path d="m20930 6283c14-10 28-21 42-32"/><path d="m20996 6229c13-12 25-25 37-38"/><path d="m21055 6167c11-14 22-28 33-42"/><path d="m21106 6098c10-15 19-30 27-45"/><path d="m21148 6024c7-16 14-33 20-49"/><path d="m21179 5944c5-17 9-34 13-51"/><path d="m21197 5861c2-18 4-35 4-53"/><path d="m21201 5776v-54"/><path d="m21201 5690v-53"/><path d="m21201 5605v-53"/><path d="m21201 5519v-53"/><path d="m21201 5434v-53"/><path d="m21201 5348v-53"/><path d="m21201 5263v-53"/><path d="m21201 5178v-54"/><path d="m21201 5092v-53"/><path d="m21201 5007v-53"/><path d="m21201 4921v-53"/><path d="m21201 4836v-53"/><path d="m21201 4750v-53"/><path d="m21201 4665v-53"/><path d="m21201 4579v-53"/><path d="m21201 4494v-53"/><path d="m21201 4409v-53"/><path d="m21201 4323v-53"/><path d="m21201 4238v-53"/><path d="m21201 4152v-53"/><path d="m21201 4067v-53"/><path d="m21201 3981v-53"/><path d="m21201 3896v-53"/><path d="m21201 3811v-53"/><path d="m21201 3725v-53"/><path d="m21201 3640v-53"/><path d="m21201 3554v-53"/><path d="m21201 3469v-53"/><path d="m21201 3383c-1-17-3-35-5-52"/><path d="m21190 3299c-4-17-8-35-14-51"/><path d="m21165 3217c-6-16-13-33-21-49"/><path d="m21129 3140c-9-16-18-31-28-46"/><path d="m21082 3068c-10-14-21-28-33-42"/><path d="m21027 3002c-12-13-24-25-37-37"/><path d="m20965 2944c-14-12-28-22-42-33"/><path d="m20896 2893c-15-9-30-18-46-27"/><path d="m20821 2852c-16-8-32-14-49-20"/><path d="m20741 2821c-17-5-34-9-51-12"/><path d="m20658 2804c-18-3-35-4-53-4"/><path d="m20573 2800h-53"/><path d="m20487 2800h-53"/><path d="m20402 2800h-53"/><path d="m20316 2800h-53"/><path d="m20231 2800h-53"/><path d="m20146 2800h-54"/><path d="m20060 2800h-53"/><path d="m19975 2800h-53"/><path d="m19889 2800h-53"/><path d="m19804 2800h-53"/><path d="m19718 2800h-53"/><path d="m19633 2800h-53"/><path d="m19548 2800h-54"/><path d="m19462 2800h-53"/><path d="m19377 2800h-53"/><path d="m19291 2800h-53"/><path d="m19206 2800h-53"/><path d="m19120 2800h-53"/><path d="m19035 2800h-53"/><path d="m18950 2800h-54"/><path d="m18864 2800h-53"/><path d="m18779 2800h-53"/><path d="m18693 2800h-53"/><path d="m18608 2800h-53"/><path d="m18522 2800h-53"/><path d="m18437 2800h-53"/><path d="m18352 2800h-54"/><path d="m18266 2800h-53"/><path d="m18181 2800h-53"/><path d="m18095 2800h-53"/><path d="m18010 2800h-53"/><path d="m17924 2800h-53"/><path d="m17839 2800h-53"/><path d="m17753 2800h-53"/><path d="m17668 2800h-53"/><path d="m17583 2800h-53"/><path d="m17497 2800h-53"/><path d="m17412 2800h-53"/><path d="m17326 2800h-53"/><path d="m17241 2800h-53"/><path d="m17155 2800h-53"/><path d="m17070 2800h-53"/><path d="m16985 2800h-53"/><path d="m16899 2800h-53"/><path d="m16814 2800h-53"/><path d="m16728 2800h-53"/><path d="m16643 2800h-53"/><path d="m16557 2800h-53"/><path d="m16472 2800h-53"/><path d="m16387 2800h-54"/><path d="m16301 2800h-53"/><path d="m16216 2800h-53"/><path d="m16130 2800h-53"/><path d="m16045 2800h-53"/><path d="m15959 2800h-53"/><path d="m15874 2800h-53"/><path d="m15789 2800h-54"/><path d="m15703 2800h-53"/><path d="m15618 2800h-53"/><path d="m15532 2800h-53"/><path d="m15447 2800h-53"/><path d="m15361 2800h-53"/><path d="m15276 2800h-53"/><path d="m15191 2800h-54"/><path d="m15105 2800h-53"/><path d="m15020 2800h-53"/><path d="m14934 2800h-53"/><path d="m14849 2800h-53"/><path d="m14763 2800h-53"/><path d="m14678 2800h-53"/><path d="m14593 2800h-54"/><path d="m14507 2800h-53"/><path d="m14422 2800h-53"/><path d="m14336 2800h-53"/><path d="m14251 2800h-53"/><path d="m14165 2800h-53"/><path d="m14080 2800h-53"/><path d="m13994 2800h-53"/><path d="m13909 2800h-53"/><path d="m13824 2800h-53"/><path d="m13738 2800h-53"/><path d="m13653 2800h-53"/><path d="m13567 2800h-53"/><path d="m13482 2800h-53"/><path d="m13396 2800h-53"/><path d="m13311 2800h-53"/><path d="m13226 2800h-53"/><path d="m13140 2800h-53"/><path d="m13055 2800h-53"/><path d="m12969 2800h-53"/><path d="m12884 2800h-53"/><path d="m12798 2800h-53"/><path d="m12713 2800h-53"/><path d="m12628 2800h-53"/><path d="m12542 2800h-53"/><path d="m12457 2800h-53"/><path d="m12371 2800h-53"/><path d="m12286 2800h-53"/><path d="m12200 2800h-53"/><path d="m12115 2800h-53"/><path d="m12030 2800h-54"/><path d="m11944 2800h-53"/><path d="m11859 2800h-53"/><path d="m11773 2800h-53"/><path d="m11688 2800h-53"/><path d="m11602 2800h-53"/><path d="m11517 2800h-53"/><path d="m11432 2800h-54"/><path d="m11346 2800h-53"/><path d="m11261 2800h-53"/><path d="m11175 2800h-53"/><path d="m11090 2800h-53"/><path d="m11004 2800h-53"/><path d="m10919 2800h-53"/><path d="m10834 2800h-54"/><path d="m10748 2800h-53"/><path d="m10663 2800h-53"/><path d="m10577 2800h-53"/><path d="m10492 2800h-53"/><path d="m10406 2800h-53"/><path d="m10321 2800h-53"/><path d="m10236 2800h-54"/><path d="m10150 2800h-53"/><path d="m10065 2800h-53"/><path d="m9979 2800h-53"/><path d="m9894 2800h-53"/><path d="m9808 2800h-53"/><path d="m9723 2800h-53"/><path d="m9637 2800h-53"/><path d="m9552 2800h-53"/><path d="m9467 2800h-53"/><path d="m9381 2800h-53"/><path d="m9296 2800h-53"/><path d="m9210 2800h-53"/><path d="m9125 2800h-53"/><path d="m9039 2800h-53"/><path d="m8954 2800h-53"/><path d="m8869 2800h-53"/><path d="m8783 2800h-53"/><path d="m8698 2800h-53"/><path d="m8612 2800h-53"/><path d="m8527 2800h-53"/><path d="m8441 2800h-53"/><path d="m8356 2800h-53"/><path d="m8271 2800h-54"/><path d="m8185 2800h-53"/><path d="m8100 2800h-53"/><path d="m8014 2800h-53"/><path d="m7929 2800h-53"/><path d="m7843 2800h-53"/><path d="m7758 2800h-53"/><path d="m7673 2800h-54"/><path d="m7587 2800h-53"/><path d="m7502 2800h-53"/><path d="m7416 2800h-53"/><path d="m7331 2800h-53"/><path d="m7245 2800h-53"/><path d="m7160 2800h-53"/><path d="m7075 2800h-54"/><path d="m6989 2800h-53"/><path d="m6904 2800h-53"/><path d="m6818 2800h-53"/><path d="m6733 2800h-53"/><path d="m6647 2800h-53"/><path d="m6562 2800h-53"/><path d="m6477 2800h-54"/><path d="m6391 2800h-53"/><path d="m6306 2800h-53"/><path d="m6220 2800h-53"/><path d="m6135 2800h-53"/><path d="m6049 2800h-53"/><path d="m5964 2800h-53"/><path d="m5879 2800h-54"/><path d="m5793 2800h-53"/><path d="m5708 2800h-53"/><path d="m5622 2800h-53"/><path d="m5537 2800h-53"/><path d="m5451 2800h-53"/><path d="m5366 2800h-53"/><path d="m5280 2800h-53"/><path d="m5195 2800h-53"/><path d="m5110 2800h-53"/><path d="m5024 2800h-53"/><path d="m4939 2800h-53"/><path d="m4853 2800h-53"/><path d="m4768 2800h-53"/><path d="m4682 2800h-53"/><path d="m4597 2800h-53"/><path d="m4512 2800h-53"/><path d="m4426 2800h-53"/><path d="m4341 2800h-53"/><path d="m4255 2800h-53"/><path d="m4170 2800h-53"/><path d="m4084 2800h-53"/><path d="m3999 2800h-53"/><path d="m3914 2800h-54"/><path d="m3828 2800h-53"/><path d="m3743 2800h-53"/><path d="m3657 2800h-53"/><path d="m3572 2800h-53"/><path d="m3486 2800h-53"/><path d="m3401 2800h-53"/><path d="m3316 2800h-54"/><path d="m3230 2800h-53"/><path d="m3145 2800h-53"/><path d="m3059 2800h-53"/></g></g><g transform="translate(-2197.3 -2186)"><rect height="1100.7" width="1213.6" y="6917.1" x="23255" fill="#f3e777"/><path fill="#ca4677" d="m22802 7700.4v-405.46l150.7-169.16c82.886-93.039 170.53-186.62 194.77-207.96l44.069-38.798 783.23-0.086 783.23-0.086v613.5 613.5h-978-978v-405.46zm1027.7 136.98v-78.372l-169.91 4.925-169.91 4.9249-5.09 45.854c-8.249 74.303 46.711 101.04 207.69 101.04h137.21v-78.372zm235.86-262.94 4.495-341.31 207.2-8.6408 207.2-8.6408 5.144-46.443c9.596-86.615-41.863-102.05-322.02-96.607l-246.71 4.7956-4.438 419.08-4.439 419.08h74.537 74.538l4.494-341.31zm391.3 313.72c26.41-19.286 36.255-41.399 32.697-73.447l-5.09-45.854h-174.05-174.05l-5.38 48.984c-9.97 90.771 0.993 97.91 150.36 97.91 99.305 0 148.27-7.6982 175.52-27.594zm-627.16-274.84v-77.768h-174.05-174.05v66.246c0 36.436 4.973 71.431 11.051 77.768 6.078 6.3366 84.401 11.521 174.05 11.521h163v-77.768zm659.89-4.9154 5.125-74.042-179.18 4.9155-179.18 4.9155-5.38 48.984c-10.473 95.348-2.259 99.57 183.28 94.197l170.2-4.9284 5.125-74.042zm-659.89-237.63v-78.372l-169.91 4.925-169.91 4.925-5.097 73.447-5.097 73.447h175 175v-78.372zm659.86 4.925-5.097-73.447h-174.05-174.05l-5.38 48.984c-10.289 93.673-2.146 97.91 188.15 97.91h175.52l-5.097-73.447zm-659.86-228.98v-77.768h-137.21c-97.358 0-147.91 7.8138-174.05 26.902-34.952 25.523-49.645 92.242-25.79 117.11 6.078 6.3366 84.401 11.521 174.05 11.521h163v-77.768z"/></g><g transform="matrix(.84874 0 0 .76147 2408.1 3615.3)"><rect height="3076.2" width="2734.3" y="13264" x="19249" fill="#6076b3"/><g stroke-linejoin="round" fill-rule="evenodd" stroke-width="28.222" fill="#e0ee2c"><rect y="13369" width="356.65" x="18937" height="180.95"/><rect y="13708" width="356.65" x="18937" height="180.95"/><rect y="14048" width="356.65" x="18937" height="180.95"/><rect y="14387" width="356.65" x="18937" height="180.95"/><rect y="14726" width="356.65" x="18937" height="180.95"/><rect y="15066" width="356.65" x="18937" height="180.95"/><rect y="15405" width="356.65" x="18937" height="180.95"/><rect y="15744" width="356.65" x="18937" height="180.95"/><rect y="16083" width="356.65" x="18937" height="180.95"/><rect y="13324" width="356.65" x="21939" height="180.95"/><rect y="13663" width="356.65" x="21939" height="180.95"/><rect y="14002" width="356.65" x="21939" height="180.95"/><rect y="14342" width="356.65" x="21939" height="180.95"/><rect y="14681" width="356.65" x="21939" height="180.95"/><rect y="15020" width="356.65" x="21939" height="180.95"/><rect y="15360" width="356.65" x="21939" height="180.95"/><rect y="15699" width="356.65" x="21939" height="180.95"/><rect y="16038" width="356.65" x="21939" height="180.95"/></g><g stroke-linejoin="round" fill-rule="evenodd" transform="matrix(.98702 0 0 .90336 -2675 7020.8)" class="com.sun.star.drawing.TextShape" stroke-width="28.222"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"/></text>
+<text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="1128.9px" y="9042.0264" x="22439.668" font-family="Sans" line-height="125%" fill="#000000"><tspan y="9042.0264" x="22439.668">CPU</tspan></text>
+</g></g><g stroke-linejoin="round" fill-rule="evenodd" transform="translate(-11752 543.6)" class="com.sun.star.drawing.TextShape" stroke-width="28.222"><text class="TextShape"><tspan font-size="706px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15832" x="24341" class="TextPosition" transform="matrix(0,-1,1,0,8509,40173)"><tspan fill="#000000">PCI, USB, SPI, I2C, ...</tspan></tspan></tspan></text>
+</g><g stroke-linejoin="round" fill-rule="evenodd" transform="translate(-655.31 963.83)" class="com.sun.star.drawing.RectangleShape" stroke-width="28.222"><g transform="matrix(.49166 0 0 1.0059 6045.6 -82.24)"><path fill="#cfe7f5" d="m14169 14572h-2268v-1412h4536v1412h-2268z"/><path fill="none" d="m14169 14572h-2268v-1412h4536v1412h-2268z" stroke="#3465af"/></g><text y="-395.11282" x="-790.22229" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="13686.9" x="12091.779" class="TextPosition"><tspan fill="#000000">Bridge</tspan></tspan></tspan></text>
+<text y="338.66486" x="-846.66675" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14420.677" x="12035.335" class="TextPosition"><tspan fill="#000000"> DMA</tspan></tspan></tspan></text>
+</g></svg>
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: net.h
+===========
+
+.. code-block:: c
+
+ /*
+ * net.h
+ *
+ * Copyright (C) 2000 Marcus Metzler <marcus@convergence.de>
+ * & Ralph Metzler <ralph@convergence.de>
+ * for convergence integrated media GmbH
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program 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.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+ #ifndef _DVBNET_H_
+ #define _DVBNET_H_
+
+ #include <linux/types.h>
+
+ struct dvb_net_if {
+ __u16 pid;
+ __u16 if_num;
+ __u8 feedtype;
+ #define DVB_NET_FEEDTYPE_MPE 0 /* multi protocol encapsulation */
+ #define DVB_NET_FEEDTYPE_ULE 1 /* ultra lightweight encapsulation */
+ };
+
+
+ #define NET_ADD_IF _IOWR('o', 52, struct dvb_net_if)
+ #define NET_REMOVE_IF _IO('o', 53)
+ #define NET_GET_IF _IOWR('o', 54, struct dvb_net_if)
+
+
+ /* binary compatibility cruft: */
+ struct __dvb_net_if_old {
+ __u16 pid;
+ __u16 if_num;
+ };
+ #define __NET_ADD_IF_OLD _IOWR('o', 52, struct __dvb_net_if_old)
+ #define __NET_GET_IF_OLD _IOWR('o', 54, struct __dvb_net_if_old)
+
+
+ #endif /*_DVBNET_H_*/
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: video.h
+=============
+
+.. code-block:: c
+
+ /*
+ * video.h
+ *
+ * Copyright (C) 2000 Marcus Metzler <marcus@convergence.de>
+ * & Ralph Metzler <ralph@convergence.de>
+ * for convergence integrated media GmbH
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program 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.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+ #ifndef _UAPI_DVBVIDEO_H_
+ #define _UAPI_DVBVIDEO_H_
+
+ #include <linux/types.h>
+ #ifndef __KERNEL__
+ #include <time.h>
+ #endif
+
+ 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;
+
+
+ typedef enum {
+ VIDEO_SYSTEM_PAL,
+ VIDEO_SYSTEM_NTSC,
+ VIDEO_SYSTEM_PALN,
+ VIDEO_SYSTEM_PALNc,
+ VIDEO_SYSTEM_PALM,
+ VIDEO_SYSTEM_NTSC60,
+ VIDEO_SYSTEM_PAL60,
+ VIDEO_SYSTEM_PALM60
+ } video_system_t;
+
+
+ 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;
+
+ typedef struct {
+ int w;
+ int h;
+ video_format_t aspect_ratio;
+ } video_size_t;
+
+ 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;
+
+
+ typedef enum {
+ VIDEO_STOPPED, /* Video is stopped */
+ VIDEO_PLAYING, /* Video is currently playing */
+ VIDEO_FREEZED /* Video is freezed */
+ } video_play_state_t;
+
+
+ /* Decoder commands */
+ #define VIDEO_CMD_PLAY (0)
+ #define VIDEO_CMD_STOP (1)
+ #define VIDEO_CMD_FREEZE (2)
+ #define VIDEO_CMD_CONTINUE (3)
+
+ /* Flags for VIDEO_CMD_FREEZE */
+ #define VIDEO_CMD_FREEZE_TO_BLACK (1 << 0)
+
+ /* Flags for VIDEO_CMD_STOP */
+ #define VIDEO_CMD_STOP_TO_BLACK (1 << 0)
+ #define VIDEO_CMD_STOP_IMMEDIATELY (1 << 1)
+
+ /* Play input formats: */
+ /* The decoder has no special format requirements */
+ #define VIDEO_PLAY_FMT_NONE (0)
+ /* The decoder requires full GOPs */
+ #define VIDEO_PLAY_FMT_GOP (1)
+
+ /* 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;
+ };
+ };
+
+ /* FIELD_UNKNOWN can be used if the hardware does not know whether
+ the Vsync is for an odd, even or progressive (i.e.ie; non-interlaced)
+ field. */
+ #define VIDEO_VSYNC_FIELD_UNKNOWN (0)
+ #define VIDEO_VSYNC_FIELD_ODD (1)
+ #define VIDEO_VSYNC_FIELD_EVEN (2)
+ #define VIDEO_VSYNC_FIELD_PROGRESSIVE (3)
+
+ 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
+ __kernel_time_t timestamp;
+ union {
+ video_size_t size;
+ unsigned int frame_rate; /* in frames per 1000sec */
+ unsigned char vsync_field; /* unknown/odd/even/progressive */
+ } u;
+ };
+
+
+ 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 */
+ };
+
+
+ struct video_still_picture {
+ char __user *iFrame; /* pointer to a single iframe in memory */
+ __s32 size;
+ };
+
+
+ typedef
+ struct video_highlight {
+ int active; /* 1=show highlight, 0=hide highlight */
+ __u8 contrast1; /* 7- 4 Pattern pixel contrast */
+ /* 3- 0 Background pixel contrast */
+ __u8 contrast2; /* 7- 4 Emphasis pixel-2 contrast */
+ /* 3- 0 Emphasis pixel-1 contrast */
+ __u8 color1; /* 7- 4 Pattern pixel color */
+ /* 3- 0 Background pixel color */
+ __u8 color2; /* 7- 4 Emphasis pixel-2 color */
+ /* 3- 0 Emphasis pixel-1 color */
+ __u32 ypos; /* 23-22 auto action mode */
+ /* 21-12 start y */
+ /* 9- 0 end y */
+ __u32 xpos; /* 23-22 button color number */
+ /* 21-12 start x */
+ /* 9- 0 end x */
+ } video_highlight_t;
+
+
+ typedef struct video_spu {
+ int active;
+ int stream_id;
+ } video_spu_t;
+
+
+ typedef struct video_spu_palette { /* SPU Palette information */
+ int length;
+ __u8 __user *palette;
+ } video_spu_palette_t;
+
+
+ typedef struct video_navi_pack {
+ int length; /* 0 ... 1024 */
+ __u8 data[1024];
+ } video_navi_pack_t;
+
+
+ typedef __u16 video_attributes_t;
+ /* bits: descr. */
+ /* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */
+ /* 13-12 TV system (0=525/60, 1=625/50) */
+ /* 11-10 Aspect ratio (0=4:3, 3=16:9) */
+ /* 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */
+ /* 7 line 21-1 data present in GOP (1=yes, 0=no) */
+ /* 6 line 21-2 data present in GOP (1=yes, 0=no) */
+ /* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */
+ /* 2 source letterboxed (1=yes, 0=no) */
+ /* 0 film/camera mode (0=camera, 1=film (625/50 only)) */
+
+
+ /* 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
+
+
+ #define VIDEO_STOP _IO('o', 21)
+ #define VIDEO_PLAY _IO('o', 22)
+ #define VIDEO_FREEZE _IO('o', 23)
+ #define VIDEO_CONTINUE _IO('o', 24)
+ #define VIDEO_SELECT_SOURCE _IO('o', 25)
+ #define VIDEO_SET_BLANK _IO('o', 26)
+ #define VIDEO_GET_STATUS _IOR('o', 27, struct video_status)
+ #define VIDEO_GET_EVENT _IOR('o', 28, struct video_event)
+ #define VIDEO_SET_DISPLAY_FORMAT _IO('o', 29)
+ #define VIDEO_STILLPICTURE _IOW('o', 30, struct video_still_picture)
+ #define VIDEO_FAST_FORWARD _IO('o', 31)
+ #define VIDEO_SLOWMOTION _IO('o', 32)
+ #define VIDEO_GET_CAPABILITIES _IOR('o', 33, unsigned int)
+ #define VIDEO_CLEAR_BUFFER _IO('o', 34)
+ #define VIDEO_SET_ID _IO('o', 35)
+ #define VIDEO_SET_STREAMTYPE _IO('o', 36)
+ #define VIDEO_SET_FORMAT _IO('o', 37)
+ #define VIDEO_SET_SYSTEM _IO('o', 38)
+ #define VIDEO_SET_HIGHLIGHT _IOW('o', 39, video_highlight_t)
+ #define VIDEO_SET_SPU _IOW('o', 50, video_spu_t)
+ #define VIDEO_SET_SPU_PALETTE _IOW('o', 51, video_spu_palette_t)
+ #define VIDEO_GET_NAVI _IOR('o', 52, video_navi_pack_t)
+ #define VIDEO_SET_ATTRIBUTES _IO('o', 53)
+ #define VIDEO_GET_SIZE _IOR('o', 55, video_size_t)
+ #define VIDEO_GET_FRAME_RATE _IOR('o', 56, unsigned int)
+
+ /**
+ * VIDEO_GET_PTS
+ *
+ * Read the 33 bit presentation time stamp 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.
+ */
+ #define VIDEO_GET_PTS _IOR('o', 57, __u64)
+
+ /* Read the number of displayed frames since the decoder was started */
+ #define VIDEO_GET_FRAME_COUNT _IOR('o', 58, __u64)
+
+ #define VIDEO_COMMAND _IOWR('o', 59, struct video_command)
+ #define VIDEO_TRY_COMMAND _IOWR('o', 60, struct video_command)
+
+ #endif /* _UAPI_DVBVIDEO_H_ */
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: videodev2.h
+=================
+
+.. code-block:: c
+
+ /*
+ * Video for Linux Two header file
+ *
+ * Copyright (C) 1999-2012 the contributors
+ *
+ * This program 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; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program 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.
+ *
+ * Alternatively you can redistribute this file under the terms of the
+ * BSD license as stated below:
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in
+ * the documentation and/or other materials provided with the
+ * distribution.
+ * 3. The names of its contributors may not be used to endorse or promote
+ * products derived from this software without specific prior written
+ * permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * Header file for v4l or V4L2 drivers and applications
+ * with public API.
+ * All kernel-specific stuff were moved to media/v4l2-dev.h, so
+ * no #if __KERNEL tests are allowed here
+ *
+ * See https://linuxtv.org for more info
+ *
+ * Author: Bill Dirks <bill@thedirks.org>
+ * Justin Schoeman
+ * Hans Verkuil <hverkuil@xs4all.nl>
+ * et al.
+ */
+ #ifndef _UAPI__LINUX_VIDEODEV2_H
+ #define _UAPI__LINUX_VIDEODEV2_H
+
+ #ifndef __KERNEL__
+ #include <sys/time.h>
+ #endif
+ #include <linux/compiler.h>
+ #include <linux/ioctl.h>
+ #include <linux/types.h>
+ #include <linux/v4l2-common.h>
+ #include <linux/v4l2-controls.h>
+
+ /*
+ * Common stuff for both V4L1 and V4L2
+ * Moved from videodev.h
+ */
+ #define VIDEO_MAX_FRAME 32
+ #define VIDEO_MAX_PLANES 8
+
+ /*
+ * M I S C E L L A N E O U S
+ */
+
+ /* Four-character-code (FOURCC) */
+ #define v4l2_fourcc(a, b, c, d)
+ ((__u32)(a) | ((__u32)(b) << 8) | ((__u32)(c) << 16) | ((__u32)(d) << 24))
+ #define v4l2_fourcc_be(a, b, c, d) (v4l2_fourcc(a, b, c, d) | (1 << 31))
+
+ /*
+ * E N U M S
+ */
+ enum v4l2_field {
+ V4L2_FIELD_ANY = 0, /* driver can choose from none,
+ top, bottom, interlaced
+ depending on whatever it thinks
+ is approximate ... */
+ V4L2_FIELD_NONE = 1, /* this device has no fields ... */
+ V4L2_FIELD_TOP = 2, /* top field only */
+ V4L2_FIELD_BOTTOM = 3, /* bottom field only */
+ V4L2_FIELD_INTERLACED = 4, /* both fields interlaced */
+ V4L2_FIELD_SEQ_TB = 5, /* both fields sequential into one
+ buffer, top-bottom order */
+ V4L2_FIELD_SEQ_BT = 6, /* same as above + bottom-top order */
+ V4L2_FIELD_ALTERNATE = 7, /* both fields alternating into
+ separate buffers */
+ V4L2_FIELD_INTERLACED_TB = 8, /* both fields interlaced, top field
+ first and the top field is
+ transmitted first */
+ V4L2_FIELD_INTERLACED_BT = 9, /* both fields interlaced, top field
+ first and the bottom field is
+ transmitted first */
+ };
+ #define V4L2_FIELD_HAS_TOP(field)
+ ((field) == V4L2_FIELD_TOP ||
+ (field) == V4L2_FIELD_INTERLACED ||
+ (field) == V4L2_FIELD_INTERLACED_TB ||
+ (field) == V4L2_FIELD_INTERLACED_BT ||
+ (field) == V4L2_FIELD_SEQ_TB ||
+ (field) == V4L2_FIELD_SEQ_BT)
+ #define V4L2_FIELD_HAS_BOTTOM(field)
+ ((field) == V4L2_FIELD_BOTTOM ||
+ (field) == V4L2_FIELD_INTERLACED ||
+ (field) == V4L2_FIELD_INTERLACED_TB ||
+ (field) == V4L2_FIELD_INTERLACED_BT ||
+ (field) == V4L2_FIELD_SEQ_TB ||
+ (field) == V4L2_FIELD_SEQ_BT)
+ #define V4L2_FIELD_HAS_BOTH(field)
+ ((field) == V4L2_FIELD_INTERLACED ||
+ (field) == V4L2_FIELD_INTERLACED_TB ||
+ (field) == V4L2_FIELD_INTERLACED_BT ||
+ (field) == V4L2_FIELD_SEQ_TB ||
+ (field) == V4L2_FIELD_SEQ_BT)
+ #define V4L2_FIELD_HAS_T_OR_B(field)
+ ((field) == V4L2_FIELD_BOTTOM ||
+ (field) == V4L2_FIELD_TOP ||
+ (field) == V4L2_FIELD_ALTERNATE)
+
+ enum v4l2_buf_type {
+ V4L2_BUF_TYPE_VIDEO_CAPTURE = 1,
+ V4L2_BUF_TYPE_VIDEO_OUTPUT = 2,
+ V4L2_BUF_TYPE_VIDEO_OVERLAY = 3,
+ V4L2_BUF_TYPE_VBI_CAPTURE = 4,
+ V4L2_BUF_TYPE_VBI_OUTPUT = 5,
+ V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6,
+ V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7,
+ V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8,
+ V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE = 9,
+ V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE = 10,
+ V4L2_BUF_TYPE_SDR_CAPTURE = 11,
+ V4L2_BUF_TYPE_SDR_OUTPUT = 12,
+ /* Deprecated, do not use */
+ V4L2_BUF_TYPE_PRIVATE = 0x80,
+ };
+
+ #define V4L2_TYPE_IS_MULTIPLANAR(type)
+ ((type) == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
+ || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE)
+
+ #define V4L2_TYPE_IS_OUTPUT(type)
+ ((type) == V4L2_BUF_TYPE_VIDEO_OUTPUT
+ || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE
+ || (type) == V4L2_BUF_TYPE_VIDEO_OVERLAY
+ || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY
+ || (type) == V4L2_BUF_TYPE_VBI_OUTPUT
+ || (type) == V4L2_BUF_TYPE_SLICED_VBI_OUTPUT
+ || (type) == V4L2_BUF_TYPE_SDR_OUTPUT)
+
+ enum v4l2_tuner_type {
+ V4L2_TUNER_RADIO = 1,
+ V4L2_TUNER_ANALOG_TV = 2,
+ V4L2_TUNER_DIGITAL_TV = 3,
+ V4L2_TUNER_SDR = 4,
+ V4L2_TUNER_RF = 5,
+ };
+
+ /* Deprecated, do not use */
+ #define V4L2_TUNER_ADC V4L2_TUNER_SDR
+
+ enum v4l2_memory {
+ V4L2_MEMORY_MMAP = 1,
+ V4L2_MEMORY_USERPTR = 2,
+ V4L2_MEMORY_OVERLAY = 3,
+ V4L2_MEMORY_DMABUF = 4,
+ };
+
+ /* see also http://vektor.theorem.ca/graphics/ycbcr/ */
+ enum v4l2_colorspace {
+ /*
+ * Default colorspace, i.e.ie; let the driver figure it out.
+ * Can only be used with video capture.
+ */
+ V4L2_COLORSPACE_DEFAULT = 0,
+
+ /* SMPTE 170M: used for broadcast NTSC/PAL SDTV */
+ V4L2_COLORSPACE_SMPTE170M = 1,
+
+ /* Obsolete pre-1998 SMPTE 240M HDTV standard, superseded by Rec 709 */
+ V4L2_COLORSPACE_SMPTE240M = 2,
+
+ /* Rec.709: used for HDTV */
+ V4L2_COLORSPACE_REC709 = 3,
+
+ /*
+ * Deprecated, do not use. No driver will ever return this. This was
+ * based on a misunderstanding of the bt878 datasheet.
+ */
+ V4L2_COLORSPACE_BT878 = 4,
+
+ /*
+ * NTSC 1953 colorspace. This only makes sense when dealing with
+ * really, really old NTSC recordings. Superseded by SMPTE 170M.
+ */
+ V4L2_COLORSPACE_470_SYSTEM_M = 5,
+
+ /*
+ * EBU Tech 3213 PAL/SECAM colorspace. This only makes sense when
+ * dealing with really old PAL/SECAM recordings. Superseded by
+ * SMPTE 170M.
+ */
+ V4L2_COLORSPACE_470_SYSTEM_BG = 6,
+
+ /*
+ * Effectively shorthand for V4L2_COLORSPACE_SRGB, V4L2_YCBCR_ENC_601
+ * and V4L2_QUANTIZATION_FULL_RANGE. To be used for (Motion-)JPEG.
+ */
+ V4L2_COLORSPACE_JPEG = 7,
+
+ /* For RGB colorspaces such as produces by most webcams. */
+ V4L2_COLORSPACE_SRGB = 8,
+
+ /* AdobeRGB colorspace */
+ V4L2_COLORSPACE_ADOBERGB = 9,
+
+ /* BT.2020 colorspace, used for UHDTV. */
+ V4L2_COLORSPACE_BT2020 = 10,
+
+ /* Raw colorspace: for RAW unprocessed images */
+ V4L2_COLORSPACE_RAW = 11,
+
+ /* DCI-P3 colorspace, used by cinema projectors */
+ V4L2_COLORSPACE_DCI_P3 = 12,
+ };
+
+ /*
+ * Determine how COLORSPACE_DEFAULT should map to a proper colorspace.
+ * This depends on whether this is a SDTV image (use SMPTE 170M), an
+ * HDTV image (use Rec. 709), or something else (use sRGB).
+ */
+ #define V4L2_MAP_COLORSPACE_DEFAULT(is_sdtv, is_hdtv)
+ ((is_sdtv) ? V4L2_COLORSPACE_SMPTE170M :
+ ((is_hdtv) ? V4L2_COLORSPACE_REC709 : V4L2_COLORSPACE_SRGB))
+
+ enum v4l2_xfer_func {
+ /*
+ * Mapping of V4L2_XFER_FUNC_DEFAULT to actual transfer functions
+ * for the various colorspaces:
+ *
+ * V4L2_COLORSPACE_SMPTE170M, V4L2_COLORSPACE_470_SYSTEM_M,
+ * V4L2_COLORSPACE_470_SYSTEM_BG, V4L2_COLORSPACE_REC709 and
+ * V4L2_COLORSPACE_BT2020: V4L2_XFER_FUNC_709
+ *
+ * V4L2_COLORSPACE_SRGB, V4L2_COLORSPACE_JPEG: V4L2_XFER_FUNC_SRGB
+ *
+ * V4L2_COLORSPACE_ADOBERGB: V4L2_XFER_FUNC_ADOBERGB
+ *
+ * V4L2_COLORSPACE_SMPTE240M: V4L2_XFER_FUNC_SMPTE240M
+ *
+ * V4L2_COLORSPACE_RAW: V4L2_XFER_FUNC_NONE
+ *
+ * V4L2_COLORSPACE_DCI_P3: V4L2_XFER_FUNC_DCI_P3
+ */
+ V4L2_XFER_FUNC_DEFAULT = 0,
+ V4L2_XFER_FUNC_709 = 1,
+ V4L2_XFER_FUNC_SRGB = 2,
+ V4L2_XFER_FUNC_ADOBERGB = 3,
+ V4L2_XFER_FUNC_SMPTE240M = 4,
+ V4L2_XFER_FUNC_NONE = 5,
+ V4L2_XFER_FUNC_DCI_P3 = 6,
+ V4L2_XFER_FUNC_SMPTE2084 = 7,
+ };
+
+ /*
+ * Determine how XFER_FUNC_DEFAULT should map to a proper transfer function.
+ * This depends on the colorspace.
+ */
+ #define V4L2_MAP_XFER_FUNC_DEFAULT(colsp)
+ ((colsp) == V4L2_COLORSPACE_ADOBERGB ? V4L2_XFER_FUNC_ADOBERGB :
+ ((colsp) == V4L2_COLORSPACE_SMPTE240M ? V4L2_XFER_FUNC_SMPTE240M :
+ ((colsp) == V4L2_COLORSPACE_DCI_P3 ? V4L2_XFER_FUNC_DCI_P3 :
+ ((colsp) == V4L2_COLORSPACE_RAW ? V4L2_XFER_FUNC_NONE :
+ ((colsp) == V4L2_COLORSPACE_SRGB || (colsp) == V4L2_COLORSPACE_JPEG ?
+ V4L2_XFER_FUNC_SRGB : V4L2_XFER_FUNC_709)))))
+
+ enum v4l2_ycbcr_encoding {
+ /*
+ * Mapping of V4L2_YCBCR_ENC_DEFAULT to actual encodings for the
+ * various colorspaces:
+ *
+ * V4L2_COLORSPACE_SMPTE170M, V4L2_COLORSPACE_470_SYSTEM_M,
+ * V4L2_COLORSPACE_470_SYSTEM_BG, V4L2_COLORSPACE_ADOBERGB and
+ * V4L2_COLORSPACE_JPEG: V4L2_YCBCR_ENC_601
+ *
+ * V4L2_COLORSPACE_REC709 and V4L2_COLORSPACE_DCI_P3: V4L2_YCBCR_ENC_709
+ *
+ * V4L2_COLORSPACE_SRGB: V4L2_YCBCR_ENC_SYCC
+ *
+ * V4L2_COLORSPACE_BT2020: V4L2_YCBCR_ENC_BT2020
+ *
+ * V4L2_COLORSPACE_SMPTE240M: V4L2_YCBCR_ENC_SMPTE240M
+ */
+ V4L2_YCBCR_ENC_DEFAULT = 0,
+
+ /* ITU-R 601 -- SDTV */
+ V4L2_YCBCR_ENC_601 = 1,
+
+ /* Rec. 709 -- HDTV */
+ V4L2_YCBCR_ENC_709 = 2,
+
+ /* ITU-R 601/EN 61966-2-4 Extended Gamut -- SDTV */
+ V4L2_YCBCR_ENC_XV601 = 3,
+
+ /* Rec. 709/EN 61966-2-4 Extended Gamut -- HDTV */
+ V4L2_YCBCR_ENC_XV709 = 4,
+
+ /* sYCC (Y'CbCr encoding of sRGB) */
+ V4L2_YCBCR_ENC_SYCC = 5,
+
+ /* BT.2020 Non-constant Luminance Y'CbCr */
+ V4L2_YCBCR_ENC_BT2020 = 6,
+
+ /* BT.2020 Constant Luminance Y'CbcCrc */
+ V4L2_YCBCR_ENC_BT2020_CONST_LUM = 7,
+
+ /* SMPTE 240M -- Obsolete HDTV */
+ V4L2_YCBCR_ENC_SMPTE240M = 8,
+ };
+
+ /*
+ * Determine how YCBCR_ENC_DEFAULT should map to a proper Y'CbCr encoding.
+ * This depends on the colorspace.
+ */
+ #define V4L2_MAP_YCBCR_ENC_DEFAULT(colsp)
+ (((colsp) == V4L2_COLORSPACE_REC709 ||
+ (colsp) == V4L2_COLORSPACE_DCI_P3) ? V4L2_YCBCR_ENC_709 :
+ ((colsp) == V4L2_COLORSPACE_BT2020 ? V4L2_YCBCR_ENC_BT2020 :
+ ((colsp) == V4L2_COLORSPACE_SMPTE240M ? V4L2_YCBCR_ENC_SMPTE240M :
+ V4L2_YCBCR_ENC_601)))
+
+ enum v4l2_quantization {
+ /*
+ * The default for R'G'B' quantization is always full range, except
+ * for the BT2020 colorspace. For Y'CbCr the quantization is always
+ * limited range, except for COLORSPACE_JPEG, SYCC, XV601 or XV709:
+ * those are full range.
+ */
+ V4L2_QUANTIZATION_DEFAULT = 0,
+ V4L2_QUANTIZATION_FULL_RANGE = 1,
+ V4L2_QUANTIZATION_LIM_RANGE = 2,
+ };
+
+ /*
+ * Determine how QUANTIZATION_DEFAULT should map to a proper quantization.
+ * This depends on whether the image is RGB or not, the colorspace and the
+ * Y'CbCr encoding.
+ */
+ #define V4L2_MAP_QUANTIZATION_DEFAULT(is_rgb, colsp, ycbcr_enc)
+ (((is_rgb) && (colsp) == V4L2_COLORSPACE_BT2020) ? V4L2_QUANTIZATION_LIM_RANGE :
+ (((is_rgb) || (ycbcr_enc) == V4L2_YCBCR_ENC_XV601 ||
+ (ycbcr_enc) == V4L2_YCBCR_ENC_XV709 || (colsp) == V4L2_COLORSPACE_JPEG) ?
+ V4L2_QUANTIZATION_FULL_RANGE : V4L2_QUANTIZATION_LIM_RANGE))
+
+ enum v4l2_priority {
+ V4L2_PRIORITY_UNSET = 0, /* not initialized */
+ V4L2_PRIORITY_BACKGROUND = 1,
+ V4L2_PRIORITY_INTERACTIVE = 2,
+ V4L2_PRIORITY_RECORD = 3,
+ V4L2_PRIORITY_DEFAULT = V4L2_PRIORITY_INTERACTIVE,
+ };
+
+ struct v4l2_rect {
+ __s32 left;
+ __s32 top;
+ __u32 width;
+ __u32 height;
+ };
+
+ struct v4l2_fract {
+ __u32 numerator;
+ __u32 denominator;
+ };
+
+ /**
+ * struct v4l2_capability - Describes V4L2 device caps returned by VIDIOC_QUERYCAP
+ *
+ * @driver: name of the driver module (e.g. "bttv")
+ * @card: name of the card (e.g. "Hauppauge WinTV")
+ * @bus_info: name of the bus (e.g. "PCI:" + pci_name(pci_dev) )
+ * @version: KERNEL_VERSION
+ * @capabilities: capabilities of the physical device as a whole
+ * @device_caps: capabilities accessed via this particular device (node)
+ * @reserved: reserved fields for future extensions
+ */
+ struct v4l2_capability {
+ __u8 driver[16];
+ __u8 card[32];
+ __u8 bus_info[32];
+ __u32 version;
+ __u32 capabilities;
+ __u32 device_caps;
+ __u32 reserved[3];
+ };
+
+ /* Values for 'capabilities' field */
+ #define V4L2_CAP_VIDEO_CAPTURE 0x00000001 /* Is a video capture device */
+ #define V4L2_CAP_VIDEO_OUTPUT 0x00000002 /* Is a video output device */
+ #define V4L2_CAP_VIDEO_OVERLAY 0x00000004 /* Can do video overlay */
+ #define V4L2_CAP_VBI_CAPTURE 0x00000010 /* Is a raw VBI capture device */
+ #define V4L2_CAP_VBI_OUTPUT 0x00000020 /* Is a raw VBI output device */
+ #define V4L2_CAP_SLICED_VBI_CAPTURE 0x00000040 /* Is a sliced VBI capture device */
+ #define V4L2_CAP_SLICED_VBI_OUTPUT 0x00000080 /* Is a sliced VBI output device */
+ #define V4L2_CAP_RDS_CAPTURE 0x00000100 /* RDS data capture */
+ #define V4L2_CAP_VIDEO_OUTPUT_OVERLAY 0x00000200 /* Can do video output overlay */
+ #define V4L2_CAP_HW_FREQ_SEEK 0x00000400 /* Can do hardware frequency seek */
+ #define V4L2_CAP_RDS_OUTPUT 0x00000800 /* Is an RDS encoder */
+
+ /* Is a video capture device that supports multiplanar formats */
+ #define V4L2_CAP_VIDEO_CAPTURE_MPLANE 0x00001000
+ /* Is a video output device that supports multiplanar formats */
+ #define V4L2_CAP_VIDEO_OUTPUT_MPLANE 0x00002000
+ /* Is a video mem-to-mem device that supports multiplanar formats */
+ #define V4L2_CAP_VIDEO_M2M_MPLANE 0x00004000
+ /* Is a video mem-to-mem device */
+ #define V4L2_CAP_VIDEO_M2M 0x00008000
+
+ #define V4L2_CAP_TUNER 0x00010000 /* has a tuner */
+ #define V4L2_CAP_AUDIO 0x00020000 /* has audio support */
+ #define V4L2_CAP_RADIO 0x00040000 /* is a radio device */
+ #define V4L2_CAP_MODULATOR 0x00080000 /* has a modulator */
+
+ #define V4L2_CAP_SDR_CAPTURE 0x00100000 /* Is a SDR capture device */
+ #define V4L2_CAP_EXT_PIX_FORMAT 0x00200000 /* Supports the extended pixel format */
+ #define V4L2_CAP_SDR_OUTPUT 0x00400000 /* Is a SDR output device */
+
+ #define V4L2_CAP_READWRITE 0x01000000 /* read/write systemcalls */
+ #define V4L2_CAP_ASYNCIO 0x02000000 /* async I/O */
+ #define V4L2_CAP_STREAMING 0x04000000 /* streaming I/O ioctls */
+
+ #define V4L2_CAP_DEVICE_CAPS 0x80000000 /* sets device capabilities field */
+
+ /*
+ * V I D E O I M A G E F O R M A T
+ */
+ struct v4l2_pix_format {
+ __u32 width;
+ __u32 height;
+ __u32 pixelformat;
+ __u32 field; /* enum v4l2_field */
+ __u32 bytesperline; /* for padding, zero if unused */
+ __u32 sizeimage;
+ __u32 colorspace; /* enum v4l2_colorspace */
+ __u32 priv; /* private data, depends on pixelformat */
+ __u32 flags; /* format flags (V4L2_PIX_FMT_FLAG_*) */
+ __u32 ycbcr_enc; /* enum v4l2_ycbcr_encoding */
+ __u32 quantization; /* enum v4l2_quantization */
+ __u32 xfer_func; /* enum v4l2_xfer_func */
+ };
+
+ /* Pixel format FOURCC depth Description */
+
+ /* RGB formats */
+ #define V4L2_PIX_FMT_RGB332 v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */
+ #define V4L2_PIX_FMT_RGB444 v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */
+ #define V4L2_PIX_FMT_ARGB444 v4l2_fourcc('A', 'R', '1', '2') /* 16 aaaarrrr ggggbbbb */
+ #define V4L2_PIX_FMT_XRGB444 v4l2_fourcc('X', 'R', '1', '2') /* 16 xxxxrrrr ggggbbbb */
+ #define V4L2_PIX_FMT_RGB555 v4l2_fourcc('R', 'G', 'B', 'O') /* 16 RGB-5-5-5 */
+ #define V4L2_PIX_FMT_ARGB555 v4l2_fourcc('A', 'R', '1', '5') /* 16 ARGB-1-5-5-5 */
+ #define V4L2_PIX_FMT_XRGB555 v4l2_fourcc('X', 'R', '1', '5') /* 16 XRGB-1-5-5-5 */
+ #define V4L2_PIX_FMT_RGB565 v4l2_fourcc('R', 'G', 'B', 'P') /* 16 RGB-5-6-5 */
+ #define V4L2_PIX_FMT_RGB555X v4l2_fourcc('R', 'G', 'B', 'Q') /* 16 RGB-5-5-5 BE */
+ #define V4L2_PIX_FMT_ARGB555X v4l2_fourcc_be('A', 'R', '1', '5') /* 16 ARGB-5-5-5 BE */
+ #define V4L2_PIX_FMT_XRGB555X v4l2_fourcc_be('X', 'R', '1', '5') /* 16 XRGB-5-5-5 BE */
+ #define V4L2_PIX_FMT_RGB565X v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */
+ #define V4L2_PIX_FMT_BGR666 v4l2_fourcc('B', 'G', 'R', 'H') /* 18 BGR-6-6-6 */
+ #define V4L2_PIX_FMT_BGR24 v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */
+ #define V4L2_PIX_FMT_RGB24 v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */
+ #define V4L2_PIX_FMT_BGR32 v4l2_fourcc('B', 'G', 'R', '4') /* 32 BGR-8-8-8-8 */
+ #define V4L2_PIX_FMT_ABGR32 v4l2_fourcc('A', 'R', '2', '4') /* 32 BGRA-8-8-8-8 */
+ #define V4L2_PIX_FMT_XBGR32 v4l2_fourcc('X', 'R', '2', '4') /* 32 BGRX-8-8-8-8 */
+ #define V4L2_PIX_FMT_RGB32 v4l2_fourcc('R', 'G', 'B', '4') /* 32 RGB-8-8-8-8 */
+ #define V4L2_PIX_FMT_ARGB32 v4l2_fourcc('B', 'A', '2', '4') /* 32 ARGB-8-8-8-8 */
+ #define V4L2_PIX_FMT_XRGB32 v4l2_fourcc('B', 'X', '2', '4') /* 32 XRGB-8-8-8-8 */
+
+ /* Grey formats */
+ #define V4L2_PIX_FMT_GREY v4l2_fourcc('G', 'R', 'E', 'Y') /* 8 Greyscale */
+ #define V4L2_PIX_FMT_Y4 v4l2_fourcc('Y', '0', '4', ' ') /* 4 Greyscale */
+ #define V4L2_PIX_FMT_Y6 v4l2_fourcc('Y', '0', '6', ' ') /* 6 Greyscale */
+ #define V4L2_PIX_FMT_Y10 v4l2_fourcc('Y', '1', '0', ' ') /* 10 Greyscale */
+ #define V4L2_PIX_FMT_Y12 v4l2_fourcc('Y', '1', '2', ' ') /* 12 Greyscale */
+ #define V4L2_PIX_FMT_Y16 v4l2_fourcc('Y', '1', '6', ' ') /* 16 Greyscale */
+ #define V4L2_PIX_FMT_Y16_BE v4l2_fourcc_be('Y', '1', '6', ' ') /* 16 Greyscale BE */
+
+ /* Grey bit-packed formats */
+ #define V4L2_PIX_FMT_Y10BPACK v4l2_fourcc('Y', '1', '0', 'B') /* 10 Greyscale bit-packed */
+
+ /* Palette formats */
+ #define V4L2_PIX_FMT_PAL8 v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */
+
+ /* Chrominance formats */
+ #define V4L2_PIX_FMT_UV8 v4l2_fourcc('U', 'V', '8', ' ') /* 8 UV 4:4 */
+
+ /* Luminance+Chrominance formats */
+ #define V4L2_PIX_FMT_YVU410 v4l2_fourcc('Y', 'V', 'U', '9') /* 9 YVU 4:1:0 */
+ #define V4L2_PIX_FMT_YVU420 v4l2_fourcc('Y', 'V', '1', '2') /* 12 YVU 4:2:0 */
+ #define V4L2_PIX_FMT_YUYV v4l2_fourcc('Y', 'U', 'Y', 'V') /* 16 YUV 4:2:2 */
+ #define V4L2_PIX_FMT_YYUV v4l2_fourcc('Y', 'Y', 'U', 'V') /* 16 YUV 4:2:2 */
+ #define V4L2_PIX_FMT_YVYU v4l2_fourcc('Y', 'V', 'Y', 'U') /* 16 YVU 4:2:2 */
+ #define V4L2_PIX_FMT_UYVY v4l2_fourcc('U', 'Y', 'V', 'Y') /* 16 YUV 4:2:2 */
+ #define V4L2_PIX_FMT_VYUY v4l2_fourcc('V', 'Y', 'U', 'Y') /* 16 YUV 4:2:2 */
+ #define V4L2_PIX_FMT_YUV422P v4l2_fourcc('4', '2', '2', 'P') /* 16 YVU422 planar */
+ #define V4L2_PIX_FMT_YUV411P v4l2_fourcc('4', '1', '1', 'P') /* 16 YVU411 planar */
+ #define V4L2_PIX_FMT_Y41P v4l2_fourcc('Y', '4', '1', 'P') /* 12 YUV 4:1:1 */
+ #define V4L2_PIX_FMT_YUV444 v4l2_fourcc('Y', '4', '4', '4') /* 16 xxxxyyyy uuuuvvvv */
+ #define V4L2_PIX_FMT_YUV555 v4l2_fourcc('Y', 'U', 'V', 'O') /* 16 YUV-5-5-5 */
+ #define V4L2_PIX_FMT_YUV565 v4l2_fourcc('Y', 'U', 'V', 'P') /* 16 YUV-5-6-5 */
+ #define V4L2_PIX_FMT_YUV32 v4l2_fourcc('Y', 'U', 'V', '4') /* 32 YUV-8-8-8-8 */
+ #define V4L2_PIX_FMT_YUV410 v4l2_fourcc('Y', 'U', 'V', '9') /* 9 YUV 4:1:0 */
+ #define V4L2_PIX_FMT_YUV420 v4l2_fourcc('Y', 'U', '1', '2') /* 12 YUV 4:2:0 */
+ #define V4L2_PIX_FMT_HI240 v4l2_fourcc('H', 'I', '2', '4') /* 8 8-bit color */
+ #define V4L2_PIX_FMT_HM12 v4l2_fourcc('H', 'M', '1', '2') /* 8 YUV 4:2:0 16x16 macroblocks */
+ #define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
+
+ /* two planes -- one Y, one Cr + Cb interleaved */
+ #define V4L2_PIX_FMT_NV12 v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */
+ #define V4L2_PIX_FMT_NV21 v4l2_fourcc('N', 'V', '2', '1') /* 12 Y/CrCb 4:2:0 */
+ #define V4L2_PIX_FMT_NV16 v4l2_fourcc('N', 'V', '1', '6') /* 16 Y/CbCr 4:2:2 */
+ #define V4L2_PIX_FMT_NV61 v4l2_fourcc('N', 'V', '6', '1') /* 16 Y/CrCb 4:2:2 */
+ #define V4L2_PIX_FMT_NV24 v4l2_fourcc('N', 'V', '2', '4') /* 24 Y/CbCr 4:4:4 */
+ #define V4L2_PIX_FMT_NV42 v4l2_fourcc('N', 'V', '4', '2') /* 24 Y/CrCb 4:4:4 */
+
+ /* two non contiguous planes - one Y, one Cr + Cb interleaved */
+ #define V4L2_PIX_FMT_NV12M v4l2_fourcc('N', 'M', '1', '2') /* 12 Y/CbCr 4:2:0 */
+ #define V4L2_PIX_FMT_NV21M v4l2_fourcc('N', 'M', '2', '1') /* 21 Y/CrCb 4:2:0 */
+ #define V4L2_PIX_FMT_NV16M v4l2_fourcc('N', 'M', '1', '6') /* 16 Y/CbCr 4:2:2 */
+ #define V4L2_PIX_FMT_NV61M v4l2_fourcc('N', 'M', '6', '1') /* 16 Y/CrCb 4:2:2 */
+ #define V4L2_PIX_FMT_NV12MT v4l2_fourcc('T', 'M', '1', '2') /* 12 Y/CbCr 4:2:0 64x32 macroblocks */
+ #define V4L2_PIX_FMT_NV12MT_16X16 v4l2_fourcc('V', 'M', '1', '2') /* 12 Y/CbCr 4:2:0 16x16 macroblocks */
+
+ /* three non contiguous planes - Y, Cb, Cr */
+ #define V4L2_PIX_FMT_YUV420M v4l2_fourcc('Y', 'M', '1', '2') /* 12 YUV420 planar */
+ #define V4L2_PIX_FMT_YVU420M v4l2_fourcc('Y', 'M', '2', '1') /* 12 YVU420 planar */
+ #define V4L2_PIX_FMT_YUV422M v4l2_fourcc('Y', 'M', '1', '6') /* 16 YUV422 planar */
+ #define V4L2_PIX_FMT_YVU422M v4l2_fourcc('Y', 'M', '6', '1') /* 16 YVU422 planar */
+ #define V4L2_PIX_FMT_YUV444M v4l2_fourcc('Y', 'M', '2', '4') /* 24 YUV444 planar */
+ #define V4L2_PIX_FMT_YVU444M v4l2_fourcc('Y', 'M', '4', '2') /* 24 YVU444 planar */
+
+ /* Bayer formats - see http://www.siliconimaging.com/RGB%20Bayer.htm */
+ #define V4L2_PIX_FMT_SBGGR8 v4l2_fourcc('B', 'A', '8', '1') /* 8 BGBG.. GRGR.. */
+ #define V4L2_PIX_FMT_SGBRG8 v4l2_fourcc('G', 'B', 'R', 'G') /* 8 GBGB.. RGRG.. */
+ #define V4L2_PIX_FMT_SGRBG8 v4l2_fourcc('G', 'R', 'B', 'G') /* 8 GRGR.. BGBG.. */
+ #define V4L2_PIX_FMT_SRGGB8 v4l2_fourcc('R', 'G', 'G', 'B') /* 8 RGRG.. GBGB.. */
+ #define V4L2_PIX_FMT_SBGGR10 v4l2_fourcc('B', 'G', '1', '0') /* 10 BGBG.. GRGR.. */
+ #define V4L2_PIX_FMT_SGBRG10 v4l2_fourcc('G', 'B', '1', '0') /* 10 GBGB.. RGRG.. */
+ #define V4L2_PIX_FMT_SGRBG10 v4l2_fourcc('B', 'A', '1', '0') /* 10 GRGR.. BGBG.. */
+ #define V4L2_PIX_FMT_SRGGB10 v4l2_fourcc('R', 'G', '1', '0') /* 10 RGRG.. GBGB.. */
+ /* 10bit raw bayer packed, 5 bytes for every 4 pixels */
+ #define V4L2_PIX_FMT_SBGGR10P v4l2_fourcc('p', 'B', 'A', 'A')
+ #define V4L2_PIX_FMT_SGBRG10P v4l2_fourcc('p', 'G', 'A', 'A')
+ #define V4L2_PIX_FMT_SGRBG10P v4l2_fourcc('p', 'g', 'A', 'A')
+ #define V4L2_PIX_FMT_SRGGB10P v4l2_fourcc('p', 'R', 'A', 'A')
+ /* 10bit raw bayer a-law compressed to 8 bits */
+ #define V4L2_PIX_FMT_SBGGR10ALAW8 v4l2_fourcc('a', 'B', 'A', '8')
+ #define V4L2_PIX_FMT_SGBRG10ALAW8 v4l2_fourcc('a', 'G', 'A', '8')
+ #define V4L2_PIX_FMT_SGRBG10ALAW8 v4l2_fourcc('a', 'g', 'A', '8')
+ #define V4L2_PIX_FMT_SRGGB10ALAW8 v4l2_fourcc('a', 'R', 'A', '8')
+ /* 10bit raw bayer DPCM compressed to 8 bits */
+ #define V4L2_PIX_FMT_SBGGR10DPCM8 v4l2_fourcc('b', 'B', 'A', '8')
+ #define V4L2_PIX_FMT_SGBRG10DPCM8 v4l2_fourcc('b', 'G', 'A', '8')
+ #define V4L2_PIX_FMT_SGRBG10DPCM8 v4l2_fourcc('B', 'D', '1', '0')
+ #define V4L2_PIX_FMT_SRGGB10DPCM8 v4l2_fourcc('b', 'R', 'A', '8')
+ #define V4L2_PIX_FMT_SBGGR12 v4l2_fourcc('B', 'G', '1', '2') /* 12 BGBG.. GRGR.. */
+ #define V4L2_PIX_FMT_SGBRG12 v4l2_fourcc('G', 'B', '1', '2') /* 12 GBGB.. RGRG.. */
+ #define V4L2_PIX_FMT_SGRBG12 v4l2_fourcc('B', 'A', '1', '2') /* 12 GRGR.. BGBG.. */
+ #define V4L2_PIX_FMT_SRGGB12 v4l2_fourcc('R', 'G', '1', '2') /* 12 RGRG.. GBGB.. */
+ #define V4L2_PIX_FMT_SBGGR16 v4l2_fourcc('B', 'Y', 'R', '2') /* 16 BGBG.. GRGR.. */
+
+ /* compressed formats */
+ #define V4L2_PIX_FMT_MJPEG v4l2_fourcc('M', 'J', 'P', 'G') /* Motion-JPEG */
+ #define V4L2_PIX_FMT_JPEG v4l2_fourcc('J', 'P', 'E', 'G') /* JFIF JPEG */
+ #define V4L2_PIX_FMT_DV v4l2_fourcc('d', 'v', 's', 'd') /* 1394 */
+ #define V4L2_PIX_FMT_MPEG v4l2_fourcc('M', 'P', 'E', 'G') /* MPEG-1/2/4 Multiplexed */
+ #define V4L2_PIX_FMT_H264 v4l2_fourcc('H', '2', '6', '4') /* H264 with start codes */
+ #define V4L2_PIX_FMT_H264_NO_SC v4l2_fourcc('A', 'V', 'C', '1') /* H264 without start codes */
+ #define V4L2_PIX_FMT_H264_MVC v4l2_fourcc('M', '2', '6', '4') /* H264 MVC */
+ #define V4L2_PIX_FMT_H263 v4l2_fourcc('H', '2', '6', '3') /* H263 */
+ #define V4L2_PIX_FMT_MPEG1 v4l2_fourcc('M', 'P', 'G', '1') /* MPEG-1 ES */
+ #define V4L2_PIX_FMT_MPEG2 v4l2_fourcc('M', 'P', 'G', '2') /* MPEG-2 ES */
+ #define V4L2_PIX_FMT_MPEG4 v4l2_fourcc('M', 'P', 'G', '4') /* MPEG-4 part 2 ES */
+ #define V4L2_PIX_FMT_XVID v4l2_fourcc('X', 'V', 'I', 'D') /* Xvid */
+ #define V4L2_PIX_FMT_VC1_ANNEX_G v4l2_fourcc('V', 'C', '1', 'G') /* SMPTE 421M Annex G compliant stream */
+ #define V4L2_PIX_FMT_VC1_ANNEX_L v4l2_fourcc('V', 'C', '1', 'L') /* SMPTE 421M Annex L compliant stream */
+ #define V4L2_PIX_FMT_VP8 v4l2_fourcc('V', 'P', '8', '0') /* VP8 */
+
+ /* Vendor-specific formats */
+ #define V4L2_PIX_FMT_CPIA1 v4l2_fourcc('C', 'P', 'I', 'A') /* cpia1 YUV */
+ #define V4L2_PIX_FMT_WNVA v4l2_fourcc('W', 'N', 'V', 'A') /* Winnov hw compress */
+ #define V4L2_PIX_FMT_SN9C10X v4l2_fourcc('S', '9', '1', '0') /* SN9C10x compression */
+ #define V4L2_PIX_FMT_SN9C20X_I420 v4l2_fourcc('S', '9', '2', '0') /* SN9C20x YUV 4:2:0 */
+ #define V4L2_PIX_FMT_PWC1 v4l2_fourcc('P', 'W', 'C', '1') /* pwc older webcam */
+ #define V4L2_PIX_FMT_PWC2 v4l2_fourcc('P', 'W', 'C', '2') /* pwc newer webcam */
+ #define V4L2_PIX_FMT_ET61X251 v4l2_fourcc('E', '6', '2', '5') /* ET61X251 compression */
+ #define V4L2_PIX_FMT_SPCA501 v4l2_fourcc('S', '5', '0', '1') /* YUYV per line */
+ #define V4L2_PIX_FMT_SPCA505 v4l2_fourcc('S', '5', '0', '5') /* YYUV per line */
+ #define V4L2_PIX_FMT_SPCA508 v4l2_fourcc('S', '5', '0', '8') /* YUVY per line */
+ #define V4L2_PIX_FMT_SPCA561 v4l2_fourcc('S', '5', '6', '1') /* compressed GBRG bayer */
+ #define V4L2_PIX_FMT_PAC207 v4l2_fourcc('P', '2', '0', '7') /* compressed BGGR bayer */
+ #define V4L2_PIX_FMT_MR97310A v4l2_fourcc('M', '3', '1', '0') /* compressed BGGR bayer */
+ #define V4L2_PIX_FMT_JL2005BCD v4l2_fourcc('J', 'L', '2', '0') /* compressed RGGB bayer */
+ #define V4L2_PIX_FMT_SN9C2028 v4l2_fourcc('S', 'O', 'N', 'X') /* compressed GBRG bayer */
+ #define V4L2_PIX_FMT_SQ905C v4l2_fourcc('9', '0', '5', 'C') /* compressed RGGB bayer */
+ #define V4L2_PIX_FMT_PJPG v4l2_fourcc('P', 'J', 'P', 'G') /* Pixart 73xx JPEG */
+ #define V4L2_PIX_FMT_OV511 v4l2_fourcc('O', '5', '1', '1') /* ov511 JPEG */
+ #define V4L2_PIX_FMT_OV518 v4l2_fourcc('O', '5', '1', '8') /* ov518 JPEG */
+ #define V4L2_PIX_FMT_STV0680 v4l2_fourcc('S', '6', '8', '0') /* stv0680 bayer */
+ #define V4L2_PIX_FMT_TM6000 v4l2_fourcc('T', 'M', '6', '0') /* tm5600/tm60x0 */
+ #define V4L2_PIX_FMT_CIT_YYVYUY v4l2_fourcc('C', 'I', 'T', 'V') /* one line of Y then 1 line of VYUY */
+ #define V4L2_PIX_FMT_KONICA420 v4l2_fourcc('K', 'O', 'N', 'I') /* YUV420 planar in blocks of 256 pixels */
+ #define V4L2_PIX_FMT_JPGL v4l2_fourcc('J', 'P', 'G', 'L') /* JPEG-Lite */
+ #define V4L2_PIX_FMT_SE401 v4l2_fourcc('S', '4', '0', '1') /* se401 janggu compressed rgb */
+ #define V4L2_PIX_FMT_S5C_UYVY_JPG v4l2_fourcc('S', '5', 'C', 'I') /* S5C73M3 interleaved UYVY/JPEG */
+ #define V4L2_PIX_FMT_Y8I v4l2_fourcc('Y', '8', 'I', ' ') /* Greyscale 8-bit L/R interleaved */
+ #define V4L2_PIX_FMT_Y12I v4l2_fourcc('Y', '1', '2', 'I') /* Greyscale 12-bit L/R interleaved */
+ #define V4L2_PIX_FMT_Z16 v4l2_fourcc('Z', '1', '6', ' ') /* Depth data 16-bit */
+
+ /* SDR formats - used only for Software Defined Radio devices */
+ #define V4L2_SDR_FMT_CU8 v4l2_fourcc('C', 'U', '0', '8') /* IQ u8 */
+ #define V4L2_SDR_FMT_CU16LE v4l2_fourcc('C', 'U', '1', '6') /* IQ u16le */
+ #define V4L2_SDR_FMT_CS8 v4l2_fourcc('C', 'S', '0', '8') /* complex s8 */
+ #define V4L2_SDR_FMT_CS14LE v4l2_fourcc('C', 'S', '1', '4') /* complex s14le */
+ #define V4L2_SDR_FMT_RU12LE v4l2_fourcc('R', 'U', '1', '2') /* real u12le */
+
+ /* priv field value to indicates that subsequent fields are valid. */
+ #define V4L2_PIX_FMT_PRIV_MAGIC 0xfeedcafe
+
+ /* Flags */
+ #define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA 0x00000001
+
+ /*
+ * F O R M A T E N U M E R A T I O N
+ */
+ struct v4l2_fmtdesc {
+ __u32 index; /* Format number */
+ __u32 type; /* enum v4l2_buf_type */
+ __u32 flags;
+ __u8 description[32]; /* Description string */
+ __u32 pixelformat; /* Format fourcc */
+ __u32 reserved[4];
+ };
+
+ #define V4L2_FMT_FLAG_COMPRESSED 0x0001
+ #define V4L2_FMT_FLAG_EMULATED 0x0002
+
+ /* Frame Size and frame rate enumeration */
+ /*
+ * F R A M E S I Z E E N U M E R A T I O N
+ */
+ enum v4l2_frmsizetypes {
+ V4L2_FRMSIZE_TYPE_DISCRETE = 1,
+ V4L2_FRMSIZE_TYPE_CONTINUOUS = 2,
+ V4L2_FRMSIZE_TYPE_STEPWISE = 3,
+ };
+
+ struct v4l2_frmsize_discrete {
+ __u32 width; /* Frame width [pixel] */
+ __u32 height; /* Frame height [pixel] */
+ };
+
+ struct v4l2_frmsize_stepwise {
+ __u32 min_width; /* Minimum frame width [pixel] */
+ __u32 max_width; /* Maximum frame width [pixel] */
+ __u32 step_width; /* Frame width step size [pixel] */
+ __u32 min_height; /* Minimum frame height [pixel] */
+ __u32 max_height; /* Maximum frame height [pixel] */
+ __u32 step_height; /* Frame height step size [pixel] */
+ };
+
+ struct v4l2_frmsizeenum {
+ __u32 index; /* Frame size number */
+ __u32 pixel_format; /* Pixel format */
+ __u32 type; /* Frame size type the device supports. */
+
+ union { /* Frame size */
+ struct v4l2_frmsize_discrete discrete;
+ struct v4l2_frmsize_stepwise stepwise;
+ };
+
+ __u32 reserved[2]; /* Reserved space for future use */
+ };
+
+ /*
+ * F R A M E R A T E E N U M E R A T I O N
+ */
+ enum v4l2_frmivaltypes {
+ V4L2_FRMIVAL_TYPE_DISCRETE = 1,
+ V4L2_FRMIVAL_TYPE_CONTINUOUS = 2,
+ V4L2_FRMIVAL_TYPE_STEPWISE = 3,
+ };
+
+ struct v4l2_frmival_stepwise {
+ struct v4l2_fract min; /* Minimum frame interval [s] */
+ struct v4l2_fract max; /* Maximum frame interval [s] */
+ struct v4l2_fract step; /* Frame interval step size [s] */
+ };
+
+ struct v4l2_frmivalenum {
+ __u32 index; /* Frame format index */
+ __u32 pixel_format; /* Pixel format */
+ __u32 width; /* Frame width */
+ __u32 height; /* Frame height */
+ __u32 type; /* Frame interval type the device supports. */
+
+ union { /* Frame interval */
+ struct v4l2_fract discrete;
+ struct v4l2_frmival_stepwise stepwise;
+ };
+
+ __u32 reserved[2]; /* Reserved space for future use */
+ };
+
+ /*
+ * T I M E C O D E
+ */
+ struct v4l2_timecode {
+ __u32 type;
+ __u32 flags;
+ __u8 frames;
+ __u8 seconds;
+ __u8 minutes;
+ __u8 hours;
+ __u8 userbits[4];
+ };
+
+ /* Type */
+ #define V4L2_TC_TYPE_24FPS 1
+ #define V4L2_TC_TYPE_25FPS 2
+ #define V4L2_TC_TYPE_30FPS 3
+ #define V4L2_TC_TYPE_50FPS 4
+ #define V4L2_TC_TYPE_60FPS 5
+
+ /* Flags */
+ #define V4L2_TC_FLAG_DROPFRAME 0x0001 /* "drop-frame" mode */
+ #define V4L2_TC_FLAG_COLORFRAME 0x0002
+ #define V4L2_TC_USERBITS_field 0x000C
+ #define V4L2_TC_USERBITS_USERDEFINED 0x0000
+ #define V4L2_TC_USERBITS_8BITCHARS 0x0008
+ /* The above is based on SMPTE timecodes */
+
+ struct v4l2_jpegcompression {
+ int quality;
+
+ int APPn; /* Number of APP segment to be written,
+ * must be 0..15 */
+ int APP_len; /* Length of data in JPEG APPn segment */
+ char APP_data[60]; /* Data in the JPEG APPn segment. */
+
+ int COM_len; /* Length of data in JPEG COM segment */
+ char COM_data[60]; /* Data in JPEG COM segment */
+
+ __u32 jpeg_markers; /* Which markers should go into the JPEG
+ * output. Unless you exactly know what
+ * you do, leave them untouched.
+ * Including less markers will make the
+ * resulting code smaller, but there will
+ * be fewer applications which can read it.
+ * The presence of the APP and COM marker
+ * is influenced by APP_len and COM_len
+ * ONLY, not by this property! */
+
+ #define V4L2_JPEG_MARKER_DHT (1<<3) /* Define Huffman Tables */
+ #define V4L2_JPEG_MARKER_DQT (1<<4) /* Define Quantization Tables */
+ #define V4L2_JPEG_MARKER_DRI (1<<5) /* Define Restart Interval */
+ #define V4L2_JPEG_MARKER_COM (1<<6) /* Comment segment */
+ #define V4L2_JPEG_MARKER_APP (1<<7) /* App segment, driver will
+ * always use APP0 */
+ };
+
+ /*
+ * M E M O R Y - M A P P I N G B U F F E R S
+ */
+ struct v4l2_requestbuffers {
+ __u32 count;
+ __u32 type; /* enum v4l2_buf_type */
+ __u32 memory; /* enum v4l2_memory */
+ __u32 reserved[2];
+ };
+
+ /**
+ * struct v4l2_plane - plane info for multi-planar buffers
+ * @bytesused: number of bytes occupied by data in the plane (payload)
+ * @length: size of this plane (NOT the payload) in bytes
+ * @mem_offset: when memory in the associated struct v4l2_buffer is
+ * V4L2_MEMORY_MMAP, equals the offset from the start of
+ * the device memory for this plane (or is a "cookie" that
+ * should be passed to mmap() called on the video node)
+ * @userptr: when memory is V4L2_MEMORY_USERPTR, a userspace pointer
+ * pointing to this plane
+ * @fd: when memory is V4L2_MEMORY_DMABUF, a userspace file
+ * descriptor associated with this plane
+ * @data_offset: offset in the plane to the start of data; usually 0,
+ * unless there is a header in front of the data
+ *
+ * Multi-planar buffers consist of one or more planes, e.g. an YCbCr buffer
+ * with two planes can have one plane for Y, and another for interleaved CbCr
+ * components. Each plane can reside in a separate memory buffer, or even in
+ * a completely separate memory node (e.g. in embedded devices).
+ */
+ struct v4l2_plane {
+ __u32 bytesused;
+ __u32 length;
+ union {
+ __u32 mem_offset;
+ unsigned long userptr;
+ __s32 fd;
+ } m;
+ __u32 data_offset;
+ __u32 reserved[11];
+ };
+
+ /**
+ * struct v4l2_buffer - video buffer info
+ * @index: id number of the buffer
+ * @type: enum v4l2_buf_type; buffer type (type == *_MPLANE for
+ * multiplanar buffers);
+ * @bytesused: number of bytes occupied by data in the buffer (payload);
+ * unused (set to 0) for multiplanar buffers
+ * @flags: buffer informational flags
+ * @field: enum v4l2_field; field order of the image in the buffer
+ * @timestamp: frame timestamp
+ * @timecode: frame timecode
+ * @sequence: sequence count of this frame
+ * @memory: enum v4l2_memory; the method, in which the actual video data is
+ * passed
+ * @offset: for non-multiplanar buffers with memory == V4L2_MEMORY_MMAP;
+ * offset from the start of the device memory for this plane,
+ * (or a "cookie" that should be passed to mmap() as offset)
+ * @userptr: for non-multiplanar buffers with memory == V4L2_MEMORY_USERPTR;
+ * a userspace pointer pointing to this buffer
+ * @fd: for non-multiplanar buffers with memory == V4L2_MEMORY_DMABUF;
+ * a userspace file descriptor associated with this buffer
+ * @planes: for multiplanar buffers; userspace pointer to the array of plane
+ * info structs for this buffer
+ * @length: size in bytes of the buffer (NOT its payload) for single-plane
+ * buffers (when type != *_MPLANE); number of elements in the
+ * planes array for multi-plane buffers
+ *
+ * Contains data exchanged by application and driver using one of the Streaming
+ * I/O methods.
+ */
+ struct v4l2_buffer {
+ __u32 index;
+ __u32 type;
+ __u32 bytesused;
+ __u32 flags;
+ __u32 field;
+ struct timeval timestamp;
+ struct v4l2_timecode timecode;
+ __u32 sequence;
+
+ /* memory location */
+ __u32 memory;
+ union {
+ __u32 offset;
+ unsigned long userptr;
+ struct v4l2_plane *planes;
+ __s32 fd;
+ } m;
+ __u32 length;
+ __u32 reserved2;
+ __u32 reserved;
+ };
+
+ /* Flags for 'flags' field */
+ /* Buffer is mapped (flag) */
+ #define V4L2_BUF_FLAG_MAPPED 0x00000001
+ /* Buffer is queued for processing */
+ #define V4L2_BUF_FLAG_QUEUED 0x00000002
+ /* Buffer is ready */
+ #define V4L2_BUF_FLAG_DONE 0x00000004
+ /* Image is a keyframe (I-frame) */
+ #define V4L2_BUF_FLAG_KEYFRAME 0x00000008
+ /* Image is a P-frame */
+ #define V4L2_BUF_FLAG_PFRAME 0x00000010
+ /* Image is a B-frame */
+ #define V4L2_BUF_FLAG_BFRAME 0x00000020
+ /* Buffer is ready, but the data contained within is corrupted. */
+ #define V4L2_BUF_FLAG_ERROR 0x00000040
+ /* timecode field is valid */
+ #define V4L2_BUF_FLAG_TIMECODE 0x00000100
+ /* Buffer is prepared for queuing */
+ #define V4L2_BUF_FLAG_PREPARED 0x00000400
+ /* Cache handling flags */
+ #define V4L2_BUF_FLAG_NO_CACHE_INVALIDATE 0x00000800
+ #define V4L2_BUF_FLAG_NO_CACHE_CLEAN 0x00001000
+ /* Timestamp type */
+ #define V4L2_BUF_FLAG_TIMESTAMP_MASK 0x0000e000
+ #define V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN 0x00000000
+ #define V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC 0x00002000
+ #define V4L2_BUF_FLAG_TIMESTAMP_COPY 0x00004000
+ /* Timestamp sources. */
+ #define V4L2_BUF_FLAG_TSTAMP_SRC_MASK 0x00070000
+ #define V4L2_BUF_FLAG_TSTAMP_SRC_EOF 0x00000000
+ #define V4L2_BUF_FLAG_TSTAMP_SRC_SOE 0x00010000
+ /* mem2mem encoder/decoder */
+ #define V4L2_BUF_FLAG_LAST 0x00100000
+
+ /**
+ * struct v4l2_exportbuffer - export of video buffer as DMABUF file descriptor
+ *
+ * @index: id number of the buffer
+ * @type: enum v4l2_buf_type; buffer type (type == *_MPLANE for
+ * multiplanar buffers);
+ * @plane: index of the plane to be exported, 0 for single plane queues
+ * @flags: flags for newly created file, currently only O_CLOEXEC is
+ * supported, refer to manual of open syscall for more details
+ * @fd: file descriptor associated with DMABUF (set by driver)
+ *
+ * Contains data used for exporting a video buffer as DMABUF file descriptor.
+ * The buffer is identified by a 'cookie' returned by VIDIOC_QUERYBUF
+ * (identical to the cookie used to mmap() the buffer to userspace). All
+ * reserved fields must be set to zero. The field reserved0 is expected to
+ * become a structure 'type' allowing an alternative layout of the structure
+ * content. Therefore this field should not be used for any other extensions.
+ */
+ struct v4l2_exportbuffer {
+ __u32 type; /* enum v4l2_buf_type */
+ __u32 index;
+ __u32 plane;
+ __u32 flags;
+ __s32 fd;
+ __u32 reserved[11];
+ };
+
+ /*
+ * O V E R L A Y P R E V I E W
+ */
+ struct v4l2_framebuffer {
+ __u32 capability;
+ __u32 flags;
+ /* FIXME: in theory we should pass something like PCI device + memory
+ * region + offset instead of some physical address */
+ void *base;
+ struct {
+ __u32 width;
+ __u32 height;
+ __u32 pixelformat;
+ __u32 field; /* enum v4l2_field */
+ __u32 bytesperline; /* for padding, zero if unused */
+ __u32 sizeimage;
+ __u32 colorspace; /* enum v4l2_colorspace */
+ __u32 priv; /* reserved field, set to 0 */
+ } fmt;
+ };
+ /* Flags for the 'capability' field. Read only */
+ #define V4L2_FBUF_CAP_EXTERNOVERLAY 0x0001
+ #define V4L2_FBUF_CAP_CHROMAKEY 0x0002
+ #define V4L2_FBUF_CAP_LIST_CLIPPING 0x0004
+ #define V4L2_FBUF_CAP_BITMAP_CLIPPING 0x0008
+ #define V4L2_FBUF_CAP_LOCAL_ALPHA 0x0010
+ #define V4L2_FBUF_CAP_GLOBAL_ALPHA 0x0020
+ #define V4L2_FBUF_CAP_LOCAL_INV_ALPHA 0x0040
+ #define V4L2_FBUF_CAP_SRC_CHROMAKEY 0x0080
+ /* Flags for the 'flags' field. */
+ #define V4L2_FBUF_FLAG_PRIMARY 0x0001
+ #define V4L2_FBUF_FLAG_OVERLAY 0x0002
+ #define V4L2_FBUF_FLAG_CHROMAKEY 0x0004
+ #define V4L2_FBUF_FLAG_LOCAL_ALPHA 0x0008
+ #define V4L2_FBUF_FLAG_GLOBAL_ALPHA 0x0010
+ #define V4L2_FBUF_FLAG_LOCAL_INV_ALPHA 0x0020
+ #define V4L2_FBUF_FLAG_SRC_CHROMAKEY 0x0040
+
+ struct v4l2_clip {
+ struct v4l2_rect c;
+ struct v4l2_clip __user *next;
+ };
+
+ struct v4l2_window {
+ struct v4l2_rect w;
+ __u32 field; /* enum v4l2_field */
+ __u32 chromakey;
+ struct v4l2_clip __user *clips;
+ __u32 clipcount;
+ void __user *bitmap;
+ __u8 global_alpha;
+ };
+
+ /*
+ * C A P T U R E P A R A M E T E R S
+ */
+ struct v4l2_captureparm {
+ __u32 capability; /* Supported modes */
+ __u32 capturemode; /* Current mode */
+ struct v4l2_fract timeperframe; /* Time per frame in seconds */
+ __u32 extendedmode; /* Driver-specific extensions */
+ __u32 readbuffers; /* # of buffers for read */
+ __u32 reserved[4];
+ };
+
+ /* Flags for 'capability' and 'capturemode' fields */
+ #define V4L2_MODE_HIGHQUALITY 0x0001 /* High quality imaging mode */
+ #define V4L2_CAP_TIMEPERFRAME 0x1000 /* timeperframe field is supported */
+
+ struct v4l2_outputparm {
+ __u32 capability; /* Supported modes */
+ __u32 outputmode; /* Current mode */
+ struct v4l2_fract timeperframe; /* Time per frame in seconds */
+ __u32 extendedmode; /* Driver-specific extensions */
+ __u32 writebuffers; /* # of buffers for write */
+ __u32 reserved[4];
+ };
+
+ /*
+ * I N P U T I M A G E C R O P P I N G
+ */
+ struct v4l2_cropcap {
+ __u32 type; /* enum v4l2_buf_type */
+ struct v4l2_rect bounds;
+ struct v4l2_rect defrect;
+ struct v4l2_fract pixelaspect;
+ };
+
+ struct v4l2_crop {
+ __u32 type; /* enum v4l2_buf_type */
+ struct v4l2_rect c;
+ };
+
+ /**
+ * struct v4l2_selection - selection info
+ * @type: buffer type (do not use *_MPLANE types)
+ * @target: Selection target, used to choose one of possible rectangles;
+ * defined in v4l2-common.h; V4L2_SEL_TGT_* .
+ * @flags: constraints flags, defined in v4l2-common.h; V4L2_SEL_FLAG_*.
+ * @r: coordinates of selection window
+ * @reserved: for future use, rounds structure size to 64 bytes, set to zero
+ *
+ * Hardware may use multiple helper windows to process a video stream.
+ * The structure is used to exchange this selection areas between
+ * an application and a driver.
+ */
+ struct v4l2_selection {
+ __u32 type;
+ __u32 target;
+ __u32 flags;
+ struct v4l2_rect r;
+ __u32 reserved[9];
+ };
+
+
+ /*
+ * A N A L O G V I D E O S T A N D A R D
+ */
+
+ typedef __u64 v4l2_std_id;
+
+ /* one bit for each */
+ #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
+ #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
+ #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
+ #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
+ #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
+ #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
+ #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
+ #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
+
+ #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
+ #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
+ #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
+ #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
+
+ #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) /* BTSC */
+ #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) /* EIA-J */
+ #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
+ #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) /* FM A2 */
+
+ #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
+ #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
+ #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
+ #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
+ #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
+ #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
+ #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
+ #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
+
+ /* ATSC/HDTV */
+ #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
+ #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
+
+ /* FIXME:
+ Although std_id is 64 bits, there is an issue on PPC32 architecture that
+ makes switch(__u64) to break. So, there's a hack on v4l2-common.c rounding
+ this value to 32 bits.
+ As, currently, the max value is for V4L2_STD_ATSC_16_VSB (30 bits wide),
+ it should work fine. However, if needed to add more than two standards,
+ v4l2-common.c should be fixed.
+ */
+
+ /*
+ * Some macros to merge video standards in order to make live easier for the
+ * drivers and V4L2 applications
+ */
+
+ /*
+ * "Common" NTSC/M - It should be noticed that V4L2_STD_NTSC_443 is
+ * Missing here.
+ */
+ #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |
+ V4L2_STD_NTSC_M_JP |
+ V4L2_STD_NTSC_M_KR)
+ /* Secam macros */
+ #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |
+ V4L2_STD_SECAM_K |
+ V4L2_STD_SECAM_K1)
+ /* All Secam Standards */
+ #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |
+ V4L2_STD_SECAM_G |
+ V4L2_STD_SECAM_H |
+ V4L2_STD_SECAM_DK |
+ V4L2_STD_SECAM_L |
+ V4L2_STD_SECAM_LC)
+ /* PAL macros */
+ #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |
+ V4L2_STD_PAL_B1 |
+ V4L2_STD_PAL_G)
+ #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |
+ V4L2_STD_PAL_D1 |
+ V4L2_STD_PAL_K)
+ /*
+ * "Common" PAL - This macro is there to be compatible with the old
+ * V4L1 concept of "PAL": /BGDKHI.
+ * Several PAL standards are missing here: /M, /N and /Nc
+ */
+ #define V4L2_STD_PAL (V4L2_STD_PAL_BG |
+ V4L2_STD_PAL_DK |
+ V4L2_STD_PAL_H |
+ V4L2_STD_PAL_I)
+ /* Chroma "agnostic" standards */
+ #define V4L2_STD_B (V4L2_STD_PAL_B |
+ V4L2_STD_PAL_B1 |
+ V4L2_STD_SECAM_B)
+ #define V4L2_STD_G (V4L2_STD_PAL_G |
+ V4L2_STD_SECAM_G)
+ #define V4L2_STD_H (V4L2_STD_PAL_H |
+ V4L2_STD_SECAM_H)
+ #define V4L2_STD_L (V4L2_STD_SECAM_L |
+ V4L2_STD_SECAM_LC)
+ #define V4L2_STD_GH (V4L2_STD_G |
+ V4L2_STD_H)
+ #define V4L2_STD_DK (V4L2_STD_PAL_DK |
+ V4L2_STD_SECAM_DK)
+ #define V4L2_STD_BG (V4L2_STD_B |
+ V4L2_STD_G)
+ #define V4L2_STD_MN (V4L2_STD_PAL_M |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc |
+ V4L2_STD_NTSC)
+
+ /* Standards where MTS/BTSC stereo could be found */
+ #define V4L2_STD_MTS (V4L2_STD_NTSC_M |
+ V4L2_STD_PAL_M |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc)
+
+ /* Standards for Countries with 60Hz Line frequency */
+ #define V4L2_STD_525_60 (V4L2_STD_PAL_M |
+ V4L2_STD_PAL_60 |
+ V4L2_STD_NTSC |
+ V4L2_STD_NTSC_443)
+ /* Standards for Countries with 50Hz Line frequency */
+ #define V4L2_STD_625_50 (V4L2_STD_PAL |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc |
+ V4L2_STD_SECAM)
+
+ #define V4L2_STD_ATSC (V4L2_STD_ATSC_8_VSB |
+ V4L2_STD_ATSC_16_VSB)
+ /* Macros with none and all analog standards */
+ #define V4L2_STD_UNKNOWN 0
+ #define V4L2_STD_ALL (V4L2_STD_525_60 |
+ V4L2_STD_625_50)
+
+ struct v4l2_standard {
+ __u32 index;
+ v4l2_std_id id;
+ __u8 name[24];
+ struct v4l2_fract frameperiod; /* Frames, not fields */
+ __u32 framelines;
+ __u32 reserved[4];
+ };
+
+ /*
+ * D V B T T I M I N G S
+ */
+
+ /** struct v4l2_bt_timings - BT.656/BT.1120 timing data
+ * @width: total width of the active video in pixels
+ * @height: total height of the active video in lines
+ * @interlaced: Interlaced or progressive
+ * @polarities: Positive or negative polarities
+ * @pixelclock: Pixel clock in HZ. Ex. 74.25MHz->74250000
+ * @hfrontporch:Horizontal front porch in pixels
+ * @hsync: Horizontal Sync length in pixels
+ * @hbackporch: Horizontal back porch in pixels
+ * @vfrontporch:Vertical front porch in lines
+ * @vsync: Vertical Sync length in lines
+ * @vbackporch: Vertical back porch in lines
+ * @il_vfrontporch:Vertical front porch for the even field
+ * (aka field 2) of interlaced field formats
+ * @il_vsync: Vertical Sync length for the even field
+ * (aka field 2) of interlaced field formats
+ * @il_vbackporch:Vertical back porch for the even field
+ * (aka field 2) of interlaced field formats
+ * @standards: Standards the timing belongs to
+ * @flags: Flags
+ * @reserved: Reserved fields, must be zeroed.
+ *
+ * A note regarding vertical interlaced timings: height refers to the total
+ * height of the active video frame (= two fields). The blanking timings refer
+ * to the blanking of each field. So the height of the total frame is
+ * calculated as follows:
+ *
+ * tot_height = height + vfrontporch + vsync + vbackporch +
+ * il_vfrontporch + il_vsync + il_vbackporch
+ *
+ * The active height of each field is height / 2.
+ */
+ struct v4l2_bt_timings {
+ __u32 width;
+ __u32 height;
+ __u32 interlaced;
+ __u32 polarities;
+ __u64 pixelclock;
+ __u32 hfrontporch;
+ __u32 hsync;
+ __u32 hbackporch;
+ __u32 vfrontporch;
+ __u32 vsync;
+ __u32 vbackporch;
+ __u32 il_vfrontporch;
+ __u32 il_vsync;
+ __u32 il_vbackporch;
+ __u32 standards;
+ __u32 flags;
+ __u32 reserved[14];
+ } __attribute__ ((packed));
+
+ /* Interlaced or progressive format */
+ #define V4L2_DV_PROGRESSIVE 0
+ #define V4L2_DV_INTERLACED 1
+
+ /* Polarities. If bit is not set, it is assumed to be negative polarity */
+ #define V4L2_DV_VSYNC_POS_POL 0x00000001
+ #define V4L2_DV_HSYNC_POS_POL 0x00000002
+
+ /* Timings standards */
+ #define V4L2_DV_BT_STD_CEA861 (1 << 0) /* CEA-861 Digital TV Profile */
+ #define V4L2_DV_BT_STD_DMT (1 << 1) /* VESA Discrete Monitor Timings */
+ #define V4L2_DV_BT_STD_CVT (1 << 2) /* VESA Coordinated Video Timings */
+ #define V4L2_DV_BT_STD_GTF (1 << 3) /* VESA Generalized Timings Formula */
+
+ /* Flags */
+
+ /* CVT/GTF specific: timing uses reduced blanking (CVT) or the 'Secondary
+ GTF' curve (GTF). In both cases the horizontal and/or vertical blanking
+ intervals are reduced, allowing a higher resolution over the same
+ bandwidth. This is a read-only flag. */
+ #define V4L2_DV_FL_REDUCED_BLANKING (1 << 0)
+ /* CEA-861 specific: set for CEA-861 formats with a framerate of a multiple
+ of six. These formats can be optionally played at 1 / 1.001 speed.
+ This is a read-only flag. */
+ #define V4L2_DV_FL_CAN_REDUCE_FPS (1 << 1)
+ /* CEA-861 specific: only valid for video transmitters, the flag is cleared
+ by receivers.
+ If the framerate of the format is a multiple of six, then the pixelclock
+ used to set up the transmitter is divided by 1.001 to make it compatible
+ with 60 Hz based standards such as NTSC and PAL-M that use a framerate of
+ 29.97 Hz. Otherwise this flag is cleared. If the transmitter can't generate
+ such frequencies, then the flag will also be cleared. */
+ #define V4L2_DV_FL_REDUCED_FPS (1 << 2)
+ /* Specific to interlaced formats: if set, then field 1 is really one half-line
+ longer and field 2 is really one half-line shorter, so each field has
+ exactly the same number of half-lines. Whether half-lines can be detected
+ or used depends on the hardware. */
+ #define V4L2_DV_FL_HALF_LINE (1 << 3)
+ /* If set, then this is a Consumer Electronics (CE) video format. Such formats
+ * differ from other formats (commonly called IT formats) in that if RGB
+ * encoding is used then by default the RGB values use limited range (i.e.ie;
+ * use the range 16-235) as opposed to 0-255. All formats defined in CEA-861
+ * except for the 640x480 format are CE formats. */
+ #define V4L2_DV_FL_IS_CE_VIDEO (1 << 4)
+
+ /* A few useful defines to calculate the total blanking and frame sizes */
+ #define V4L2_DV_BT_BLANKING_WIDTH(bt)
+ ((bt)->hfrontporch + (bt)->hsync + (bt)->hbackporch)
+ #define V4L2_DV_BT_FRAME_WIDTH(bt)
+ ((bt)->width + V4L2_DV_BT_BLANKING_WIDTH(bt))
+ #define V4L2_DV_BT_BLANKING_HEIGHT(bt)
+ ((bt)->vfrontporch + (bt)->vsync + (bt)->vbackporch + \\
+ (bt)->il_vfrontporch + (bt)->il_vsync + (bt)->il_vbackporch)
+ #define V4L2_DV_BT_FRAME_HEIGHT(bt)
+ ((bt)->height + V4L2_DV_BT_BLANKING_HEIGHT(bt))
+
+ /** struct v4l2_dv_timings - DV timings
+ * @type: the type of the timings
+ * @bt: BT656/1120 timings
+ */
+ struct v4l2_dv_timings {
+ __u32 type;
+ union {
+ struct v4l2_bt_timings bt;
+ __u32 reserved[32];
+ };
+ } __attribute__ ((packed));
+
+ /* Values for the type field */
+ #define V4L2_DV_BT_656_1120 0 /* BT.656/1120 timing type */
+
+
+ /** struct v4l2_enum_dv_timings - DV timings enumeration
+ * @index: enumeration index
+ * @pad: the pad number for which to enumerate timings (used with
+ * v4l-subdev nodes only)
+ * @reserved: must be zeroed
+ * @timings: the timings for the given index
+ */
+ struct v4l2_enum_dv_timings {
+ __u32 index;
+ __u32 pad;
+ __u32 reserved[2];
+ struct v4l2_dv_timings timings;
+ };
+
+ /** struct v4l2_bt_timings_cap - BT.656/BT.1120 timing capabilities
+ * @min_width: width in pixels
+ * @max_width: width in pixels
+ * @min_height: height in lines
+ * @max_height: height in lines
+ * @min_pixelclock: Pixel clock in HZ. Ex. 74.25MHz->74250000
+ * @max_pixelclock: Pixel clock in HZ. Ex. 74.25MHz->74250000
+ * @standards: Supported standards
+ * @capabilities: Supported capabilities
+ * @reserved: Must be zeroed
+ */
+ struct v4l2_bt_timings_cap {
+ __u32 min_width;
+ __u32 max_width;
+ __u32 min_height;
+ __u32 max_height;
+ __u64 min_pixelclock;
+ __u64 max_pixelclock;
+ __u32 standards;
+ __u32 capabilities;
+ __u32 reserved[16];
+ } __attribute__ ((packed));
+
+ /* Supports interlaced formats */
+ #define V4L2_DV_BT_CAP_INTERLACED (1 << 0)
+ /* Supports progressive formats */
+ #define V4L2_DV_BT_CAP_PROGRESSIVE (1 << 1)
+ /* Supports CVT/GTF reduced blanking */
+ #define V4L2_DV_BT_CAP_REDUCED_BLANKING (1 << 2)
+ /* Supports custom formats */
+ #define V4L2_DV_BT_CAP_CUSTOM (1 << 3)
+
+ /** struct v4l2_dv_timings_cap - DV timings capabilities
+ * @type: the type of the timings (same as in struct v4l2_dv_timings)
+ * @pad: the pad number for which to query capabilities (used with
+ * v4l-subdev nodes only)
+ * @bt: the BT656/1120 timings capabilities
+ */
+ struct v4l2_dv_timings_cap {
+ __u32 type;
+ __u32 pad;
+ __u32 reserved[2];
+ union {
+ struct v4l2_bt_timings_cap bt;
+ __u32 raw_data[32];
+ };
+ };
+
+
+ /*
+ * V I D E O I N P U T S
+ */
+ struct v4l2_input {
+ __u32 index; /* Which input */
+ __u8 name[32]; /* Label */
+ __u32 type; /* Type of input */
+ __u32 audioset; /* Associated audios (bitfield) */
+ __u32 tuner; /* enum v4l2_tuner_type */
+ v4l2_std_id std;
+ __u32 status;
+ __u32 capabilities;
+ __u32 reserved[3];
+ };
+
+ /* Values for the 'type' field */
+ #define V4L2_INPUT_TYPE_TUNER 1
+ #define V4L2_INPUT_TYPE_CAMERA 2
+
+ /* field 'status' - general */
+ #define V4L2_IN_ST_NO_POWER 0x00000001 /* Attached device is off */
+ #define V4L2_IN_ST_NO_SIGNAL 0x00000002
+ #define V4L2_IN_ST_NO_COLOR 0x00000004
+
+ /* field 'status' - sensor orientation */
+ /* If sensor is mounted upside down set both bits */
+ #define V4L2_IN_ST_HFLIP 0x00000010 /* Frames are flipped horizontally */
+ #define V4L2_IN_ST_VFLIP 0x00000020 /* Frames are flipped vertically */
+
+ /* field 'status' - analog */
+ #define V4L2_IN_ST_NO_H_LOCK 0x00000100 /* No horizontal sync lock */
+ #define V4L2_IN_ST_COLOR_KILL 0x00000200 /* Color killer is active */
+
+ /* field 'status' - digital */
+ #define V4L2_IN_ST_NO_SYNC 0x00010000 /* No synchronization lock */
+ #define V4L2_IN_ST_NO_EQU 0x00020000 /* No equalizer lock */
+ #define V4L2_IN_ST_NO_CARRIER 0x00040000 /* Carrier recovery failed */
+
+ /* field 'status' - VCR and set-top box */
+ #define V4L2_IN_ST_MACROVISION 0x01000000 /* Macrovision detected */
+ #define V4L2_IN_ST_NO_ACCESS 0x02000000 /* Conditional access denied */
+ #define V4L2_IN_ST_VTR 0x04000000 /* VTR time constant */
+
+ /* capabilities flags */
+ #define V4L2_IN_CAP_DV_TIMINGS 0x00000002 /* Supports S_DV_TIMINGS */
+ #define V4L2_IN_CAP_CUSTOM_TIMINGS V4L2_IN_CAP_DV_TIMINGS /* For compatibility */
+ #define V4L2_IN_CAP_STD 0x00000004 /* Supports S_STD */
+ #define V4L2_IN_CAP_NATIVE_SIZE 0x00000008 /* Supports setting native size */
+
+ /*
+ * V I D E O O U T P U T S
+ */
+ struct v4l2_output {
+ __u32 index; /* Which output */
+ __u8 name[32]; /* Label */
+ __u32 type; /* Type of output */
+ __u32 audioset; /* Associated audios (bitfield) */
+ __u32 modulator; /* Associated modulator */
+ v4l2_std_id std;
+ __u32 capabilities;
+ __u32 reserved[3];
+ };
+ /* Values for the 'type' field */
+ #define V4L2_OUTPUT_TYPE_MODULATOR 1
+ #define V4L2_OUTPUT_TYPE_ANALOG 2
+ #define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY 3
+
+ /* capabilities flags */
+ #define V4L2_OUT_CAP_DV_TIMINGS 0x00000002 /* Supports S_DV_TIMINGS */
+ #define V4L2_OUT_CAP_CUSTOM_TIMINGS V4L2_OUT_CAP_DV_TIMINGS /* For compatibility */
+ #define V4L2_OUT_CAP_STD 0x00000004 /* Supports S_STD */
+ #define V4L2_OUT_CAP_NATIVE_SIZE 0x00000008 /* Supports setting native size */
+
+ /*
+ * C O N T R O L S
+ */
+ struct v4l2_control {
+ __u32 id;
+ __s32 value;
+ };
+
+ struct v4l2_ext_control {
+ __u32 id;
+ __u32 size;
+ __u32 reserved2[1];
+ union {
+ __s32 value;
+ __s64 value64;
+ char __user *string;
+ __u8 __user *p_u8;
+ __u16 __user *p_u16;
+ __u32 __user *p_u32;
+ void __user *ptr;
+ };
+ } __attribute__ ((packed));
+
+ struct v4l2_ext_controls {
+ union {
+ #ifndef __KERNEL__
+ __u32 ctrl_class;
+ #endif
+ __u32 which;
+ };
+ __u32 count;
+ __u32 error_idx;
+ __u32 reserved[2];
+ struct v4l2_ext_control *controls;
+ };
+
+ #define V4L2_CTRL_ID_MASK (0x0fffffff)
+ #ifndef __KERNEL__
+ #define V4L2_CTRL_ID2CLASS(id) ((id) & 0x0fff0000UL)
+ #endif
+ #define V4L2_CTRL_ID2WHICH(id) ((id) & 0x0fff0000UL)
+ #define V4L2_CTRL_DRIVER_PRIV(id) (((id) & 0xffff) >= 0x1000)
+ #define V4L2_CTRL_MAX_DIMS (4)
+ #define V4L2_CTRL_WHICH_CUR_VAL 0
+ #define V4L2_CTRL_WHICH_DEF_VAL 0x0f000000
+
+ enum v4l2_ctrl_type {
+ V4L2_CTRL_TYPE_INTEGER = 1,
+ V4L2_CTRL_TYPE_BOOLEAN = 2,
+ V4L2_CTRL_TYPE_MENU = 3,
+ V4L2_CTRL_TYPE_BUTTON = 4,
+ V4L2_CTRL_TYPE_INTEGER64 = 5,
+ V4L2_CTRL_TYPE_CTRL_CLASS = 6,
+ V4L2_CTRL_TYPE_STRING = 7,
+ V4L2_CTRL_TYPE_BITMASK = 8,
+ V4L2_CTRL_TYPE_INTEGER_MENU = 9,
+
+ /* Compound types are >= 0x0100 */
+ V4L2_CTRL_COMPOUND_TYPES = 0x0100,
+ V4L2_CTRL_TYPE_U8 = 0x0100,
+ V4L2_CTRL_TYPE_U16 = 0x0101,
+ V4L2_CTRL_TYPE_U32 = 0x0102,
+ };
+
+ /* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */
+ struct v4l2_queryctrl {
+ __u32 id;
+ __u32 type; /* enum v4l2_ctrl_type */
+ __u8 name[32]; /* Whatever */
+ __s32 minimum; /* Note signedness */
+ __s32 maximum;
+ __s32 step;
+ __s32 default_value;
+ __u32 flags;
+ __u32 reserved[2];
+ };
+
+ /* Used in the VIDIOC_QUERY_EXT_CTRL ioctl for querying extended controls */
+ struct v4l2_query_ext_ctrl {
+ __u32 id;
+ __u32 type;
+ char name[32];
+ __s64 minimum;
+ __s64 maximum;
+ __u64 step;
+ __s64 default_value;
+ __u32 flags;
+ __u32 elem_size;
+ __u32 elems;
+ __u32 nr_of_dims;
+ __u32 dims[V4L2_CTRL_MAX_DIMS];
+ __u32 reserved[32];
+ };
+
+ /* Used in the VIDIOC_QUERYMENU ioctl for querying menu items */
+ struct v4l2_querymenu {
+ __u32 id;
+ __u32 index;
+ union {
+ __u8 name[32]; /* Whatever */
+ __s64 value;
+ };
+ __u32 reserved;
+ } __attribute__ ((packed));
+
+ /* Control flags */
+ #define V4L2_CTRL_FLAG_DISABLED 0x0001
+ #define V4L2_CTRL_FLAG_GRABBED 0x0002
+ #define V4L2_CTRL_FLAG_READ_ONLY 0x0004
+ #define V4L2_CTRL_FLAG_UPDATE 0x0008
+ #define V4L2_CTRL_FLAG_INACTIVE 0x0010
+ #define V4L2_CTRL_FLAG_SLIDER 0x0020
+ #define V4L2_CTRL_FLAG_WRITE_ONLY 0x0040
+ #define V4L2_CTRL_FLAG_VOLATILE 0x0080
+ #define V4L2_CTRL_FLAG_HAS_PAYLOAD 0x0100
+ #define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE 0x0200
+
+ /* Query flags, to be ORed with the control ID */
+ #define V4L2_CTRL_FLAG_NEXT_CTRL 0x80000000
+ #define V4L2_CTRL_FLAG_NEXT_COMPOUND 0x40000000
+
+ /* User-class control IDs defined by V4L2 */
+ #define V4L2_CID_MAX_CTRLS 1024
+ /* IDs reserved for driver specific controls */
+ #define V4L2_CID_PRIVATE_BASE 0x08000000
+
+
+ /*
+ * T U N I N G
+ */
+ struct v4l2_tuner {
+ __u32 index;
+ __u8 name[32];
+ __u32 type; /* enum v4l2_tuner_type */
+ __u32 capability;
+ __u32 rangelow;
+ __u32 rangehigh;
+ __u32 rxsubchans;
+ __u32 audmode;
+ __s32 signal;
+ __s32 afc;
+ __u32 reserved[4];
+ };
+
+ struct v4l2_modulator {
+ __u32 index;
+ __u8 name[32];
+ __u32 capability;
+ __u32 rangelow;
+ __u32 rangehigh;
+ __u32 txsubchans;
+ __u32 type; /* enum v4l2_tuner_type */
+ __u32 reserved[3];
+ };
+
+ /* Flags for the 'capability' field */
+ #define V4L2_TUNER_CAP_LOW 0x0001
+ #define V4L2_TUNER_CAP_NORM 0x0002
+ #define V4L2_TUNER_CAP_HWSEEK_BOUNDED 0x0004
+ #define V4L2_TUNER_CAP_HWSEEK_WRAP 0x0008
+ #define V4L2_TUNER_CAP_STEREO 0x0010
+ #define V4L2_TUNER_CAP_LANG2 0x0020
+ #define V4L2_TUNER_CAP_SAP 0x0020
+ #define V4L2_TUNER_CAP_LANG1 0x0040
+ #define V4L2_TUNER_CAP_RDS 0x0080
+ #define V4L2_TUNER_CAP_RDS_BLOCK_IO 0x0100
+ #define V4L2_TUNER_CAP_RDS_CONTROLS 0x0200
+ #define V4L2_TUNER_CAP_FREQ_BANDS 0x0400
+ #define V4L2_TUNER_CAP_HWSEEK_PROG_LIM 0x0800
+ #define V4L2_TUNER_CAP_1HZ 0x1000
+
+ /* Flags for the 'rxsubchans' field */
+ #define V4L2_TUNER_SUB_MONO 0x0001
+ #define V4L2_TUNER_SUB_STEREO 0x0002
+ #define V4L2_TUNER_SUB_LANG2 0x0004
+ #define V4L2_TUNER_SUB_SAP 0x0004
+ #define V4L2_TUNER_SUB_LANG1 0x0008
+ #define V4L2_TUNER_SUB_RDS 0x0010
+
+ /* Values for the 'audmode' field */
+ #define V4L2_TUNER_MODE_MONO 0x0000
+ #define V4L2_TUNER_MODE_STEREO 0x0001
+ #define V4L2_TUNER_MODE_LANG2 0x0002
+ #define V4L2_TUNER_MODE_SAP 0x0002
+ #define V4L2_TUNER_MODE_LANG1 0x0003
+ #define V4L2_TUNER_MODE_LANG1_LANG2 0x0004
+
+ struct v4l2_frequency {
+ __u32 tuner;
+ __u32 type; /* enum v4l2_tuner_type */
+ __u32 frequency;
+ __u32 reserved[8];
+ };
+
+ #define V4L2_BAND_MODULATION_VSB (1 << 1)
+ #define V4L2_BAND_MODULATION_FM (1 << 2)
+ #define V4L2_BAND_MODULATION_AM (1 << 3)
+
+ struct v4l2_frequency_band {
+ __u32 tuner;
+ __u32 type; /* enum v4l2_tuner_type */
+ __u32 index;
+ __u32 capability;
+ __u32 rangelow;
+ __u32 rangehigh;
+ __u32 modulation;
+ __u32 reserved[9];
+ };
+
+ struct v4l2_hw_freq_seek {
+ __u32 tuner;
+ __u32 type; /* enum v4l2_tuner_type */
+ __u32 seek_upward;
+ __u32 wrap_around;
+ __u32 spacing;
+ __u32 rangelow;
+ __u32 rangehigh;
+ __u32 reserved[5];
+ };
+
+ /*
+ * R D S
+ */
+
+ struct v4l2_rds_data {
+ __u8 lsb;
+ __u8 msb;
+ __u8 block;
+ } __attribute__ ((packed));
+
+ #define V4L2_RDS_BLOCK_MSK 0x7
+ #define V4L2_RDS_BLOCK_A 0
+ #define V4L2_RDS_BLOCK_B 1
+ #define V4L2_RDS_BLOCK_C 2
+ #define V4L2_RDS_BLOCK_D 3
+ #define V4L2_RDS_BLOCK_C_ALT 4
+ #define V4L2_RDS_BLOCK_INVALID 7
+
+ #define V4L2_RDS_BLOCK_CORRECTED 0x40
+ #define V4L2_RDS_BLOCK_ERROR 0x80
+
+ /*
+ * A U D I O
+ */
+ struct v4l2_audio {
+ __u32 index;
+ __u8 name[32];
+ __u32 capability;
+ __u32 mode;
+ __u32 reserved[2];
+ };
+
+ /* Flags for the 'capability' field */
+ #define V4L2_AUDCAP_STEREO 0x00001
+ #define V4L2_AUDCAP_AVL 0x00002
+
+ /* Flags for the 'mode' field */
+ #define V4L2_AUDMODE_AVL 0x00001
+
+ struct v4l2_audioout {
+ __u32 index;
+ __u8 name[32];
+ __u32 capability;
+ __u32 mode;
+ __u32 reserved[2];
+ };
+
+ /*
+ * M P E G S E R V I C E S
+ */
+ #if 1
+ #define V4L2_ENC_IDX_FRAME_I (0)
+ #define V4L2_ENC_IDX_FRAME_P (1)
+ #define V4L2_ENC_IDX_FRAME_B (2)
+ #define V4L2_ENC_IDX_FRAME_MASK (0xf)
+
+ struct v4l2_enc_idx_entry {
+ __u64 offset;
+ __u64 pts;
+ __u32 length;
+ __u32 flags;
+ __u32 reserved[2];
+ };
+
+ #define V4L2_ENC_IDX_ENTRIES (64)
+ struct v4l2_enc_idx {
+ __u32 entries;
+ __u32 entries_cap;
+ __u32 reserved[4];
+ struct v4l2_enc_idx_entry entry[V4L2_ENC_IDX_ENTRIES];
+ };
+
+
+ #define V4L2_ENC_CMD_START (0)
+ #define V4L2_ENC_CMD_STOP (1)
+ #define V4L2_ENC_CMD_PAUSE (2)
+ #define V4L2_ENC_CMD_RESUME (3)
+
+ /* Flags for V4L2_ENC_CMD_STOP */
+ #define V4L2_ENC_CMD_STOP_AT_GOP_END (1 << 0)
+
+ struct v4l2_encoder_cmd {
+ __u32 cmd;
+ __u32 flags;
+ union {
+ struct {
+ __u32 data[8];
+ } raw;
+ };
+ };
+
+ /* Decoder commands */
+ #define V4L2_DEC_CMD_START (0)
+ #define V4L2_DEC_CMD_STOP (1)
+ #define V4L2_DEC_CMD_PAUSE (2)
+ #define V4L2_DEC_CMD_RESUME (3)
+
+ /* Flags for V4L2_DEC_CMD_START */
+ #define V4L2_DEC_CMD_START_MUTE_AUDIO (1 << 0)
+
+ /* Flags for V4L2_DEC_CMD_PAUSE */
+ #define V4L2_DEC_CMD_PAUSE_TO_BLACK (1 << 0)
+
+ /* Flags for V4L2_DEC_CMD_STOP */
+ #define V4L2_DEC_CMD_STOP_TO_BLACK (1 << 0)
+ #define V4L2_DEC_CMD_STOP_IMMEDIATELY (1 << 1)
+
+ /* Play format requirements (returned by the driver): */
+
+ /* The decoder has no special format requirements */
+ #define V4L2_DEC_START_FMT_NONE (0)
+ /* The decoder requires full GOPs */
+ #define V4L2_DEC_START_FMT_GOP (1)
+
+ /* The structure must be zeroed before use by the application
+ This ensures it can be extended safely in the future. */
+ struct v4l2_decoder_cmd {
+ __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;
+ } start;
+
+ struct {
+ __u32 data[16];
+ } raw;
+ };
+ };
+ #endif
+
+
+ /*
+ * D A T A S E R V I C E S ( V B I )
+ *
+ * Data services API by Michael Schimek
+ */
+
+ /* Raw VBI */
+ struct v4l2_vbi_format {
+ __u32 sampling_rate; /* in 1 Hz */
+ __u32 offset;
+ __u32 samples_per_line;
+ __u32 sample_format; /* V4L2_PIX_FMT_* */
+ __s32 start[2];
+ __u32 count[2];
+ __u32 flags; /* V4L2_VBI_* */
+ __u32 reserved[2]; /* must be zero */
+ };
+
+ /* VBI flags */
+ #define V4L2_VBI_UNSYNC (1 << 0)
+ #define V4L2_VBI_INTERLACED (1 << 1)
+
+ /* ITU-R start lines for each field */
+ #define V4L2_VBI_ITU_525_F1_START (1)
+ #define V4L2_VBI_ITU_525_F2_START (264)
+ #define V4L2_VBI_ITU_625_F1_START (1)
+ #define V4L2_VBI_ITU_625_F2_START (314)
+
+ /* Sliced VBI
+ *
+ * This implements is a proposal V4L2 API to allow SLICED VBI
+ * required for some hardware encoders. It should change without
+ * notice in the definitive implementation.
+ */
+
+ struct v4l2_sliced_vbi_format {
+ __u16 service_set;
+ /* service_lines[0][...] specifies lines 0-23 (1-23 used) of the first field
+ service_lines[1][...] specifies lines 0-23 (1-23 used) of the second field
+ (equals frame lines 313-336 for 625 line video
+ standards, 263-286 for 525 line standards) */
+ __u16 service_lines[2][24];
+ __u32 io_size;
+ __u32 reserved[2]; /* must be zero */
+ };
+
+ /* Teletext World System Teletext
+ (WST), defined on ITU-R BT.653-2 */
+ #define V4L2_SLICED_TELETEXT_B (0x0001)
+ /* Video Program System, defined on ETS 300 231*/
+ #define V4L2_SLICED_VPS (0x0400)
+ /* Closed Caption, defined on EIA-608 */
+ #define V4L2_SLICED_CAPTION_525 (0x1000)
+ /* Wide Screen System, defined on ITU-R BT1119.1 */
+ #define V4L2_SLICED_WSS_625 (0x4000)
+
+ #define V4L2_SLICED_VBI_525 (V4L2_SLICED_CAPTION_525)
+ #define V4L2_SLICED_VBI_625 (V4L2_SLICED_TELETEXT_B | V4L2_SLICED_VPS | V4L2_SLICED_WSS_625)
+
+ struct v4l2_sliced_vbi_cap {
+ __u16 service_set;
+ /* service_lines[0][...] specifies lines 0-23 (1-23 used) of the first field
+ service_lines[1][...] specifies lines 0-23 (1-23 used) of the second field
+ (equals frame lines 313-336 for 625 line video
+ standards, 263-286 for 525 line standards) */
+ __u16 service_lines[2][24];
+ __u32 type; /* enum v4l2_buf_type */
+ __u32 reserved[3]; /* must be 0 */
+ };
+
+ struct v4l2_sliced_vbi_data {
+ __u32 id;
+ __u32 field; /* 0: first field, 1: second field */
+ __u32 line; /* 1-23 */
+ __u32 reserved; /* must be 0 */
+ __u8 data[48];
+ };
+
+ /*
+ * Sliced VBI data inserted into MPEG Streams
+ */
+
+ /*
+ * V4L2_MPEG_STREAM_VBI_FMT_IVTV:
+ *
+ * Structure of payload contained in an MPEG 2 Private Stream 1 PES Packet in an
+ * MPEG-2 Program Pack that contains V4L2_MPEG_STREAM_VBI_FMT_IVTV Sliced VBI
+ * data
+ *
+ * Note, the MPEG-2 Program Pack and Private Stream 1 PES packet header
+ * definitions are not included here. See the MPEG-2 specifications for details
+ * on these headers.
+ */
+
+ /* Line type IDs */
+ #define V4L2_MPEG_VBI_IVTV_TELETEXT_B (1)
+ #define V4L2_MPEG_VBI_IVTV_CAPTION_525 (4)
+ #define V4L2_MPEG_VBI_IVTV_WSS_625 (5)
+ #define V4L2_MPEG_VBI_IVTV_VPS (7)
+
+ struct v4l2_mpeg_vbi_itv0_line {
+ __u8 id; /* One of V4L2_MPEG_VBI_IVTV_* above */
+ __u8 data[42]; /* Sliced VBI data for the line */
+ } __attribute__ ((packed));
+
+ struct v4l2_mpeg_vbi_itv0 {
+ __le32 linemask[2]; /* Bitmasks of VBI service lines present */
+ struct v4l2_mpeg_vbi_itv0_line line[35];
+ } __attribute__ ((packed));
+
+ struct v4l2_mpeg_vbi_ITV0 {
+ struct v4l2_mpeg_vbi_itv0_line line[36];
+ } __attribute__ ((packed));
+
+ #define V4L2_MPEG_VBI_IVTV_MAGIC0 "itv0"
+ #define V4L2_MPEG_VBI_IVTV_MAGIC1 "ITV0"
+
+ struct v4l2_mpeg_vbi_fmt_ivtv {
+ __u8 magic[4];
+ union {
+ struct v4l2_mpeg_vbi_itv0 itv0;
+ struct v4l2_mpeg_vbi_ITV0 ITV0;
+ };
+ } __attribute__ ((packed));
+
+ /*
+ * A G G R E G A T E S T R U C T U R E S
+ */
+
+ /**
+ * struct v4l2_plane_pix_format - additional, per-plane format definition
+ * @sizeimage: maximum size in bytes required for data, for which
+ * this plane will be used
+ * @bytesperline: distance in bytes between the leftmost pixels in two
+ * adjacent lines
+ */
+ struct v4l2_plane_pix_format {
+ __u32 sizeimage;
+ __u32 bytesperline;
+ __u16 reserved[6];
+ } __attribute__ ((packed));
+
+ /**
+ * struct v4l2_pix_format_mplane - multiplanar format definition
+ * @width: image width in pixels
+ * @height: image height in pixels
+ * @pixelformat: little endian four character code (fourcc)
+ * @field: enum v4l2_field; field order (for interlaced video)
+ * @colorspace: enum v4l2_colorspace; supplemental to pixelformat
+ * @plane_fmt: per-plane information
+ * @num_planes: number of planes for this format
+ * @flags: format flags (V4L2_PIX_FMT_FLAG_*)
+ * @ycbcr_enc: enum v4l2_ycbcr_encoding, Y'CbCr encoding
+ * @quantization: enum v4l2_quantization, colorspace quantization
+ * @xfer_func: enum v4l2_xfer_func, colorspace transfer function
+ */
+ struct v4l2_pix_format_mplane {
+ __u32 width;
+ __u32 height;
+ __u32 pixelformat;
+ __u32 field;
+ __u32 colorspace;
+
+ struct v4l2_plane_pix_format plane_fmt[VIDEO_MAX_PLANES];
+ __u8 num_planes;
+ __u8 flags;
+ __u8 ycbcr_enc;
+ __u8 quantization;
+ __u8 xfer_func;
+ __u8 reserved[7];
+ } __attribute__ ((packed));
+
+ /**
+ * struct v4l2_sdr_format - SDR format definition
+ * @pixelformat: little endian four character code (fourcc)
+ * @buffersize: maximum size in bytes required for data
+ */
+ struct v4l2_sdr_format {
+ __u32 pixelformat;
+ __u32 buffersize;
+ __u8 reserved[24];
+ } __attribute__ ((packed));
+
+ /**
+ * struct v4l2_format - stream data format
+ * @type: enum v4l2_buf_type; type of the data stream
+ * @pix: definition of an image format
+ * @pix_mp: definition of a multiplanar image format
+ * @win: definition of an overlaid image
+ * @vbi: raw VBI capture or output parameters
+ * @sliced: sliced VBI capture or output parameters
+ * @raw_data: placeholder for future extensions and custom formats
+ */
+ struct v4l2_format {
+ __u32 type;
+ union {
+ struct v4l2_pix_format pix; /* V4L2_BUF_TYPE_VIDEO_CAPTURE */
+ struct v4l2_pix_format_mplane pix_mp; /* V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE */
+ struct v4l2_window win; /* V4L2_BUF_TYPE_VIDEO_OVERLAY */
+ struct v4l2_vbi_format vbi; /* V4L2_BUF_TYPE_VBI_CAPTURE */
+ struct v4l2_sliced_vbi_format sliced; /* V4L2_BUF_TYPE_SLICED_VBI_CAPTURE */
+ struct v4l2_sdr_format sdr; /* V4L2_BUF_TYPE_SDR_CAPTURE */
+ __u8 raw_data[200]; /* user-defined */
+ } fmt;
+ };
+
+ /* Stream type-dependent parameters
+ */
+ struct v4l2_streamparm {
+ __u32 type; /* enum v4l2_buf_type */
+ union {
+ struct v4l2_captureparm capture;
+ struct v4l2_outputparm output;
+ __u8 raw_data[200]; /* user-defined */
+ } parm;
+ };
+
+ /*
+ * E V E N T S
+ */
+
+ #define V4L2_EVENT_ALL 0
+ #define V4L2_EVENT_VSYNC 1
+ #define V4L2_EVENT_EOS 2
+ #define V4L2_EVENT_CTRL 3
+ #define V4L2_EVENT_FRAME_SYNC 4
+ #define V4L2_EVENT_SOURCE_CHANGE 5
+ #define V4L2_EVENT_MOTION_DET 6
+ #define V4L2_EVENT_PRIVATE_START 0x08000000
+
+ /* Payload for V4L2_EVENT_VSYNC */
+ struct v4l2_event_vsync {
+ /* Can be V4L2_FIELD_ANY, _NONE, _TOP or _BOTTOM */
+ __u8 field;
+ } __attribute__ ((packed));
+
+ /* Payload for V4L2_EVENT_CTRL */
+ #define V4L2_EVENT_CTRL_CH_VALUE (1 << 0)
+ #define V4L2_EVENT_CTRL_CH_FLAGS (1 << 1)
+ #define V4L2_EVENT_CTRL_CH_RANGE (1 << 2)
+
+ struct v4l2_event_ctrl {
+ __u32 changes;
+ __u32 type;
+ union {
+ __s32 value;
+ __s64 value64;
+ };
+ __u32 flags;
+ __s32 minimum;
+ __s32 maximum;
+ __s32 step;
+ __s32 default_value;
+ };
+
+ struct v4l2_event_frame_sync {
+ __u32 frame_sequence;
+ };
+
+ #define V4L2_EVENT_SRC_CH_RESOLUTION (1 << 0)
+
+ struct v4l2_event_src_change {
+ __u32 changes;
+ };
+
+ #define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ (1 << 0)
+
+ /**
+ * struct v4l2_event_motion_det - motion detection event
+ * @flags: if V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ is set, then the
+ * frame_sequence field is valid.
+ * @frame_sequence: the frame sequence number associated with this event.
+ * @region_mask: which regions detected motion.
+ */
+ struct v4l2_event_motion_det {
+ __u32 flags;
+ __u32 frame_sequence;
+ __u32 region_mask;
+ };
+
+ struct v4l2_event {
+ __u32 type;
+ union {
+ struct v4l2_event_vsync vsync;
+ struct v4l2_event_ctrl ctrl;
+ struct v4l2_event_frame_sync frame_sync;
+ struct v4l2_event_src_change src_change;
+ struct v4l2_event_motion_det motion_det;
+ __u8 data[64];
+ } u;
+ __u32 pending;
+ __u32 sequence;
+ struct timespec timestamp;
+ __u32 id;
+ __u32 reserved[8];
+ };
+
+ #define V4L2_EVENT_SUB_FL_SEND_INITIAL (1 << 0)
+ #define V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK (1 << 1)
+
+ struct v4l2_event_subscription {
+ __u32 type;
+ __u32 id;
+ __u32 flags;
+ __u32 reserved[5];
+ };
+
+ /*
+ * A D V A N C E D D E B U G G I N G
+ *
+ * NOTE: EXPERIMENTAL API, NEVER RELY ON THIS IN APPLICATIONS!
+ * FOR DEBUGGING, TESTING AND INTERNAL USE ONLY!
+ */
+
+ /* VIDIOC_DBG_G_REGISTER and VIDIOC_DBG_S_REGISTER */
+
+ #define V4L2_CHIP_MATCH_BRIDGE 0 /* Match against chip ID on the bridge (0 for the bridge) */
+ #define V4L2_CHIP_MATCH_SUBDEV 4 /* Match against subdev index */
+
+ /* The following four defines are no longer in use */
+ #define V4L2_CHIP_MATCH_HOST V4L2_CHIP_MATCH_BRIDGE
+ #define V4L2_CHIP_MATCH_I2C_DRIVER 1 /* Match against I2C driver name */
+ #define V4L2_CHIP_MATCH_I2C_ADDR 2 /* Match against I2C 7-bit address */
+ #define V4L2_CHIP_MATCH_AC97 3 /* Match against ancillary AC97 chip */
+
+ struct v4l2_dbg_match {
+ __u32 type; /* Match type */
+ union { /* Match this chip, meaning determined by type */
+ __u32 addr;
+ char name[32];
+ };
+ } __attribute__ ((packed));
+
+ struct v4l2_dbg_register {
+ struct v4l2_dbg_match match;
+ __u32 size; /* register size in bytes */
+ __u64 reg;
+ __u64 val;
+ } __attribute__ ((packed));
+
+ #define V4L2_CHIP_FL_READABLE (1 << 0)
+ #define V4L2_CHIP_FL_WRITABLE (1 << 1)
+
+ /* VIDIOC_DBG_G_CHIP_INFO */
+ struct v4l2_dbg_chip_info {
+ struct v4l2_dbg_match match;
+ char name[32];
+ __u32 flags;
+ __u32 reserved[32];
+ } __attribute__ ((packed));
+
+ /**
+ * struct v4l2_create_buffers - VIDIOC_CREATE_BUFS argument
+ * @index: on return, index of the first created buffer
+ * @count: entry: number of requested buffers,
+ * return: number of created buffers
+ * @memory: enum v4l2_memory; buffer memory type
+ * @format: frame format, for which buffers are requested
+ * @reserved: future extensions
+ */
+ struct v4l2_create_buffers {
+ __u32 index;
+ __u32 count;
+ __u32 memory;
+ struct v4l2_format format;
+ __u32 reserved[8];
+ };
+
+ /*
+ * I O C T L C O D E S F O R V I D E O D E V I C E S
+ *
+ */
+ #define VIDIOC_QUERYCAP _IOR('V', 0, struct v4l2_capability)
+ #define VIDIOC_RESERVED _IO('V', 1)
+ #define VIDIOC_ENUM_FMT _IOWR('V', 2, struct v4l2_fmtdesc)
+ #define VIDIOC_G_FMT _IOWR('V', 4, struct v4l2_format)
+ #define VIDIOC_S_FMT _IOWR('V', 5, struct v4l2_format)
+ #define VIDIOC_REQBUFS _IOWR('V', 8, struct v4l2_requestbuffers)
+ #define VIDIOC_QUERYBUF _IOWR('V', 9, struct v4l2_buffer)
+ #define VIDIOC_G_FBUF _IOR('V', 10, struct v4l2_framebuffer)
+ #define VIDIOC_S_FBUF _IOW('V', 11, struct v4l2_framebuffer)
+ #define VIDIOC_OVERLAY _IOW('V', 14, int)
+ #define VIDIOC_QBUF _IOWR('V', 15, struct v4l2_buffer)
+ #define VIDIOC_EXPBUF _IOWR('V', 16, struct v4l2_exportbuffer)
+ #define VIDIOC_DQBUF _IOWR('V', 17, struct v4l2_buffer)
+ #define VIDIOC_STREAMON _IOW('V', 18, int)
+ #define VIDIOC_STREAMOFF _IOW('V', 19, int)
+ #define VIDIOC_G_PARM _IOWR('V', 21, struct v4l2_streamparm)
+ #define VIDIOC_S_PARM _IOWR('V', 22, struct v4l2_streamparm)
+ #define VIDIOC_G_STD _IOR('V', 23, v4l2_std_id)
+ #define VIDIOC_S_STD _IOW('V', 24, v4l2_std_id)
+ #define VIDIOC_ENUMSTD _IOWR('V', 25, struct v4l2_standard)
+ #define VIDIOC_ENUMINPUT _IOWR('V', 26, struct v4l2_input)
+ #define VIDIOC_G_CTRL _IOWR('V', 27, struct v4l2_control)
+ #define VIDIOC_S_CTRL _IOWR('V', 28, struct v4l2_control)
+ #define VIDIOC_G_TUNER _IOWR('V', 29, struct v4l2_tuner)
+ #define VIDIOC_S_TUNER _IOW('V', 30, struct v4l2_tuner)
+ #define VIDIOC_G_AUDIO _IOR('V', 33, struct v4l2_audio)
+ #define VIDIOC_S_AUDIO _IOW('V', 34, struct v4l2_audio)
+ #define VIDIOC_QUERYCTRL _IOWR('V', 36, struct v4l2_queryctrl)
+ #define VIDIOC_QUERYMENU _IOWR('V', 37, struct v4l2_querymenu)
+ #define VIDIOC_G_INPUT _IOR('V', 38, int)
+ #define VIDIOC_S_INPUT _IOWR('V', 39, int)
+ #define VIDIOC_G_EDID _IOWR('V', 40, struct v4l2_edid)
+ #define VIDIOC_S_EDID _IOWR('V', 41, struct v4l2_edid)
+ #define VIDIOC_G_OUTPUT _IOR('V', 46, int)
+ #define VIDIOC_S_OUTPUT _IOWR('V', 47, int)
+ #define VIDIOC_ENUMOUTPUT _IOWR('V', 48, struct v4l2_output)
+ #define VIDIOC_G_AUDOUT _IOR('V', 49, struct v4l2_audioout)
+ #define VIDIOC_S_AUDOUT _IOW('V', 50, struct v4l2_audioout)
+ #define VIDIOC_G_MODULATOR _IOWR('V', 54, struct v4l2_modulator)
+ #define VIDIOC_S_MODULATOR _IOW('V', 55, struct v4l2_modulator)
+ #define VIDIOC_G_FREQUENCY _IOWR('V', 56, struct v4l2_frequency)
+ #define VIDIOC_S_FREQUENCY _IOW('V', 57, struct v4l2_frequency)
+ #define VIDIOC_CROPCAP _IOWR('V', 58, struct v4l2_cropcap)
+ #define VIDIOC_G_CROP _IOWR('V', 59, struct v4l2_crop)
+ #define VIDIOC_S_CROP _IOW('V', 60, struct v4l2_crop)
+ #define VIDIOC_G_JPEGCOMP _IOR('V', 61, struct v4l2_jpegcompression)
+ #define VIDIOC_S_JPEGCOMP _IOW('V', 62, struct v4l2_jpegcompression)
+ #define VIDIOC_QUERYSTD _IOR('V', 63, v4l2_std_id)
+ #define VIDIOC_TRY_FMT _IOWR('V', 64, struct v4l2_format)
+ #define VIDIOC_ENUMAUDIO _IOWR('V', 65, struct v4l2_audio)
+ #define VIDIOC_ENUMAUDOUT _IOWR('V', 66, struct v4l2_audioout)
+ #define VIDIOC_G_PRIORITY _IOR('V', 67, __u32) /* enum v4l2_priority */
+ #define VIDIOC_S_PRIORITY _IOW('V', 68, __u32) /* enum v4l2_priority */
+ #define VIDIOC_G_SLICED_VBI_CAP _IOWR('V', 69, struct v4l2_sliced_vbi_cap)
+ #define VIDIOC_LOG_STATUS _IO('V', 70)
+ #define VIDIOC_G_EXT_CTRLS _IOWR('V', 71, struct v4l2_ext_controls)
+ #define VIDIOC_S_EXT_CTRLS _IOWR('V', 72, struct v4l2_ext_controls)
+ #define VIDIOC_TRY_EXT_CTRLS _IOWR('V', 73, struct v4l2_ext_controls)
+ #define VIDIOC_ENUM_FRAMESIZES _IOWR('V', 74, struct v4l2_frmsizeenum)
+ #define VIDIOC_ENUM_FRAMEINTERVALS _IOWR('V', 75, struct v4l2_frmivalenum)
+ #define VIDIOC_G_ENC_INDEX _IOR('V', 76, struct v4l2_enc_idx)
+ #define VIDIOC_ENCODER_CMD _IOWR('V', 77, struct v4l2_encoder_cmd)
+ #define VIDIOC_TRY_ENCODER_CMD _IOWR('V', 78, struct v4l2_encoder_cmd)
+
+ /*
+ * Experimental, meant for debugging, testing and internal use.
+ * Only implemented if CONFIG_VIDEO_ADV_DEBUG is defined.
+ * You must be root to use these ioctls. Never use these in applications!
+ */
+ #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
+ #define VIDIOC_DBG_G_REGISTER _IOWR('V', 80, struct v4l2_dbg_register)
+
+ #define VIDIOC_S_HW_FREQ_SEEK _IOW('V', 82, struct v4l2_hw_freq_seek)
+ #define VIDIOC_S_DV_TIMINGS _IOWR('V', 87, struct v4l2_dv_timings)
+ #define VIDIOC_G_DV_TIMINGS _IOWR('V', 88, struct v4l2_dv_timings)
+ #define VIDIOC_DQEVENT _IOR('V', 89, struct v4l2_event)
+ #define VIDIOC_SUBSCRIBE_EVENT _IOW('V', 90, struct v4l2_event_subscription)
+ #define VIDIOC_UNSUBSCRIBE_EVENT _IOW('V', 91, struct v4l2_event_subscription)
+ #define VIDIOC_CREATE_BUFS _IOWR('V', 92, struct v4l2_create_buffers)
+ #define VIDIOC_PREPARE_BUF _IOWR('V', 93, struct v4l2_buffer)
+ #define VIDIOC_G_SELECTION _IOWR('V', 94, struct v4l2_selection)
+ #define VIDIOC_S_SELECTION _IOWR('V', 95, struct v4l2_selection)
+ #define VIDIOC_DECODER_CMD _IOWR('V', 96, struct v4l2_decoder_cmd)
+ #define VIDIOC_TRY_DECODER_CMD _IOWR('V', 97, struct v4l2_decoder_cmd)
+ #define VIDIOC_ENUM_DV_TIMINGS _IOWR('V', 98, struct v4l2_enum_dv_timings)
+ #define VIDIOC_QUERY_DV_TIMINGS _IOR('V', 99, struct v4l2_dv_timings)
+ #define VIDIOC_DV_TIMINGS_CAP _IOWR('V', 100, struct v4l2_dv_timings_cap)
+ #define VIDIOC_ENUM_FREQ_BANDS _IOWR('V', 101, struct v4l2_frequency_band)
+
+ /*
+ * Experimental, meant for debugging, testing and internal use.
+ * Never use this in applications!
+ */
+ #define VIDIOC_DBG_G_CHIP_INFO _IOWR('V', 102, struct v4l2_dbg_chip_info)
+
+ #define VIDIOC_QUERY_EXT_CTRL _IOWR('V', 103, struct v4l2_query_ext_ctrl)
+
+ /* Reminder: when adding new ioctls please add support for them to
+ drivers/media/v4l2-core/v4l2-compat-ioctl32.c as well! */
+
+ #define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */
+
+ #endif /* _UAPI__LINUX_VIDEODEV2_H */
+
+
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------
projects / GitHub / moto-9609 / android_kernel_motorola_exynos9610.git / commitdiff
