hollalinux
/
linux-sg2042
mirror of https://github.com/sophgo/linux-riscv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
This commit is contained in:
Markus Heiser 2016-06-30 15:18:56 +02:00 committed by Mauro Carvalho Chehab
parent 6ab99fa6a0
commit 5377d91f3e
323 changed files with 74156 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/index.rst
View File

@ -14,6 +14,7 @@ Contents:
:maxdepth: 2
kernel-documentation
linux_tv/index
Indices and tables
==================

153
Documentation/linux_tv/audio.h.rst Normal file
View File

@ -0,0 +1,153 @@
.. -*- coding: utf-8; mode: rst -*-
file: audio.h
=============
.. code-block:: c
/*
* audio.h
*
* Copyright (C) 2000 Ralph Metzler <ralph@convergence.de>
* & Marcus Metzler <marcus@convergence.de>
* for convergence integrated media GmbH
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Lesser Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*
*/
#ifndef _DVBAUDIO_H_
#define _DVBAUDIO_H_
#include <linux/types.h>
typedef enum {
AUDIO_SOURCE_DEMUX, /* Select the demux as the main source */
AUDIO_SOURCE_MEMORY /* Select internal memory as the main source */
} audio_stream_source_t;
typedef enum {
AUDIO_STOPPED, /* Device is stopped */
AUDIO_PLAYING, /* Device is currently playing */
AUDIO_PAUSED /* Device is paused */
} audio_play_state_t;
typedef enum {
AUDIO_STEREO,
AUDIO_MONO_LEFT,
AUDIO_MONO_RIGHT,
AUDIO_MONO,
AUDIO_STEREO_SWAPPED
} audio_channel_select_t;
typedef struct audio_mixer {
unsigned int volume_left;
unsigned int volume_right;
// what else do we need? bass, pass-through, ...
} audio_mixer_t;
typedef struct audio_status {
int AV_sync_state; /* sync audio and video? */
int mute_state; /* audio is muted */
audio_play_state_t play_state; /* current playback state */
audio_stream_source_t stream_source; /* current stream source */
audio_channel_select_t channel_select; /* currently selected channel */
int bypass_mode; /* pass on audio data to */
audio_mixer_t mixer_state; /* current mixer state */
} audio_status_t; /* separate decoder hardware */
typedef
struct audio_karaoke { /* if Vocal1 or Vocal2 are non-zero, they get mixed */
int vocal1; /* into left and right t at 70% each */
int vocal2; /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets*/
int melody; /* mixed into the left channel and */
/* Vocal2 into the right channel at 100% each. */
/* if Melody is non-zero, the melody channel gets mixed*/
} audio_karaoke_t; /* into left and right */
typedef __u16 audio_attributes_t;
/* bits: descr. */
/* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */
/* 12 multichannel extension */
/* 11-10 audio type (0=not spec, 1=language included) */
/* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */
/* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */
/* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */
/* 2- 0 number of audio channels (n+1 channels) */
/* for GET_CAPABILITIES and SET_FORMAT, the latter should only set one bit */
#define AUDIO_CAP_DTS 1
#define AUDIO_CAP_LPCM 2
#define AUDIO_CAP_MP1 4
#define AUDIO_CAP_MP2 8
#define AUDIO_CAP_MP3 16
#define AUDIO_CAP_AAC 32
#define AUDIO_CAP_OGG 64
#define AUDIO_CAP_SDDS 128
#define AUDIO_CAP_AC3 256
#define AUDIO_STOP _IO('o', 1)
#define AUDIO_PLAY _IO('o', 2)
#define AUDIO_PAUSE _IO('o', 3)
#define AUDIO_CONTINUE _IO('o', 4)
#define AUDIO_SELECT_SOURCE _IO('o', 5)
#define AUDIO_SET_MUTE _IO('o', 6)
#define AUDIO_SET_AV_SYNC _IO('o', 7)
#define AUDIO_SET_BYPASS_MODE _IO('o', 8)
#define AUDIO_CHANNEL_SELECT _IO('o', 9)
#define AUDIO_GET_STATUS _IOR('o', 10, audio_status_t)
#define AUDIO_GET_CAPABILITIES _IOR('o', 11, unsigned int)
#define AUDIO_CLEAR_BUFFER _IO('o', 12)
#define AUDIO_SET_ID _IO('o', 13)
#define AUDIO_SET_MIXER _IOW('o', 14, audio_mixer_t)
#define AUDIO_SET_STREAMTYPE _IO('o', 15)
#define AUDIO_SET_EXT_ID _IO('o', 16)
#define AUDIO_SET_ATTRIBUTES _IOW('o', 17, audio_attributes_t)
#define AUDIO_SET_KARAOKE _IOW('o', 18, audio_karaoke_t)
/**
* AUDIO_GET_PTS
*
* Read the 33 bit presentation time stamp as defined
* in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
*
* The PTS should belong to the currently played
* frame if possible, but may also be a value close to it
* like the PTS of the last decoded frame or the last PTS
* extracted by the PES parser.
*/
#define AUDIO_GET_PTS _IOR('o', 19, __u64)
#define AUDIO_BILINGUAL_CHANNEL_SELECT _IO('o', 20)
#endif /* _DVBAUDIO_H_ */
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

108
Documentation/linux_tv/ca.h.rst Normal file
View File

@ -0,0 +1,108 @@
.. -*- coding: utf-8; mode: rst -*-
file: ca.h
==========
.. code-block:: c
/*
* ca.h
*
* Copyright (C) 2000 Ralph Metzler <ralph@convergence.de>
* & Marcus Metzler <marcus@convergence.de>
* for convergence integrated media GmbH
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Lesser Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*
*/
#ifndef _DVBCA_H_
#define _DVBCA_H_
/* slot interface types and info */
typedef struct ca_slot_info {
int num; /* slot number */
int type; /* CA interface this slot supports */
#define CA_CI 1 /* CI high level interface */
#define CA_CI_LINK 2 /* CI link layer level interface */
#define CA_CI_PHYS 4 /* CI physical layer level interface */
#define CA_DESCR 8 /* built-in descrambler */
#define CA_SC 128 /* simple smart card interface */
unsigned int flags;
#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
#define CA_CI_MODULE_READY 2
} ca_slot_info_t;
/* descrambler types and info */
typedef struct ca_descr_info {
unsigned int num; /* number of available descramblers (keys) */
unsigned int type; /* type of supported scrambling system */
#define CA_ECD 1
#define CA_NDS 2
#define CA_DSS 4
} ca_descr_info_t;
typedef struct ca_caps {
unsigned int slot_num; /* total number of CA card and module slots */
unsigned int slot_type; /* OR of all supported types */
unsigned int descr_num; /* total number of descrambler slots (keys) */
unsigned int descr_type; /* OR of all supported types */
} ca_caps_t;
/* a message to/from a CI-CAM */
typedef struct ca_msg {
unsigned int index;
unsigned int type;
unsigned int length;
unsigned char msg[256];
} ca_msg_t;
typedef struct ca_descr {
unsigned int index;
unsigned int parity; /* 0 == even, 1 == odd */
unsigned char cw[8];
} ca_descr_t;
typedef struct ca_pid {
unsigned int pid;
int index; /* -1 == disable*/
} ca_pid_t;
#define CA_RESET _IO('o', 128)
#define CA_GET_CAP _IOR('o', 129, ca_caps_t)
#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t)
#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
#define CA_GET_MSG _IOR('o', 132, ca_msg_t)
#define CA_SEND_MSG _IOW('o', 133, ca_msg_t)
#define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
#define CA_SET_PID _IOW('o', 135, ca_pid_t)
#endif
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

221
Documentation/linux_tv/conf.py Normal file
View File

@ -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
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = pathjoin(BASE_FOLDER, "_tex", "logo.png")
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path.extend([])
# Output file base name for HTML help builder.
htmlhelp_basename = main_name
# ------------------------------------------------------------------------------
# Options for rst2pdf output
# ------------------------------------------------------------------------------
# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# The options element is a dictionary that lets you override
# this config per-document.
# For example,
# ('index', u'MyProject', u'My Project', u'Author Name',
# dict(pdf_compressed = True))
# would mean that specific document would be compressed
# regardless of the global pdf_compressed setting.
#
# further: http://rst2pdf.ralsina.me/handbook.html#sphinx
# FIXME: at this time, the rst2pdf fails with a bug
#pdf_documents = [
# (master_doc, main_name, project, author)
# , ]
# If false, no index is generated.
pdf_use_index = False
# How many levels deep should the table of contents be?
pdf_toc_depth = 3
# Add section number to section references
pdf_use_numbered_links = False
# Background images fitting mode
pdf_fit_background_mode = 'scale'
# ------------------------------------------------------------------------------
# Options for manual page output
# ------------------------------------------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
# man_pages = [
# (master_doc, 'kernel-doc', u'Kernel-Doc',
# [author], 1)
# ]
# If true, show URL addresses after external links.
#man_show_urls = False
# ------------------------------------------------------------------------------
# Options for Texinfo output
# ------------------------------------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
# texinfo_documents = [
# (master_doc, 'Kernel-Doc', u'Kernel-Doc Documentation',
# author, 'Kernel-Doc', 'One line description of project.',
# 'Miscellaneous'),
# ]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# ------------------------------------------------------------------------------
# Options for Epub output
# ------------------------------------------------------------------------------
# Bibliographic Dublin Core info.
# epub_title = project
# epub_author = author
# epub_publisher = author
# epub_copyright = copyright
# The basename for the epub file. It defaults to the project name.
#epub_basename = project
# The HTML theme for the epub output. Since the default themes are not
# optimized for small screen space, using the same theme for HTML and epub
# output is usually not wise. This defaults to 'epub', a theme designed to save
# visual space.
#epub_theme = 'epub'
# The language of the text. It defaults to the language option
# or 'en' if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# A unique identification for the text.
#epub_uid = ''
# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()
# A sequence of (type, uri, title) tuples for the guide element of content.opf.
#epub_guide = ()
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files.extend([])
# HTML files that should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files.extend([])
# A list of files that should not be packed into the epub file.
epub_exclude_files.extend([])
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True
# Choose between 'default' and 'includehidden'.
#epub_tocscope = 'default'
# Fix unsupported image types using the Pillow.
#epub_fix_images = False
# Scale large images.
#epub_max_image_width = 0
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#epub_show_urls = 'inline'
# If false, no index is generated.
#epub_use_index = True

173
Documentation/linux_tv/dmx.h.rst Normal file
View File

@ -0,0 +1,173 @@
.. -*- coding: utf-8; mode: rst -*-
file: dmx.h
===========
.. code-block:: c
/*
* dmx.h
*
* Copyright (C) 2000 Marcus Metzler <marcus@convergence.de>
* & Ralph Metzler <ralph@convergence.de>
* for convergence integrated media GmbH
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*
*/
#ifndef _UAPI_DVBDMX_H_
#define _UAPI_DVBDMX_H_
#include <linux/types.h>
#ifndef __KERNEL__
#include <time.h>
#endif
#define DMX_FILTER_SIZE 16
enum dmx_output
{
DMX_OUT_DECODER, /* Streaming directly to decoder. */
DMX_OUT_TAP, /* Output going to a memory buffer */
/* (to be retrieved via the read command).*/
DMX_OUT_TS_TAP, /* Output multiplexed into a new TS */
/* (to be retrieved by reading from the */
/* logical DVR device). */
DMX_OUT_TSDEMUX_TAP /* Like TS_TAP but retrieved from the DMX device */
};
typedef enum dmx_output dmx_output_t;
typedef enum dmx_input
{
DMX_IN_FRONTEND, /* Input from a front-end device. */
DMX_IN_DVR /* Input from the logical DVR device. */
} dmx_input_t;
typedef enum dmx_ts_pes
{
DMX_PES_AUDIO0,
DMX_PES_VIDEO0,
DMX_PES_TELETEXT0,
DMX_PES_SUBTITLE0,
DMX_PES_PCR0,
DMX_PES_AUDIO1,
DMX_PES_VIDEO1,
DMX_PES_TELETEXT1,
DMX_PES_SUBTITLE1,
DMX_PES_PCR1,
DMX_PES_AUDIO2,
DMX_PES_VIDEO2,
DMX_PES_TELETEXT2,
DMX_PES_SUBTITLE2,
DMX_PES_PCR2,
DMX_PES_AUDIO3,
DMX_PES_VIDEO3,
DMX_PES_TELETEXT3,
DMX_PES_SUBTITLE3,
DMX_PES_PCR3,
DMX_PES_OTHER
} dmx_pes_type_t;
#define DMX_PES_AUDIO DMX_PES_AUDIO0
#define DMX_PES_VIDEO DMX_PES_VIDEO0
#define DMX_PES_TELETEXT DMX_PES_TELETEXT0
#define DMX_PES_SUBTITLE DMX_PES_SUBTITLE0
#define DMX_PES_PCR DMX_PES_PCR0
typedef struct dmx_filter
{
__u8 filter[DMX_FILTER_SIZE];
__u8 mask[DMX_FILTER_SIZE];
__u8 mode[DMX_FILTER_SIZE];
} dmx_filter_t;
struct dmx_sct_filter_params
{
__u16 pid;
dmx_filter_t filter;
__u32 timeout;
__u32 flags;
#define DMX_CHECK_CRC 1
#define DMX_ONESHOT 2
#define DMX_IMMEDIATE_START 4
#define DMX_KERNEL_CLIENT 0x8000
};
struct dmx_pes_filter_params
{
__u16 pid;
dmx_input_t input;
dmx_output_t output;
dmx_pes_type_t pes_type;
__u32 flags;
};
typedef struct dmx_caps {
__u32 caps;
int num_decoders;
} dmx_caps_t;
typedef enum dmx_source {
DMX_SOURCE_FRONT0 = 0,
DMX_SOURCE_FRONT1,
DMX_SOURCE_FRONT2,
DMX_SOURCE_FRONT3,
DMX_SOURCE_DVR0 = 16,
DMX_SOURCE_DVR1,
DMX_SOURCE_DVR2,
DMX_SOURCE_DVR3
} dmx_source_t;
struct dmx_stc {
unsigned int num; /* input : which STC? 0..N */
unsigned int base; /* output: divisor for stc to get 90 kHz clock */
__u64 stc; /* output: stc in 'base'*90 kHz units */
};
#define DMX_START _IO('o', 41)
#define DMX_STOP _IO('o', 42)
#define DMX_SET_FILTER _IOW('o', 43, struct dmx_sct_filter_params)
#define DMX_SET_PES_FILTER _IOW('o', 44, struct dmx_pes_filter_params)
#define DMX_SET_BUFFER_SIZE _IO('o', 45)
#define DMX_GET_PES_PIDS _IOR('o', 47, __u16[5])
#define DMX_GET_CAPS _IOR('o', 48, dmx_caps_t)
#define DMX_SET_SOURCE _IOW('o', 49, dmx_source_t)
#define DMX_GET_STC _IOWR('o', 50, struct dmx_stc)
#define DMX_ADD_PID _IOW('o', 51, __u16)
#define DMX_REMOVE_PID _IOW('o', 52, __u16)
#endif /* _UAPI_DVBDMX_H_ */
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

620
Documentation/linux_tv/frontend.h.rst Normal file
View File

