From: Markus Heiser Date: Thu, 30 Jun 2016 13:18:56 +0000 (+0200) Subject: doc-rst: linux_tv DocBook to reST migration (docs-next) X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=5377d91f3e88d5c8da46b1feba78b00d379fb7b6;p=GitHub%2Fmoto-9609%2Fandroid_kernel_motorola_exynos9610.git doc-rst: linux_tv DocBook to reST migration (docs-next) This is the restructuredText (reST) migration of the ``media`` DocBook-XML set from the linux_tv project. Signed-off-by: Markus Heiser Signed-off-by: Mauro Carvalho Chehab --- diff --git a/Documentation/index.rst b/Documentation/index.rst index f92854f01773..8bc7bf4e6041 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -14,6 +14,7 @@ Contents: :maxdepth: 2 kernel-documentation + linux_tv/index Indices and tables ================== diff --git a/Documentation/linux_tv/audio.h.rst b/Documentation/linux_tv/audio.h.rst new file mode 100644 index 000000000000..abf29027f8ea --- /dev/null +++ b/Documentation/linux_tv/audio.h.rst @@ -0,0 +1,153 @@ +.. -*- coding: utf-8; mode: rst -*- + +file: audio.h +============= + +.. code-block:: c + + /* + * audio.h + * + * Copyright (C) 2000 Ralph Metzler + * & Marcus Metzler + * 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 + + 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/ca.h.rst b/Documentation/linux_tv/ca.h.rst new file mode 100644 index 000000000000..b69ce287aa8c --- /dev/null +++ b/Documentation/linux_tv/ca.h.rst @@ -0,0 +1,108 @@ +.. -*- coding: utf-8; mode: rst -*- + +file: ca.h +========== + +.. code-block:: c + + /* + * ca.h + * + * Copyright (C) 2000 Ralph Metzler + * & Marcus Metzler + * 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/conf.py b/Documentation/linux_tv/conf.py new file mode 100644 index 000000000000..8013c921256b --- /dev/null +++ b/Documentation/linux_tv/conf.py @@ -0,0 +1,221 @@ +# -*- 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 +# " v 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 + diff --git a/Documentation/linux_tv/dmx.h.rst b/Documentation/linux_tv/dmx.h.rst new file mode 100644 index 000000000000..9ced07899e57 --- /dev/null +++ b/Documentation/linux_tv/dmx.h.rst @@ -0,0 +1,173 @@ +.. -*- coding: utf-8; mode: rst -*- + +file: dmx.h +=========== + +.. code-block:: c + + /* + * dmx.h + * + * Copyright (C) 2000 Marcus Metzler + * & Ralph Metzler + * 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 + #ifndef __KERNEL__ + #include + #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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/frontend.h.rst b/Documentation/linux_tv/frontend.h.rst new file mode 100644 index 000000000000..1b65b2037778 --- /dev/null +++ b/Documentation/linux_tv/frontend.h.rst @@ -0,0 +1,620 @@ +.. -*- coding: utf-8; mode: rst -*- + +file: frontend.h +================ + +.. code-block:: c + + /* + * frontend.h + * + * Copyright (C) 2000 Marcus Metzler + * Ralph Metzler + * Holger Waechtler + * Andre Draszik + * 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 + + 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/index.rst b/Documentation/linux_tv/index.rst new file mode 100644 index 000000000000..42b3d4520942 --- /dev/null +++ b/Documentation/linux_tv/index.rst @@ -0,0 +1,100 @@ +.. -*- 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 `__. + +For discussing improvements, reporting troubles, sending new drivers, +etc, please mail to: +`Linux Media Mailing List (LMML). `__. + + +.. 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:: + diff --git a/Documentation/linux_tv/media/dvb/FE_DISHNETWORK_SEND_LEGACY_CMD.rst b/Documentation/linux_tv/media/dvb/FE_DISHNETWORK_SEND_LEGACY_CMD.rst new file mode 100644 index 000000000000..f4effaab9a1a --- /dev/null +++ b/Documentation/linux_tv/media/dvb/FE_DISHNETWORK_SEND_LEGACY_CMD.rst @@ -0,0 +1,55 @@ +.. -*- 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 `, +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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/FE_GET_EVENT.rst b/Documentation/linux_tv/media/dvb/FE_GET_EVENT.rst new file mode 100644 index 000000000000..75eab893c184 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/FE_GET_EVENT.rst @@ -0,0 +1,89 @@ +.. -*- 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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/FE_GET_FRONTEND.rst b/Documentation/linux_tv/media/dvb/FE_GET_FRONTEND.rst new file mode 100644 index 000000000000..30c85cf0423c --- /dev/null +++ b/Documentation/linux_tv/media/dvb/FE_GET_FRONTEND.rst @@ -0,0 +1,77 @@ +.. -*- 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 `, 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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/FE_READ_BER.rst b/Documentation/linux_tv/media/dvb/FE_READ_BER.rst new file mode 100644 index 000000000000..e21451886dc2 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/FE_READ_BER.rst @@ -0,0 +1,61 @@ +.. -*- 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 `, +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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/FE_READ_SIGNAL_STRENGTH.rst b/Documentation/linux_tv/media/dvb/FE_READ_SIGNAL_STRENGTH.rst new file mode 100644 index 000000000000..3e34bea21b6c --- /dev/null +++ b/Documentation/linux_tv/media/dvb/FE_READ_SIGNAL_STRENGTH.rst @@ -0,0 +1,64 @@ +.. -*- 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 `, +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 ` + 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/FE_READ_SNR.rst b/Documentation/linux_tv/media/dvb/FE_READ_SNR.rst new file mode 100644 index 000000000000..b8a639706e9e --- /dev/null +++ b/Documentation/linux_tv/media/dvb/FE_READ_SNR.rst @@ -0,0 +1,61 @@ +.. -*- 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 `, +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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/FE_READ_UNCORRECTED_BLOCKS.rst b/Documentation/linux_tv/media/dvb/FE_READ_UNCORRECTED_BLOCKS.rst new file mode 100644 index 000000000000..261eb20ddadf --- /dev/null +++ b/Documentation/linux_tv/media/dvb/FE_READ_UNCORRECTED_BLOCKS.rst @@ -0,0 +1,66 @@ +.. -*- 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 `, +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 ` + 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/FE_SET_FRONTEND.rst b/Documentation/linux_tv/media/dvb/FE_SET_FRONTEND.rst new file mode 100644 index 000000000000..885f9e3ceb59 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/FE_SET_FRONTEND.rst @@ -0,0 +1,84 @@ +.. -*- 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 ` and +FrontendEvent.) If a new :ref:`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 `, 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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/audio.rst b/Documentation/linux_tv/media/dvb/audio.rst new file mode 100644 index 000000000000..d6b6f9edf3b3 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/audio.rst @@ -0,0 +1,37 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/audio_data_types.rst b/Documentation/linux_tv/media/dvb/audio_data_types.rst new file mode 100644 index 000000000000..b3f5aa0ac6e4 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/audio_data_types.rst @@ -0,0 +1,187 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/audio_function_calls.rst b/Documentation/linux_tv/media/dvb/audio_function_calls.rst new file mode 100644 index 000000000000..41a5757ffd72 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/audio_function_calls.rst @@ -0,0 +1,1308 @@ +.. -*- 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 `__). + +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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/audio_h.rst b/Documentation/linux_tv/media/dvb/audio_h.rst new file mode 100644 index 000000000000..09a73a54ab00 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/audio_h.rst @@ -0,0 +1,24 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/ca.rst b/Documentation/linux_tv/media/dvb/ca.rst new file mode 100644 index 000000000000..bb01d93f0256 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/ca.rst @@ -0,0 +1,29 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/ca_data_types.rst b/Documentation/linux_tv/media/dvb/ca_data_types.rst new file mode 100644 index 000000000000..bb0cdfa7c9a6 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/ca_data_types.rst @@ -0,0 +1,121 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/ca_function_calls.rst b/Documentation/linux_tv/media/dvb/ca_function_calls.rst new file mode 100644 index 000000000000..9984b355f48f --- /dev/null +++ b/Documentation/linux_tv/media/dvb/ca_function_calls.rst @@ -0,0 +1,541 @@ +.. -*- 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/ca_h.rst b/Documentation/linux_tv/media/dvb/ca_h.rst new file mode 100644 index 000000000000..229bfbca045b --- /dev/null +++ b/Documentation/linux_tv/media/dvb/ca_h.rst @@ -0,0 +1,24 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/demux.rst b/Documentation/linux_tv/media/dvb/demux.rst new file mode 100644 index 000000000000..3bcee72c68fb --- /dev/null +++ b/Documentation/linux_tv/media/dvb/demux.rst @@ -0,0 +1,29 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dmx_fcalls.rst b/Documentation/linux_tv/media/dvb/dmx_fcalls.rst new file mode 100644 index 000000000000..5982b57f0a3b --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dmx_fcalls.rst @@ -0,0 +1,1013 @@ +.. -*- 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dmx_h.rst b/Documentation/linux_tv/media/dvb/dmx_h.rst new file mode 100644 index 000000000000..19e2691b7eab --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dmx_h.rst @@ -0,0 +1,24 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dmx_types.rst b/Documentation/linux_tv/media/dvb/dmx_types.rst new file mode 100644 index 000000000000..83859366b73e --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dmx_types.rst @@ -0,0 +1,253 @@ +.. -*- 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dtv-fe-stats.rst b/Documentation/linux_tv/media/dvb/dtv-fe-stats.rst new file mode 100644 index 000000000000..17b26fa050f5 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dtv-fe-stats.rst @@ -0,0 +1,28 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dtv-properties.rst b/Documentation/linux_tv/media/dvb/dtv-properties.rst new file mode 100644 index 000000000000..b1b28342d09d --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dtv-properties.rst @@ -0,0 +1,26 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dtv-property.rst b/Documentation/linux_tv/media/dvb/dtv-property.rst new file mode 100644 index 000000000000..4dff00eb610c --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dtv-property.rst @@ -0,0 +1,42 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dtv-stats.rst b/Documentation/linux_tv/media/dvb/dtv-stats.rst new file mode 100644 index 000000000000..e70e5a5283ff --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dtv-stats.rst @@ -0,0 +1,29 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dvb-fe-read-status.rst b/Documentation/linux_tv/media/dvb/dvb-fe-read-status.rst new file mode 100644 index 000000000000..12d8749e9e05 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dvb-fe-read-status.rst @@ -0,0 +1,31 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dvb-fe-read-status: + +*************************************** +Querying frontend status and statistics +*************************************** + +Once :ref:`FE_SET_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 `. + +Signal statistics are provided via +:ref:`FE_GET_PROPERTY `. Please note that several +statistics require the demodulator to be fully locked (e. g. with +FE_HAS_LOCK bit set). See +:ref:`Frontend statistics indicators ` for +more details. + + +.. ------------------------------------------------------------------------------ +.. This file was automatically converted from DocBook-XML with the dbxml +.. library (https://github.com/return42/sphkerneldoc). The origin XML comes +.. from the linux kernel, refer to: +.. +.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dvb-frontend-event.rst b/Documentation/linux_tv/media/dvb/dvb-frontend-event.rst new file mode 100644 index 000000000000..82965e4d7450 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dvb-frontend-event.rst @@ -0,0 +1,26 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dvb-frontend-parameters.rst b/Documentation/linux_tv/media/dvb/dvb-frontend-parameters.rst new file mode 100644 index 000000000000..0a1766f68917 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dvb-frontend-parameters.rst @@ -0,0 +1,130 @@ +.. -*- 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 ` +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 ` +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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dvbapi.rst b/Documentation/linux_tv/media/dvb/dvbapi.rst new file mode 100644 index 000000000000..5e513ac86052 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dvbapi.rst @@ -0,0 +1,95 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dvbproperty-006.rst b/Documentation/linux_tv/media/dvb/dvbproperty-006.rst new file mode 100644 index 000000000000..4b89d607358c --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dvbproperty-006.rst @@ -0,0 +1,21 @@ +.. -*- coding: utf-8; mode: rst -*- + +************** +Property types +************** + +On :ref:`FE_GET_PROPERTY and FE_SET_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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/dvbproperty.rst b/Documentation/linux_tv/media/dvb/dvbproperty.rst new file mode 100644 index 000000000000..a68b17808bc2 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/dvbproperty.rst @@ -0,0 +1,122 @@ +.. -*- 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 `. +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 ` ioctl: + +- :ref:`DTV_DELIVERY_SYSTEM ` = + SYS_DVBC_ANNEX_A + +- :ref:`DTV_FREQUENCY ` = 651000000 + +- :ref:`DTV_MODULATION ` = QAM_256 + +- :ref:`DTV_INVERSION ` = INVERSION_AUTO + +- :ref:`DTV_SYMBOL_RATE ` = 5217000 + +- :ref:`DTV_INNER_FEC ` = FEC_3_4 + +- :ref:`DTV_TUNE ` + +The code that would do the above is: + + +.. code-block:: c + + #include + #include + #include + #include + + 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 `__, 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/examples.rst b/Documentation/linux_tv/media/dvb/examples.rst new file mode 100644 index 000000000000..b3a94dedcd39 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/examples.rst @@ -0,0 +1,391 @@ +.. -*- 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 `__ 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 + #include + #include + #include + #include + #include + #include + #include + + #include + #include + #include + #include + + #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 + #include + #include + #include + #include + #include + #include + #include + + #include + #include + #include + #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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-bandwidth-t.rst b/Documentation/linux_tv/media/dvb/fe-bandwidth-t.rst new file mode 100644 index 000000000000..c6e56aba012a --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-bandwidth-t.rst @@ -0,0 +1,88 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/linux_tv/media/dvb/fe-diseqc-recv-slave-reply.rst new file mode 100644 index 000000000000..309930f9b3cd --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-diseqc-recv-slave-reply.rst @@ -0,0 +1,88 @@ +.. -*- 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() `. + +``request`` + FE_DISEQC_RECV_SLAVE_REPLY + +``argp`` + pointer to struct + :ref:`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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-diseqc-reset-overload.rst b/Documentation/linux_tv/media/dvb/fe-diseqc-reset-overload.rst new file mode 100644 index 000000000000..dc7ae1a02725 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-diseqc-reset-overload.rst @@ -0,0 +1,51 @@ +.. -*- 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() `. + +``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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-diseqc-send-burst.rst b/Documentation/linux_tv/media/dvb/fe-diseqc-send-burst.rst new file mode 100644 index 000000000000..34c787903eb1 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-diseqc-send-burst.rst @@ -0,0 +1,93 @@ +.. -*- 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() `. + +``request`` + FE_DISEQC_SEND_BURST + +``tone`` + pointer to enum :ref:`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. `__ + +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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/linux_tv/media/dvb/fe-diseqc-send-master-cmd.rst new file mode 100644 index 000000000000..974a45f632a6 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-diseqc-send-master-cmd.rst @@ -0,0 +1,78 @@ +.. -*- 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() `. + +``request`` + FE_DISEQC_SEND_MASTER_CMD + +``argp`` + pointer to struct + :ref:`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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/linux_tv/media/dvb/fe-enable-high-lnb-voltage.rst new file mode 100644 index 000000000000..207c65a44120 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-enable-high-lnb-voltage.rst @@ -0,0 +1,58 @@ +.. -*- 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() `. + +``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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-get-info.rst b/Documentation/linux_tv/media/dvb/fe-get-info.rst new file mode 100644 index 000000000000..5ac74c232b12 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-get-info.rst @@ -0,0 +1,434 @@ +.. -*- 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() `. + +``request`` + FE_GET_INFO + +``argp`` + pointer to struct struct + :ref:`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 ` 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 ` + + - 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-get-property.rst b/Documentation/linux_tv/media/dvb/fe-get-property.rst new file mode 100644 index 000000000000..8a6c5de041e8 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-get-property.rst @@ -0,0 +1,75 @@ +.. -*- 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() `. + +``request`` + FE_SET_PROPERTY, FE_GET_PROPERTY + +``argp`` + pointer to struct :ref:`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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-read-status.rst b/Documentation/linux_tv/media/dvb/fe-read-status.rst new file mode 100644 index 000000000000..41396a8f1c3d --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-read-status.rst @@ -0,0 +1,143 @@ +.. -*- 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() `. + +``request`` + FE_READ_STATUS + +``status`` + pointer to a bitmask integer filled with the values defined by enum + :ref:`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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-set-frontend-tune-mode.rst b/Documentation/linux_tv/media/dvb/fe-set-frontend-tune-mode.rst new file mode 100644 index 000000000000..1167d22c2382 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-set-frontend-tune-mode.rst @@ -0,0 +1,60 @@ +.. -*- 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() `. + +``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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-set-tone.rst b/Documentation/linux_tv/media/dvb/fe-set-tone.rst new file mode 100644 index 000000000000..f98c4b3b8760 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-set-tone.rst @@ -0,0 +1,100 @@ +.. -*- 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() `. + +``request`` + FE_SET_TONE + +``tone`` + pointer to enum :ref:`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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-set-voltage.rst b/Documentation/linux_tv/media/dvb/fe-set-voltage.rst new file mode 100644 index 000000000000..eb4ab28b479a --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-set-voltage.rst @@ -0,0 +1,68 @@ +.. -*- 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() `. + +``request`` + FE_SET_VOLTAGE + +``voltage`` + pointer to enum :ref:`fe_sec_voltage ` + + Valid values are described at enum + :ref:`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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe-type-t.rst b/Documentation/linux_tv/media/dvb/fe-type-t.rst new file mode 100644 index 000000000000..49fa8090010b --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe-type-t.rst @@ -0,0 +1,100 @@ +.. -*- 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 ` 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 ` +ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM ` +parameter. + +In the old days, struct :ref:`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 ` instead. + +On devices that support multiple delivery systems, struct +:ref:`dvb_frontend_info `::``fe_type_t`` is +filled with the currently standard, as selected by the last call to +:ref:`FE_SET_PROPERTY ` using the +:ref:`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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/fe_property_parameters.rst b/Documentation/linux_tv/media/dvb/fe_property_parameters.rst new file mode 100644 index 000000000000..cf8514d79a20 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/fe_property_parameters.rst @@ -0,0 +1,1976 @@ +.. -*- 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-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 `: + + +.. _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 `. + + +.. _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 `. + + +.. _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 `. + + +.. _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 `. + + +.. _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 `. + + +.. _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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend-property-cable-systems.rst b/Documentation/linux_tv/media/dvb/frontend-property-cable-systems.rst new file mode 100644 index 000000000000..360966ef50cf --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend-property-cable-systems.rst @@ -0,0 +1,84 @@ +.. -*- 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 ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_SYMBOL_RATE ` + +- :ref:`DTV_INNER_FEC ` + +- :ref:`DTV_LNA ` + +In addition, the :ref:`DTV QoS statistics ` +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 ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_LNA ` + +In addition, the :ref:`DTV QoS statistics ` +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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend-property-satellite-systems.rst b/Documentation/linux_tv/media/dvb/frontend-property-satellite-systems.rst new file mode 100644 index 000000000000..1a204ac01afd --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend-property-satellite-systems.rst @@ -0,0 +1,112 @@ +.. -*- 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 ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_SYMBOL_RATE ` + +- :ref:`DTV_INNER_FEC ` + +- :ref:`DTV_VOLTAGE ` + +- :ref:`DTV_TONE ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + +Future implementations might add those two missing parameters: + +- :ref:`DTV_DISEQC_MASTER ` + +- :ref:`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 ` + +- :ref:`DTV_PILOT ` + +- :ref:`DTV_ROLLOFF ` + +- :ref:`DTV_STREAM_ID ` + +In addition, the :ref:`DTV QoS statistics ` +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 ` + + +.. _isdbs-params: + +ISDB-S delivery system +====================== + +The following parameters are valid for ISDB-S: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_SYMBOL_RATE ` + +- :ref:`DTV_INNER_FEC ` + +- :ref:`DTV_VOLTAGE ` + +- :ref:`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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend-property-terrestrial-systems.rst b/Documentation/linux_tv/media/dvb/frontend-property-terrestrial-systems.rst new file mode 100644 index 000000000000..78026596f46f --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend-property-terrestrial-systems.rst @@ -0,0 +1,303 @@ +.. -*- 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 ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_CODE_RATE_HP ` + +- :ref:`DTV_CODE_RATE_LP ` + +- :ref:`DTV_GUARD_INTERVAL ` + +- :ref:`DTV_TRANSMISSION_MODE ` + +- :ref:`DTV_HIERARCHY ` + +- :ref:`DTV_LNA ` + +In addition, the :ref:`DTV QoS statistics ` +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 ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_CODE_RATE_HP ` + +- :ref:`DTV_CODE_RATE_LP ` + +- :ref:`DTV_GUARD_INTERVAL ` + +- :ref:`DTV_TRANSMISSION_MODE ` + +- :ref:`DTV_HIERARCHY ` + +- :ref:`DTV_STREAM_ID ` + +- :ref:`DTV_LNA ` + +In addition, the :ref:`DTV QoS statistics ` +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 ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_GUARD_INTERVAL ` + +- :ref:`DTV_TRANSMISSION_MODE ` + +- :ref:`DTV_ISDBT_LAYER_ENABLED ` + +- :ref:`DTV_ISDBT_PARTIAL_RECEPTION ` + +- :ref:`DTV_ISDBT_SOUND_BROADCASTING ` + +- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID ` + +- :ref:`DTV_ISDBT_SB_SEGMENT_IDX ` + +- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT ` + +- :ref:`DTV_ISDBT_LAYERA_FEC ` + +- :ref:`DTV_ISDBT_LAYERA_MODULATION ` + +- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT ` + +- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING ` + +- :ref:`DTV_ISDBT_LAYERB_FEC ` + +- :ref:`DTV_ISDBT_LAYERB_MODULATION ` + +- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT ` + +- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING ` + +- :ref:`DTV_ISDBT_LAYERC_FEC ` + +- :ref:`DTV_ISDBT_LAYERC_MODULATION ` + +- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT ` + +- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _atsc-params: + +ATSC delivery system +==================== + +The following parameters are valid for ATSC: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _atscmh-params: + +ATSC-MH delivery system +======================= + +The following parameters are valid for ATSC-MH: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_ATSCMH_FIC_VER ` + +- :ref:`DTV_ATSCMH_PARADE_ID ` + +- :ref:`DTV_ATSCMH_NOG ` + +- :ref:`DTV_ATSCMH_TNOG ` + +- :ref:`DTV_ATSCMH_SGN ` + +- :ref:`DTV_ATSCMH_PRC ` + +- :ref:`DTV_ATSCMH_RS_FRAME_MODE ` + +- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE ` + +- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI ` + +- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC ` + +- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE ` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A ` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B ` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C ` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _dtmb-params: + +DTMB delivery system +==================== + +The following parameters are valid for DTMB: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_INNER_FEC ` + +- :ref:`DTV_GUARD_INTERVAL ` + +- :ref:`DTV_TRANSMISSION_MODE ` + +- :ref:`DTV_INTERLEAVING ` + +- :ref:`DTV_LNA ` + +In addition, the :ref:`DTV QoS statistics ` +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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend-stat-properties.rst b/Documentation/linux_tv/media/dvb/frontend-stat-properties.rst new file mode 100644 index 000000000000..36461d65a661 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend-stat-properties.rst @@ -0,0 +1,254 @@ +.. -*- 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 ` 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 `. + +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 ` +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-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 `. + +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 ` +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-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 ` +measurement was taken. + +It can be used to calculate the PER indicator, by dividing +:ref:`DTV_STAT_ERROR_BLOCK_COUNT ` by +:ref:`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 `. + + +.. ------------------------------------------------------------------------------ +.. This file was automatically converted from DocBook-XML with the dbxml +.. library (https://github.com/return42/sphkerneldoc). The origin XML comes +.. from the linux kernel, refer to: +.. +.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend.rst b/Documentation/linux_tv/media/dvb/frontend.rst new file mode 100644 index 000000000000..46be409e76b6 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend.rst @@ -0,0 +1,62 @@ +.. -*- 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 `__. + + +.. 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend_f_close.rst b/Documentation/linux_tv/media/dvb/frontend_f_close.rst new file mode 100644 index 000000000000..cde87322859a --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend_f_close.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _frontend_f_close: + +******************** +DVB frontend close() +******************** + +*man fe-close(2)* + +Close a frontend device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. c:function:: int close( int fd ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend_f_open.rst b/Documentation/linux_tv/media/dvb/frontend_f_open.rst new file mode 100644 index 000000000000..676ae922338d --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend_f_open.rst @@ -0,0 +1,108 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _frontend_f_open: + +******************* +DVB frontend open() +******************* + +*man fe-open(2)* + +Open a frontend device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. 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 `. + +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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend_fcalls.rst b/Documentation/linux_tv/media/dvb/frontend_fcalls.rst new file mode 100644 index 000000000000..8eae0e9461ab --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend_fcalls.rst @@ -0,0 +1,35 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend_h.rst b/Documentation/linux_tv/media/dvb/frontend_h.rst new file mode 100644 index 000000000000..3f616c6bd01d --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend_h.rst @@ -0,0 +1,24 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend_legacy_api.rst b/Documentation/linux_tv/media/dvb/frontend_legacy_api.rst new file mode 100644 index 000000000000..dcc62d4a8516 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend_legacy_api.rst @@ -0,0 +1,49 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/frontend_legacy_dvbv3_api.rst b/Documentation/linux_tv/media/dvb/frontend_legacy_dvbv3_api.rst new file mode 100644 index 000000000000..1dbff41f6a34 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/frontend_legacy_dvbv3_api.rst @@ -0,0 +1,29 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/intro.rst b/Documentation/linux_tv/media/dvb/intro.rst new file mode 100644 index 000000000000..0508f0d2c9db --- /dev/null +++ b/Documentation/linux_tv/media/dvb/intro.rst @@ -0,0 +1,204 @@ +.. -*- 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 + + +.. code-block:: c + + #include + + +.. code-block:: c + + #include + + +.. code-block:: c + + #include + + +.. code-block:: c + + #include + + +.. code-block:: c + + #include + + +.. code-block:: c + + #include + +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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/intro_files/dvbstb.pdf b/Documentation/linux_tv/media/dvb/intro_files/dvbstb.pdf new file mode 100644 index 000000000000..0fa75d90c3eb Binary files /dev/null and b/Documentation/linux_tv/media/dvb/intro_files/dvbstb.pdf differ diff --git a/Documentation/linux_tv/media/dvb/intro_files/dvbstb.png b/Documentation/linux_tv/media/dvb/intro_files/dvbstb.png new file mode 100644 index 000000000000..9b8f372e7afd Binary files /dev/null and b/Documentation/linux_tv/media/dvb/intro_files/dvbstb.png differ diff --git a/Documentation/linux_tv/media/dvb/legacy_dvb_apis.rst b/Documentation/linux_tv/media/dvb/legacy_dvb_apis.rst new file mode 100644 index 000000000000..15e0d88c2866 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/legacy_dvb_apis.rst @@ -0,0 +1,31 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/net.rst b/Documentation/linux_tv/media/dvb/net.rst new file mode 100644 index 000000000000..040ffc70601d --- /dev/null +++ b/Documentation/linux_tv/media/dvb/net.rst @@ -0,0 +1,219 @@ +.. -*- 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) `__ + +- `Ultra Lightweight Encapsulation (ULE) `__ + +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() `. + +``request`` + FE_SET_TONE + +``net_if`` + pointer to struct :ref:`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 `::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 ` 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() `. + +``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 `. + +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 ` 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 `. + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_SET_TONE + +``net_if`` + pointer to struct :ref:`dvb_net_if ` + + +Description +=========== + +The NET_GET_IF ioctl uses the interface number given by the struct +:ref:`dvb_net_if `::ifnum field and fills the content of +struct :ref:`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 `, 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/net_h.rst b/Documentation/linux_tv/media/dvb/net_h.rst new file mode 100644 index 000000000000..357713b4a5ef --- /dev/null +++ b/Documentation/linux_tv/media/dvb/net_h.rst @@ -0,0 +1,24 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/query-dvb-frontend-info.rst b/Documentation/linux_tv/media/dvb/query-dvb-frontend-info.rst new file mode 100644 index 000000000000..4a4fd5af6e0f --- /dev/null +++ b/Documentation/linux_tv/media/dvb/query-dvb-frontend-info.rst @@ -0,0 +1,22 @@ +.. -*- 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 `. 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/video.rst b/Documentation/linux_tv/media/dvb/video.rst new file mode 100644 index 000000000000..9783e9f344f6 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/video.rst @@ -0,0 +1,46 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/video_function_calls.rst b/Documentation/linux_tv/media/dvb/video_function_calls.rst new file mode 100644 index 000000000000..3add2b85450d --- /dev/null +++ b/Documentation/linux_tv/media/dvb/video_function_calls.rst @@ -0,0 +1,1880 @@ +.. -*- 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` ioctl. + +This ioctl commands the decoder. The ``video_command`` struct is a +subset of the ``v4l2_decoder_cmd`` struct, so refer to the +:ref:`VIDIOC_DECODER_CMD ` documentation for +more information. + +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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/video_h.rst b/Documentation/linux_tv/media/dvb/video_h.rst new file mode 100644 index 000000000000..348d20c3cab7 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/video_h.rst @@ -0,0 +1,24 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/dvb/video_types.rst b/Documentation/linux_tv/media/dvb/video_types.rst new file mode 100644 index 000000000000..f57233825e42 --- /dev/null +++ b/Documentation/linux_tv/media/dvb/video_types.rst @@ -0,0 +1,390 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/Remote_controllers_Intro.rst b/Documentation/linux_tv/media/v4l/Remote_controllers_Intro.rst new file mode 100644 index 000000000000..5e461ac39947 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/Remote_controllers_Intro.rst @@ -0,0 +1,33 @@ +.. -*- 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 `. + + +.. ------------------------------------------------------------------------------ +.. This file was automatically converted from DocBook-XML with the dbxml +.. library (https://github.com/return42/sphkerneldoc). The origin XML comes +.. from the linux kernel, refer to: +.. +.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/Remote_controllers_table_change.rst b/Documentation/linux_tv/media/v4l/Remote_controllers_table_change.rst new file mode 100644 index 000000000000..a04cc2cbbbb3 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/Remote_controllers_table_change.rst @@ -0,0 +1,29 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/Remote_controllers_tables.rst b/Documentation/linux_tv/media/v4l/Remote_controllers_tables.rst new file mode 100644 index 000000000000..2243d5b2dcd1 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/Remote_controllers_tables.rst @@ -0,0 +1,768 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/app-pri.rst b/Documentation/linux_tv/media/v4l/app-pri.rst new file mode 100644 index 000000000000..9716437ae14d --- /dev/null +++ b/Documentation/linux_tv/media/v4l/app-pri.rst @@ -0,0 +1,39 @@ +.. -*- 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 ` and +:ref:`VIDIOC_S_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 ` ioctl. + +Ioctls changing driver properties, such as +:ref:`VIDIOC_S_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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/async.rst b/Documentation/linux_tv/media/v4l/async.rst new file mode 100644 index 000000000000..82a56e88a54d --- /dev/null +++ b/Documentation/linux_tv/media/v4l/async.rst @@ -0,0 +1,18 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/audio.rst b/Documentation/linux_tv/media/v4l/audio.rst new file mode 100644 index 000000000000..5e37adfbb49c --- /dev/null +++ b/Documentation/linux_tv/media/v4l/audio.rst @@ -0,0 +1,97 @@ +.. -*- 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 ` or struct +:ref:`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 ` and +:ref:`VIDIOC_ENUMAUDOUT ` ioctl, respectively. +The struct :ref:`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 ` and +:ref:`VIDIOC_G_AUDOUT ` ioctls report the current +audio input and output, respectively. Note that, unlike +:ref:`VIDIOC_G_INPUT ` and +:ref:`VIDIOC_G_OUTPUT ` these ioctls return a +structure as ``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 ` ioctl. To select an audio +output (which presently has no changeable properties) applications call +the :ref:`VIDIOC_S_AUDOUT ` 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 ` returned by +the :ref:`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 ` ought to have a + ``tuner`` field like struct :ref:`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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/biblio.rst b/Documentation/linux_tv/media/v4l/biblio.rst new file mode 100644 index 000000000000..44dc7deb24b2 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/biblio.rst @@ -0,0 +1,390 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/buffer.rst b/Documentation/linux_tv/media/v4l/buffer.rst new file mode 100644 index 000000000000..e4cec63979c2 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/buffer.rst @@ -0,0 +1,966 @@ +.. -*- 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 `, +:ref:`VIDIOC_QBUF ` and +:ref:`VIDIOC_DQBUF ` 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 ` or +:ref:`VIDIOC_S_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 `, then it is set by the + driver. This field can range from zero to the number of buffers + allocated with the :ref:`VIDIOC_REQBUFS ` ioctl + (struct :ref:`v4l2_requestbuffers ` + ``count``), plus any buffers allocated with + :ref:`VIDIOC_CREATE_BUFS ` minus one. + + - .. row 2 + + - __u32 + + - ``type`` + + - + - Type of the buffer, same as struct + :ref:`v4l2_format ` ``type`` or struct + :ref:`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 ` + + - ``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 ` 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 ` 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() ` 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 `. 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 ` and/or + :ref:`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 ` and/or + :ref:`VIDIOC_CREATE_BUFS `. + + - .. row 3 + + - union + + - ``m`` + + - + - + + - .. row 4 + + - + - __u32 + + - ``mem_offset`` + + - When the memory type in the containing struct + :ref:`v4l2_buffer ` is ``V4L2_MEMORY_MMAP``, this + is the value that should be passed to :ref:`mmap() `, + similar to the ``offset`` field in struct + :ref:`v4l2_buffer `. + + - .. row 5 + + - + - unsigned long + + - ``userptr`` + + - When the memory type in the containing struct + :ref:`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 ` is ``V4L2_MEMORY_DMABUF``, + this is a file descriptor associated with a DMABUF buffer, similar + to the ``fd`` field in struct :ref:`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 `, + :ref:`VIDIOC_QBUF ` or + :ref:`VIDIOC_DQBUF ` 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 `, + :ref:`VIDIOC_PREPARE_BUF `, + :ref:`VIDIOC_QBUF ` or + :ref:`VIDIOC_DQBUF ` 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 ` or + :ref:`VIDIOC_DQBUF ` 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 ` 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 ` I/O. + + - .. row 2 + + - ``V4L2_MEMORY_USERPTR`` + + - 2 + + - The buffer is used for :ref:`user pointer ` 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 ` 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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/capture-example.rst b/Documentation/linux_tv/media/v4l/capture-example.rst new file mode 100644 index 000000000000..8d35e379cea7 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/capture-example.rst @@ -0,0 +1,24 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/capture.c.rst b/Documentation/linux_tv/media/v4l/capture.c.rst new file mode 100644 index 000000000000..41e96c78a6dd --- /dev/null +++ b/Documentation/linux_tv/media/v4l/capture.c.rst @@ -0,0 +1,675 @@ +.. -*- 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 + #include + #include + #include + + #include /* getopt_long() */ + + #include /* low-level i/o */ + #include + #include + #include + #include + #include + #include + #include + + #include + + #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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/colorspaces.rst b/Documentation/linux_tv/media/v4l/colorspaces.rst new file mode 100644 index 000000000000..85d0b33b60a3 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/colorspaces.rst @@ -0,0 +1,172 @@ +.. -*- 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 `__ +website is an excellent resource, especially with respect to the +mathematics behind colorspace conversions. The wikipedia +`CIE 1931 colorspace `__ +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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/common-defs.rst b/Documentation/linux_tv/media/v4l/common-defs.rst new file mode 100644 index 000000000000..3f90a8c6e28c --- /dev/null +++ b/Documentation/linux_tv/media/v4l/common-defs.rst @@ -0,0 +1,24 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/common.rst b/Documentation/linux_tv/media/v4l/common.rst new file mode 100644 index 000000000000..0e85b46b2efc --- /dev/null +++ b/Documentation/linux_tv/media/v4l/common.rst @@ -0,0 +1,56 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/compat.rst b/Documentation/linux_tv/media/v4l/compat.rst new file mode 100644 index 000000000000..8a6d883ae6af --- /dev/null +++ b/Documentation/linux_tv/media/v4l/compat.rst @@ -0,0 +1,29 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/control.rst b/Documentation/linux_tv/media/v4l/control.rst new file mode 100644 index 000000000000..16eb34472892 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/control.rst @@ -0,0 +1,536 @@ +.. -*- 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 `, 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 `__. + +``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 ` 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 `) 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 ` and +:ref:`VIDIOC_QUERYMENU ` ioctls, get and set a +control value with the :ref:`VIDIOC_G_CTRL ` and +:ref:`VIDIOC_S_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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/controls.rst b/Documentation/linux_tv/media/v4l/controls.rst new file mode 100644 index 000000000000..fe5bca543699 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/controls.rst @@ -0,0 +1,18 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/crop.rst b/Documentation/linux_tv/media/v4l/crop.rst new file mode 100644 index 000000000000..b9014d03865f --- /dev/null +++ b/Documentation/linux_tv/media/v4l/crop.rst @@ -0,0 +1,300 @@ +.. -*- 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 `, +:ref:`VIDIOC_G_CROP ` and +:ref:`VIDIOC_S_CROP ` ioctls apply to input as well +as output devices.* + +Scaling requires a source and a target. On a video capture or overlay +device the source is the video signal, and the cropping ioctls determine +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 ` +and :ref:`VIDIOC_S_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 ` +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 ` using the same coordinate system as +struct :ref:`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 `. 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 ` 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 ` may be smaller than the struct +:ref:`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 ` 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/crop_files/crop.gif b/Documentation/linux_tv/media/v4l/crop_files/crop.gif new file mode 100644 index 000000000000..3b9e7d836d4b Binary files /dev/null and b/Documentation/linux_tv/media/v4l/crop_files/crop.gif differ diff --git a/Documentation/linux_tv/media/v4l/crop_files/crop.pdf b/Documentation/linux_tv/media/v4l/crop_files/crop.pdf new file mode 100644 index 000000000000..c9fb81cd32f3 Binary files /dev/null and b/Documentation/linux_tv/media/v4l/crop_files/crop.pdf differ diff --git a/Documentation/linux_tv/media/v4l/depth-formats.rst b/Documentation/linux_tv/media/v4l/depth-formats.rst new file mode 100644 index 000000000000..c363eaf741f5 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/depth-formats.rst @@ -0,0 +1,26 @@ +.. -*- 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 +.. ------------------------------------------------------------------------------ diff --git a/Documentation/linux_tv/media/v4l/dev-capture.rst b/Documentation/linux_tv/media/v4l/dev-capture.rst new file mode 100644 index 000000000000..21207ab2e604 --- /dev/null +++ b/Documentation/linux_tv/media/v4l/dev-capture.rst @@ -0,0 +1,111 @@ +.. -*- 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 ` returned by the +:ref:`VIDIOC_QUERYCAP ` ioctl. As secondary device +functions they may also support the :ref:`video overlay ` +(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture ` +(``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