@ -0,0 +1,620 @@
.. -*- coding: utf-8; mode: rst -*-
file: frontend.h
================
.. code-block:: c
/*
* frontend.h
*
* Copyright (C) 2000 Marcus Metzler <marcus@convergence.de>
* Ralph Metzler <ralph@convergence.de>
* Holger Waechtler <holger@convergence.de>
* Andre Draszik <ad@convergence.de>
* for convergence integrated media GmbH
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*
*/
#ifndef _DVBFRONTEND_H_
#define _DVBFRONTEND_H_
#include <linux/types.h>
enum fe_type {
FE_QPSK,
FE_QAM,
FE_OFDM,
FE_ATSC
};
enum fe_caps {
FE_IS_STUPID = 0,
FE_CAN_INVERSION_AUTO = 0x1,
FE_CAN_FEC_1_2 = 0x2,
FE_CAN_FEC_2_3 = 0x4,
FE_CAN_FEC_3_4 = 0x8,
FE_CAN_FEC_4_5 = 0x10,
FE_CAN_FEC_5_6 = 0x20,
FE_CAN_FEC_6_7 = 0x40,
FE_CAN_FEC_7_8 = 0x80,
FE_CAN_FEC_8_9 = 0x100,
FE_CAN_FEC_AUTO = 0x200,
FE_CAN_QPSK = 0x400,
FE_CAN_QAM_16 = 0x800,
FE_CAN_QAM_32 = 0x1000,
FE_CAN_QAM_64 = 0x2000,
FE_CAN_QAM_128 = 0x4000,
FE_CAN_QAM_256 = 0x8000,
FE_CAN_QAM_AUTO = 0x10000,
FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000,
FE_CAN_BANDWIDTH_AUTO = 0x40000,
FE_CAN_GUARD_INTERVAL_AUTO = 0x80000,
FE_CAN_HIERARCHY_AUTO = 0x100000,
FE_CAN_8VSB = 0x200000,
FE_CAN_16VSB = 0x400000,
FE_HAS_EXTENDED_CAPS = 0x800000, /* We need more bitspace for newer APIs, indicate this. */
FE_CAN_MULTISTREAM = 0x4000000, /* frontend supports multistream filtering */
FE_CAN_TURBO_FEC = 0x8000000, /* frontend supports "turbo fec modulation" */
FE_CAN_2G_MODULATION = 0x10000000, /* frontend supports "2nd generation modulation" (DVB-S2) */
FE_NEEDS_BENDING = 0x20000000, /* not supported anymore, don't use (frontend requires frequency bending) */
FE_CAN_RECOVER = 0x40000000, /* frontend can recover from a cable unplug automatically */
FE_CAN_MUTE_TS = 0x80000000 /* frontend can stop spurious TS data output */
};
struct dvb_frontend_info {
char name[128];
enum fe_type type; /* DEPRECATED. Use DTV_ENUM_DELSYS instead */
__u32 frequency_min;
__u32 frequency_max;
__u32 frequency_stepsize;
__u32 frequency_tolerance;
__u32 symbol_rate_min;
__u32 symbol_rate_max;
__u32 symbol_rate_tolerance; /* ppm */
__u32 notifier_delay; /* DEPRECATED */
enum fe_caps caps;
};
/**
* Check out the DiSEqC bus spec available on http://www.eutelsat.org/ for
* the meaning of this struct...
*/
struct dvb_diseqc_master_cmd {
__u8 msg [6]; /* { framing, address, command, data [3] } */
__u8 msg_len; /* valid values are 3...6 */
};
struct dvb_diseqc_slave_reply {
__u8 msg [4]; /* { framing, data [3] } */
__u8 msg_len; /* valid values are 0...4, 0 means no msg */
int timeout; /* return from ioctl after timeout ms with */
}; /* errorcode when no message was received */
enum fe_sec_voltage {
SEC_VOLTAGE_13,
SEC_VOLTAGE_18,
SEC_VOLTAGE_OFF
};
enum fe_sec_tone_mode {
SEC_TONE_ON,
SEC_TONE_OFF
};
enum fe_sec_mini_cmd {
SEC_MINI_A,
SEC_MINI_B
};
/**
* enum fe_status - enumerates the possible frontend status
* @FE_HAS_SIGNAL: found something above the noise level
* @FE_HAS_CARRIER: found a DVB signal
* @FE_HAS_VITERBI: FEC is stable
* @FE_HAS_SYNC: found sync bytes
* @FE_HAS_LOCK: everything's working
* @FE_TIMEDOUT: no lock within the last ~2 seconds
* @FE_REINIT: frontend was reinitialized, application is recommended
* to reset DiSEqC, tone and parameters
*/
enum fe_status {
FE_HAS_SIGNAL = 0x01,
FE_HAS_CARRIER = 0x02,
FE_HAS_VITERBI = 0x04,
FE_HAS_SYNC = 0x08,
FE_HAS_LOCK = 0x10,
FE_TIMEDOUT = 0x20,
FE_REINIT = 0x40,
};
enum fe_spectral_inversion {
INVERSION_OFF,
INVERSION_ON,
INVERSION_AUTO
};
enum fe_code_rate {
FEC_NONE = 0,
FEC_1_2,
FEC_2_3,
FEC_3_4,
FEC_4_5,
FEC_5_6,
FEC_6_7,
FEC_7_8,
FEC_8_9,
FEC_AUTO,
FEC_3_5,
FEC_9_10,
FEC_2_5,
};
enum fe_modulation {
QPSK,
QAM_16,
QAM_32,
QAM_64,
QAM_128,
QAM_256,
QAM_AUTO,
VSB_8,
VSB_16,
PSK_8,
APSK_16,
APSK_32,
DQPSK,
QAM_4_NR,
};
enum fe_transmit_mode {
TRANSMISSION_MODE_2K,
TRANSMISSION_MODE_8K,
TRANSMISSION_MODE_AUTO,
TRANSMISSION_MODE_4K,
TRANSMISSION_MODE_1K,
TRANSMISSION_MODE_16K,
TRANSMISSION_MODE_32K,
TRANSMISSION_MODE_C1,
TRANSMISSION_MODE_C3780,
};
enum fe_guard_interval {
GUARD_INTERVAL_1_32,
GUARD_INTERVAL_1_16,
GUARD_INTERVAL_1_8,
GUARD_INTERVAL_1_4,
GUARD_INTERVAL_AUTO,
GUARD_INTERVAL_1_128,
GUARD_INTERVAL_19_128,
GUARD_INTERVAL_19_256,
GUARD_INTERVAL_PN420,
GUARD_INTERVAL_PN595,
GUARD_INTERVAL_PN945,
};
enum fe_hierarchy {
HIERARCHY_NONE,
HIERARCHY_1,
HIERARCHY_2,
HIERARCHY_4,
HIERARCHY_AUTO
};
enum fe_interleaving {
INTERLEAVING_NONE,
INTERLEAVING_AUTO,
INTERLEAVING_240,
INTERLEAVING_720,
};
/* S2API Commands */
#define DTV_UNDEFINED 0
#define DTV_TUNE 1
#define DTV_CLEAR 2
#define DTV_FREQUENCY 3
#define DTV_MODULATION 4
#define DTV_BANDWIDTH_HZ 5
#define DTV_INVERSION 6
#define DTV_DISEQC_MASTER 7
#define DTV_SYMBOL_RATE 8
#define DTV_INNER_FEC 9
#define DTV_VOLTAGE 10
#define DTV_TONE 11
#define DTV_PILOT 12
#define DTV_ROLLOFF 13
#define DTV_DISEQC_SLAVE_REPLY 14
/* Basic enumeration set for querying unlimited capabilities */
#define DTV_FE_CAPABILITY_COUNT 15
#define DTV_FE_CAPABILITY 16
#define DTV_DELIVERY_SYSTEM 17
/* ISDB-T and ISDB-Tsb */
#define DTV_ISDBT_PARTIAL_RECEPTION 18
#define DTV_ISDBT_SOUND_BROADCASTING 19
#define DTV_ISDBT_SB_SUBCHANNEL_ID 20
#define DTV_ISDBT_SB_SEGMENT_IDX 21
#define DTV_ISDBT_SB_SEGMENT_COUNT 22
#define DTV_ISDBT_LAYERA_FEC 23
#define DTV_ISDBT_LAYERA_MODULATION 24
#define DTV_ISDBT_LAYERA_SEGMENT_COUNT 25
#define DTV_ISDBT_LAYERA_TIME_INTERLEAVING 26
#define DTV_ISDBT_LAYERB_FEC 27
#define DTV_ISDBT_LAYERB_MODULATION 28
#define DTV_ISDBT_LAYERB_SEGMENT_COUNT 29
#define DTV_ISDBT_LAYERB_TIME_INTERLEAVING 30
#define DTV_ISDBT_LAYERC_FEC 31
#define DTV_ISDBT_LAYERC_MODULATION 32
#define DTV_ISDBT_LAYERC_SEGMENT_COUNT 33
#define DTV_ISDBT_LAYERC_TIME_INTERLEAVING 34
#define DTV_API_VERSION 35
#define DTV_CODE_RATE_HP 36
#define DTV_CODE_RATE_LP 37
#define DTV_GUARD_INTERVAL 38
#define DTV_TRANSMISSION_MODE 39
#define DTV_HIERARCHY 40
#define DTV_ISDBT_LAYER_ENABLED 41
#define DTV_STREAM_ID 42
#define DTV_ISDBS_TS_ID_LEGACY DTV_STREAM_ID
#define DTV_DVBT2_PLP_ID_LEGACY 43
#define DTV_ENUM_DELSYS 44
/* ATSC-MH */
#define DTV_ATSCMH_FIC_VER 45
#define DTV_ATSCMH_PARADE_ID 46
#define DTV_ATSCMH_NOG 47
#define DTV_ATSCMH_TNOG 48
#define DTV_ATSCMH_SGN 49
#define DTV_ATSCMH_PRC 50
#define DTV_ATSCMH_RS_FRAME_MODE 51
#define DTV_ATSCMH_RS_FRAME_ENSEMBLE 52
#define DTV_ATSCMH_RS_CODE_MODE_PRI 53
#define DTV_ATSCMH_RS_CODE_MODE_SEC 54
#define DTV_ATSCMH_SCCC_BLOCK_MODE 55
#define DTV_ATSCMH_SCCC_CODE_MODE_A 56
#define DTV_ATSCMH_SCCC_CODE_MODE_B 57
#define DTV_ATSCMH_SCCC_CODE_MODE_C 58
#define DTV_ATSCMH_SCCC_CODE_MODE_D 59
#define DTV_INTERLEAVING 60
#define DTV_LNA 61
/* Quality parameters */
#define DTV_STAT_SIGNAL_STRENGTH 62
#define DTV_STAT_CNR 63
#define DTV_STAT_PRE_ERROR_BIT_COUNT 64
#define DTV_STAT_PRE_TOTAL_BIT_COUNT 65
#define DTV_STAT_POST_ERROR_BIT_COUNT 66
#define DTV_STAT_POST_TOTAL_BIT_COUNT 67
#define DTV_STAT_ERROR_BLOCK_COUNT 68
#define DTV_STAT_TOTAL_BLOCK_COUNT 69
#define DTV_MAX_COMMAND DTV_STAT_TOTAL_BLOCK_COUNT
enum fe_pilot {
PILOT_ON,
PILOT_OFF,
PILOT_AUTO,
};
enum fe_rolloff {
ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */
ROLLOFF_20,
ROLLOFF_25,
ROLLOFF_AUTO,
};
enum fe_delivery_system {
SYS_UNDEFINED,
SYS_DVBC_ANNEX_A,
SYS_DVBC_ANNEX_B,
SYS_DVBT,
SYS_DSS,
SYS_DVBS,
SYS_DVBS2,
SYS_DVBH,
SYS_ISDBT,
SYS_ISDBS,
SYS_ISDBC,
SYS_ATSC,
SYS_ATSCMH,
SYS_DTMB,
SYS_CMMB,
SYS_DAB,
SYS_DVBT2,
SYS_TURBO,
SYS_DVBC_ANNEX_C,
};
/* backward compatibility */
#define SYS_DVBC_ANNEX_AC SYS_DVBC_ANNEX_A
#define SYS_DMBTH SYS_DTMB /* DMB-TH is legacy name, use DTMB instead */
/* ATSC-MH */
enum atscmh_sccc_block_mode {
ATSCMH_SCCC_BLK_SEP = 0,
ATSCMH_SCCC_BLK_COMB = 1,
ATSCMH_SCCC_BLK_RES = 2,
};
enum atscmh_sccc_code_mode {
ATSCMH_SCCC_CODE_HLF = 0,
ATSCMH_SCCC_CODE_QTR = 1,
ATSCMH_SCCC_CODE_RES = 2,
};
enum atscmh_rs_frame_ensemble {
ATSCMH_RSFRAME_ENS_PRI = 0,
ATSCMH_RSFRAME_ENS_SEC = 1,
};
enum atscmh_rs_frame_mode {
ATSCMH_RSFRAME_PRI_ONLY = 0,
ATSCMH_RSFRAME_PRI_SEC = 1,
ATSCMH_RSFRAME_RES = 2,
};
enum atscmh_rs_code_mode {
ATSCMH_RSCODE_211_187 = 0,
ATSCMH_RSCODE_223_187 = 1,
ATSCMH_RSCODE_235_187 = 2,
ATSCMH_RSCODE_RES = 3,
};
#define NO_STREAM_ID_FILTER (~0U)
#define LNA_AUTO (~0U)
struct dtv_cmds_h {
char *name; /* A display name for debugging purposes */
__u32 cmd; /* A unique ID */
/* Flags */
__u32 set:1; /* Either a set or get property */
__u32 buffer:1; /* Does this property use the buffer? */
__u32 reserved:30; /* Align */
};
/**
* Scale types for the quality parameters.
* @FE_SCALE_NOT_AVAILABLE: That QoS measure is not available. That
* could indicate a temporary or a permanent
* condition.
* @FE_SCALE_DECIBEL: The scale is measured in 0.001 dB steps, typically
* used on signal measures.
* @FE_SCALE_RELATIVE: The scale is a relative percentual measure,
* ranging from 0 (0%) to 0xffff (100%).
* @FE_SCALE_COUNTER: The scale counts the occurrence of an event, like
* bit error, block error, lapsed time.
*/
enum fecap_scale_params {
FE_SCALE_NOT_AVAILABLE = 0,
FE_SCALE_DECIBEL,
FE_SCALE_RELATIVE,
FE_SCALE_COUNTER
};
/**
* struct dtv_stats - Used for reading a DTV status property
*
* @value: value of the measure. Should range from 0 to 0xffff;
* @scale: Filled with enum fecap_scale_params - the scale
* in usage for that parameter
*
* For most delivery systems, this will return a single value for each
* parameter.
* It should be noticed, however, that new OFDM delivery systems like
* ISDB can use different modulation types for each group of carriers.
* On such standards, up to 8 groups of statistics can be provided, one
* for each carrier group (called "layer" on ISDB).
* In order to be consistent with other delivery systems, the first
* value refers to the entire set of carriers ("global").
* dtv_status:scale should use the value FE_SCALE_NOT_AVAILABLE when
* the value for the entire group of carriers or from one specific layer
* is not provided by the hardware.
* st.len should be filled with the latest filled status + 1.
*
* In other words, for ISDB, those values should be filled like:
* u.st.stat.svalue[0] = global statistics;
* u.st.stat.scale[0] = FE_SCALE_DECIBEL;
* u.st.stat.value[1] = layer A statistics;
* u.st.stat.scale[1] = FE_SCALE_NOT_AVAILABLE (if not available);
* u.st.stat.svalue[2] = layer B statistics;
* u.st.stat.scale[2] = FE_SCALE_DECIBEL;
* u.st.stat.svalue[3] = layer C statistics;
* u.st.stat.scale[3] = FE_SCALE_DECIBEL;
* u.st.len = 4;
*/
struct dtv_stats {
__u8 scale; /* enum fecap_scale_params type */
union {
__u64 uvalue; /* for counters and relative scales */
__s64 svalue; /* for 0.001 dB measures */
};
} __attribute__ ((packed));
#define MAX_DTV_STATS 4
struct dtv_fe_stats {
__u8 len;
struct dtv_stats stat[MAX_DTV_STATS];
} __attribute__ ((packed));
struct dtv_property {
__u32 cmd;
__u32 reserved[3];
union {
__u32 data;
struct dtv_fe_stats st;
struct {
__u8 data[32];
__u32 len;
__u32 reserved1[3];
void *reserved2;
} buffer;
} u;
int result;
} __attribute__ ((packed));
/* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
#define DTV_IOCTL_MAX_MSGS 64
struct dtv_properties {
__u32 num;
struct dtv_property *props;
};
#if defined(__DVB_CORE__) || !defined (__KERNEL__)
/*
* DEPRECATED: The DVBv3 ioctls, structs and enums should not be used on
* newer programs, as it doesn't support the second generation of digital
* TV standards, nor supports newer delivery systems.
*/
enum fe_bandwidth {
BANDWIDTH_8_MHZ,
BANDWIDTH_7_MHZ,
BANDWIDTH_6_MHZ,
BANDWIDTH_AUTO,
BANDWIDTH_5_MHZ,
BANDWIDTH_10_MHZ,
BANDWIDTH_1_712_MHZ,
};
/* This is needed for legacy userspace support */
typedef enum fe_sec_voltage fe_sec_voltage_t;
typedef enum fe_caps fe_caps_t;
typedef enum fe_type fe_type_t;
typedef enum fe_sec_tone_mode fe_sec_tone_mode_t;
typedef enum fe_sec_mini_cmd fe_sec_mini_cmd_t;
typedef enum fe_status fe_status_t;
typedef enum fe_spectral_inversion fe_spectral_inversion_t;
typedef enum fe_code_rate fe_code_rate_t;
typedef enum fe_modulation fe_modulation_t;
typedef enum fe_transmit_mode fe_transmit_mode_t;
typedef enum fe_bandwidth fe_bandwidth_t;
typedef enum fe_guard_interval fe_guard_interval_t;
typedef enum fe_hierarchy fe_hierarchy_t;
typedef enum fe_pilot fe_pilot_t;
typedef enum fe_rolloff fe_rolloff_t;
typedef enum fe_delivery_system fe_delivery_system_t;
struct dvb_qpsk_parameters {
__u32 symbol_rate; /* symbol rate in Symbols per second */
fe_code_rate_t fec_inner; /* forward error correction (see above) */
};
struct dvb_qam_parameters {
__u32 symbol_rate; /* symbol rate in Symbols per second */
fe_code_rate_t fec_inner; /* forward error correction (see above) */
fe_modulation_t modulation; /* modulation type (see above) */
};
struct dvb_vsb_parameters {
fe_modulation_t modulation; /* modulation type (see above) */
};
struct dvb_ofdm_parameters {
fe_bandwidth_t bandwidth;
fe_code_rate_t code_rate_HP; /* high priority stream code rate */
fe_code_rate_t code_rate_LP; /* low priority stream code rate */
fe_modulation_t constellation; /* modulation type (see above) */
fe_transmit_mode_t transmission_mode;
fe_guard_interval_t guard_interval;
fe_hierarchy_t hierarchy_information;
};
struct dvb_frontend_parameters {
__u32 frequency; /* (absolute) frequency in Hz for DVB-C/DVB-T/ATSC */
/* intermediate frequency in kHz for DVB-S */
fe_spectral_inversion_t inversion;
union {
struct dvb_qpsk_parameters qpsk; /* DVB-S */
struct dvb_qam_parameters qam; /* DVB-C */
struct dvb_ofdm_parameters ofdm; /* DVB-T */
struct dvb_vsb_parameters vsb; /* ATSC */
} u;
};
struct dvb_frontend_event {
fe_status_t status;
struct dvb_frontend_parameters parameters;
};
#endif
#define FE_SET_PROPERTY _IOW('o', 82, struct dtv_properties)
#define FE_GET_PROPERTY _IOR('o', 83, struct dtv_properties)
/**
* When set, this flag will disable any zigzagging or other "normal" tuning
* behaviour. Additionally, there will be no automatic monitoring of the lock
* status, and hence no frontend events will be generated. If a frontend device
* is closed, this flag will be automatically turned off when the device is
* reopened read-write.
*/
#define FE_TUNE_MODE_ONESHOT 0x01
#define FE_GET_INFO _IOR('o', 61, struct dvb_frontend_info)
#define FE_DISEQC_RESET_OVERLOAD _IO('o', 62)
#define FE_DISEQC_SEND_MASTER_CMD _IOW('o', 63, struct dvb_diseqc_master_cmd)
#define FE_DISEQC_RECV_SLAVE_REPLY _IOR('o', 64, struct dvb_diseqc_slave_reply)
#define FE_DISEQC_SEND_BURST _IO('o', 65) /* fe_sec_mini_cmd_t */
#define FE_SET_TONE _IO('o', 66) /* fe_sec_tone_mode_t */
#define FE_SET_VOLTAGE _IO('o', 67) /* fe_sec_voltage_t */
#define FE_ENABLE_HIGH_LNB_VOLTAGE _IO('o', 68) /* int */
#define FE_READ_STATUS _IOR('o', 69, fe_status_t)
#define FE_READ_BER _IOR('o', 70, __u32)
#define FE_READ_SIGNAL_STRENGTH _IOR('o', 71, __u16)
#define FE_READ_SNR _IOR('o', 72, __u16)
#define FE_READ_UNCORRECTED_BLOCKS _IOR('o', 73, __u32)
#define FE_SET_FRONTEND _IOW('o', 76, struct dvb_frontend_parameters)
#define FE_GET_FRONTEND _IOR('o', 77, struct dvb_frontend_parameters)
#define FE_SET_FRONTEND_TUNE_MODE _IO('o', 81) /* unsigned int */
#define FE_GET_EVENT _IOR('o', 78, struct dvb_frontend_event)
#define FE_DISHNETWORK_SEND_LEGACY_CMD _IO('o', 80) /* unsigned int */
#endif /*_DVBFRONTEND_H_*/
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

100
Documentation/linux_tv/index.rst Normal file
View File

@ -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 <https://linuxtv.org>`__.
For discussing improvements, reporting troubles, sending new drivers,
etc, please mail to:
`Linux Media Mailing List (LMML). <http://vger.kernel.org/vger-lists.html#linux-media>`__.
.. toctree::
:maxdepth: 1
media/v4l/v4l2
media/dvb/dvbapi
media/v4l/remote_controllers
media/v4l/media-controller
media/v4l/gen-errors
media/v4l/fdl-appendix
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
.. only:: html
Retrieval
=========
* :ref:`genindex`
.. todolist::

55
Documentation/linux_tv/media/dvb/FE_DISHNETWORK_SEND_LEGACY_CMD.rst Normal file
View File

@ -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 <FE_DISHNETWORK_SEND_LEGACY_CMD>`,
unsigned long cmd);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- unsigned long cmd
- sends the specified raw cmd to the dish via DISEqC.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

89
Documentation/linux_tv/media/dvb/FE_GET_EVENT.rst Normal file
View File

@ -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 <FE_GET_EVENT>` for this command.
- .. row 3
- struct dvb_frontend_event *ev
- Points to the location where the event,
- .. row 4
-
- if any, is to be stored.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- EWOULDBLOCK
- There is no event pending, and the device is in non-blocking mode.
- .. row 2
- EOVERFLOW
- Overflow in event queue - one or more events were lost.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

77
Documentation/linux_tv/media/dvb/FE_GET_FRONTEND.rst Normal file
View File

@ -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 <FE_GET_FRONTEND>`, struct
dvb_frontend_parameters *p);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals :ref:`FE_SET_FRONTEND <FE_SET_FRONTEND>` for this
command.
- .. row 3
- struct dvb_frontend_parameters *p
- Points to parameters for tuning operation.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- EINVAL
- Maximum supported symbol rate reached.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

61
Documentation/linux_tv/media/dvb/FE_READ_BER.rst Normal file
View File

@ -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 <FE_READ_BER>`,
uint32_t *ber);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals :ref:`FE_READ_BER <FE_READ_BER>` for this command.
- .. row 3
- uint32_t *ber
- The bit error rate is stored into *ber.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

64
Documentation/linux_tv/media/dvb/FE_READ_SIGNAL_STRENGTH.rst Normal file
View File

@ -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 <FE_READ_SIGNAL_STRENGTH>`,
uint16_t *strength);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals
:ref:`FE_READ_SIGNAL_STRENGTH <FE_READ_SIGNAL_STRENGTH>`
for this command.
- .. row 3
- uint16_t *strength
- The signal strength value is stored into *strength.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

61
Documentation/linux_tv/media/dvb/FE_READ_SNR.rst Normal file
View File

@ -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 <FE_READ_SNR>`,
uint16_t *snr);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals :ref:`FE_READ_SNR <FE_READ_SNR>` for this command.
- .. row 3
- uint16_t *snr
- The signal-to-noise ratio is stored into *snr.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

66
Documentation/linux_tv/media/dvb/FE_READ_UNCORRECTED_BLOCKS.rst Normal file
View File

@ -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 <FE_READ_UNCORRECTED_BLOCKS>`,
uint32_t *ublocks);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals
:ref:`FE_READ_UNCORRECTED_BLOCKS <FE_READ_UNCORRECTED_BLOCKS>`
for this command.
- .. row 3
- uint32_t *ublocks
- The total number of uncorrected blocks seen by the driver so far.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

84
Documentation/linux_tv/media/dvb/FE_SET_FRONTEND.rst Normal file
View File

@ -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 <FE_GET_EVENT>` and
FrontendEvent.) If a new :ref:`FE_SET_FRONTEND <FE_SET_FRONTEND>`
operation is initiated before the previous one was completed, the
previous operation will be aborted in favor of the new one. This command
requires read/write access to the device.
SYNOPSIS
int ioctl(int fd, int request =
:ref:`FE_SET_FRONTEND <FE_SET_FRONTEND>`, struct
dvb_frontend_parameters *p);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals :ref:`FE_SET_FRONTEND <FE_SET_FRONTEND>` for this
command.
- .. row 3
- struct dvb_frontend_parameters *p
- Points to parameters for tuning operation.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- EINVAL
- Maximum supported symbol rate reached.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

37
Documentation/linux_tv/media/dvb/audio.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

187
Documentation/linux_tv/media/dvb/audio_data_types.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

1308
Documentation/linux_tv/media/dvb/audio_function_calls.rst Normal file
View File

File diff suppressed because it is too large Load Diff

24
Documentation/linux_tv/media/dvb/audio_h.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

29
Documentation/linux_tv/media/dvb/ca.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

121
Documentation/linux_tv/media/dvb/ca_data_types.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

541
Documentation/linux_tv/media/dvb/ca_function_calls.rst Normal file
View File

@ -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 <gen-errors>` chapter.
.. _CA_GET_CAP:
CA_GET_CAP
==========
DESCRIPTION
This ioctl is undocumented. Documentation is welcome.
SYNOPSIS
int ioctl(fd, int request = CA_GET_CAP, ca_caps_t *);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals CA_GET_CAP for this command.
- .. row 3
- ca_caps_t *
- Undocumented.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _CA_GET_SLOT_INFO:
CA_GET_SLOT_INFO
================
DESCRIPTION
This ioctl is undocumented. Documentation is welcome.
SYNOPSIS
int ioctl(fd, int request = CA_GET_SLOT_INFO, ca_slot_info_t *);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals CA_GET_SLOT_INFO for this command.
- .. row 3
- ca_slot_info_t *
- Undocumented.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _CA_GET_DESCR_INFO:
CA_GET_DESCR_INFO
=================
DESCRIPTION
This ioctl is undocumented. Documentation is welcome.
SYNOPSIS
int ioctl(fd, int request = CA_GET_DESCR_INFO, ca_descr_info_t *);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals CA_GET_DESCR_INFO for this command.
- .. row 3
- ca_descr_info_t *
- Undocumented.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _CA_GET_MSG:
CA_GET_MSG
==========
DESCRIPTION
This ioctl is undocumented. Documentation is welcome.
SYNOPSIS
int ioctl(fd, int request = CA_GET_MSG, ca_msg_t *);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals CA_GET_MSG for this command.
- .. row 3
- ca_msg_t *
- Undocumented.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _CA_SEND_MSG:
CA_SEND_MSG
===========
DESCRIPTION
This ioctl is undocumented. Documentation is welcome.
SYNOPSIS
int ioctl(fd, int request = CA_SEND_MSG, ca_msg_t *);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals CA_SEND_MSG for this command.
- .. row 3
- ca_msg_t *
- Undocumented.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _CA_SET_DESCR:
CA_SET_DESCR
============
DESCRIPTION
This ioctl is undocumented. Documentation is welcome.
SYNOPSIS
int ioctl(fd, int request = CA_SET_DESCR, ca_descr_t *);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals CA_SET_DESCR for this command.
- .. row 3
- ca_descr_t *
- Undocumented.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _CA_SET_PID:
CA_SET_PID
==========
DESCRIPTION
This ioctl is undocumented. Documentation is welcome.
SYNOPSIS
int ioctl(fd, int request = CA_SET_PID, ca_pid_t *);
PARAMETERS
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals CA_SET_PID for this command.
- .. row 3
- ca_pid_t *
- Undocumented.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

24
Documentation/linux_tv/media/dvb/ca_h.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

29
Documentation/linux_tv/media/dvb/demux.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

1013
Documentation/linux_tv/media/dvb/dmx_fcalls.rst Normal file
View File

File diff suppressed because it is too large Load Diff

24
Documentation/linux_tv/media/dvb/dmx_h.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

253
Documentation/linux_tv/media/dvb/dmx_types.rst Normal file
View File

@ -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 <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
.. ------------------------------------------------------------------------------

28
Documentation/linux_tv/media/dvb/dtv-fe-stats.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

26
Documentation/linux_tv/media/dvb/dtv-properties.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

42
Documentation/linux_tv/media/dvb/dtv-property.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

29
Documentation/linux_tv/media/dvb/dtv-stats.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

31
Documentation/linux_tv/media/dvb/dvb-fe-read-status.rst Normal file
View File

@ -0,0 +1,31 @@
.. -*- coding: utf-8; mode: rst -*-
.. _dvb-fe-read-status:
***************************************
Querying frontend status and statistics
***************************************
Once :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` is called, the
frontend will run a kernel thread that will periodically check for the
tuner lock status and provide statistics about the quality of the
signal.
The information about the frontend tuner locking status can be queried
using :ref:`FE_READ_STATUS <FE_READ_STATUS>`.
Signal statistics are provided via
:ref:`FE_GET_PROPERTY <FE_GET_PROPERTY>`. Please note that several
statistics require the demodulator to be fully locked (e. g. with
FE_HAS_LOCK bit set). See
:ref:`Frontend statistics indicators <frontend-stat-properties>` for
more details.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

26
Documentation/linux_tv/media/dvb/dvb-frontend-event.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

130
Documentation/linux_tv/media/dvb/dvb-frontend-parameters.rst Normal file
View File

@ -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 <FE_GET_PROPERTY>`
ioctl's. The new API is flexible enough to add new parameters to
existing delivery systems, and to add newer delivery systems.
So, newer applications should use
:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
instead, in order to be able to support the newer System Delivery like
DVB-S2, DVB-T2, DVB-C2, ISDB, etc.
All kinds of parameters are combined as an union in the
FrontendParameters structure:
.. code-block:: c
struct dvb_frontend_parameters {
uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */
/* intermediate frequency in kHz for QPSK */
fe_spectral_inversion_t inversion;
union {
struct dvb_qpsk_parameters qpsk;
struct dvb_qam_parameters qam;
struct dvb_ofdm_parameters ofdm;
struct dvb_vsb_parameters vsb;
} u;
};
In the case of QPSK frontends the ``frequency`` field specifies the
intermediate frequency, i.e. the offset which is effectively added to
the local oscillator frequency (LOF) of the LNB. The intermediate
frequency has to be specified in units of kHz. For QAM and OFDM
frontends the ``frequency`` specifies the absolute frequency and is
given in Hz.
.. _dvb-qpsk-parameters:
QPSK parameters
===============
For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters``
structure:
.. code-block:: c
struct dvb_qpsk_parameters {
uint32_t symbol_rate; /* symbol rate in Symbols per second */
fe_code_rate_t fec_inner; /* forward error correction (see above) */
};
.. _dvb-qam-parameters:
QAM parameters
==============
for cable QAM frontend you use the ``dvb_qam_parameters`` structure:
.. code-block:: c
struct dvb_qam_parameters {
uint32_t symbol_rate; /* symbol rate in Symbols per second */
fe_code_rate_t fec_inner; /* forward error correction (see above) */
fe_modulation_t modulation; /* modulation type (see above) */
};
.. _dvb-vsb-parameters:
VSB parameters
==============
ATSC frontends are supported by the ``dvb_vsb_parameters`` structure:
.. code-block:: c
struct dvb_vsb_parameters {
fe_modulation_t modulation; /* modulation type (see above) */
};
.. _dvb-ofdm-parameters:
OFDM parameters
===============
DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure:
.. code-block:: c
struct dvb_ofdm_parameters {
fe_bandwidth_t bandwidth;
fe_code_rate_t code_rate_HP; /* high priority stream code rate */
fe_code_rate_t code_rate_LP; /* low priority stream code rate */
fe_modulation_t constellation; /* modulation type (see above) */
fe_transmit_mode_t transmission_mode;
fe_guard_interval_t guard_interval;
fe_hierarchy_t hierarchy_information;
};
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

95
Documentation/linux_tv/media/dvb/dvbapi.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

21
Documentation/linux_tv/media/dvb/dvbproperty-006.rst Normal file
View File

@ -0,0 +1,21 @@
.. -*- coding: utf-8; mode: rst -*-
**************
Property types
**************
On :ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>`,
the actual action is determined by the dtv_property cmd/data pairs.
With one single ioctl, is possible to get/set up to 64 properties. The
actual meaning of each property is described on the next sections.
The available frontend property types are shown on the next section.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

122
Documentation/linux_tv/media/dvb/dvbproperty.rst Normal file
View File

@ -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 <dvb-frontend-parameters>`.
This got replaced on version 5 (also called "S2API", as this API were
added originally_enabled to provide support for DVB-S2), because the
old API has a very limited support to new standards and new hardware.
This section describes the new and recommended way to set the frontend,
with suppports all digital TV delivery systems.
Example: with the properties based approach, in order to set the tuner
to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and
symbol rate of 5.217 Mbauds, those properties should be sent to
:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` =
SYS_DVBC_ANNEX_A
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
- :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
- :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
- :ref:`DTV_TUNE <DTV-TUNE>`
The code that would do the above is:
.. code-block:: c
#include <stdio.h>
#include <fcntl.h>
#include <sys/ioctl.h>
#include <linux/dvb/frontend.h>
static struct dtv_property props[] = {
{ .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
{ .cmd = DTV_FREQUENCY, .u.data = 651000000 },
{ .cmd = DTV_MODULATION, .u.data = QAM_256 },
{ .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO },
{ .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 },
{ .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 },
{ .cmd = DTV_TUNE }
};
static struct dtv_properties dtv_prop = {
.num = 6, .props = props
};
int main(void)
{
int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
if (!fd) {
perror ("open");
return -1;
}
if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
perror("ioctl");
return -1;
}
printf("Frontend set\\n");
return 0;
}
NOTE: While it is possible to directly call the Kernel code like the
above example, it is strongly recommended to use
`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
provides abstraction to work with the supported digital TV standards and
provides methods for usual operations like program scanning and to
read/write channel descriptor files.
.. toctree::
:maxdepth: 1
dtv-stats
dtv-fe-stats
dtv-property
dtv-properties
dvbproperty-006
fe_property_parameters
frontend-stat-properties
frontend-property-terrestrial-systems
frontend-property-cable-systems
frontend-property-satellite-systems
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

391
Documentation/linux_tv/media/dvb/examples.rst Normal file
View File

@ -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 <https://linuxtv.org/docs/libdvbv5/index.html>`__ for
updated/recommended examples.
.. _tuning:
Tuning
======
We will start with a generic tuning subroutine that uses the frontend
and SEC, as well as the demux devices. The example is given for QPSK
tuners, but can easily be adjusted for QAM.
.. code-block:: c
#include <sys/ioctl.h>
#include <stdio.h>
#include <stdint.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <time.h>
#include <unistd.h>
#include <linux/dvb/dmx.h>
#include <linux/dvb/frontend.h>
#include <linux/dvb/sec.h>
#include <sys/poll.h>
#define DMX "/dev/dvb/adapter0/demux1"
#define FRONT "/dev/dvb/adapter0/frontend1"
#define SEC "/dev/dvb/adapter0/sec1"
/* routine for checking if we have a signal and other status information*/
int FEReadStatus(int fd, fe_status_t *stat)
{
int ans;
if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){
perror("FE READ STATUS: ");
return -1;
}
if (*stat & FE_HAS_POWER)
printf("FE HAS POWER\\n");
if (*stat & FE_HAS_SIGNAL)
printf("FE HAS SIGNAL\\n");
if (*stat & FE_SPECTRUM_INV)
printf("SPEKTRUM INV\\n");
return 0;
}
/* tune qpsk */
/* freq: frequency of transponder */
/* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */
/* diseqc: DiSEqC address of the used LNB */
/* pol: Polarisation */
/* srate: Symbol Rate */
/* fec. FEC */
/* lnb_lof1: local frequency of lower LNB band */
/* lnb_lof2: local frequency of upper LNB band */
/* lnb_slof: switch frequency of LNB */
int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
int diseqc, int pol, int srate, int fec, int lnb_lof1,
int lnb_lof2, int lnb_slof)
{
struct secCommand scmd;
struct secCmdSequence scmds;
struct dmx_pes_filter_params pesFilterParams;
FrontendParameters frp;
struct pollfd pfd[1];
FrontendEvent event;
int demux1, demux2, demux3, front;
frequency = (uint32_t) freq;
symbolrate = (uint32_t) srate;
if((front = open(FRONT,O_RDWR)) < 0){
perror("FRONTEND DEVICE: ");
return -1;
}
if((sec = open(SEC,O_RDWR)) < 0){
perror("SEC DEVICE: ");
return -1;
}
if (demux1 < 0){
if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
< 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
if (demux2 < 0){
if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
< 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
if (demux3 < 0){
if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
< 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
if (freq < lnb_slof) {
frp.Frequency = (freq - lnb_lof1);
scmds.continuousTone = SEC_TONE_OFF;
} else {
frp.Frequency = (freq - lnb_lof2);
scmds.continuousTone = SEC_TONE_ON;
}
frp.Inversion = INVERSION_AUTO;
if (pol) scmds.voltage = SEC_VOLTAGE_18;
else scmds.voltage = SEC_VOLTAGE_13;
scmd.type=0;
scmd.u.diseqc.addr=0x10;
scmd.u.diseqc.cmd=0x38;
scmd.u.diseqc.numParams=1;
scmd.u.diseqc.params[0] = 0xF0 | ((diseqc * 4) & 0x0F) |
(scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
(scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
scmds.miniCommand=SEC_MINI_NONE;
scmds.numCommands=1;
scmds.commands=&scmd;
if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
perror("SEC SEND: ");
return -1;
}
if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
perror("SEC SEND: ");
return -1;
}
frp.u.qpsk.SymbolRate = srate;
frp.u.qpsk.FEC_inner = fec;
if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){
perror("QPSK TUNE: ");
return -1;
}
pfd[0].fd = front;
pfd[0].events = POLLIN;
if (poll(pfd,1,3000)){
if (pfd[0].revents & POLLIN){
printf("Getting QPSK event\\n");
if ( ioctl(front, FE_GET_EVENT, &event)
== -EOVERFLOW){
perror("qpsk get event");
return -1;
}
printf("Received ");
switch(event.type){
case FE_UNEXPECTED_EV:
printf("unexpected event\\n");
return -1;
case FE_FAILURE_EV:
printf("failure event\\n");
return -1;
case FE_COMPLETION_EV:
printf("completion event\\n");
}
}
}
pesFilterParams.pid = vpid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_DECODER;
pesFilterParams.pes_type = DMX_PES_VIDEO;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
perror("set_vpid");
return -1;
}
pesFilterParams.pid = apid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_DECODER;
pesFilterParams.pes_type = DMX_PES_AUDIO;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
perror("set_apid");
return -1;
}
pesFilterParams.pid = tpid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_DECODER;
pesFilterParams.pes_type = DMX_PES_TELETEXT;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
perror("set_tpid");
return -1;
}
return has_signal(fds);
}
The program assumes that you are using a universal LNB and a standard
DiSEqC switch with up to 4 addresses. Of course, you could build in some
more checking if tuning was successful and maybe try to repeat the
tuning process. Depending on the external hardware, i.e. LNB and DiSEqC
switch, and weather conditions this may be necessary.
.. _the_dvr_device:
The DVR device
==============
The following program code shows how to use the DVR device for
recording.
.. code-block:: c
#include <sys/ioctl.h>
#include <stdio.h>
#include <stdint.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <time.h>
#include <unistd.h>
#include <linux/dvb/dmx.h>
#include <linux/dvb/video.h>
#include <sys/poll.h>
#define DVR "/dev/dvb/adapter0/dvr1"
#define AUDIO "/dev/dvb/adapter0/audio1"
#define VIDEO "/dev/dvb/adapter0/video1"
#define BUFFY (188*20)
#define MAX_LENGTH (1024*1024*5) /* record 5MB */
/* switch the demuxes to recording, assuming the transponder is tuned */
/* demux1, demux2: file descriptor of video and audio filters */
/* vpid, apid: PIDs of video and audio channels */
int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
{
struct dmx_pes_filter_params pesFilterParams;
if (demux1 < 0){
if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
< 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
if (demux2 < 0){
if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
< 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
pesFilterParams.pid = vpid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_TS_TAP;
pesFilterParams.pes_type = DMX_PES_VIDEO;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
perror("DEMUX DEVICE");
return -1;
}
pesFilterParams.pid = apid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_TS_TAP;
pesFilterParams.pes_type = DMX_PES_AUDIO;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
perror("DEMUX DEVICE");
return -1;
}
return 0;
}
/* start recording MAX_LENGTH , assuming the transponder is tuned */
/* demux1, demux2: file descriptor of video and audio filters */
/* vpid, apid: PIDs of video and audio channels */
int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
{
int i;
int len;
int written;
uint8_t buf[BUFFY];
uint64_t length;
struct pollfd pfd[1];
int dvr, dvr_out;
/* open dvr device */
if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){
perror("DVR DEVICE");
return -1;
}
/* switch video and audio demuxes to dvr */
printf ("Switching dvr on\\n");
i = switch_to_record(demux1, demux2, vpid, apid);
printf("finished: ");
printf("Recording %2.0f MB of test file in TS format\\n",
MAX_LENGTH/(1024.0*1024.0));
length = 0;
/* open output file */
if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
|O_TRUNC, S_IRUSR|S_IWUSR
|S_IRGRP|S_IWGRP|S_IROTH|
S_IWOTH)) < 0){
perror("Can't open file for dvr test");
return -1;
}
pfd[0].fd = dvr;
pfd[0].events = POLLIN;
/* poll for dvr data and write to file */
while (length < MAX_LENGTH ) {
if (poll(pfd,1,1)){
if (pfd[0].revents & POLLIN){
len = read(dvr, buf, BUFFY);
if (len < 0){
perror("recording");
return -1;
}
if (len > 0){
written = 0;
while (written < len)
written +=
write (dvr_out,
buf, len);
length += len;
printf("written %2.0f MB\\r",
length/1024./1024.);
}
}
}
}
return 0;
}
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

88
Documentation/linux_tv/media/dvb/fe-bandwidth-t.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

88
Documentation/linux_tv/media/dvb/fe-diseqc-recv-slave-reply.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_DISEQC_RECV_SLAVE_REPLY
``argp``
pointer to struct
:ref:`dvb_diseqc_slave_reply <dvb-diseqc-slave-reply>`
Description
===========
Receives reply from a DiSEqC 2.0 command.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _dvb-diseqc-slave-reply:
.. flat-table:: struct dvb_diseqc_slave_reply
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
- .. row 1
- uint8_t
- msg[4]
- DiSEqC message (framing, data[3])
- .. row 2
- uint8_t
- msg_len
- Length of the DiSEqC message. Valid values are 0 to 4, where 0
means no msg
- .. row 3
- int
- timeout
- Return from ioctl after timeout ms with errorcode when no message
was received
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

51
Documentation/linux_tv/media/dvb/fe-diseqc-reset-overload.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_DISEQC_RESET_OVERLOAD
Description
===========
If the bus has been automatically powered off due to power overload,
this ioctl call restores the power to the bus. The call requires
read/write access to the device. This call has no effect if the device
is manually powered off. Not all DVB adapters support this ioctl.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

93
Documentation/linux_tv/media/dvb/fe-diseqc-send-burst.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_DISEQC_SEND_BURST
``tone``
pointer to enum :ref:`fe_sec_mini_cmd <fe-sec-mini-cmd>`
Description
===========
This ioctl is used to set the generation of a 22kHz tone burst for mini
DiSEqC satellite selection for 2x1 switches. This call requires
read/write permissions.
It provides support for what's specified at
`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. <http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf>`__
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _fe-sec-mini-cmd-t:
enum fe_sec_mini_cmd
====================
.. _fe-sec-mini-cmd:
.. flat-table:: enum fe_sec_mini_cmd
:header-rows: 1
:stub-columns: 0
- .. row 1
- ID
- Description
- .. row 2
- .. _`SEC-MINI-A`:
``SEC_MINI_A``
- Sends a mini-DiSEqC 22kHz '0' Tone Burst to select satellite-A
- .. row 3
- .. _`SEC-MINI-B`:
``SEC_MINI_B``
- Sends a mini-DiSEqC 22kHz '1' Data Burst to select satellite-B
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

78
Documentation/linux_tv/media/dvb/fe-diseqc-send-master-cmd.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_DISEQC_SEND_MASTER_CMD
``argp``
pointer to struct
:ref:`dvb_diseqc_master_cmd <dvb-diseqc-master-cmd>`
Description
===========
Sends a DiSEqC command to the antenna subsystem.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _dvb-diseqc-master-cmd:
.. flat-table:: struct dvb_diseqc_master_cmd
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
- .. row 1
- uint8_t
- msg[6]
- DiSEqC message (framing, address, command, data[3])
- .. row 2
- uint8_t
- msg_len
- Length of the DiSEqC message. Valid values are 3 to 6
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

58
Documentation/linux_tv/media/dvb/fe-enable-high-lnb-voltage.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_ENABLE_HIGH_LNB_VOLTAGE
``high``
Valid flags:
- 0 - normal 13V and 18V.
- >0 - enables slightly higher voltages instead of 13/18V, in order
to compensate for long antenna cables.
Description
===========
Select output DC level between normal LNBf voltages or higher LNBf
voltages between 0 (normal) or a value grater than 0 for higher
voltages.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

434
Documentation/linux_tv/media/dvb/fe-get-info.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_GET_INFO
``argp``
pointer to struct struct
:ref:`dvb_frontend_info <dvb-frontend-info>`
Description
===========
All DVB frontend devices support the ``FE_GET_INFO`` ioctl. It is used
to identify kernel devices compatible with this specification and to
obtain information about driver and hardware capabilities. The ioctl
takes a pointer to dvb_frontend_info which is filled by the driver.
When the driver is not compatible with this specification the ioctl
returns an error.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _dvb-frontend-info:
.. flat-table:: struct dvb_frontend_info
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
- .. row 1
- char
- name[128]
- Name of the frontend
- .. row 2
- fe_type_t
- type
- **DEPRECATED**. DVBv3 type. Should not be used on modern programs,
as a frontend may have more than one type. So, the DVBv5 API
should be used instead to enumerate and select the frontend type.
- .. row 3
- uint32_t
- frequency_min
- Minimal frequency supported by the frontend
- .. row 4
- uint32_t
- frequency_max
- Maximal frequency supported by the frontend
- .. row 5
- uint32_t
- frequency_stepsize
- Frequency step - all frequencies are multiple of this value
- .. row 6
- uint32_t
- frequency_tolerance
- Tolerance of the frequency
- .. row 7
- uint32_t
- symbol_rate_min
- Minimal symbol rate (for Cable/Satellite systems), in bauds
- .. row 8
- uint32_t
- symbol_rate_max
- Maximal symbol rate (for Cable/Satellite systems), in bauds
- .. row 9
- uint32_t
- symbol_rate_tolerance
- Maximal symbol rate tolerance, in ppm
- .. row 10
- uint32_t
- notifier_delay
- **DEPRECATED**. Not used by any driver.
- .. row 11
- enum :ref:`fe_caps <fe-caps>`
- caps
- Capabilities supported by the frontend
NOTE: The frequencies are specified in Hz for Terrestrial and Cable
systems. They're specified in kHz for Satellite systems
.. _fe-caps-t:
frontend capabilities
=====================
Capabilities describe what a frontend can do. Some capabilities are
supported only on some specific frontend types.
.. _fe-caps:
.. flat-table:: enum fe_caps
:header-rows: 1
:stub-columns: 0
- .. row 1
- ID
- Description
- .. row 2
- .. _`FE-IS-STUPID`:
``FE_IS_STUPID``
- There's something wrong at the frontend, and it can't report its
capabilities
- .. row 3
- .. _`FE-CAN-INVERSION-AUTO`:
``FE_CAN_INVERSION_AUTO``
- The frontend is capable of auto-detecting inversion
- .. row 4
- .. _`FE-CAN-FEC-1-2`:
``FE_CAN_FEC_1_2``
- The frontend supports FEC 1/2
- .. row 5
- .. _`FE-CAN-FEC-2-3`:
``FE_CAN_FEC_2_3``
- The frontend supports FEC 2/3
- .. row 6
- .. _`FE-CAN-FEC-3-4`:
``FE_CAN_FEC_3_4``
- The frontend supports FEC 3/4
- .. row 7
- .. _`FE-CAN-FEC-4-5`:
``FE_CAN_FEC_4_5``
- The frontend supports FEC 4/5
- .. row 8
- .. _`FE-CAN-FEC-5-6`:
``FE_CAN_FEC_5_6``
- The frontend supports FEC 5/6
- .. row 9
- .. _`FE-CAN-FEC-6-7`:
``FE_CAN_FEC_6_7``
- The frontend supports FEC 6/7
- .. row 10
- .. _`FE-CAN-FEC-7-8`:
``FE_CAN_FEC_7_8``
- The frontend supports FEC 7/8
- .. row 11
- .. _`FE-CAN-FEC-8-9`:
``FE_CAN_FEC_8_9``
- The frontend supports FEC 8/9
- .. row 12
- .. _`FE-CAN-FEC-AUTO`:
``FE_CAN_FEC_AUTO``
- The frontend can autodetect FEC.
- .. row 13
- .. _`FE-CAN-QPSK`:
``FE_CAN_QPSK``
- The frontend supports QPSK modulation
- .. row 14
- .. _`FE-CAN-QAM-16`:
``FE_CAN_QAM_16``
- The frontend supports 16-QAM modulation
- .. row 15
- .. _`FE-CAN-QAM-32`:
``FE_CAN_QAM_32``
- The frontend supports 32-QAM modulation
- .. row 16
- .. _`FE-CAN-QAM-64`:
``FE_CAN_QAM_64``
- The frontend supports 64-QAM modulation
- .. row 17
- .. _`FE-CAN-QAM-128`:
``FE_CAN_QAM_128``
- The frontend supports 128-QAM modulation
- .. row 18
- .. _`FE-CAN-QAM-256`:
``FE_CAN_QAM_256``
- The frontend supports 256-QAM modulation
- .. row 19
- .. _`FE-CAN-QAM-AUTO`:
``FE_CAN_QAM_AUTO``
- The frontend can autodetect modulation
- .. row 20
- .. _`FE-CAN-TRANSMISSION-MODE-AUTO`:
``FE_CAN_TRANSMISSION_MODE_AUTO``
- The frontend can autodetect the transmission mode
- .. row 21
- .. _`FE-CAN-BANDWIDTH-AUTO`:
``FE_CAN_BANDWIDTH_AUTO``
- The frontend can autodetect the bandwidth
- .. row 22
- .. _`FE-CAN-GUARD-INTERVAL-AUTO`:
``FE_CAN_GUARD_INTERVAL_AUTO``
- The frontend can autodetect the guard interval
- .. row 23
- .. _`FE-CAN-HIERARCHY-AUTO`:
``FE_CAN_HIERARCHY_AUTO``
- The frontend can autodetect hierarch
- .. row 24
- .. _`FE-CAN-8VSB`:
``FE_CAN_8VSB``
- The frontend supports 8-VSB modulation
- .. row 25
- .. _`FE-CAN-16VSB`:
``FE_CAN_16VSB``
- The frontend supports 16-VSB modulation
- .. row 26
- .. _`FE-HAS-EXTENDED-CAPS`:
``FE_HAS_EXTENDED_CAPS``
- Currently, unused
- .. row 27
- .. _`FE-CAN-MULTISTREAM`:
``FE_CAN_MULTISTREAM``
- The frontend supports multistream filtering
- .. row 28
- .. _`FE-CAN-TURBO-FEC`:
``FE_CAN_TURBO_FEC``
- The frontend supports turbo FEC modulation
- .. row 29
- .. _`FE-CAN-2G-MODULATION`:
``FE_CAN_2G_MODULATION``
- The frontend supports "2nd generation modulation" (DVB-S2/T2)>
- .. row 30
- .. _`FE-NEEDS-BENDING`:
``FE_NEEDS_BENDING``
- Not supported anymore, don't use it
- .. row 31
- .. _`FE-CAN-RECOVER`:
``FE_CAN_RECOVER``
- The frontend can recover from a cable unplug automatically
- .. row 32
- .. _`FE-CAN-MUTE-TS`:
``FE_CAN_MUTE_TS``
- The frontend can stop spurious TS data output
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

75
Documentation/linux_tv/media/dvb/fe-get-property.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_SET_PROPERTY, FE_GET_PROPERTY
``argp``
pointer to struct :ref:`dtv_properties <dtv-properties>`
Description
===========
All DVB frontend devices support the ``FE_SET_PROPERTY`` and
``FE_GET_PROPERTY`` ioctls. The supported properties and statistics
depends on the delivery system and on the device:
- ``FE_SET_PROPERTY:``
- This ioctl is used to set one or more frontend properties.
- This is the basic command to request the frontend to tune into
some frequency and to start decoding the digital TV signal.
- This call requires read/write access to the device.
- At return, the values are updated to reflect the actual parameters
used.
- ``FE_GET_PROPERTY:``
- This ioctl is used to get properties and statistics from the
frontend.
- No properties are changed, and statistics aren't reset.
- This call only requires read-only access to the device.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

143
Documentation/linux_tv/media/dvb/fe-read-status.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_READ_STATUS
``status``
pointer to a bitmask integer filled with the values defined by enum
:ref:`fe_status <fe-status>`.
Description
===========
All DVB frontend devices support the ``FE_READ_STATUS`` ioctl. It is
used to check about the locking status of the frontend after being
tuned. The ioctl takes a pointer to an integer where the status will be
written.
NOTE: the size of status is actually sizeof(enum fe_status), with
varies according with the architecture. This needs to be fixed in the
future.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _fe-status-t:
int fe_status
=============
The fe_status parameter is used to indicate the current state and/or
state changes of the frontend hardware. It is produced using the enum
:ref:`fe_status <fe-status>` values on a bitmask
.. _fe-status:
.. flat-table:: enum fe_status
:header-rows: 1
:stub-columns: 0
- .. row 1
- ID
- Description
- .. row 2
- .. _`FE-HAS-SIGNAL`:
``FE_HAS_SIGNAL``
- The frontend has found something above the noise level
- .. row 3
- .. _`FE-HAS-CARRIER`:
``FE_HAS_CARRIER``
- The frontend has found a DVB signal
- .. row 4
- .. _`FE-HAS-VITERBI`:
``FE_HAS_VITERBI``
- The frontend FEC inner coding (Viterbi, LDPC or other inner code)
is stable
- .. row 5
- .. _`FE-HAS-SYNC`:
``FE_HAS_SYNC``
- Synchronization bytes was found
- .. row 6
- .. _`FE-HAS-LOCK`:
``FE_HAS_LOCK``
- The DVB were locked and everything is working
- .. row 7
- .. _`FE-TIMEDOUT`:
``FE_TIMEDOUT``
- no lock within the last about 2 seconds
- .. row 8
- .. _`FE-REINIT`:
``FE_REINIT``
- The frontend was reinitialized, application is recommended to
reset DiSEqC, tone and parameters
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

60
Documentation/linux_tv/media/dvb/fe-set-frontend-tune-mode.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_SET_FRONTEND_TUNE_MODE
``flags``
Valid flags:
- 0 - normal tune mode
- FE_TUNE_MODE_ONESHOT - When set, this flag will disable any
zigzagging or other "normal" tuning behaviour. Additionally,
there will be no automatic monitoring of the lock status, and
hence no frontend events will be generated. If a frontend device
is closed, this flag will be automatically turned off when the
device is reopened read-write.
Description
===========
Allow setting tuner mode flags to the frontend, between 0 (normal) or
FE_TUNE_MODE_ONESHOT mode
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

100
Documentation/linux_tv/media/dvb/fe-set-tone.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_SET_TONE
``tone``
pointer to enum :ref:`fe_sec_tone_mode <fe-sec-tone-mode>`
Description
===========
This ioctl is used to set the generation of the continuous 22kHz tone.
This call requires read/write permissions.
Usually, satellite antenna subsystems require that the digital TV device
to send a 22kHz tone in order to select between high/low band on some
dual-band LNBf. It is also used to send signals to DiSEqC equipment, but
this is done using the DiSEqC ioctls.
NOTE: if more than one device is connected to the same antenna, setting
a tone may interfere on other devices, as they may lose the capability
of selecting the band. So, it is recommended that applications would
change to SEC_TONE_OFF when the device is not used.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _fe-sec-tone-mode-t:
enum fe_sec_tone_mode
=====================
.. _fe-sec-tone-mode:
.. flat-table:: enum fe_sec_tone_mode
:header-rows: 1
:stub-columns: 0
- .. row 1
- ID
- Description
- .. row 2
- .. _`SEC-TONE-ON`:
``SEC_TONE_ON``
- Sends a 22kHz tone burst to the antenna
- .. row 3
- .. _`SEC-TONE-OFF`:
``SEC_TONE_OFF``
- Don't send a 22kHz tone to the antenna (except if the
FE_DISEQC_* ioctls are called)
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

68
Documentation/linux_tv/media/dvb/fe-set-voltage.rst Normal file
View File

@ -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() <frontend_f_open>`.
``request``
FE_SET_VOLTAGE
``voltage``
pointer to enum :ref:`fe_sec_voltage <fe-sec-voltage>`
Valid values are described at enum
:ref:`fe_sec_voltage <fe-sec-voltage>`.
Description
===========
This ioctl allows to set the DC voltage level sent through the antenna
cable to 13V, 18V or off.
Usually, a satellite antenna subsystems require that the digital TV
device to send a DC voltage to feed power to the LNBf. Depending on the
LNBf type, the polarization or the intermediate frequency (IF) of the
LNBf can controlled by the voltage level. Other devices (for example,
the ones that implement DISEqC and multipoint LNBf's don't need to
control the voltage level, provided that either 13V or 18V is sent to
power up the LNBf.
NOTE: if more than one device is connected to the same antenna, setting
a voltage level may interfere on other devices, as they may lose the
capability of setting polarization or IF. So, on those cases, setting
the voltage to SEC_VOLTAGE_OFF while the device is not is used is
recommended.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

100
Documentation/linux_tv/media/dvb/fe-type-t.rst Normal file
View File

@ -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 <DTV-DELIVERY-SYSTEM>` equivalent
type
- .. row 2
- .. _`FE-QPSK`:
``FE_QPSK``
- For DVB-S standard
- ``SYS_DVBS``
- .. row 3
- .. _`FE-QAM`:
``FE_QAM``
- For DVB-C annex A standard
- ``SYS_DVBC_ANNEX_A``
- .. row 4
- .. _`FE-OFDM`:
``FE_OFDM``
- For DVB-T standard
- ``SYS_DVBT``
- .. row 5
- .. _`FE-ATSC`:
``FE_ATSC``
- For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used
in US.
- ``SYS_ATSC`` (terrestrial) or ``SYS_DVBC_ANNEX_B`` (cable)
Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described
at the above, as they're supported via the new
:ref:`FE_GET_PROPERTY/FE_GET_SET_PROPERTY <FE_GET_PROPERTY>`
ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
parameter.
In the old days, struct :ref:`dvb_frontend_info <dvb-frontend-info>`
used to contain ``fe_type_t`` field to indicate the delivery systems,
filled with either FE_QPSK, FE_QAM, FE_OFDM or FE_ATSC. While this
is still filled to keep backward compatibility, the usage of this field
is deprecated, as it can report just one delivery system, but some
devices support multiple delivery systems. Please use
:ref:`DTV_ENUM_DELSYS <DTV-ENUM-DELSYS>` instead.
On devices that support multiple delivery systems, struct
:ref:`dvb_frontend_info <dvb-frontend-info>`::``fe_type_t`` is
filled with the currently standard, as selected by the last call to
:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` using the
:ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` property.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

1976
Documentation/linux_tv/media/dvb/fe_property_parameters.rst Normal file
View File

File diff suppressed because it is too large Load Diff

84
Documentation/linux_tv/media/dvb/frontend-property-cable-systems.rst Normal file
View File

@ -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 <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_MODULATION <DTV-MODULATION>`
- :ref:`DTV_INVERSION <DTV-INVERSION>`
- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
- :ref:`DTV_LNA <DTV-LNA>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. _dvbc-annex-b-params:
DVB-C Annex B delivery system
=============================
The DVB-C Annex-B is only used on a few Countries like the United
States.
The following parameters are valid for DVB-C Annex B:
- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_MODULATION <DTV-MODULATION>`
- :ref:`DTV_INVERSION <DTV-INVERSION>`
- :ref:`DTV_LNA <DTV-LNA>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

112
Documentation/linux_tv/media/dvb/frontend-property-satellite-systems.rst Normal file
View File

@ -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 <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_INVERSION <DTV-INVERSION>`
- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>`
- :ref:`DTV_TONE <DTV-TONE>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
Future implementations might add those two missing parameters:
- :ref:`DTV_DISEQC_MASTER <DTV-DISEQC-MASTER>`
- :ref:`DTV_DISEQC_SLAVE_REPLY <DTV-DISEQC-SLAVE-REPLY>`
.. _dvbs2-params:
DVB-S2 delivery system
======================
In addition to all parameters valid for DVB-S, DVB-S2 supports the
following parameters:
- :ref:`DTV_MODULATION <DTV-MODULATION>`
- :ref:`DTV_PILOT <DTV-PILOT>`
- :ref:`DTV_ROLLOFF <DTV-ROLLOFF>`
- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. _turbo-params:
Turbo code delivery system
==========================
In addition to all parameters valid for DVB-S, turbo code supports the
following parameters:
- :ref:`DTV_MODULATION <DTV-MODULATION>`
.. _isdbs-params:
ISDB-S delivery system
======================
The following parameters are valid for ISDB-S:
- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_INVERSION <DTV-INVERSION>`
- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>`
- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

303
Documentation/linux_tv/media/dvb/frontend-property-terrestrial-systems.rst Normal file
View File

@ -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 <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_MODULATION <DTV-MODULATION>`
- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
- :ref:`DTV_INVERSION <DTV-INVERSION>`
- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`
- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`
- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`
- :ref:`DTV_LNA <DTV-LNA>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. _dvbt2-params:
DVB-T2 delivery system
======================
DVB-T2 support is currently in the early stages of development, so
expect that this section maygrow and become more detailed with time.
The following parameters are valid for DVB-T2:
- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_MODULATION <DTV-MODULATION>`
- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
- :ref:`DTV_INVERSION <DTV-INVERSION>`
- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`
- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`
- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`
- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
- :ref:`DTV_LNA <DTV-LNA>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. _isdbt:
ISDB-T delivery system
======================
This ISDB-T/ISDB-Tsb API extension should reflect all information needed
to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some
very sophisticated devices won't need certain parameters to tune.
The information given here should help application writers to know how
to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.
The details given here about ISDB-T and ISDB-Tsb are just enough to
basically show the dependencies between the needed parameter values, but
surely some information is left out. For more detailed information see
the following documents:
ARIB STD-B31 - "Transmission System for Digital Terrestrial Television
Broadcasting" and
ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television
Broadcasting".
In order to understand the ISDB specific parameters, one has to have
some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has
to be known to the reader that an ISDB-T channel consists of 13
segments, that it can have up to 3 layer sharing those segments, and
things like that.
The following parameters are valid for ISDB-T:
- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
- :ref:`DTV_INVERSION <DTV-INVERSION>`
- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
- :ref:`DTV_ISDBT_LAYER_ENABLED <DTV-ISDBT-LAYER-ENABLED>`
- :ref:`DTV_ISDBT_PARTIAL_RECEPTION <DTV-ISDBT-PARTIAL-RECEPTION>`
- :ref:`DTV_ISDBT_SOUND_BROADCASTING <DTV-ISDBT-SOUND-BROADCASTING>`
- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID <DTV-ISDBT-SB-SUBCHANNEL-ID>`
- :ref:`DTV_ISDBT_SB_SEGMENT_IDX <DTV-ISDBT-SB-SEGMENT-IDX>`
- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT <DTV-ISDBT-SB-SEGMENT-COUNT>`
- :ref:`DTV_ISDBT_LAYERA_FEC <DTV-ISDBT-LAYER-FEC>`
- :ref:`DTV_ISDBT_LAYERA_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
- :ref:`DTV_ISDBT_LAYERB_FEC <DTV-ISDBT-LAYER-FEC>`
- :ref:`DTV_ISDBT_LAYERB_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
- :ref:`DTV_ISDBT_LAYERC_FEC <DTV-ISDBT-LAYER-FEC>`
- :ref:`DTV_ISDBT_LAYERC_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. _atsc-params:
ATSC delivery system
====================
The following parameters are valid for ATSC:
- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_MODULATION <DTV-MODULATION>`
- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. _atscmh-params:
ATSC-MH delivery system
=======================
The following parameters are valid for ATSC-MH:
- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
- :ref:`DTV_ATSCMH_FIC_VER <DTV-ATSCMH-FIC-VER>`
- :ref:`DTV_ATSCMH_PARADE_ID <DTV-ATSCMH-PARADE-ID>`
- :ref:`DTV_ATSCMH_NOG <DTV-ATSCMH-NOG>`
- :ref:`DTV_ATSCMH_TNOG <DTV-ATSCMH-TNOG>`
- :ref:`DTV_ATSCMH_SGN <DTV-ATSCMH-SGN>`
- :ref:`DTV_ATSCMH_PRC <DTV-ATSCMH-PRC>`
- :ref:`DTV_ATSCMH_RS_FRAME_MODE <DTV-ATSCMH-RS-FRAME-MODE>`
- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE <DTV-ATSCMH-RS-FRAME-ENSEMBLE>`
- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI <DTV-ATSCMH-RS-CODE-MODE-PRI>`
- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC <DTV-ATSCMH-RS-CODE-MODE-SEC>`
- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE <DTV-ATSCMH-SCCC-BLOCK-MODE>`
- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A <DTV-ATSCMH-SCCC-CODE-MODE-A>`
- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B <DTV-ATSCMH-SCCC-CODE-MODE-B>`
- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C <DTV-ATSCMH-SCCC-CODE-MODE-C>`
- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D <DTV-ATSCMH-SCCC-CODE-MODE-D>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. _dtmb-params:
DTMB delivery system
====================
The following parameters are valid for DTMB:
- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
- :ref:`DTV_TUNE <DTV-TUNE>`
- :ref:`DTV_CLEAR <DTV-CLEAR>`
- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
- :ref:`DTV_MODULATION <DTV-MODULATION>`
- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
- :ref:`DTV_INVERSION <DTV-INVERSION>`
- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
- :ref:`DTV_INTERLEAVING <DTV-INTERLEAVING>`
- :ref:`DTV_LNA <DTV-LNA>`
In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

254
Documentation/linux_tv/media/dvb/frontend-stat-properties.rst Normal file
View File

@ -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 <dtv-stats>` array refers
to the global metric. The other elements of the array represent each
layer, starting from layer A(index 1), layer B (index 2) and so on.
The number of filled elements are stored at ``dtv_property.stat.len``.
Each element of the ``dtv_property.stat.dtv_stats`` array consists on
two elements:
- ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of
the measure (dB measures) and ``uvalue`` is for unsigned values
(counters, relative scale)
- ``scale`` - Scale for the value. It can be:
- ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the
frontend, but it was not possible to collect it (could be a
transitory or permanent condition)
- ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in
1/1000 dB
- ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0
means 0% and 65535 means 100%.
- ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts
the occurrence of an event, like bit error, block error, or lapsed
time.
.. _DTV-STAT-SIGNAL-STRENGTH:
DTV_STAT_SIGNAL_STRENGTH
========================
Indicates the signal strength level at the analog part of the tuner or
of the demod.
Possible scales for this metric are:
- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
measurement was not complete yet.
- ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power
measured in miliwatts. This value is generally negative.
- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
measurement for power (actually, 0 to 65535).
.. _DTV-STAT-CNR:
DTV_STAT_CNR
============
Indicates the Signal to Noise ratio for the main carrier.
Possible scales for this metric are:
- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
measurement was not complete yet.
- ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units.
- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
measurement for Signal/Noise (actually, 0 to 65535).
.. _DTV-STAT-PRE-ERROR-BIT-COUNT:
DTV_STAT_PRE_ERROR_BIT_COUNT
============================
Measures the number of bit errors before the forward error correction
(FEC) on the inner coding block (before Viterbi, LDPC or other inner
code).
This measure is taken during the same interval as
``DTV_STAT_PRE_TOTAL_BIT_COUNT``.
In order to get the BER (Bit Error Rate) measurement, it should be
divided by
:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.
This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.
Possible scales for this metric are:
- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
measurement was not complete yet.
- ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner
coding.
.. _DTV-STAT-PRE-TOTAL-BIT-COUNT:
DTV_STAT_PRE_TOTAL_BIT_COUNT
============================
Measures the amount of bits received before the inner code block, during
the same period as
:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
measurement was taken.
It should be noted that this measurement can be smaller than the total
amount of bits on the transport stream, as the frontend may need to
manually restart the measurement, losing some data between each
measurement interval.
This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.
Possible scales for this metric are:
- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
measurement was not complete yet.
- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`.
.. _DTV-STAT-POST-ERROR-BIT-COUNT:
DTV_STAT_POST_ERROR_BIT_COUNT
=============================
Measures the number of bit errors after the forward error correction
(FEC) done by inner code block (after Viterbi, LDPC or other inner
code).
This measure is taken during the same interval as
``DTV_STAT_POST_TOTAL_BIT_COUNT``.
In order to get the BER (Bit Error Rate) measurement, it should be
divided by
:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.
This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.
Possible scales for this metric are:
- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
measurement was not complete yet.
- ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner
coding.
.. _DTV-STAT-POST-TOTAL-BIT-COUNT:
DTV_STAT_POST_TOTAL_BIT_COUNT
=============================
Measures the amount of bits received after the inner coding, during the
same period as
:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
measurement was taken.
It should be noted that this measurement can be smaller than the total
amount of bits on the transport stream, as the frontend may need to
manually restart the measurement, losing some data between each
measurement interval.
This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.
Possible scales for this metric are:
- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
measurement was not complete yet.
- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`.
.. _DTV-STAT-ERROR-BLOCK-COUNT:
DTV_STAT_ERROR_BLOCK_COUNT
==========================
Measures the number of block errors after the outer forward error
correction coding (after Reed-Solomon or other outer code).
This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.
Possible scales for this metric are:
- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
measurement was not complete yet.
- ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer
coding.
.. _DTV-STAT-TOTAL-BLOCK-COUNT:
DTV-STAT_TOTAL_BLOCK_COUNT
==========================
Measures the total number of blocks received during the same period as
:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
measurement was taken.
It can be used to calculate the PER indicator, by dividing
:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` by
:ref:`DTV-STAT-TOTAL-BLOCK-COUNT <DTV-STAT-TOTAL-BLOCK-COUNT>`.
Possible scales for this metric are:
- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
measurement was not complete yet.
- ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring
:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

62
Documentation/linux_tv/media/dvb/frontend.rst Normal file
View File

@ -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 <http://www.eutelsat.com/satellites/4_5_5.html>`__.
.. toctree::
:maxdepth: 1
query-dvb-frontend-info
dvb-fe-read-status
dvbproperty
frontend_fcalls
frontend_legacy_dvbv3_api
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

55
Documentation/linux_tv/media/dvb/frontend_f_close.rst Normal file
View File

@ -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 <unistd.h>
.. c:function:: int close( int fd )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <func-open>`.
Description
===========
This system call closes a previously opened front-end device. After
closing a front-end device, its corresponding hardware might be powered
down automatically.
Return Value
============
The function returns 0 on success, -1 on failure and the ``errno`` is
set appropriately. Possible error codes:
EBADF
``fd`` is not a valid open file descriptor.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

108
Documentation/linux_tv/media/dvb/frontend_f_open.rst Normal file
View File

@ -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 <fcntl.h>
.. c:function:: int open( const char *device_name, int flags )
Arguments
=========
``device_name``
Device to be opened.
``flags``
Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``.
Multiple opens are allowed with ``O_RDONLY``. In this mode, only
query and read ioctls are allowed.
Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are
allowed.
When the ``O_NONBLOCK`` flag is given, the system calls may return
EAGAIN error code when no data is available or when the device
driver is temporarily busy.
Other flags have no effect.
Description
===========
This system call opens a named frontend device
(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
thing to do after a successful open is to find out the frontend type
with :ref:`FE_GET_INFO <FE_GET_INFO>`.
The device can be opened in read-only mode, which only allows monitoring
of device status and statistics, or read/write mode, which allows any
kind of use (e.g. performing tuning operations.)
In a system with multiple front-ends, it is usually the case that
multiple devices cannot be open in read/write mode simultaneously. As
long as a front-end device is opened in read/write mode, other open()
calls in read/write mode will either fail or block, depending on whether
non-blocking or blocking mode was specified. A front-end device opened
in blocking mode can later be put into non-blocking mode (and vice
versa) using the F_SETFL command of the fcntl system call. This is a
standard system call, documented in the Linux manual page for fcntl.
When an open() call has succeeded, the device will be ready for use in
the specified mode. This implies that the corresponding hardware is
powered up, and that other front-ends may have been powered down to make
that possible.
Return Value
============
On success :c:func:`open()` returns the new file descriptor. On error
-1 is returned, and the ``errno`` variable is set appropriately.
Possible error codes are:
EACCES
The caller has no permission to access the device.
EBUSY
The the device driver is already in use.
ENXIO
No device corresponding to this device special file exists.
ENOMEM
Not enough kernel memory was available to complete the request.
EMFILE
The process already has the maximum number of files open.
ENFILE
The limit on the total number of files open on the system has been
reached.
ENODEV
The device got removed.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

35
Documentation/linux_tv/media/dvb/frontend_fcalls.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

24
Documentation/linux_tv/media/dvb/frontend_h.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

49
Documentation/linux_tv/media/dvb/frontend_legacy_api.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

29
Documentation/linux_tv/media/dvb/frontend_legacy_dvbv3_api.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

204
Documentation/linux_tv/media/dvb/intro.rst Normal file
View File

@ -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 <linux/dvb/audio.h>
.. code-block:: c
#include <linux/dvb/ca.h>
.. code-block:: c
#include <linux/dvb/dmx.h>
.. code-block:: c
#include <linux/dvb/frontend.h>
.. code-block:: c
#include <linux/dvb/net.h>
.. code-block:: c
#include <linux/dvb/osd.h>
.. code-block:: c
#include <linux/dvb/video.h>
To enable applications to support different API version, an additional
include file ``linux/dvb/version.h`` exists, which defines the constant
``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

BIN
Documentation/linux_tv/media/dvb/intro_files/dvbstb.pdf Normal file
View File

Binary file not shown.

BIN
Documentation/linux_tv/media/dvb/intro_files/dvbstb.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

31
Documentation/linux_tv/media/dvb/legacy_dvb_apis.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

219
Documentation/linux_tv/media/dvb/net.rst Normal file
View File

@ -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) <http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation>`__
- `Ultra Lightweight Encapsulation (ULE) <http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation>`__
In order to create the Linux virtual network interfaces, an application
needs to tell to the Kernel what are the PIDs and the encapsulation
types that are present on the transport stream. This is done through
``/dev/dvb/adapter?/net?`` device node. The data will be available via
virtual ``dvb?_?`` network interfaces, and will be controlled/routed via
the standard ip tools (like ip, route, netstat, ifconfig, etc).
Data types and and ioctl definitions are defined via ``linux/dvb/net.h``
header.
.. _net_fcalls:
######################
DVB net Function Calls
######################
.. _NET_ADD_IF:
****************
ioctl NET_ADD_IF
****************
*man NET_ADD_IF(2)*
Creates a new network interface for a given Packet ID.
Synopsis
========
.. c:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``request``
FE_SET_TONE
``net_if``
pointer to struct :ref:`dvb_net_if <dvb-net-if>`
Description
===========
The NET_ADD_IF ioctl system call selects the Packet ID (PID) that
contains a TCP/IP traffic, the type of encapsulation to be used (MPE or
ULE) and the interface number for the new interface to be created. When
the system call successfully returns, a new virtual network interface is
created.
The struct :ref:`dvb_net_if <dvb-net-if>`::ifnum field will be
filled with the number of the created interface.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _dvb-net-if-t:
struct dvb_net_if description
=============================
.. _dvb-net-if:
.. flat-table:: struct dvb_net_if
:header-rows: 1
:stub-columns: 0
- .. row 1
- ID
- Description
- .. row 2
- pid
- Packet ID (PID) of the MPEG-TS that contains data
- .. row 3
- ifnum
- number of the DVB interface.
- .. row 4
- feedtype
- Encapsulation type of the feed. It can be:
``DVB_NET_FEEDTYPE_MPE`` for MPE encoding or
``DVB_NET_FEEDTYPE_ULE`` for ULE encoding.
.. _NET_REMOVE_IF:
*******************
ioctl NET_REMOVE_IF
*******************
*man NET_REMOVE_IF(2)*
Removes a network interface.
Synopsis
========
.. c:function:: int ioctl( int fd, int request, int ifnum )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``request``
FE_SET_TONE
``net_if``
number of the interface to be removed
Description
===========
The NET_REMOVE_IF ioctl deletes an interface previously created via
:ref:`NET_ADD_IF <net>`.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. _NET_GET_IF:
****************
ioctl NET_GET_IF
****************
*man NET_GET_IF(2)*
Read the configuration data of an interface created via
:ref:`NET_ADD_IF <net>`.
Synopsis
========
.. c:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``request``
FE_SET_TONE
``net_if``
pointer to struct :ref:`dvb_net_if <dvb-net-if>`
Description
===========
The NET_GET_IF ioctl uses the interface number given by the struct
:ref:`dvb_net_if <dvb-net-if>`::ifnum field and fills the content of
struct :ref:`dvb_net_if <dvb-net-if>` with the packet ID and
encapsulation type used on such interface. If the interface was not
created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill
the ``errno`` with ``EINVAL`` error code.
RETURN VALUE
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

24
Documentation/linux_tv/media/dvb/net_h.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

22
Documentation/linux_tv/media/dvb/query-dvb-frontend-info.rst Normal file
View File

@ -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 <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
.. ------------------------------------------------------------------------------

46
Documentation/linux_tv/media/dvb/video.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

1880
Documentation/linux_tv/media/dvb/video_function_calls.rst Normal file
View File

File diff suppressed because it is too large Load Diff

24
Documentation/linux_tv/media/dvb/video_h.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

390
Documentation/linux_tv/media/dvb/video_types.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

33
Documentation/linux_tv/media/v4l/Remote_controllers_Intro.rst Normal file
View File

@ -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 <remote_controllers_sysfs_nodes>`.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

29
Documentation/linux_tv/media/v4l/Remote_controllers_table_change.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

768
Documentation/linux_tv/media/v4l/Remote_controllers_tables.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

39
Documentation/linux_tv/media/v4l/app-pri.rst Normal file
View File

@ -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 <vidioc-g-priority>` and
:ref:`VIDIOC_S_PRIORITY <vidioc-g-priority>` ioctls to request and
query the access priority associate with a file descriptor. Opening a
device assigns a medium priority, compatible with earlier versions of
V4L2 and drivers not supporting these ioctls. Applications requiring a
different priority will usually call ``VIDIOC_S_PRIORITY`` after
verifying the device with the
:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl.
Ioctls changing driver properties, such as
:ref:`VIDIOC_S_INPUT <vidioc-g-input>`, return an EBUSY error code
after another application obtained higher priority.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

18
Documentation/linux_tv/media/v4l/async.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

97
Documentation/linux_tv/media/v4l/audio.rst Normal file
View File

@ -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 <v4l2-input>` or struct
:ref:`v4l2_output <v4l2-output>`, where each bit represents the index
number, starting at zero, of one audio input or output.
To learn about the number and attributes of the available inputs and
outputs applications can enumerate them with the
:ref:`VIDIOC_ENUMAUDIO <vidioc-enumaudio>` and
:ref:`VIDIOC_ENUMAUDOUT <vidioc-enumaudioout>` ioctl, respectively.
The struct :ref:`v4l2_audio <v4l2-audio>` returned by the
``VIDIOC_ENUMAUDIO`` ioctl also contains signal status information
applicable when the current audio input is queried.
The :ref:`VIDIOC_G_AUDIO <vidioc-g-audio>` and
:ref:`VIDIOC_G_AUDOUT <vidioc-g-audioout>` ioctls report the current
audio input and output, respectively. Note that, unlike
:ref:`VIDIOC_G_INPUT <vidioc-g-input>` and
:ref:`VIDIOC_G_OUTPUT <vidioc-g-output>` these ioctls return a
structure as ``VIDIOC_ENUMAUDIO`` and ``VIDIOC_ENUMAUDOUT`` do, not just
an index.
To select an audio input and change its properties applications call the
:ref:`VIDIOC_S_AUDIO <vidioc-g-audio>` ioctl. To select an audio
output (which presently has no changeable properties) applications call
the :ref:`VIDIOC_S_AUDOUT <vidioc-g-audioout>` ioctl.
Drivers must implement all audio input ioctls when the device has
multiple selectable audio inputs, all audio output ioctls when the
device has multiple selectable audio outputs. When the device has any
audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
in the struct :ref:`v4l2_capability <v4l2-capability>` returned by
the :ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl.
.. code-block:: c
struct v4l2_audio audio;
memset(&audio, 0, sizeof(audio));
if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
perror("VIDIOC_G_AUDIO");
exit(EXIT_FAILURE);
}
printf("Current input: %s\\n", audio.name);
.. code-block:: c
struct v4l2_audio audio;
memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
audio.index = 0;
if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
perror("VIDIOC_S_AUDIO");
exit(EXIT_FAILURE);
}
.. [1]
Actually struct :ref:`v4l2_audio <v4l2-audio>` ought to have a
``tuner`` field like struct :ref:`v4l2_input <v4l2-input>`, not
only making the API more consistent but also permitting radio devices
with multiple tuners.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

390
Documentation/linux_tv/media/v4l/biblio.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

966
Documentation/linux_tv/media/v4l/buffer.rst Normal file
View File

@ -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 <vidioc-querybuf>`,
:ref:`VIDIOC_QBUF <vidioc-qbuf>` and
:ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl. In the multi-planar API,
some plane-specific members of struct :c:type:`struct v4l2_buffer`,
such as pointers and sizes for each plane, are stored in struct
:c:type:`struct v4l2_plane` instead. In that case, struct
:c:type:`struct v4l2_buffer` contains an array of plane structures.
Dequeued video buffers come with timestamps. The driver decides at which
part of the frame and with which clock the timestamp is taken. Please
see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and
``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
are always valid and constant across all buffers during the whole video
stream. Changes in these flags may take place as a side effect of
:ref:`VIDIOC_S_INPUT <vidioc-g-input>` or
:ref:`VIDIOC_S_OUTPUT <vidioc-g-output>` however. The
``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on
mem-to-mem devices is an exception to the rule: the timestamp source
flags are copied from the OUTPUT video buffer to the CAPTURE video
buffer.
.. _v4l2-buffer:
.. flat-table:: struct v4l2_buffer
:header-rows: 0
:stub-columns: 0
:widths: 1 1 1 2
- .. row 1
- __u32
- ``index``
-
- Number of the buffer, set by the application except when calling
:ref:`VIDIOC_DQBUF <vidioc-qbuf>`, then it is set by the
driver. This field can range from zero to the number of buffers
allocated with the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl
(struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>`
``count``), plus any buffers allocated with
:ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>` minus one.
- .. row 2
- __u32
- ``type``
-
- Type of the buffer, same as struct
:ref:`v4l2_format <v4l2-format>` ``type`` or struct
:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
by the application. See :ref:`v4l2-buf-type`
- .. row 3
- __u32
- ``bytesused``
-
- The number of bytes occupied by the data in the buffer. It depends
on the negotiated data format and may change with each buffer for
compressed variable size data like JPEG images. Drivers must set
this field when ``type`` refers to a capture stream, applications
when it refers to an output stream. If the application sets this
to 0 for an output stream, then ``bytesused`` will be set to the
size of the buffer (see the ``length`` field of this struct) by
the driver. For multiplanar formats this field is ignored and the
``planes`` pointer is used instead.
- .. row 4
- __u32
- ``flags``
-
- Flags set by the application or driver, see :ref:`buffer-flags`.
- .. row 5
- __u32
- ``field``
-
- Indicates the field order of the image in the buffer, see
:ref:`v4l2-field`. This field is not used when the buffer
contains VBI data. Drivers must set it when ``type`` refers to a
capture stream, applications when it refers to an output stream.
- .. row 6
- struct timeval
- ``timestamp``
-
- For capture streams this is time when the first data byte was
captured, as returned by the :c:func:`clock_gettime()` function
for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
:ref:`buffer-flags`. For output streams the driver stores the
time at which the last data byte was actually sent out in the
``timestamp`` field. This permits applications to monitor the
drift between the video and system clock. For output streams that
use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
in the timestamp which will be copied by the driver to the capture
stream.
- .. row 7
- struct :ref:`v4l2_timecode <v4l2-timecode>`
- ``timecode``
-
- When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the
``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
structure contains a frame timecode. In
:ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
bottom field contain the same timecode. Timecodes are intended to
help video editing and are typically recorded on video tapes, but
also embedded in compressed formats like MPEG. This field is
independent of the ``timestamp`` and ``sequence`` fields.
- .. row 8
- __u32
- ``sequence``
-
- Set by the driver, counting the frames (not fields!) in sequence.
This field is set for both input and output devices.
- .. row 9
- :cspan:`3`
In :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
bottom field have the same sequence number. The count starts at
zero and includes dropped or repeated frames. A dropped frame was
received by an input device but could not be stored due to lack of
free buffer space. A repeated frame was displayed again by an
output device because the application did not pass new data in
time.
Note this may count the frames received e.g. over USB, without
taking into account the frames dropped by the remote hardware due
to limited compression throughput or bus bandwidth. These devices
identify by not enumerating any video standards, see
:ref:`standard`.
- .. row 10
- __u32
- ``memory``
-
- This field must be set by applications and/or drivers in
accordance with the selected I/O method. See :ref:`v4l2-memory`
- .. row 11
- union
- ``m``
- .. row 12
-
- __u32
- ``offset``
- For the single-planar API and when ``memory`` is
``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
start of the device memory. The value is returned by the driver
and apart of serving as parameter to the
:ref:`mmap() <func-mmap>` function not useful for applications.
See :ref:`mmap` for details
- .. row 13
-
- unsigned long
- ``userptr``
- For the single-planar API and when ``memory`` is
``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
unsigned long type) in virtual memory, set by the application. See
:ref:`userp` for details.
- .. row 14
-
- struct v4l2_plane
- ``*planes``
- When using the multi-planar API, contains a userspace pointer to
an array of struct :ref:`v4l2_plane <v4l2-plane>`. The size of
the array should be put in the ``length`` field of this
:c:type:`struct v4l2_buffer` structure.
- .. row 15
-
- int
- ``fd``
- For the single-plane API and when ``memory`` is
``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
a DMABUF buffer.
- .. row 16
- __u32
- ``length``
-
- Size of the buffer (not the payload) in bytes for the
single-planar API. This is set by the driver based on the calls to
:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and/or
:ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>`. For the
multi-planar API the application sets this to the number of
elements in the ``planes`` array. The driver will fill in the
actual number of valid elements in that array.
- .. row 17
- __u32
- ``reserved2``
-
- A place holder for future extensions. Drivers and applications
must set this to 0.
- .. row 18
- __u32
- ``reserved``
-
- A place holder for future extensions. Drivers and applications
must set this to 0.
.. _v4l2-plane:
.. flat-table:: struct v4l2_plane
:header-rows: 0
:stub-columns: 0
:widths: 1 1 1 2
- .. row 1
- __u32
- ``bytesused``
-
- The number of bytes occupied by data in the plane (its payload).
Drivers must set this field when ``type`` refers to a capture
stream, applications when it refers to an output stream. If the
application sets this to 0 for an output stream, then
``bytesused`` will be set to the size of the plane (see the
``length`` field of this struct) by the driver. Note that the
actual image data starts at ``data_offset`` which may not be 0.
- .. row 2
- __u32
- ``length``
-
- Size in bytes of the plane (not its payload). This is set by the
driver based on the calls to
:ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and/or
:ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>`.
- .. row 3
- union
- ``m``
-
-
- .. row 4
-
- __u32
- ``mem_offset``
- When the memory type in the containing struct
:ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_MMAP``, this
is the value that should be passed to :ref:`mmap() <func-mmap>`,
similar to the ``offset`` field in struct
:ref:`v4l2_buffer <v4l2-buffer>`.
- .. row 5
-
- unsigned long
- ``userptr``
- When the memory type in the containing struct
:ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_USERPTR``,
this is a userspace pointer to the memory allocated for this plane
by an application.
- .. row 6
-
- int
- ``fd``
- When the memory type in the containing struct
:ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_DMABUF``,
this is a file descriptor associated with a DMABUF buffer, similar
to the ``fd`` field in struct :ref:`v4l2_buffer <v4l2-buffer>`.
- .. row 7
- __u32
- ``data_offset``
-
- Offset in bytes to video data in the plane. Drivers must set this
field when ``type`` refers to a capture stream, applications when
it refers to an output stream. Note that data_offset is included
in ``bytesused``. So the size of the image in the plane is
``bytesused``-``data_offset`` at offset ``data_offset`` from the
start of the plane.
- .. row 8
- __u32
- ``reserved[11]``
-
- Reserved for future use. Should be zeroed by drivers and
applications.
.. _v4l2-buf-type:
.. flat-table:: enum v4l2_buf_type
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
- .. row 1
- ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
- 1
- Buffer of a single-planar video capture stream, see
:ref:`capture`.
- .. row 2
- ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
- 9
- Buffer of a multi-planar video capture stream, see
:ref:`capture`.
- .. row 3
- ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
- 2
- Buffer of a single-planar video output stream, see
:ref:`output`.
- .. row 4
- ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
- 10
- Buffer of a multi-planar video output stream, see :ref:`output`.
- .. row 5
- ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
- 3
- Buffer for video overlay, see :ref:`overlay`.
- .. row 6
- ``V4L2_BUF_TYPE_VBI_CAPTURE``
- 4
- Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
- .. row 7
- ``V4L2_BUF_TYPE_VBI_OUTPUT``
- 5
- Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
- .. row 8
- ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
- 6
- Buffer of a sliced VBI capture stream, see :ref:`sliced`.
- .. row 9
- ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
- 7
- Buffer of a sliced VBI output stream, see :ref:`sliced`.
- .. row 10
- ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
- 8
- Buffer for video output overlay (OSD), see :ref:`osd`.
- .. row 11
- ``V4L2_BUF_TYPE_SDR_CAPTURE``
- 11
- Buffer for Software Defined Radio (SDR) capture stream, see
:ref:`sdr`.
- .. row 12
- ``V4L2_BUF_TYPE_SDR_OUTPUT``
- 12
- Buffer for Software Defined Radio (SDR) output stream, see
:ref:`sdr`.
.. _buffer-flags:
.. flat-table:: Buffer Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
- .. row 1
- ``V4L2_BUF_FLAG_MAPPED``
- 0x00000001
- The buffer resides in device memory and has been mapped into the
application's address space, see :ref:`mmap` for details.
Drivers set or clear this flag when the
:ref:`VIDIOC_QUERYBUF <vidioc-querybuf>`,
:ref:`VIDIOC_QBUF <vidioc-qbuf>` or
:ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl is called. Set by the
driver.
- .. row 2
- ``V4L2_BUF_FLAG_QUEUED``
- 0x00000002
- Internally drivers maintain two buffer queues, an incoming and
outgoing queue. When this flag is set, the buffer is currently on
the incoming queue. It automatically moves to the outgoing queue
after the buffer has been filled (capture devices) or displayed
(output devices). Drivers set or clear this flag when the
``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
the ``VIDIOC_QBUF``\ ioctl it is always set and after
``VIDIOC_DQBUF`` always cleared.
- .. row 3
- ``V4L2_BUF_FLAG_DONE``
- 0x00000004
- When this flag is set, the buffer is currently on the outgoing
queue, ready to be dequeued from the driver. Drivers set or clear
this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
cleared. Of course a buffer cannot be on both queues at the same
time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
are mutually exclusive. They can be both cleared however, then the
buffer is in "dequeued" state, in the application domain so to
say.
- .. row 4
- ``V4L2_BUF_FLAG_ERROR``
- 0x00000040
- When this flag is set, the buffer has been dequeued successfully,
although the data might have been corrupted. This is recoverable,
streaming may continue as normal and the buffer may be reused
normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
called.
- .. row 5
- ``V4L2_BUF_FLAG_KEYFRAME``
- 0x00000008
- Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
ioctl. It may be set by video capture devices when the buffer
contains a compressed image which is a key frame (or field), i. e.
can be decompressed on its own. Also known as an I-frame.
Applications can set this bit when ``type`` refers to an output
stream.
- .. row 6
- ``V4L2_BUF_FLAG_PFRAME``
- 0x00000010
- Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
or fields which contain only differences to a previous key frame.
Applications can set this bit when ``type`` refers to an output
stream.
- .. row 7
- ``V4L2_BUF_FLAG_BFRAME``
- 0x00000020
- Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
predicted frame or field which contains only the differences
between the current frame and both the preceding and following key
frames to specify its content. Applications can set this bit when
``type`` refers to an output stream.
- .. row 8
- ``V4L2_BUF_FLAG_TIMECODE``
- 0x00000100
- The ``timecode`` field is valid. Drivers set or clear this flag
when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
this bit and the corresponding ``timecode`` structure when
``type`` refers to an output stream.
- .. row 9
- ``V4L2_BUF_FLAG_PREPARED``
- 0x00000400
- The buffer has been prepared for I/O and can be queued by the
application. Drivers set or clear this flag when the
:ref:`VIDIOC_QUERYBUF <vidioc-querybuf>`,
:ref:`VIDIOC_PREPARE_BUF <vidioc-qbuf>`,
:ref:`VIDIOC_QBUF <vidioc-qbuf>` or
:ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl is called.
- .. row 10
- ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
- 0x00000800
- Caches do not have to be invalidated for this buffer. Typically
applications shall use this flag if the data captured in the
buffer is not going to be touched by the CPU, instead the buffer
will, probably, be passed on to a DMA-capable hardware unit for
further processing or output.
- .. row 11
- ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
- 0x00001000
- Caches do not have to be cleaned for this buffer. Typically
applications shall use this flag for output buffers if the data in
this buffer has not been created by the CPU but by some
DMA-capable unit, in which case caches have not been used.
- .. row 12
- ``V4L2_BUF_FLAG_LAST``
- 0x00100000
- Last buffer produced by the hardware. mem2mem codec drivers set
this flag on the capture queue for the last buffer when the
:ref:`VIDIOC_QUERYBUF <vidioc-querybuf>` or
:ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl is called. Due to
hardware limitations, the last buffer may be empty. In this case
the driver will set the ``bytesused`` field to 0, regardless of
the format. Any Any subsequent call to the
:ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl will not block anymore,
but return an EPIPE error code.
- .. row 13
- ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
- 0x0000e000
- Mask for timestamp types below. To test the timestamp type, mask
out bits not belonging to timestamp type by performing a logical
and operation with buffer flags and timestamp mask.
- .. row 14
- ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
- 0x00000000
- Unknown timestamp type. This type is used by drivers before Linux
3.9 and may be either monotonic (see below) or realtime (wall
clock). Monotonic clock has been favoured in embedded systems
whereas most of the drivers use the realtime clock. Either kinds
of timestamps are available in user space via
:c:func:`clock_gettime(2)` using clock IDs ``CLOCK_MONOTONIC``
and ``CLOCK_REALTIME``, respectively.
- .. row 15
- ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
- 0x00002000
- The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
clock. To access the same clock outside V4L2, use
:c:func:`clock_gettime(2)`.
- .. row 16
- ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
- 0x00004000
- The CAPTURE buffer timestamp has been taken from the corresponding
OUTPUT buffer. This flag applies only to mem2mem devices.
- .. row 17
- ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
- 0x00070000
- Mask for timestamp sources below. The timestamp source defines the
point of time the timestamp is taken in relation to the frame.
Logical 'and' operation between the ``flags`` field and
``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
timestamp source. Applications must set the timestamp source when
``type`` refers to an output stream and
``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
- .. row 18
- ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
- 0x00000000
- End Of Frame. The buffer timestamp has been taken when the last
pixel of the frame has been received or the last pixel of the
frame has been transmitted. In practice, software generated
timestamps will typically be read from the clock a small amount of
time after the last pixel has been received or transmitten,
depending on the system and other activity in it.
- .. row 19
- ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
- 0x00010000
- Start Of Exposure. The buffer timestamp has been taken when the
exposure of the frame has begun. This is only valid for the
``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
.. _v4l2-memory:
.. flat-table:: enum v4l2_memory
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
- .. row 1
- ``V4L2_MEMORY_MMAP``
- 1
- The buffer is used for :ref:`memory mapping <mmap>` I/O.
- .. row 2
- ``V4L2_MEMORY_USERPTR``
- 2
- The buffer is used for :ref:`user pointer <userp>` I/O.
- .. row 3
- ``V4L2_MEMORY_OVERLAY``
- 3
- [to do]
- .. row 4
- ``V4L2_MEMORY_DMABUF``
- 4
- The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
Timecodes
=========
The :c:type:`struct v4l2_timecode` structure is designed to hold a
:ref:`smpte12m` or similar timecode. (struct
:c:type:`struct timeval` timestamps are stored in struct
:ref:`v4l2_buffer <v4l2-buffer>` field ``timestamp``.)
.. _v4l2-timecode:
.. flat-table:: struct v4l2_timecode
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
- .. row 1
- __u32
- ``type``
- Frame rate the timecodes are based on, see :ref:`timecode-type`.
- .. row 2
- __u32
- ``flags``
- Timecode flags, see :ref:`timecode-flags`.
- .. row 3
- __u8
- ``frames``
- Frame count, 0 ... 23/24/29/49/59, depending on the type of
timecode.
- .. row 4
- __u8
- ``seconds``
- Seconds count, 0 ... 59. This is a binary, not BCD number.
- .. row 5
- __u8
- ``minutes``
- Minutes count, 0 ... 59. This is a binary, not BCD number.
- .. row 6
- __u8
- ``hours``
- Hours count, 0 ... 29. This is a binary, not BCD number.
- .. row 7
- __u8
- ``userbits``\ [4]
- The "user group" bits from the timecode.
.. _timecode-type:
.. flat-table:: Timecode Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
- .. row 1
- ``V4L2_TC_TYPE_24FPS``
- 1
- 24 frames per second, i. e. film.
- .. row 2
- ``V4L2_TC_TYPE_25FPS``
- 2
- 25 frames per second, i. e. PAL or SECAM video.
- .. row 3
- ``V4L2_TC_TYPE_30FPS``
- 3
- 30 frames per second, i. e. NTSC video.
- .. row 4
- ``V4L2_TC_TYPE_50FPS``
- 4
-
- .. row 5
- ``V4L2_TC_TYPE_60FPS``
- 5
-
.. _timecode-flags:
.. flat-table:: Timecode Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
- .. row 1
- ``V4L2_TC_FLAG_DROPFRAME``
- 0x0001
- Indicates "drop frame" semantics for counting frames in 29.97 fps
material. When set, frame numbers 0 and 1 at the start of each
minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
count.
- .. row 2
- ``V4L2_TC_FLAG_COLORFRAME``
- 0x0002
- The "color frame" flag.
- .. row 3
- ``V4L2_TC_USERBITS_field``
- 0x000C
- Field mask for the "binary group flags".
- .. row 4
- ``V4L2_TC_USERBITS_USERDEFINED``
- 0x0000
- Unspecified format.
- .. row 5
- ``V4L2_TC_USERBITS_8BITCHARS``
- 0x0008
- 8-bit ISO characters.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

24
Documentation/linux_tv/media/v4l/capture-example.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

675
Documentation/linux_tv/media/v4l/capture.c.rst Normal file
View File

@ -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 <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <getopt.h> /* getopt_long() */
#include <fcntl.h> /* low-level i/o */
#include <unistd.h>
#include <errno.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <sys/time.h>
#include <sys/mman.h>
#include <sys/ioctl.h>
#include <linux/videodev2.h>
#define CLEAR(x) memset(&(x), 0, sizeof(x))
enum io_method {
IO_METHOD_READ,
IO_METHOD_MMAP,
IO_METHOD_USERPTR,
};
struct buffer {
void *start;
size_t length;
};
static char *dev_name;
static enum io_method io = IO_METHOD_MMAP;
static int fd = -1;
struct buffer *buffers;
static unsigned int n_buffers;
static int out_buf;
static int force_format;
static int frame_count = 70;
static void errno_exit(const char *s)
{
fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno));
exit(EXIT_FAILURE);
}
static int xioctl(int fh, int request, void *arg)
{
int r;
do {
r = ioctl(fh, request, arg);
} while (-1 == r && EINTR == errno);
return r;
}
static void process_image(const void *p, int size)
{
if (out_buf)
fwrite(p, size, 1, stdout);
fflush(stderr);
fprintf(stderr, ".");
fflush(stdout);
}
static int read_frame(void)
{
struct v4l2_buffer buf;
unsigned int i;
switch (io) {
case IO_METHOD_READ:
if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
switch (errno) {
case EAGAIN:
return 0;
case EIO:
/* Could ignore EIO, see spec. */
/* fall through */
default:
errno_exit("read");
}
}
process_image(buffers[0].start, buffers[0].length);
break;
case IO_METHOD_MMAP:
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
switch (errno) {
case EAGAIN:
return 0;
case EIO:
/* Could ignore EIO, see spec. */
/* fall through */
default:
errno_exit("VIDIOC_DQBUF");
}
}
assert(buf.index < n_buffers);
process_image(buffers[buf.index].start, buf.bytesused);
if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
errno_exit("VIDIOC_QBUF");
break;
case IO_METHOD_USERPTR:
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_USERPTR;
if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
switch (errno) {
case EAGAIN:
return 0;
case EIO:
/* Could ignore EIO, see spec. */
/* fall through */
default:
errno_exit("VIDIOC_DQBUF");
}
}
for (i = 0; i < n_buffers; ++i)
if (buf.m.userptr == (unsigned long)buffers[i].start
&& buf.length == buffers[i].length)
break;
assert(i < n_buffers);
process_image((void *)buf.m.userptr, buf.bytesused);
if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
errno_exit("VIDIOC_QBUF");
break;
}
return 1;
}
static void mainloop(void)
{
unsigned int count;
count = frame_count;
while (count-- > 0) {
for (;;) {
fd_set fds;
struct timeval tv;
int r;
FD_ZERO(&fds);
FD_SET(fd, &fds);
/* Timeout. */
tv.tv_sec = 2;
tv.tv_usec = 0;
r = select(fd + 1, &fds, NULL, NULL, &tv);
if (-1 == r) {
if (EINTR == errno)
continue;
errno_exit("select");
}
if (0 == r) {
fprintf(stderr, "select timeout\\n");
exit(EXIT_FAILURE);
}
if (read_frame())
break;
/* EAGAIN - continue select loop. */
}
}
}
static void stop_capturing(void)
{
enum v4l2_buf_type type;
switch (io) {
case IO_METHOD_READ:
/* Nothing to do. */
break;
case IO_METHOD_MMAP:
case IO_METHOD_USERPTR:
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type))
errno_exit("VIDIOC_STREAMOFF");
break;
}
}
static void start_capturing(void)
{
unsigned int i;
enum v4l2_buf_type type;
switch (io) {
case IO_METHOD_READ:
/* Nothing to do. */
break;
case IO_METHOD_MMAP:
for (i = 0; i < n_buffers; ++i) {
struct v4l2_buffer buf;
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
buf.index = i;
if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
errno_exit("VIDIOC_QBUF");
}
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
errno_exit("VIDIOC_STREAMON");
break;
case IO_METHOD_USERPTR:
for (i = 0; i < n_buffers; ++i) {
struct v4l2_buffer buf;
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_USERPTR;
buf.index = i;
buf.m.userptr = (unsigned long)buffers[i].start;
buf.length = buffers[i].length;
if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
errno_exit("VIDIOC_QBUF");
}
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
errno_exit("VIDIOC_STREAMON");
break;
}
}
static void uninit_device(void)
{
unsigned int i;
switch (io) {
case IO_METHOD_READ:
free(buffers[0].start);
break;
case IO_METHOD_MMAP:
for (i = 0; i < n_buffers; ++i)
if (-1 == munmap(buffers[i].start, buffers[i].length))
errno_exit("munmap");
break;
case IO_METHOD_USERPTR:
for (i = 0; i < n_buffers; ++i)
free(buffers[i].start);
break;
}
free(buffers);
}
static void init_read(unsigned int buffer_size)
{
buffers = calloc(1, sizeof(*buffers));
if (!buffers) {
fprintf(stderr, "Out of memory\\n");
exit(EXIT_FAILURE);
}
buffers[0].length = buffer_size;
buffers[0].start = malloc(buffer_size);
if (!buffers[0].start) {
fprintf(stderr, "Out of memory\\n");
exit(EXIT_FAILURE);
}
}
static void init_mmap(void)
{
struct v4l2_requestbuffers req;
CLEAR(req);
req.count = 4;
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
req.memory = V4L2_MEMORY_MMAP;
if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
if (EINVAL == errno) {
fprintf(stderr, "%s does not support "
"memory mappingn", dev_name);
exit(EXIT_FAILURE);
} else {
errno_exit("VIDIOC_REQBUFS");
}
}
if (req.count < 2) {
fprintf(stderr, "Insufficient buffer memory on %s\\n",
dev_name);
exit(EXIT_FAILURE);
}
buffers = calloc(req.count, sizeof(*buffers));
if (!buffers) {
fprintf(stderr, "Out of memory\\n");
exit(EXIT_FAILURE);
}
for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
struct v4l2_buffer buf;
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
buf.index = n_buffers;
if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf))
errno_exit("VIDIOC_QUERYBUF");
buffers[n_buffers].length = buf.length;
buffers[n_buffers].start =
mmap(NULL /* start anywhere */,
buf.length,
PROT_READ | PROT_WRITE /* required */,
MAP_SHARED /* recommended */,
fd, buf.m.offset);
if (MAP_FAILED == buffers[n_buffers].start)
errno_exit("mmap");
}
}
static void init_userp(unsigned int buffer_size)
{
struct v4l2_requestbuffers req;
CLEAR(req);
req.count = 4;
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
req.memory = V4L2_MEMORY_USERPTR;
if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
if (EINVAL == errno) {
fprintf(stderr, "%s does not support "
"user pointer i/on", dev_name);
exit(EXIT_FAILURE);
} else {
errno_exit("VIDIOC_REQBUFS");
}
}
buffers = calloc(4, sizeof(*buffers));
if (!buffers) {
fprintf(stderr, "Out of memory\\n");
exit(EXIT_FAILURE);
}
for (n_buffers = 0; n_buffers < 4; ++n_buffers) {
buffers[n_buffers].length = buffer_size;
buffers[n_buffers].start = malloc(buffer_size);
if (!buffers[n_buffers].start) {
fprintf(stderr, "Out of memory\\n");
exit(EXIT_FAILURE);
}
}
}
static void init_device(void)
{
struct v4l2_capability cap;
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
struct v4l2_format fmt;
unsigned int min;
if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) {
if (EINVAL == errno) {
fprintf(stderr, "%s is no V4L2 device\\n",
dev_name);
exit(EXIT_FAILURE);
} else {
errno_exit("VIDIOC_QUERYCAP");
}
}
if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) {
fprintf(stderr, "%s is no video capture device\\n",
dev_name);
exit(EXIT_FAILURE);
}
switch (io) {
case IO_METHOD_READ:
if (!(cap.capabilities & V4L2_CAP_READWRITE)) {
fprintf(stderr, "%s does not support read i/o\\n",
dev_name);
exit(EXIT_FAILURE);
}
break;
case IO_METHOD_MMAP:
case IO_METHOD_USERPTR:
if (!(cap.capabilities & V4L2_CAP_STREAMING)) {
fprintf(stderr, "%s does not support streaming i/o\\n",
dev_name);
exit(EXIT_FAILURE);
}
break;
}
/* Select video input, video standard and tune here. */
CLEAR(cropcap);
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) {
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
crop.c = cropcap.defrect; /* reset to default */
if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) {
switch (errno) {
case EINVAL:
/* Cropping not supported. */
break;
default:
/* Errors ignored. */
break;
}
}
} else {
/* Errors ignored. */
}
CLEAR(fmt);
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (force_format) {
fmt.fmt.pix.width = 640;
fmt.fmt.pix.height = 480;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt))
errno_exit("VIDIOC_S_FMT");
/* Note VIDIOC_S_FMT may change width and height. */
} else {
/* Preserve original settings as set by v4l2-ctl for example */
if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt))
errno_exit("VIDIOC_G_FMT");
}
/* Buggy driver paranoia. */
min = fmt.fmt.pix.width * 2;
if (fmt.fmt.pix.bytesperline < min)
fmt.fmt.pix.bytesperline = min;
min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
if (fmt.fmt.pix.sizeimage < min)
fmt.fmt.pix.sizeimage = min;
switch (io) {
case IO_METHOD_READ:
init_read(fmt.fmt.pix.sizeimage);
break;
case IO_METHOD_MMAP:
init_mmap();
break;
case IO_METHOD_USERPTR:
init_userp(fmt.fmt.pix.sizeimage);
break;
}
}
static void close_device(void)
{
if (-1 == close(fd))
errno_exit("close");
fd = -1;
}
static void open_device(void)
{
struct stat st;
if (-1 == stat(dev_name, &st)) {
fprintf(stderr, "Cannot identify '%s': %d, %s\\n",
dev_name, errno, strerror(errno));
exit(EXIT_FAILURE);
}
if (!S_ISCHR(st.st_mode)) {
fprintf(stderr, "%s is no devicen", dev_name);
exit(EXIT_FAILURE);
}
fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
if (-1 == fd) {
fprintf(stderr, "Cannot open '%s': %d, %s\\n",
dev_name, errno, strerror(errno));
exit(EXIT_FAILURE);
}
}
static void usage(FILE *fp, int argc, char **argv)
{
fprintf(fp,
"Usage: %s [options]\\n\\n"
"Version 1.3\\n"
"Options:\\n"
"-d | --device name Video device name [%s]n"
"-h | --help Print this messagen"
"-m | --mmap Use memory mapped buffers [default]n"
"-r | --read Use read() callsn"
"-u | --userp Use application allocated buffersn"
"-o | --output Outputs stream to stdoutn"
"-f | --format Force format to 640x480 YUYVn"
"-c | --count Number of frames to grab [%i]n"
"",
argv[0], dev_name, frame_count);
}
static const char short_options[] = "d:hmruofc:";
static const struct option
long_options[] = {
{ "device", required_argument, NULL, 'd' },
{ "help", no_argument, NULL, 'h' },
{ "mmap", no_argument, NULL, 'm' },
{ "read", no_argument, NULL, 'r' },
{ "userp", no_argument, NULL, 'u' },
{ "output", no_argument, NULL, 'o' },
{ "format", no_argument, NULL, 'f' },
{ "count", required_argument, NULL, 'c' },
{ 0, 0, 0, 0 }
};
int main(int argc, char **argv)
{
dev_name = "/dev/video0";
for (;;) {
int idx;
int c;
c = getopt_long(argc, argv,
short_options, long_options, &idx);
if (-1 == c)
break;
switch (c) {
case 0: /* getopt_long() flag */
break;
case 'd':
dev_name = optarg;
break;
case 'h':
usage(stdout, argc, argv);
exit(EXIT_SUCCESS);
case 'm':
io = IO_METHOD_MMAP;
break;
case 'r':
io = IO_METHOD_READ;
break;
case 'u':
io = IO_METHOD_USERPTR;
break;
case 'o':
out_buf++;
break;
case 'f':
force_format++;
break;
case 'c':
errno = 0;
frame_count = strtol(optarg, NULL, 0);
if (errno)
errno_exit(optarg);
break;
default:
usage(stderr, argc, argv);
exit(EXIT_FAILURE);
}
}
open_device();
init_device();
start_capturing();
mainloop();
stop_capturing();
uninit_device();
close_device();
fprintf(stderr, "\\n");
return 0;
}
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

172
Documentation/linux_tv/media/v4l/colorspaces.rst Normal file
View File

@ -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 <http://www.brucelindbloom.com>`__
website is an excellent resource, especially with respect to the
mathematics behind colorspace conversions. The wikipedia
`CIE 1931 colorspace <http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space>`__
article is also very useful.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

24
Documentation/linux_tv/media/v4l/common-defs.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

56
Documentation/linux_tv/media/v4l/common.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

29
Documentation/linux_tv/media/v4l/compat.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

536
Documentation/linux_tv/media/v4l/control.rst Normal file
View File

@ -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 <vidioc-subscribe-event>`, event
``V4L2_EVENT_CTRL``), panel applications might want to make use of that
in order to always reflect the correct control value.
All controls use machine endianness.
.. _control-id:
Control IDs
===========
``V4L2_CID_BASE``
First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
``V4L2_CID_USER_BASE``
Synonym of ``V4L2_CID_BASE``.
``V4L2_CID_BRIGHTNESS`` ``(integer)``
Picture brightness, or more precisely, the black level.
``V4L2_CID_CONTRAST`` ``(integer)``
Picture contrast or luma gain.
``V4L2_CID_SATURATION`` ``(integer)``
Picture color saturation or chroma gain.
``V4L2_CID_HUE`` ``(integer)``
Hue or color balance.
``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
Overall audio volume. Note some drivers also provide an OSS or ALSA
mixer interface.
``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
Audio stereo balance. Minimum corresponds to all the way left,
maximum to right.
``V4L2_CID_AUDIO_BASS`` ``(integer)``
Audio bass adjustment.
``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
Audio treble adjustment.
``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
Mute audio, i. e. set the volume to zero, however without affecting
``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
at load time to avoid excessive noise. Actually the entire device
should be reset to a low power consumption state.
``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
Loudness mode (bass boost).
``V4L2_CID_BLACK_LEVEL`` ``(integer)``
Another name for brightness (not a synonym of
``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
be used in new drivers and applications.
``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
Automatic white balance (cameras).
``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
This is an action control. When set (the value is ignored), the
device will do a white balance and then hold the current setting.
Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
which, when activated, keeps adjusting the white balance.
``V4L2_CID_RED_BALANCE`` ``(integer)``
Red chroma balance.
``V4L2_CID_BLUE_BALANCE`` ``(integer)``
Blue chroma balance.
``V4L2_CID_GAMMA`` ``(integer)``
Gamma adjust.
``V4L2_CID_WHITENESS`` ``(integer)``
Whiteness for grey-scale devices. This is a synonym for
``V4L2_CID_GAMMA``. This control is deprecated and should not be
used in new drivers and applications.
``V4L2_CID_EXPOSURE`` ``(integer)``
Exposure (cameras). [Unit?]
``V4L2_CID_AUTOGAIN`` ``(boolean)``
Automatic gain/exposure control.
``V4L2_CID_GAIN`` ``(integer)``
Gain control.
``V4L2_CID_HFLIP`` ``(boolean)``
Mirror the picture horizontally.
``V4L2_CID_VFLIP`` ``(boolean)``
Mirror the picture vertically.
.. _`v4l2-power-line-frequency`:
``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
Enables a power line frequency filter to avoid flicker. Possible
values for ``enum v4l2_power_line_frequency`` are:
``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0),
``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1),
``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and
``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3).
``V4L2_CID_HUE_AUTO`` ``(boolean)``
Enables automatic hue control by the device. The effect of setting
``V4L2_CID_HUE`` while automatic hue control is enabled is
undefined, drivers should ignore such request.
``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
This control specifies the white balance settings as a color
temperature in Kelvin. A driver should have a minimum of 2800
(incandescent) to 6500 (daylight). For more information about color
temperature see
`Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
``V4L2_CID_SHARPNESS`` ``(integer)``
Adjusts the sharpness filters in a camera. The minimum value
disables the filters, higher values give a sharper picture.
``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
Adjusts the backlight compensation in a camera. The minimum value
disables backlight compensation.
``V4L2_CID_CHROMA_AGC`` ``(boolean)``
Chroma automatic gain control.
``V4L2_CID_CHROMA_GAIN`` ``(integer)``
Adjusts the Chroma gain control (for use when chroma AGC is
disabled).
``V4L2_CID_COLOR_KILLER`` ``(boolean)``
Enable the color killer (i. e. force a black & white image in case
of a weak video signal).
.. _`v4l2-colorfx`:
``V4L2_CID_COLORFX`` ``(enum)``
Selects a color effect. The following values are defined:
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``V4L2_COLORFX_NONE``
- Color effect is disabled.
- .. row 2
- ``V4L2_COLORFX_ANTIQUE``
- An aging (old photo) effect.
- .. row 3
- ``V4L2_COLORFX_ART_FREEZE``
- Frost color effect.
- .. row 4
- ``V4L2_COLORFX_AQUA``
- Water color, cool tone.
- .. row 5
- ``V4L2_COLORFX_BW``
- Black and white.
- .. row 6
- ``V4L2_COLORFX_EMBOSS``
- Emboss, the highlights and shadows replace light/dark boundaries
and low contrast areas are set to a gray background.
- .. row 7
- ``V4L2_COLORFX_GRASS_GREEN``
- Grass green.
- .. row 8
- ``V4L2_COLORFX_NEGATIVE``
- Negative.
- .. row 9
- ``V4L2_COLORFX_SEPIA``
- Sepia tone.
- .. row 10
- ``V4L2_COLORFX_SKETCH``
- Sketch.
- .. row 11
- ``V4L2_COLORFX_SKIN_WHITEN``
- Skin whiten.
- .. row 12
- ``V4L2_COLORFX_SKY_BLUE``
- Sky blue.
- .. row 13
- ``V4L2_COLORFX_SOLARIZATION``
- Solarization, the image is partially reversed in tone, only color
values above or below a certain threshold are inverted.
- .. row 14
- ``V4L2_COLORFX_SILHOUETTE``
- Silhouette (outline).
- .. row 15
- ``V4L2_COLORFX_VIVID``
- Vivid colors.
- .. row 16
- ``V4L2_COLORFX_SET_CBCR``
- The Cb and Cr chroma components are replaced by fixed coefficients
determined by ``V4L2_CID_COLORFX_CBCR`` control.
``V4L2_CID_COLORFX_CBCR`` ``(integer)``
Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
color effect. Bits [7:0] of the supplied 32 bit value are
interpreted as Cr component, bits [15:8] as Cb component and bits
[31:16] must be zero.
``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
Enable Automatic Brightness.
``V4L2_CID_ROTATE`` ``(integer)``
Rotates the image by specified angle. Common angles are 90, 270 and
180. Rotating the image to 90 and 270 will reverse the height and
width of the display window. It is necessary to set the new height
and width of the picture using the
:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl according to the
rotation angle selected.
``V4L2_CID_BG_COLOR`` ``(integer)``
Sets the background color on the current output device. Background
color needs to be specified in the RGB24 format. The supplied 32 bit
value is interpreted as bits 0-7 Red color information, bits 8-15
Green color information, bits 16-23 Blue color information and bits
24-31 must be zero.
``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
Switch on or off the illuminator 1 or 2 of the device (usually a
microscope).
``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
This is a read-only control that can be read by the application and
used as a hint to determine the number of CAPTURE buffers to pass to
REQBUFS. The value is the minimum number of CAPTURE buffers that is
necessary for hardware to work.
``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
This is a read-only control that can be read by the application and
used as a hint to determine the number of OUTPUT buffers to pass to
REQBUFS. The value is the minimum number of OUTPUT buffers that is
necessary for hardware to work.
.. _`v4l2-alpha-component`:
``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
Sets the alpha color component. When a capture device (or capture
queue of a mem-to-mem device) produces a frame format that includes
an alpha component (e.g.
:ref:`packed RGB image formats <rgb-formats>`) and the alpha value
is not defined by the device or the mem-to-mem input data this
control lets you select the alpha component value of all pixels.
When an output device (or output queue of a mem-to-mem device)
consumes a frame format that doesn't include an alpha component and
the device supports alpha channel processing this control lets you
set the alpha component value of all pixels for further processing
in the device.
``V4L2_CID_LASTP1``
End of the predefined control IDs (currently
``V4L2_CID_ALPHA_COMPONENT`` + 1).
``V4L2_CID_PRIVATE_BASE``
ID of the first custom (driver specific) control. Applications
depending on particular custom controls should check the driver name
and version, see :ref:`querycap`.
Applications can enumerate the available controls with the
:ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` and
:ref:`VIDIOC_QUERYMENU <vidioc-queryctrl>` ioctls, get and set a
control value with the :ref:`VIDIOC_G_CTRL <vidioc-g-ctrl>` and
:ref:`VIDIOC_S_CTRL <vidioc-g-ctrl>` ioctls. Drivers must implement
``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
more menu type controls.
.. code-block:: c
struct v4l2_queryctrl queryctrl;
struct v4l2_querymenu querymenu;
static void enumerate_menu(void)
{
printf(" Menu items:\\n");
memset(&querymenu, 0, sizeof(querymenu));
querymenu.id = queryctrl.id;
for (querymenu.index = queryctrl.minimum;
querymenu.index <= queryctrl.maximum;
querymenu.index++) {
if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
printf(" %s\\n", querymenu.name);
}
}
}
memset(&queryctrl, 0, sizeof(queryctrl));
for (queryctrl.id = V4L2_CID_BASE;
queryctrl.id < V4L2_CID_LASTP1;
queryctrl.id++) {
if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
continue;
printf("Control %s\\n", queryctrl.name);
if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
enumerate_menu();
} else {
if (errno == EINVAL)
continue;
perror("VIDIOC_QUERYCTRL");
exit(EXIT_FAILURE);
}
}
for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
queryctrl.id++) {
if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
continue;
printf("Control %s\\n", queryctrl.name);
if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
enumerate_menu();
} else {
if (errno == EINVAL)
break;
perror("VIDIOC_QUERYCTRL");
exit(EXIT_FAILURE);
}
}
.. code-block:: c
memset(&queryctrl, 0, sizeof(queryctrl));
queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
break;
if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
continue;
printf("Control %s\\n", queryctrl.name);
if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
enumerate_menu();
queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
}
if (errno != EINVAL) {
perror("VIDIOC_QUERYCTRL");
exit(EXIT_FAILURE);
}
.. code-block:: c
struct v4l2_queryctrl queryctrl;
struct v4l2_control control;
memset(&queryctrl, 0, sizeof(queryctrl));
queryctrl.id = V4L2_CID_BRIGHTNESS;
if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
if (errno != EINVAL) {
perror("VIDIOC_QUERYCTRL");
exit(EXIT_FAILURE);
} else {
printf("V4L2_CID_BRIGHTNESS is not supportedn");
}
} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
printf("V4L2_CID_BRIGHTNESS is not supportedn");
} else {
memset(&control, 0, sizeof (control));
control.id = V4L2_CID_BRIGHTNESS;
control.value = queryctrl.default_value;
if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
perror("VIDIOC_S_CTRL");
exit(EXIT_FAILURE);
}
}
memset(&control, 0, sizeof(control));
control.id = V4L2_CID_CONTRAST;
if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
control.value += 1;
/* The driver may clamp the value or return ERANGE, ignored here */
if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
&& errno != ERANGE) {
perror("VIDIOC_S_CTRL");
exit(EXIT_FAILURE);
}
/* Ignore if V4L2_CID_CONTRAST is unsupported */
} else if (errno != EINVAL) {
perror("VIDIOC_G_CTRL");
exit(EXIT_FAILURE);
}
control.id = V4L2_CID_AUDIO_MUTE;
control.value = 1; /* silence */
/* Errors ignored */
ioctl(fd, VIDIOC_S_CTRL, &control);
.. [1]
The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
controls. This makes it hard to programatically set such controls
since the meaning of the control with that ID is driver dependent. In
order to resolve this drivers use unique IDs and the
``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
the real IDs.
Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
instead of using :ref:`VIDIOC_QUERYCTRL <vidioc-queryctrl>` with
the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
support for ``V4L2_CID_PRIVATE_BASE`` is still around.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

18
Documentation/linux_tv/media/v4l/controls.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

300
Documentation/linux_tv/media/v4l/crop.rst Normal file
View File

@ -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 <vidioc-cropcap>`,
:ref:`VIDIOC_G_CROP <vidioc-g-crop>` and
:ref:`VIDIOC_S_CROP <vidioc-g-crop>` ioctls apply to input as well
as output devices.*
Scaling requires a source and a target. On a video capture or overlay
device the source is the video signal, and the cropping ioctls determine
the area actually sampled. The target are images read by the application
or overlaid onto the graphics screen. Their size (and position for an
overlay) is negotiated with the :ref:`VIDIOC_G_FMT <vidioc-g-fmt>`
and :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctls.
On a video output device the source are the images passed in by the
application, and their size is again negotiated with the
``VIDIOC_G/S_FMT`` ioctls, or may be encoded in a compressed video
stream. The target is the video signal, and the cropping ioctls
determine the area where the images are inserted.
Source and target rectangles are defined even if the device does not
support scaling or the ``VIDIOC_G/S_CROP`` ioctls. Their size (and
position where applicable) will be fixed in this case. *All capture and
output device must support the ``VIDIOC_CROPCAP`` ioctl such that
applications can determine if scaling takes place.*
Cropping Structures
===================
.. _crop-scale:
.. figure:: crop_files/crop.*
:alt: crop.pdf / crop.gif
:align: center
Image Cropping, Insertion and Scaling
The cropping, insertion and scaling process
For capture devices the coordinates of the top left corner, width and
height of the area which can be sampled is given by the ``bounds``
substructure of the struct :ref:`v4l2_cropcap <v4l2-cropcap>`
returned by the ``VIDIOC_CROPCAP`` ioctl. To support a wide range of
hardware this specification does not define an origin or units. However
by convention drivers should horizontally count unscaled samples
relative to 0H (the leading edge of the horizontal sync pulse, see
:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field
(:ref:`vbi-525`, :ref:`vbi-625`), multiplied by two if the driver
can capture both fields.
The top left corner, width and height of the source rectangle, that is
the area actually sampled, is given by struct
:ref:`v4l2_crop <v4l2-crop>` using the same coordinate system as
struct :ref:`v4l2_cropcap <v4l2-cropcap>`. Applications can use the
``VIDIOC_G_CROP`` and ``VIDIOC_S_CROP`` ioctls to get and set this
rectangle. It must lie completely within the capture boundaries and the
driver may further adjust the requested size and/or position according
to hardware limitations.
Each capture device has a default source rectangle, given by the
``defrect`` substructure of struct
:ref:`v4l2_cropcap <v4l2-cropcap>`. The center of this rectangle
shall align with the center of the active picture area of the video
signal, and cover what the driver writer considers the complete picture.
Drivers shall reset the source rectangle to the default when the driver
is first loaded, but not later.
For output devices these structures and ioctls are used accordingly,
defining the *target* rectangle where the images will be inserted into
the video signal.
Scaling Adjustments
===================
Video hardware can have various cropping, insertion and scaling
limitations. It may only scale up or down, support only discrete scaling
factors, or have different scaling abilities in horizontal and vertical
direction. Also it may not support scaling at all. At the same time the
struct :ref:`v4l2_crop <v4l2-crop>` rectangle may have to be aligned,
and both the source and target rectangles may have arbitrary upper and
lower size limits. In particular the maximum ``width`` and ``height`` in
struct :ref:`v4l2_crop <v4l2-crop>` may be smaller than the struct
:ref:`v4l2_cropcap <v4l2-cropcap>`. ``bounds`` area. Therefore, as
usual, drivers are expected to adjust the requested parameters and
return the actual values selected.
Applications can change the source or the target rectangle first, as
they may prefer a particular image size or a certain area in the video
signal. If the driver has to adjust both to satisfy hardware
limitations, the last requested rectangle shall take priority, and the
driver should preferably adjust the opposite one. The
:ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl however shall not change
the driver state and therefore only adjust the requested rectangle.
Suppose scaling on a video capture device is restricted to a factor 1:1
or 2:1 in either direction and the target image size must be a multiple
of 16 × 16 pixels. The source cropping rectangle is set to defaults,
which are also the upper limit in this example, of 640 × 400 pixels at
offset 0, 0. An application requests an image size of 300 × 225 pixels,
assuming video will be scaled down from the "full picture" accordingly.
The driver sets the image size to the closest possible values 304 × 224,
then chooses the cropping rectangle closest to the requested size, that
is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is
still valid, thus unmodified. Given the default cropping rectangle
reported by ``VIDIOC_CROPCAP`` the application can easily propose
another offset to center the cropping rectangle.
Now the application may insist on covering an area using a picture
aspect ratio closer to the original request, so it asks for a cropping
rectangle of 608 × 456 pixels. The present scaling factors limit
cropping to 640 × 384, so the driver returns the cropping size 608 × 384
and adjusts the image size to closest possible 304 × 192.
Examples
========
Source and target rectangles shall remain unchanged across closing and
reopening a device, such that piping data into or out of a device will
work without special preparations. More advanced applications should
ensure the parameters are suitable before starting I/O.
(A video capture device is assumed; change
``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices.)
.. code-block:: c
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
perror ("VIDIOC_CROPCAP");
exit (EXIT_FAILURE);
}
memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
crop.c = cropcap.defrect;
/* Ignore if cropping is not supported (EINVAL). */
if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
&& errno != EINVAL) {
perror ("VIDIOC_S_CROP");
exit (EXIT_FAILURE);
}
(A video capture device is assumed.)
.. code-block:: c
struct v4l2_cropcap cropcap;
struct v4l2_format format;
reset_cropping_parameters ();
/* Scale down to 1/4 size of full picture. */
memset (&format, 0, sizeof (format)); /* defaults */
format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
format.fmt.pix.width = cropcap.defrect.width >> 1;
format.fmt.pix.height = cropcap.defrect.height >> 1;
format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
perror ("VIDIOC_S_FORMAT");
exit (EXIT_FAILURE);
}
/* We could check the actual image size now, the actual scaling factor
or if the driver can scale at all. */
.. code-block:: c
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
perror ("VIDIOC_CROPCAP");
exit (EXIT_FAILURE);
}
memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
crop.c = cropcap.defrect;
/* Scale the width and height to 50 % of their original size
and center the output. */
crop.c.width /= 2;
crop.c.height /= 2;
crop.c.left += crop.c.width / 2;
crop.c.top += crop.c.height / 2;
/* Ignore if cropping is not supported (EINVAL). */
if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
&& errno != EINVAL) {
perror ("VIDIOC_S_CROP");
exit (EXIT_FAILURE);
}
(A video capture device is assumed.)
.. code-block:: c
struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
struct v4l2_format format;
double hscale, vscale;
double aspect;
int dwidth, dheight;
memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
perror ("VIDIOC_CROPCAP");
exit (EXIT_FAILURE);
}
memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
if (errno != EINVAL) {
perror ("VIDIOC_G_CROP");
exit (EXIT_FAILURE);
}
/* Cropping not supported. */
crop.c = cropcap.defrect;
}
memset (&format, 0, sizeof (format));
format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
perror ("VIDIOC_G_FMT");
exit (EXIT_FAILURE);
}
/* The scaling applied by the driver. */
hscale = format.fmt.pix.width / (double) crop.c.width;
vscale = format.fmt.pix.height / (double) crop.c.height;
aspect = cropcap.pixelaspect.numerator /
(double) cropcap.pixelaspect.denominator;
aspect = aspect * hscale / vscale;
/* Devices following ITU-R BT.601 do not capture
square pixels. For playback on a computer monitor
we should scale the images to this size. */
dwidth = format.fmt.pix.width / aspect;
dheight = format.fmt.pix.height;
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

BIN
Documentation/linux_tv/media/v4l/crop_files/crop.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.8 KiB

BIN
Documentation/linux_tv/media/v4l/crop_files/crop.pdf Normal file
View File

Binary file not shown.

26
Documentation/linux_tv/media/v4l/depth-formats.rst Normal file
View File

@ -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
.. ------------------------------------------------------------------------------

111
Documentation/linux_tv/media/v4l/dev-capture.rst Normal file
View File

@ -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 <v4l2-capability>` returned by the
:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. As secondary device
functions they may also support the :ref:`video overlay <overlay>`
(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>`
(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or
streaming I/O methods must be supported. Tuners and audio inputs are
optional.
Supplemental Functions
======================
Video capture devices shall support :ref:`audio input <audio>`,
:ref:`tuner <tuner>`, :ref:`controls <control>`,
:ref:`cropping and scaling <crop>` and
:ref:`streaming parameter <streaming-par>` ioctls as needed. The
:ref:`video input <video>` and :ref:`video standard <standard>`
ioctls must be supported by all video capture devices.
Image Format Negotiation
========================
The result of a capture operation is determined by cropping and image
format parameters. The former select an area of the video picture to
capture, the latter how images are stored in memory, i. e. in RGB or YUV
format, the number of bits per pixel or width and height. Together they
also define how images are scaled in the process.
As usual these parameters are *not* reset at :ref:`open() <func-open>`
time to permit Unix tool chains, programming a device and then reading
from it as if it was a plain file. Well written V4L2 applications ensure
they really get what they want, including cropping and scaling.
Cropping initialization at minimum requires to reset the parameters to
defaults. An example is given in :ref:`crop`.
To query the current image format applications set the ``type`` field of
a struct :ref:`v4l2_format <v4l2-format>` to
``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the
:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl with a pointer to this
structure. Drivers fill the struct
:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
member of the ``fmt`` union.
To request different parameters applications set the ``type`` field of a
struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
``vbi`` member of the ``fmt`` union, or better just modify the results
of ``VIDIOC_G_FMT``, and call the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
ioctl with a pointer to this structure. Drivers may adjust the
parameters and finally return the actual parameters as ``VIDIOC_G_FMT``
does.
Like ``VIDIOC_S_FMT`` the :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl
can be used to learn about hardware limitations without disabling I/O or
possibly time consuming hardware preparations.
The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
discussed in :ref:`pixfmt`. See also the specification of the
``VIDIOC_G_FMT``, ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT`` ioctls for
details. Video capture devices must implement both the ``VIDIOC_G_FMT``
and ``VIDIOC_S_FMT`` ioctl, even if ``VIDIOC_S_FMT`` ignores all
requests and always returns default parameters as ``VIDIOC_G_FMT`` does.
``VIDIOC_TRY_FMT`` is optional.
Reading Images
==============
A video capture device may support the :ref:`read() function <rw>`
and/or streaming (:ref:`memory mapping <mmap>` or
:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

41
Documentation/linux_tv/media/v4l/dev-codec.rst Normal file
View File

@ -0,0 +1,41 @@
.. -*- coding: utf-8; mode: rst -*-
.. _codec:
***************
Codec Interface
***************
A V4L2 codec can compress, decompress, transform, or otherwise convert
video data from one format into another format, in memory. Typically
such devices are memory-to-memory devices (i.e. devices with the
``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set).
A memory-to-memory video node acts just like a normal video node, but it
supports both output (sending frames from memory to the codec hardware)
and capture (receiving the processed frames from the codec hardware into
memory) stream I/O. An application will have to setup the stream I/O for
both sides and finally call :ref:`VIDIOC_STREAMON <vidioc-streamon>`
for both capture and output to start the codec.
Video compression codecs use the MPEG controls to setup their codec
parameters (note that the MPEG controls actually support many more
codecs than just MPEG). See :ref:`mpeg-controls`.
Memory-to-memory devices can often be used as a shared resource: you can
open the video node multiple times, each application setting up their
own codec properties that are local to the file handle, and each can use
it independently from the others. The driver will arbitrate access to
the codec and reprogram it whenever another file handler gets access.
This is different from the usual video node behavior where the video
properties are global to the device (i.e. changing something through one
file handle is visible through another file handle).
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

31
Documentation/linux_tv/media/v4l/dev-effect.rst Normal file
View File

@ -0,0 +1,31 @@
.. -*- coding: utf-8; mode: rst -*-
.. _effect:
************************
Effect Devices Interface
************************
**Note**
This interface has been be suspended from the V4L2 API implemented
in Linux 2.6 until we have more experience with effect device
interfaces.
A V4L2 video effect device can do image effects, filtering, or combine
two or more images or image streams. For example video transitions or
wipes. Applications send data to be processed and receive the result
data either with :ref:`read() <func-read>` and
:ref:`write() <func-write>` functions, or through the streaming I/O
mechanism.
[to do]
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

56
Documentation/linux_tv/media/v4l/dev-event.rst Normal file
View File

@ -0,0 +1,56 @@
.. -*- coding: utf-8; mode: rst -*-
.. _event:
***************
Event Interface
***************
The V4L2 event interface provides a means for a user to get immediately
notified on certain conditions taking place on a device. This might
include start of frame or loss of signal events, for example. Changes in
the value or state of a V4L2 control can also be reported through
events.
To receive events, the events the user is interested in first must be
subscribed using the
:ref:`VIDIOC_SUBSCRIBE_EVENT <vidioc-subscribe-event>` ioctl. Once
an event is subscribed, the events of subscribed types are dequeueable
using the :ref:`VIDIOC_DQEVENT <vidioc-dqevent>` ioctl. Events may be
unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
type V4L2_EVENT_ALL may be used to unsubscribe all the events the
driver supports.
The event subscriptions and event queues are specific to file handles.
Subscribing an event on one file handle does not affect other file
handles.
The information on dequeueable events is obtained by using select or
poll system calls on video devices. The V4L2 events use POLLPRI events
on poll system call and exceptions on select system call.
Starting with kernel 3.1 certain guarantees can be given with regards to
events:
1. Each subscribed event has its own internal dedicated event queue.
This means that flooding of one event type will not interfere with
other event types.
2. If the internal event queue for a particular subscribed event becomes
full, then the oldest event in that queue will be dropped.
3. Where applicable, certain event types can ensure that the payload of
the oldest event that is about to be dropped will be merged with the
payload of the next oldest event. Thus ensuring that no information
is lost, but only an intermediate step leading up to that
information. See the documentation for the event you want to
subscribe to whether this is applicable for that event or not.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

154
Documentation/linux_tv/media/v4l/dev-osd.rst Normal file
View File

@ -0,0 +1,154 @@
.. -*- coding: utf-8; mode: rst -*-
.. _osd:
******************************
Video Output Overlay Interface
******************************
**Also known as On-Screen Display (OSD)**
Some video output devices can overlay a framebuffer image onto the
outgoing video signal. Applications can set up such an overlay using
this interface, which borrows structures and ioctls of the
:ref:`Video Overlay <overlay>` interface.
The OSD function is accessible through the same character special file
as the :ref:`Video Output <capture>` function. Note the default
function of such a ``/dev/video`` device is video capturing or output.
The OSD function is only available after calling the
:ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl.
Querying Capabilities
=====================
Devices supporting the *Video Output Overlay* interface set the
``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of
struct :ref:`v4l2_capability <v4l2-capability>` returned by the
:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl.
Framebuffer
===========
Contrary to the *Video Overlay* interface the framebuffer is normally
implemented on the TV card and not the graphics card. On Linux it is
accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device,
applications can find the corresponding framebuffer device by calling
the :ref:`VIDIOC_G_FBUF <vidioc-g-fbuf>` ioctl. It returns, amongst
other information, the physical address of the framebuffer in the
``base`` field of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`.
The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same
address in the ``smem_start`` field of struct
:c:type:`struct fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
ioctl and struct :c:type:`struct fb_fix_screeninfo` are defined in
the ``linux/fb.h`` header file.
The width and height of the framebuffer depends on the current video
standard. A V4L2 driver may reject attempts to change the video standard
(or any other ioctl which would imply a framebuffer size change) with an
EBUSY error code until all applications closed the framebuffer device.
.. code-block:: c
#include <linux/fb.h>
struct v4l2_framebuffer fbuf;
unsigned int i;
int fb_fd;
if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) {
perror("VIDIOC_G_FBUF");
exit(EXIT_FAILURE);
}
for (i = 0; i < 30; i++) {
char dev_name[16];
struct fb_fix_screeninfo si;
snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
fb_fd = open(dev_name, O_RDWR);
if (-1 == fb_fd) {
switch (errno) {
case ENOENT: /* no such file */
case ENXIO: /* no driver */
continue;
default:
perror("open");
exit(EXIT_FAILURE);
}
}
if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) {
if (si.smem_start == (unsigned long)fbuf.base)
break;
} else {
/* Apparently not a framebuffer device. */
}
close(fb_fd);
fb_fd = -1;
}
/* fb_fd is the file descriptor of the framebuffer device
for the video output overlay, or -1 if no device was found. */
Overlay Window and Scaling
==========================
The overlay is controlled by source and target rectangles. The source
rectangle selects a subsection of the framebuffer image to be overlaid,
the target rectangle an area in the outgoing video signal where the
image will appear. Drivers may or may not support scaling, and arbitrary
sizes and positions of these rectangles. Further drivers may support any
(or none) of the clipping/blending methods defined for the
:ref:`Video Overlay <overlay>` interface.
A struct :ref:`v4l2_window <v4l2-window>` defines the size of the
source rectangle, its position in the framebuffer and the
clipping/blending method to be used for the overlay. To get the current
parameters applications set the ``type`` field of a struct
:ref:`v4l2_format <v4l2-format>` to
``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the
:ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl. The driver fills the
:c:type:`struct v4l2_window` substructure named ``win``. It is not
possible to retrieve a previously programmed clipping list or bitmap.
To program the source rectangle applications set the ``type`` field of a
struct :ref:`v4l2_format <v4l2-format>` to
``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win``
substructure and call the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl.
The driver adjusts the parameters against hardware limits and returns
the actual parameters as ``VIDIOC_G_FMT`` does. Like ``VIDIOC_S_FMT``,
the :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl can be used to learn
about driver capabilities without actually changing driver state. Unlike
``VIDIOC_S_FMT`` this also works after the overlay has been enabled.
A struct :ref:`v4l2_crop <v4l2-crop>` defines the size and position
of the target rectangle. The scaling factor of the overlay is implied by
the width and height given in struct :ref:`v4l2_window <v4l2-window>`
and struct :ref:`v4l2_crop <v4l2-crop>`. The cropping API applies to
*Video Output* and *Video Output Overlay* devices in the same way as to
*Video Capture* and *Video Overlay* devices, merely reversing the
direction of the data flow. For more information see :ref:`crop`.
Enabling Overlay
================
There is no V4L2 ioctl to enable or disable the overlay, however the
framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

108
Documentation/linux_tv/media/v4l/dev-output.rst Normal file
View File

@ -0,0 +1,108 @@
.. -*- coding: utf-8; mode: rst -*-
.. _output:
**********************
Video Output Interface
**********************
Video output devices encode stills or image sequences as analog video
signal. With this interface applications can control the encoding
process and move images from user space to the driver.
Conventionally V4L2 video output devices are accessed through character
device special files named ``/dev/video`` and ``/dev/video0`` to
``/dev/video63`` with major number 81 and minor numbers 0 to 63.
``/dev/video`` is typically a symbolic link to the preferred video
device. Note the same device files are used for video capture devices.
Querying Capabilities
=====================
Devices supporting the video output interface set the
``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
the ``capabilities`` field of struct
:ref:`v4l2_capability <v4l2-capability>` returned by the
:ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl. As secondary device
functions they may also support the :ref:`raw VBI output <raw-vbi>`
(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
streaming I/O methods must be supported. Modulators and audio outputs
are optional.
Supplemental Functions
======================
Video output devices shall support :ref:`audio output <audio>`,
:ref:`modulator <tuner>`, :ref:`controls <control>`,
:ref:`cropping and scaling <crop>` and
:ref:`streaming parameter <streaming-par>` ioctls as needed. The
:ref:`video output <video>` and :ref:`video standard <standard>`
ioctls must be supported by all video output devices.
Image Format Negotiation
========================
The output is determined by cropping and image format parameters. The
former select an area of the video picture where the image will appear,
the latter how images are stored in memory, i. e. in RGB or YUV format,
the number of bits per pixel or width and height. Together they also
define how images are scaled in the process.
As usual these parameters are *not* reset at :ref:`open() <func-open>`
time to permit Unix tool chains, programming a device and then writing
to it as if it was a plain file. Well written V4L2 applications ensure
they really get what they want, including cropping and scaling.
Cropping initialization at minimum requires to reset the parameters to
defaults. An example is given in :ref:`crop`.
To query the current image format applications set the ``type`` field of
a struct :ref:`v4l2_format <v4l2-format>` to
``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
and call the :ref:`VIDIOC_G_FMT <vidioc-g-fmt>` ioctl with a pointer
to this structure. Drivers fill the struct
:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
member of the ``fmt`` union.
To request different parameters applications set the ``type`` field of a
struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
``vbi`` member of the ``fmt`` union, or better just modify the results
of ``VIDIOC_G_FMT``, and call the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>`
ioctl with a pointer to this structure. Drivers may adjust the
parameters and finally return the actual parameters as ``VIDIOC_G_FMT``
does.
Like ``VIDIOC_S_FMT`` the :ref:`VIDIOC_TRY_FMT <vidioc-g-fmt>` ioctl
can be used to learn about hardware limitations without disabling I/O or
possibly time consuming hardware preparations.
The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
discussed in :ref:`pixfmt`. See also the specification of the
``VIDIOC_G_FMT``, ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT`` ioctls for
details. Video output devices must implement both the ``VIDIOC_G_FMT``
and ``VIDIOC_S_FMT`` ioctl, even if ``VIDIOC_S_FMT`` ignores all
requests and always returns default parameters as ``VIDIOC_G_FMT`` does.
``VIDIOC_TRY_FMT`` is optional.
Writing Images
==============
A video output device may support the :ref:`write() function <rw>`
and/or streaming (:ref:`memory mapping <mmap>` or
:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------

Some files were not shown because too many files have changed in this diff Show More