xiaomi-sm8450/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

Browse Source 
Pull media updates from Mauro Carvalho Chehab:
 "The main set of series of patches for media subsystem, including:
   - document RC sysfs class
   - added an API to setup scancode to allow waking up systems using the
     Remote Controller
   - add API for SDR devices.  Drivers are still on staging
   - some API improvements for getting EDID data from media
     inputs/outputs
   - new DVB frontend driver for drx-j (ATSC)
   - one driver (it913x/it9137) got removed, in favor of an improvement
     on another driver (af9035)
   - added a skeleton V4L2 PCI driver at documentation
   - added a dual flash driver (lm3646)
   - added a new IR driver (img-ir)
   - added an IR scancode decoder for the Sharp protocol
   - some improvements at the usbtv driver, to allow its core to be
     reused.
   - added a new SDR driver (rtl2832u_sdr)
   - added a new tuner driver (msi001)
   - several improvements at em28xx driver to fix PM support, device
     removal and to split the V4L2 specific bits into a separate
     sub-driver
   - one driver got converted to videobuf2 (s2255drv)
   - the e4000 tuner driver now follows an improved binding model
   - some fixes at V4L2 compat32 code
   - several fixes and enhancements at videobuf2 code
   - some cleanups at V4L2 API documentation
   - usual driver enhancements, new board additions and misc fixups"

[ NOTE! This merge effective drops commit 4329b93b28 ("of: Reduce
  indentation in of_graph_get_next_endpoint").

  The of_graph_get_next_endpoint() function was moved and renamed by
  commit fd9fdb78a9 ("[media] of: move graph helpers from
  drivers/media/v4l2-core to drivers/of").  It was originally called
  v4l2_of_get_next_endpoint() and lived in the file
  drivers/media/v4l2-core/v4l2-of.c.

  In that original location, it was then fixed to support empty port
  nodes by commit b9db140c1e ("[media] v4l: of: Support empty port
  nodes"), and that commit clashes badly with the dropped "Reduce
  intendation" commit.  I had to choose one or the other, and decided
  that the "Support empty port nodes" commit was more important ]

* 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (426 commits)
  [media] em28xx-dvb: fix PCTV 461e tuner I2C binding
  Revert "[media] em28xx-dvb: fix PCTV 461e tuner I2C binding"
  [media] em28xx: fix PCTV 290e LNA oops
  [media] em28xx-dvb: fix PCTV 461e tuner I2C binding
  [media] m88ds3103: fix bug on .set_tone()
  [media] saa7134: fix WARN_ON during resume
  [media] v4l2-dv-timings: add module name, description, license
  [media] videodev2.h: add parenthesis around macro arguments
  [media] saa6752hs: depends on CRC32
  [media] si4713: fix Kconfig dependencies
  [media] Sensoray 2255 uses videobuf2
  [media] adv7180: free an interrupt on failure paths in init_device()
  [media] e4000: make VIDEO_V4L2 dependency optional
  [media] af9033: Don't export functions for the hardware filter
  [media] af9035: use af9033 PID filters
  [media] af9033: implement PID filter
  [media] rtl2832_sdr: do not use dynamic stack allocation
  [media] e4000: fix 32-bit build error
  [media] em28xx-audio: make sure audio is unmuted on open()
  [media] DocBook media: v4l2_format_sdr was renamed to v4l2_sdr_format
  ...
This commit is contained in:
Linus Torvalds
2014-04-04 09:50:07 -07:00
parent 4a4389abdd a83b93a748
commit 3c83e61e67
384 changed files with 44036 additions and 7945 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
Documentation/DocBook/media/dvb/demux.xml
View File

@@ -1042,7 +1042,14 @@ role="subsection"><title>DMX_ADD_PID</title>
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl is undocumented. Documentation is welcome.</para>
<para>This ioctl call allows to add multiple PIDs to a transport stream filter
previously set up with DMX_SET_PES_FILTER and output equal to DMX_OUT_TSDEMUX_TAP.
</para></entry></row><row><entry align="char"><para>
It is used by readers of /dev/dvb/adapterX/demuxY.
</para></entry></row><row><entry align="char"><para>
It may be called at any time, i.e. before or after the first filter on the
shared file descriptor was started. It makes it possible to record multiple
services without the need to de-multiplex or re-multiplex TS packets.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
@@ -1075,7 +1082,7 @@ role="subsection"><title>DMX_ADD_PID</title>
</para>
</entry><entry
align="char">
<para>Undocumented.</para>
<para>PID number to be filtered.</para>
</entry>
</row></tbody></tgroup></informaltable>
&return-value-dvb;
@@ -1087,7 +1094,15 @@ role="subsection"><title>DMX_REMOVE_PID</title>
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl is undocumented. Documentation is welcome.</para>
<para>This ioctl call allows to remove a PID when multiple PIDs are set on a
transport stream filter, e. g. a filter previously set up with output equal to
DMX_OUT_TSDEMUX_TAP, created via either DMX_SET_PES_FILTER or DMX_ADD_PID.
</para></entry></row><row><entry align="char"><para>
It is used by readers of /dev/dvb/adapterX/demuxY.
</para></entry></row><row><entry align="char"><para>
It may be called at any time, i.e. before or after the first filter on the
shared file descriptor was started. It makes it possible to record multiple
services without the need to de-multiplex or re-multiplex TS packets.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
@@ -1120,7 +1135,7 @@ role="subsection"><title>DMX_REMOVE_PID</title>
</para>
</entry><entry
align="char">
<para>Undocumented.</para>
<para>PID of the PES filter to be removed.</para>
</entry>
</row></tbody></tgroup></informaltable>
&return-value-dvb;

4
Documentation/DocBook/media/dvb/dvbapi.xml
View File

@@ -18,7 +18,7 @@
<firstname>Mauro</firstname>
<othername role="mi">Carvalho</othername>
<surname>Chehab</surname>
<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation>
<contrib>Ported document to Docbook XML.</contrib>
</author>
</authorgroup>
@@ -28,7 +28,7 @@
<holder>Convergence GmbH</holder>
</copyright>
<copyright>
<year>2009-2012</year>
<year>2009-2014</year>
<holder>Mauro Carvalho Chehab</holder>
</copyright>

8
Documentation/DocBook/media/dvb/frontend.xml
View File

@@ -744,7 +744,7 @@ typedef enum fe_hierarchy {
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, int16_t
<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, uint16_t
&#x22C6;snr);</para>
</entry>
</row></tbody></tgroup></informaltable>
@@ -766,7 +766,7 @@ typedef enum fe_hierarchy {
</entry>
</row><row><entry
align="char">
<para>int16_t *snr</para>
<para>uint16_t *snr</para>
</entry><entry
align="char">
<para>The signal-to-noise ratio is stored into *snr.</para>
@@ -791,7 +791,7 @@ typedef enum fe_hierarchy {
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl( int fd, int request =
<link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, int16_t &#x22C6;strength);</para>
<link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, uint16_t &#x22C6;strength);</para>
</entry>
</row></tbody></tgroup></informaltable>
@@ -814,7 +814,7 @@ typedef enum fe_hierarchy {
</entry>
</row><row><entry
align="char">
<para>int16_t *strength</para>
<para>uint16_t *strength</para>
</entry><entry
align="char">
<para>The signal strength value is stored into *strength.</para>

402
Documentation/DocBook/media/v4l/common.xml
View File

@@ -38,70 +38,41 @@ the basic concepts applicable to all devices.</para>
<para>V4L2 drivers are implemented as kernel modules, loaded
manually by the system administrator or automatically when a device is
first opened. The driver modules plug into the "videodev" kernel
first discovered. The driver modules plug into the "videodev" kernel
module. It provides helper functions and a common application
interface specified in this document.</para>
<para>Each driver thus loaded registers one or more device nodes
with major number 81 and a minor number between 0 and 255. Assigning
minor numbers to V4L2 devices is entirely up to the system administrator,
this is primarily intended to solve conflicts between devices.<footnote>
<para>Access permissions are associated with character
device special files, hence we must ensure device numbers cannot
change with the module load order. To this end minor numbers are no
longer automatically assigned by the "videodev" module as in V4L but
requested by the driver. The defaults will suffice for most people
unless two drivers compete for the same minor numbers.</para>
</footnote> The module options to select minor numbers are named
after the device special file with a "_nr" suffix. For example "video_nr"
for <filename>/dev/video</filename> video capture devices. The number is
an offset to the base minor number associated with the device type.
<footnote>
<para>In earlier versions of the V4L2 API the module options
where named after the device special file with a "unit_" prefix, expressing
the minor number itself, not an offset. Rationale for this change is unknown.
Lastly the naming and semantics are just a convention among driver writers,
the point to note is that minor numbers are not supposed to be hardcoded
into drivers.</para>
</footnote> When the driver supports multiple devices of the same
type more than one minor number can be assigned, separated by commas:
<informalexample>
with major number 81 and a minor number between 0 and 255. Minor numbers
are allocated dynamically unless the kernel is compiled with the kernel
option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
allocated in ranges depending on the device node type (video, radio, etc.).</para>
<para>Many drivers support "video_nr", "radio_nr" or "vbi_nr"
module options to select specific video/radio/vbi node numbers. This allows
the user to request that the device node is named e.g. /dev/video5 instead
of leaving it to chance. When the driver supports multiple devices of the same
type more than one device node number can be assigned, separated by commas:
<informalexample>
<screen>
&gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
&gt; modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
</informalexample></para>
<para>In <filename>/etc/modules.conf</filename> this may be
written as: <informalexample>
<screen>
alias char-major-81-0 mydriver
alias char-major-81-1 mydriver
alias char-major-81-64 mydriver <co id="alias" />
options mydriver video_nr=0,1 radio_nr=0,1 <co id="options" />
options mydriver video_nr=0,1 radio_nr=0,1
</screen>
<calloutlist>
<callout arearefs="alias">
<para>When an application attempts to open a device
special file with major number 81 and minor number 0, 1, or 64, load
"mydriver" (and the "videodev" module it depends upon).</para>
</callout>
<callout arearefs="options">
<para>Register the first two video capture devices with
minor number 0 and 1 (base number is 0), the first two radio device
with minor number 64 and 65 (base 64).</para>
</callout>
</calloutlist>
</informalexample> When no minor number is given as module
option the driver supplies a default. <xref linkend="devices" />
recommends the base minor numbers to be used for the various device
types. Obviously minor numbers must be unique. When the number is
already in use the <emphasis>offending device</emphasis> will not be
registered. <!-- Blessed by Linus Torvalds on
linux-kernel@vger.kernel.org, 2002-11-20. --></para>
</informalexample> When no device node number is given as module
option the driver supplies a default.</para>
<para>By convention system administrators create various
character device special files with these major and minor numbers in
the <filename>/dev</filename> directory. The names recommended for the
different V4L2 device types are listed in <xref linkend="devices" />.
<para>Normally udev will create the device nodes in /dev automatically
for you. If udev is not installed, then you need to enable the
CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
relate a minor number to a device node number. I.e., you need to be certain
that minor number 5 maps to device node name video5. With this kernel option
different device types have different minor number ranges. These ranges are
listed in <xref linkend="devices" />.
</para>
<para>The creation of character special files (with
@@ -110,85 +81,66 @@ devices cannot be opened by major and minor number. That means
applications cannot <emphasis>reliable</emphasis> scan for loaded or
installed drivers. The user must enter a device name, or the
application can try the conventional device names.</para>
<para>Under the device filesystem (devfs) the minor number
options are ignored. V4L2 drivers (or by proxy the "videodev" module)
automatically create the required device files in the
<filename>/dev/v4l</filename> directory using the conventional device
names above.</para>
</section>
<section id="related">
<title>Related Devices</title>
<para>Devices can support several related functions. For example
video capturing, video overlay and VBI capturing are related because
these functions share, amongst other, the same video input and tuner
frequency. V4L and earlier versions of V4L2 used the same device name
and minor number for video capturing and overlay, but different ones
for VBI. Experience showed this approach has several problems<footnote>
<para>Given a device file name one cannot reliable find
related devices. For once names are arbitrary and in a system with
multiple devices, where only some support VBI capturing, a
<filename>/dev/video2</filename> is not necessarily related to
<filename>/dev/vbi2</filename>. The V4L
<constant>VIDIOCGUNIT</constant> ioctl would require a search for a
device file with a particular major and minor number.</para>
</footnote>, and to make things worse the V4L videodev module
used to prohibit multiple opens of a device.</para>
<para>Devices can support several functions. For example
video capturing, VBI capturing and radio support.</para>
<para>As a remedy the present version of the V4L2 API relaxed the
concept of device types with specific names and minor numbers. For
compatibility with old applications drivers must still register different
minor numbers to assign a default function to the device. But if related
functions are supported by the driver they must be available under all
registered minor numbers. The desired function can be selected after
opening the device as described in <xref linkend="devices" />.</para>
<para>The V4L2 API creates different nodes for each of these functions.</para>
<para>Imagine a driver supporting video capturing, video
overlay, raw VBI capturing, and FM radio reception. It registers three
devices with minor number 0, 64 and 224 (this numbering scheme is
inherited from the V4L API). Regardless if
<filename>/dev/video</filename> (81, 0) or
<filename>/dev/vbi</filename> (81, 224) is opened the application can
select any one of the video capturing, overlay or VBI capturing
functions. Without programming (e.&nbsp;g. reading from the device
with <application>dd</application> or <application>cat</application>)
<filename>/dev/video</filename> captures video images, while
<filename>/dev/vbi</filename> captures raw VBI data.
<filename>/dev/radio</filename> (81, 64) is invariable a radio device,
unrelated to the video functions. Being unrelated does not imply the
devices can be used at the same time, however. The &func-open;
function may very well return an &EBUSY;.</para>
<para>The V4L2 API was designed with the idea that one device node could support
all functions. However, in practice this never worked: this 'feature'
was never used by applications and many drivers did not support it and if
they did it was certainly never tested. In addition, switching a device
node between different functions only works when using the streaming I/O
API, not with the read()/write() API.</para>
<para>Today each device node supports just one function.</para>
<para>Besides video input or output the hardware may also
support audio sampling or playback. If so, these functions are
implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
audio mixer. The V4L2 API makes no provisions yet to find these
related devices. If you have an idea please write to the linux-media
mailing list: &v4l-ml;.</para>
implemented as ALSA PCM devices with optional ALSA audio mixer
devices.</para>
<para>One problem with all these devices is that the V4L2 API
makes no provisions to find these related devices. Some really
complex devices use the Media Controller (see <xref linkend="media_controller" />)
which can be used for this purpose. But most drivers do not use it,
and while some code exists that uses sysfs to discover related devices
(see libmedia_dev in the <ulink url="http://git.linuxtv.org/v4l-utils/">v4l-utils</ulink>
git repository), there is no library yet that can provide a single API towards
both Media Controller-based devices and devices that do not use the Media Controller.
If you want to work on this please write to the linux-media mailing list: &v4l-ml;.</para>
</section>
<section>
<title>Multiple Opens</title>
<para>In general, V4L2 devices can be opened more than once.
<para>V4L2 devices can be opened more than once.<footnote><para>
There are still some old and obscure drivers that have not been updated to
allow for multiple opens. This implies that for such drivers &func-open; can
return an &EBUSY; when the device is already in use.</para></footnote>
When this is supported by the driver, users can for example start a
"panel" application to change controls like brightness or audio
volume, while another application captures video and audio. In other words, panel
applications are comparable to an OSS or ALSA audio mixer application.
When a device supports multiple functions like capturing and overlay
<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
use of the device by forked processes or specialized applications.</para>
applications are comparable to an ALSA audio mixer application.
Just opening a V4L2 device should not change the state of the device.<footnote>
<para>Unfortunately, opening a radio device often switches the state of the
device to radio mode in many drivers. This behavior should be fixed eventually
as it violates the V4L2 specification.</para></footnote></para>
<para>Multiple opens are optional, although drivers should
permit at least concurrent accesses without data exchange, &ie; panel
applications. This implies &func-open; can return an &EBUSY; when the
device is already in use, as well as &func-ioctl; functions initiating
data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
and &func-write; functions.</para>
<para>Once an application has allocated the memory buffers needed for
streaming data (by calling the &VIDIOC-REQBUFS; or &VIDIOC-CREATE-BUFS; ioctls,
or implicitly by calling the &func-read; or &func-write; functions) that
application (filehandle) becomes the owner of the device. It is no longer
allowed to make changes that would affect the buffer sizes (e.g. by calling
the &VIDIOC-S-FMT; ioctl) and other applications are no longer allowed to allocate
buffers or start or stop streaming. The &EBUSY; will be returned instead.</para>
<para>Mere opening a V4L2 device does not grant exclusive
<para>Merely opening a V4L2 device does not grant exclusive
access.<footnote>
<para>Drivers could recognize the
<constant>O_EXCL</constant> open flag. Presently this is not required,
@@ -206,12 +158,7 @@ additional access privileges using the priority mechanism described in
<para>V4L2 drivers should not support multiple applications
reading or writing the same data stream on a device by copying
buffers, time multiplexing or similar means. This is better handled by
a proxy application in user space. When the driver supports stream
sharing anyway it must be implemented transparently. The V4L2 API does
not specify how conflicts are solved. <!-- For example O_EXCL when the
application does not want to be preempted, PROT_READ mmapped buffers
which can be mapped twice, what happens when image formats do not
match etc.--></para>
a proxy application in user space.</para>
</section>
<section>
@@ -240,15 +187,15 @@ methods</link> supported by the device.</para>
<para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the
V4L2 API version used by the driver, with generally matches the Kernel version.
There's no need of using &VIDIOC-QUERYCAP; to check if an specific ioctl is
supported, the V4L2 core now returns ENOIOCTLCMD if a driver doesn't provide
There's no need of using &VIDIOC-QUERYCAP; to check if a specific ioctl is
supported, the V4L2 core now returns ENOTTY if a driver doesn't provide
support for an ioctl.</para>
<para>Other features can be queried
by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
to learn about the number, types and names of video connectors on the
device. Although abstraction is a major objective of this API, the
ioctl also allows driver specific applications to reliable identify
&VIDIOC-QUERYCAP; ioctl also allows driver specific applications to reliably identify
the driver.</para>
<para>All V4L2 drivers must support
@@ -278,9 +225,7 @@ Applications requiring a different priority will usually call
the &VIDIOC-QUERYCAP; ioctl.</para>
<para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
return an &EBUSY; after another application obtained higher priority.
An event mechanism to notify applications about asynchronous property
changes has been proposed but not added yet.</para>
return an &EBUSY; after another application obtained higher priority.</para>
</section>
<section id="video">
@@ -288,9 +233,9 @@ changes has been proposed but not added yet.</para>
<para>Video inputs and outputs are physical connectors of a
device. These can be for example RF connectors (antenna/cable), CVBS
a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
capture devices have inputs, output devices have outputs, at least one
each. Radio devices have no video inputs or outputs.</para>
a.k.a. Composite Video, S-Video or RGB connectors. Video and VBI
capture devices have inputs. Video and VBI output devices have outputs,
at least one each. Radio devices have no video inputs or outputs.</para>
<para>To learn about the number and attributes of the
available inputs and outputs applications can enumerate them with the
@@ -299,30 +244,13 @@ available inputs and outputs applications can enumerate them with the
ioctl also contains signal status information applicable when the
current video input is queried.</para>
<para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
<para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctls return the
index of the current video input or output. To select a different
input or output applications call the &VIDIOC-S-INPUT; and
&VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
&VIDIOC-S-OUTPUT; ioctls. Drivers must implement all the input ioctls
when the device has one or more inputs, all the output ioctls when the
device has one or more outputs.</para>
<!--
<figure id=io-tree>
<title>Input and output enumeration is the root of most device properties.</title>
<mediaobject>
<imageobject>
<imagedata fileref="links.pdf" format="ps" />
</imageobject>
<imageobject>
<imagedata fileref="links.gif" format="gif" />
</imageobject>
<textobject>
<phrase>Links between various device property structures.</phrase>
</textobject>
</mediaobject>
</figure>
-->
<example>
<title>Information about the current video input</title>
@@ -330,20 +258,20 @@ device has one or more outputs.</para>
&v4l2-input; input;
int index;
if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
perror ("VIDIOC_G_INPUT");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;index)) {
perror("VIDIOC_G_INPUT");
exit(EXIT_FAILURE);
}
memset (&amp;input, 0, sizeof (input));
memset(&amp;input, 0, sizeof(input));
input.index = index;
if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
perror ("VIDIOC_ENUMINPUT");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
perror("VIDIOC_ENUMINPUT");
exit(EXIT_FAILURE);
}
printf ("Current input: %s\n", input.name);
printf("Current input: %s\n", input.name);
</programlisting>
</example>
@@ -355,9 +283,9 @@ int index;
index = 0;
if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;index)) {
perror ("VIDIOC_S_INPUT");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-S-INPUT;, &amp;index)) {
perror("VIDIOC_S_INPUT");
exit(EXIT_FAILURE);
}
</programlisting>
</example>
@@ -397,7 +325,7 @@ available inputs and outputs applications can enumerate them with the
also contains signal status information applicable when the current
audio input is queried.</para>
<para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
<para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctls report
the current audio input and output, respectively. Note that, unlike
&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
as <constant>VIDIOC_ENUMAUDIO</constant> and
@@ -408,11 +336,11 @@ applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
output (which presently has no changeable properties) applications
call the &VIDIOC-S-AUDOUT; ioctl.</para>
<para>Drivers must implement all input ioctls when the device
has one or more inputs, all output ioctls when the device has one
or more outputs. When the device has any audio inputs or outputs the
driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
&v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
<para>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 <constant>V4L2_CAP_AUDIO</constant>
flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
<example>
<title>Information about the current audio input</title>
@@ -420,14 +348,14 @@ driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
<programlisting>
&v4l2-audio; audio;
memset (&amp;audio, 0, sizeof (audio));
memset(&amp;audio, 0, sizeof(audio));
if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
perror ("VIDIOC_G_AUDIO");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
perror("VIDIOC_G_AUDIO");
exit(EXIT_FAILURE);
}
printf ("Current input: %s\n", audio.name);
printf("Current input: %s\n", audio.name);
</programlisting>
</example>
@@ -437,13 +365,13 @@ printf ("Current input: %s\n", audio.name);
<programlisting>
&v4l2-audio; audio;
memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
memset(&amp;audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
audio.index = 0;
if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
perror ("VIDIOC_S_AUDIO");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
perror("VIDIOC_S_AUDIO");
exit(EXIT_FAILURE);
}
</programlisting>
</example>
@@ -468,7 +396,7 @@ the tuner.</para>
video inputs.</para>
<para>To query and change tuner properties applications use the
&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The
&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctls, respectively. The
&v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
contains signal status information applicable when the tuner of the
current video or radio input is queried. Note that
@@ -533,7 +461,7 @@ standards or variations of standards. Each video input and output may
support another set of standards. This set is reported by the
<structfield>std</structfield> field of &v4l2-input; and
&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
&VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
&VIDIOC-ENUMOUTPUT; ioctls, respectively.</para>
<para>V4L2 defines one bit for each analog video standard
currently in use worldwide, and sets aside bits for driver defined
@@ -564,28 +492,10 @@ automatically.</para>
<para>To query and select the standard used by the current video
input or output applications call the &VIDIOC-G-STD; and
&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote>
<para>An alternative to the current scheme is to use pointers
to indices as arguments of <constant>VIDIOC_G_STD</constant> and
<constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
&v4l2-output; <structfield>std</structfield> field would be a set of
indices like <structfield>audioset</structfield>.</para>
<para>Indices are consistent with the rest of the API
and identify the standard unambiguously. In the present scheme of
things an enumerated standard is looked up by &v4l2-std-id;. Now the
standards supported by the inputs of a device can overlap. Just
assume the tuner and composite input in the example above both
exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
a choice which does not exist. We cannot merge or omit sets, because
applications would be unable to find the standards reported by
<constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
for each input. Also selecting a standard by &v4l2-std-id; can be
ambiguous. Advantage of this method is that applications need not
identify the standard indirectly, after enumerating.</para><para>So in
summary, the lookup itself is unavoidable. The difference is only
whether the lookup is necessary to find an enumerated standard or to
switch to a standard by &v4l2-std-id;.</para>
</footnote> Drivers must implement all video standard ioctls
standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the
parameter of all these ioctls is a pointer to a &v4l2-std-id; type
(a standard set), <emphasis>not</emphasis> an index into the standard
enumeration. Drivers must implement all video standard ioctls
when the device has one or more video inputs or outputs.</para>
<para>Special rules apply to devices such as USB cameras where the notion of video
@@ -604,17 +514,10 @@ to zero and the <constant>VIDIOC_G_STD</constant>,
<constant>VIDIOC_S_STD</constant>,
<constant>VIDIOC_QUERYSTD</constant> and
<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
&ENOTTY;.<footnote>
<para>See <xref linkend="buffer" /> for a rationale.</para>
&ENOTTY; or the &EINVAL;.</para>
<para>Applications can make use of the <xref linkend="input-capabilities" /> and
<xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls
are available for the device.</para>
<para>See <xref linkend="buffer" /> for a rationale. Probably
even USB cameras follow some well known video standard. It might have
been better to explicitly indicate elsewhere if a device cannot live
up to normal expectations, instead of this exception.</para>
</footnote></para>
can be used with the given input or output.</para>
<example>
<title>Information about the current video standard</title>
@@ -623,22 +526,22 @@ up to normal expectations, instead of this exception.</para>
&v4l2-std-id; std_id;
&v4l2-standard; standard;
if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
if (-1 == ioctl(fd, &VIDIOC-G-STD;, &amp;std_id)) {
/* Note when VIDIOC_ENUMSTD always returns ENOTTY this
is no video device or it falls under the USB exception,
and VIDIOC_G_STD returning ENOTTY is no error. */
perror ("VIDIOC_G_STD");
exit (EXIT_FAILURE);
perror("VIDIOC_G_STD");
exit(EXIT_FAILURE);
}
memset (&amp;standard, 0, sizeof (standard));
memset(&amp;standard, 0, sizeof(standard));
standard.index = 0;
while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
if (standard.id &amp; std_id) {
printf ("Current video standard: %s\n", standard.name);
exit (EXIT_SUCCESS);
printf("Current video standard: %s\n", standard.name);
exit(EXIT_SUCCESS);
}
standard.index++;
@@ -648,8 +551,8 @@ while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
empty unless this device falls under the USB exception. */
if (errno == EINVAL || standard.index == 0) {
perror ("VIDIOC_ENUMSTD");
exit (EXIT_FAILURE);
perror("VIDIOC_ENUMSTD");
exit(EXIT_FAILURE);
}
</programlisting>
</example>
@@ -662,26 +565,26 @@ input</title>
&v4l2-input; input;
&v4l2-standard; standard;
memset (&amp;input, 0, sizeof (input));
memset(&amp;input, 0, sizeof(input));
if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
perror ("VIDIOC_G_INPUT");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
perror("VIDIOC_G_INPUT");
exit(EXIT_FAILURE);
}
if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
perror ("VIDIOC_ENUM_INPUT");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
perror("VIDIOC_ENUM_INPUT");
exit(EXIT_FAILURE);
}
printf ("Current input %s supports:\n", input.name);
printf("Current input %s supports:\n", input.name);
memset (&amp;standard, 0, sizeof (standard));
memset(&amp;standard, 0, sizeof(standard));
standard.index = 0;
while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
if (standard.id &amp; input.std)
printf ("%s\n", standard.name);
printf("%s\n", standard.name);
standard.index++;
}
@@ -690,8 +593,8 @@ while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
empty unless this device falls under the USB exception. */
if (errno != EINVAL || standard.index == 0) {
perror ("VIDIOC_ENUMSTD");
exit (EXIT_FAILURE);
perror("VIDIOC_ENUMSTD");
exit(EXIT_FAILURE);
}
</programlisting>
</example>
@@ -703,21 +606,21 @@ if (errno != EINVAL || standard.index == 0) {
&v4l2-input; input;
&v4l2-std-id; std_id;
memset (&amp;input, 0, sizeof (input));
memset(&amp;input, 0, sizeof(input));
if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
perror ("VIDIOC_G_INPUT");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
perror("VIDIOC_G_INPUT");
exit(EXIT_FAILURE);
}
if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
perror ("VIDIOC_ENUM_INPUT");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
perror("VIDIOC_ENUM_INPUT");
exit(EXIT_FAILURE);
}
if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
fprintf (stderr, "Oops. B/G PAL is not supported.\n");
exit (EXIT_FAILURE);
fprintf(stderr, "Oops. B/G PAL is not supported.\n");
exit(EXIT_FAILURE);
}
/* Note this is also supposed to work when only B
@@ -725,9 +628,9 @@ if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
std_id = V4L2_STD_PAL_BG;
if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
perror ("VIDIOC_S_STD");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-S-STD;, &amp;std_id)) {
perror("VIDIOC_S_STD");
exit(EXIT_FAILURE);
}
</programlisting>
</example>
@@ -740,26 +643,25 @@ corresponding video timings. Today there are many more different hardware interf
such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
video signals and there is a need to extend the API to select the video timings
for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
the limited bits available, a new set of IOCTLs was added to set/get video timings at
the input and output: </para><itemizedlist>
<listitem>
<para>DV Timings: This will allow applications to define detailed
video timings for the interface. This includes parameters such as width, height,
polarities, frontporch, backporch etc. The <filename>linux/v4l2-dv-timings.h</filename>
the limited bits available, a new set of ioctls was added to set/get video timings at
the input and output.</para>
<para>These ioctls deal with the detailed digital video timings that define
each video format. This includes parameters such as the active video width and height,
signal polarities, frontporches, backporches, sync widths etc. The <filename>linux/v4l2-dv-timings.h</filename>
header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
<xref linkend="vesadmt" /> standards.
</para>
</listitem>
</itemizedlist>
<para>To enumerate and query the attributes of the DV timings supported by a device,
<para>To enumerate and query the attributes of the DV timings supported by a device
applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
To set DV timings for the device, applications use the
To set DV timings for the device applications use the
&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
<para>Applications can make use of the <xref linkend="input-capabilities" /> and
<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
video timings for the device.</para>
<xref linkend="output-capabilities"/> flags to determine whether the digital video ioctls
can be used with the given input or output.</para>
</section>
&sub-controls;

13
Documentation/DocBook/media/v4l/compat.xml
View File

@@ -2535,6 +2535,16 @@ fields changed from _s32 to _u32.
</orderedlist>
</section>
<section>
<title>V4L2 in Linux 3.15</title>
<orderedlist>
<listitem>
<para>Added Software Defined Radio (SDR) Interface.
</para>
</listitem>
</orderedlist>
</section>
<section id="other">
<title>Relation of V4L2 to other Linux multimedia APIs</title>
@@ -2651,6 +2661,9 @@ ioctls.</para>
<listitem>
<para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para>
</listitem>
<listitem>
<para>Software Defined Radio (SDR) Interface, <xref linkend="sdr" />.</para>
</listitem>
</itemizedlist>
</section>

176
Documentation/DocBook/media/v4l/controls.xml
View File

@@ -2256,6 +2256,26 @@ Applicable to the MPEG1, MPEG2, MPEG4 encoders.</entry>
<entry>integer</entry>
</row><row><entry spanname="descr">Sets the initial delay in milliseconds for
VBV buffer control.</entry>
</row>
<row><entry></entry></row>
<row id="v4l2-mpeg-video-hor-search-range">
<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE</constant>&nbsp;</entry>
<entry>integer</entry>
</row>
<row><entry spanname="descr">Horizontal search range defines maximum horizontal search area in pixels
to search and match for the present Macroblock (MB) in the reference picture. This V4L2 control macro is used to set
horizontal search range for motion estimation module in video encoder.</entry>
</row>
<row><entry></entry></row>
<row id="v4l2-mpeg-video-vert-search-range">
<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE</constant>&nbsp;</entry>
<entry>integer</entry>
</row>
<row><entry spanname="descr">Vertical search range defines maximum vertical search area in pixels
to search and match for the present Macroblock (MB) in the reference picture. This V4L2 control macro is used to set
vertical search range for motion estimation module in video encoder.</entry>
</row>
<row><entry></entry></row>
@@ -4370,6 +4390,24 @@ interface and may change in the future.</para>
<entry>The flash controller has detected a short or open
circuit condition on the indicator LED.</entry>
</row>
<row>
<entry><constant>V4L2_FLASH_FAULT_UNDER_VOLTAGE</constant></entry>
<entry>Flash controller voltage to the flash LED
has been below the minimum limit specific to the flash
controller.</entry>
</row>
<row>
<entry><constant>V4L2_FLASH_FAULT_INPUT_VOLTAGE</constant></entry>
<entry>The input voltage of the flash controller is below
the limit under which strobing the flash at full current
will not be possible.The condition persists until this flag
is no longer set.</entry>
</row>
<row>
<entry><constant>V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE</constant></entry>
<entry>The temperature of the LED has exceeded its
allowed upper limit.</entry>
</row>
</tbody>
</entrytbl>
</row>
@@ -4971,4 +5009,142 @@ defines possible values for de-emphasis. Here they are:</entry>
</table>
</section>
<section id="rf-tuner-controls">
<title>RF Tuner Control Reference</title>
<para>
The RF Tuner (RF_TUNER) class includes controls for common features of devices
having RF tuner.
</para>
<para>
In this context, RF tuner is radio receiver circuit between antenna and
demodulator. It receives radio frequency (RF) from the antenna and converts that
received signal to lower intermediate frequency (IF) or baseband frequency (BB).
Tuners that could do baseband output are often called Zero-IF tuners. Older
tuners were typically simple PLL tuners inside a metal box, whilst newer ones
are highly integrated chips without a metal box "silicon tuners". These controls
are mostly applicable for new feature rich silicon tuners, just because older
tuners does not have much adjustable features.
</para>
<para>
For more information about RF tuners see
<ulink url="http://en.wikipedia.org/wiki/Tuner_%28radio%29">Tuner (radio)</ulink>
and
<ulink url="http://en.wikipedia.org/wiki/RF_front_end">RF front end</ulink>
from Wikipedia.
</para>
<table pgwide="1" frame="none" id="rf-tuner-control-id">
<title>RF_TUNER Control IDs</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="1*" />
<colspec colname="c2" colwidth="6*" />
<colspec colname="c3" colwidth="2*" />
<colspec colname="c4" colwidth="6*" />
<spanspec namest="c1" nameend="c2" spanname="id" />
<spanspec namest="c2" nameend="c4" spanname="descr" />
<thead>
<row>
<entry spanname="id" align="left">ID</entry>
<entry align="left">Type</entry>
</row>
<row rowsep="1">
<entry spanname="descr" align="left">Description</entry>
</row>
</thead>
<tbody valign="top">
<row><entry></entry></row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_CLASS</constant>&nbsp;</entry>
<entry>class</entry>
</row><row><entry spanname="descr">The RF_TUNER class
descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
description of this control class.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_BANDWIDTH_AUTO</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row>
<entry spanname="descr">Enables/disables tuner radio channel
bandwidth configuration. In automatic mode bandwidth configuration is performed
by the driver.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_BANDWIDTH</constant>&nbsp;</entry>
<entry>integer</entry>
</row>
<row>
<entry spanname="descr">Filter(s) on tuner signal path are used to
filter signal according to receiving party needs. Driver configures filters to
fulfill desired bandwidth requirement. Used when V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not
set. Unit is in Hz. The range and step are driver-specific.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row>
<entry spanname="descr">Enables/disables LNA automatic gain control (AGC)</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row>
<entry spanname="descr">Enables/disables mixer automatic gain control (AGC)</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_IF_GAIN_AUTO</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row>
<entry spanname="descr">Enables/disables IF automatic gain control (AGC)</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN</constant>&nbsp;</entry>
<entry>integer</entry>
</row>
<row>
<entry spanname="descr">LNA (low noise amplifier) gain is first
gain stage on the RF tuner signal path. It is located very close to tuner
antenna input. Used when <constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant> is not set.
The range and step are driver-specific.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_MIXER_GAIN</constant>&nbsp;</entry>
<entry>integer</entry>
</row>
<row>
<entry spanname="descr">Mixer gain is second gain stage on the RF
tuner signal path. It is located inside mixer block, where RF signal is
down-converted by the mixer. Used when <constant>V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO</constant>
is not set. The range and step are driver-specific.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_IF_GAIN</constant>&nbsp;</entry>
<entry>integer</entry>
</row>
<row>
<entry spanname="descr">IF gain is last gain stage on the RF tuner
signal path. It is located on output of RF tuner. It controls signal level of
intermediate frequency output or baseband output. Used when
<constant>V4L2_CID_RF_TUNER_IF_GAIN_AUTO</constant> is not set. The range and step are
driver-specific.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RF_TUNER_PLL_LOCK</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row>
<entry spanname="descr">Is synthesizer PLL locked? RF tuner is
receiving given frequency when that control is set. This is a read-only control.
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>

22
Documentation/DocBook/media/v4l/dev-osd.xml
View File

@@ -56,18 +56,18 @@ framebuffer device.</para>
unsigned int i;
int fb_fd;
if (-1 == ioctl (fd, VIDIOC_G_FBUF, &amp;fbuf)) {
perror ("VIDIOC_G_FBUF");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, VIDIOC_G_FBUF, &amp;fbuf)) {
perror("VIDIOC_G_FBUF");
exit(EXIT_FAILURE);
}
for (i = 0; i &gt; 30; ++i) {
for (i = 0; i &lt; 30; i++) {
char dev_name[16];
struct fb_fix_screeninfo si;
snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i);
snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
fb_fd = open (dev_name, O_RDWR);
fb_fd = open(dev_name, O_RDWR);
if (-1 == fb_fd) {
switch (errno) {
case ENOENT: /* no such file */
@@ -75,19 +75,19 @@ for (i = 0; i &gt; 30; ++i) {
continue;
default:
perror ("open");
exit (EXIT_FAILURE);
perror("open");
exit(EXIT_FAILURE);
}
}
if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
if (si.smem_start == (unsigned long) fbuf.base)
if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
if (si.smem_start == (unsigned long)fbuf.base)
break;
} else {
/* Apparently not a framebuffer device. */
}
close (fb_fd);
close(fb_fd);
fb_fd = -1;
}

110
Documentation/DocBook/media/v4l/dev-sdr.xml Normal file
View File

@@ -0,0 +1,110 @@
<title>Software Defined Radio Interface (SDR)</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental"> experimental </link>
interface and may change in the future.</para>
</note>
<para>
SDR is an abbreviation of Software Defined Radio, the radio device
which uses application software for modulation or demodulation. This interface
is intended for controlling and data streaming of such devices.
</para>
<para>
SDR devices are accessed through character device special files named
<filename>/dev/swradio0</filename> to <filename>/dev/swradio255</filename>
with major number 81 and dynamically allocated minor numbers 0 to 255.
</para>
<section>
<title>Querying Capabilities</title>
<para>
Devices supporting the SDR receiver interface set the
<constant>V4L2_CAP_SDR_CAPTURE</constant> and
<constant>V4L2_CAP_TUNER</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an
Analog to Digital Converter (ADC), which is a mandatory element for the SDR receiver.
At least one of the read/write, streaming or asynchronous I/O methods must
be supported.
</para>
</section>
<section>
<title>Supplemental Functions</title>
<para>
SDR devices can support <link linkend="control">controls</link>, and must
support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used
for setting the ADC sampling rate (sampling frequency) and the possible RF tuner
frequency.
</para>
<para>
The <constant>V4L2_TUNER_ADC</constant> tuner type is used for ADC tuners, and
the <constant>V4L2_TUNER_RF</constant> tuner type is used for RF tuners. The
tuner index of the RF tuner (if any) must always follow the ADC tuner index.
Normally the ADC tuner is #0 and the RF tuner is #1.
</para>
<para>
The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported.
</para>
</section>
<section>
<title>Data Format Negotiation</title>
<para>
The SDR capture device uses the <link linkend="format">format</link> ioctls to
select the capture format. Both the sampling resolution and the data streaming
format are bound to that selectable format. In addition to the basic
<link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl
must be supported as well.
</para>
<para>
To use the <link linkend="format">format</link> ioctls applications set the
<structfield>type</structfield> field of a &v4l2-format; to
<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-sdr-format;
<structfield>sdr</structfield> member of the <structfield>fmt</structfield>
union as needed per the desired operation.
Currently only the <structfield>pixelformat</structfield> field of
&v4l2-sdr-format; is used. The content of that field is the V4L2 fourcc code
of the data format.
</para>
<table pgwide="1" frame="none" id="v4l2-sdr-format">
<title>struct <structname>v4l2_sdr_format</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>pixelformat</structfield></entry>
<entry>
The data format or type of compression, set by the application. This is a
little endian <link linkend="v4l2-fourcc">four character code</link>.
V4L2 defines SDR formats in <xref linkend="sdr-formats" />.
</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>reserved[28]</structfield></entry>
<entry>This array is reserved for future extensions.
Drivers and applications must set it to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
An SDR device may support <link linkend="rw">read/write</link>
and/or streaming (<link linkend="mmap">memory mapping</link>
or <link linkend="userp">user pointer</link>) I/O.
</para>
</section>

189
Documentation/DocBook/media/v4l/io.xml
View File

@@ -339,8 +339,8 @@ returns immediately with an &EAGAIN; when no buffer is available. The
queues as a side effect. Since there is no notion of doing anything
"now" on a multitasking system, if an application needs to synchronize
with another event it should examine the &v4l2-buffer;
<structfield>timestamp</structfield> of captured buffers, or set the
field before enqueuing buffers for output.</para>
<structfield>timestamp</structfield> of captured or outputted buffers.
</para>
<para>Drivers implementing memory mapping I/O must
support the <constant>VIDIOC_REQBUFS</constant>,
@@ -457,7 +457,7 @@ queues and unlocks all buffers as a side effect. Since there is no
notion of doing anything "now" on a multitasking system, if an
application needs to synchronize with another event it should examine
the &v4l2-buffer; <structfield>timestamp</structfield> of captured
buffers, or set the field before enqueuing buffers for output.</para>
or outputted buffers.</para>
<para>Drivers implementing user pointer I/O must
support the <constant>VIDIOC_REQBUFS</constant>,
@@ -620,8 +620,7 @@ returns immediately with an &EAGAIN; when no buffer is available. The
unlocks all buffers as a side effect. Since there is no notion of doing
anything "now" on a multitasking system, if an application needs to synchronize
with another event it should examine the &v4l2-buffer;
<structfield>timestamp</structfield> of captured buffers, or set the field
before enqueuing buffers for output.</para>
<structfield>timestamp</structfield> of captured or outputted buffers.</para>
<para>Drivers implementing DMABUF importing I/O must support the
<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>,
@@ -654,38 +653,19 @@ plane, are stored in struct <structname>v4l2_plane</structname> instead.
In that case, struct <structname>v4l2_buffer</structname> contains an array of
plane structures.</para>
<para>Nominally timestamps refer to the first data byte transmitted.
In practice however the wide range of hardware covered by the V4L2 API
limits timestamp accuracy. Often an interrupt routine will
sample the system clock shortly after the field or frame was stored
completely in memory. So applications must expect a constant
difference up to one field or frame period plus a small (few scan
lines) random error. The delay and error can be much
larger due to compression or transmission over an external bus when
the frames are not properly stamped by the sender. This is frequently
the case with USB cameras. Here timestamps refer to the instant the
field or frame was received by the driver, not the capture time. These
devices identify by not enumerating any video standards, see <xref
linkend="standard" />.</para>
<para>Similar limitations apply to output timestamps. Typically
the video hardware locks to a clock controlling the video timing, the
horizontal and vertical synchronization pulses. At some point in the
line sequence, possibly the vertical blanking, an interrupt routine
samples the system clock, compares against the timestamp and programs
the hardware to repeat the previous field or frame, or to display the
buffer contents.</para>
<para>Apart of limitations of the video device and natural
inaccuracies of all clocks, it should be noted system time itself is
not perfectly stable. It can be affected by power saving cycles,
warped to insert leap seconds, or even turned back or forth by the
system administrator affecting long term measurements. <footnote>
<para>Since no other Linux multimedia
API supports unadjusted time it would be foolish to introduce here. We
must use a universally supported clock to synchronize different media,
hence time of day.</para>
</footnote></para>
<para>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
<constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and
<constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref
linkend="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 &VIDIOC-S-INPUT; or
&VIDIOC-S-OUTPUT; however. The
<constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> 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.</para>
<table frame="none" pgwide="1" id="v4l2-buffer">
<title>struct <structname>v4l2_buffer</structname></title>
@@ -696,10 +676,11 @@ hence time of day.</para>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry></entry>
<entry>Number of the buffer, set by the application. This
field is only used for <link linkend="mmap">memory mapping</link> I/O
and can range from zero to the number of buffers allocated
with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
<entry>Number of the buffer, set by the application except
when calling &VIDIOC-DQBUF;, then it is set by the driver.
This field can range from zero to the number of buffers allocated
with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>),
plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -718,7 +699,7 @@ linkend="v4l2-buf-type" /></entry>
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 <structfield>type</structfield>
refers to an input stream, applications when an output stream.</entry>
refers to an input stream, applications when it refers to an output stream.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -735,7 +716,7 @@ linkend="buffer-flags" />.</entry>
buffer, see <xref linkend="v4l2-field" />. This field is not used when
the buffer contains VBI data. Drivers must set it when
<structfield>type</structfield> refers to an input stream,
applications when an output stream.</entry>
applications when it refers to an output stream.</entry>
</row>
<row>
<entry>struct timeval</entry>
@@ -745,15 +726,13 @@ applications when an output stream.</entry>
byte was captured, as returned by the
<function>clock_gettime()</function> function for the relevant
clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in
<xref linkend="buffer-flags" />. For output streams the data
will not be displayed before this time, secondary to the nominal
frame rate determined by the current video standard in enqueued
order. Applications can for example zero this field to display
frames as soon as possible. The driver stores the time at which
the first data byte was actually sent out in the
<structfield>timestamp</structfield> field. This permits
<xref linkend="buffer-flags" />. For output streams the driver
stores the time at which the last data byte was actually sent out
in the <structfield>timestamp</structfield> field. This permits
applications to monitor the drift between the video and system
clock.</para></entry>
clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant>
the application has to fill in the timestamp which will be copied
by the driver to the capture stream.</para></entry>
</row>
<row>
<entry>&v4l2-timecode;</entry>
@@ -846,7 +825,8 @@ is the file descriptor associated with a DMABUF buffer.</entry>
<entry><structfield>length</structfield></entry>
<entry></entry>
<entry>Size of the buffer (not the payload) in bytes for the
single-planar API. For the multi-planar API the application sets
single-planar API. This is set by the driver based on the calls to
&VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets
this to the number of elements in the <structfield>planes</structfield>
array. The driver will fill in the actual number of valid elements in
that array.
@@ -880,13 +860,15 @@ should set this to 0.</entry>
<entry><structfield>bytesused</structfield></entry>
<entry></entry>
<entry>The number of bytes occupied by data in the plane
(its payload).</entry>
(its payload). Drivers must set this field when <structfield>type</structfield>
refers to an input stream, applications when it refers to an output stream.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>length</structfield></entry>
<entry></entry>
<entry>Size in bytes of the plane (not its payload).</entry>
<entry>Size in bytes of the plane (not its payload). This is set by the driver
based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry>
</row>
<row>
<entry>union</entry>
@@ -925,7 +907,9 @@ should set this to 0.</entry>
<entry>__u32</entry>
<entry><structfield>data_offset</structfield></entry>
<entry></entry>
<entry>Offset in bytes to video data in the plane, if applicable.
<entry>Offset in bytes to video data in the plane.
Drivers must set this field when <structfield>type</structfield>
refers to an input stream, applications when it refers to an output stream.
</entry>
</row>
<row>
@@ -1005,6 +989,12 @@ should set this to 0.</entry>
<entry>Buffer for video output overlay (OSD), see <xref
linkend="osd" />.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry>
<entry>11</entry>
<entry>Buffer for Software Defined Radio (SDR), see <xref
linkend="sdr" />.</entry>
</row>
</tbody>
</tgroup>
</table>
@@ -1016,7 +1006,7 @@ should set this to 0.</entry>
<tbody valign="top">
<row>
<entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
<entry>0x0001</entry>
<entry>0x00000001</entry>
<entry>The buffer resides in device memory and has been mapped
into the application's address space, see <xref linkend="mmap" /> for details.
Drivers set or clear this flag when the
@@ -1026,7 +1016,7 @@ Drivers set or clear this flag when the
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
<entry>0x0002</entry>
<entry>0x00000002</entry>
<entry>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
@@ -1039,7 +1029,7 @@ cleared.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
<entry>0x0004</entry>
<entry>0x00000004</entry>
<entry>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 <constant>VIDIOC_QUERYBUF</constant> ioctl
@@ -1049,11 +1039,11 @@ buffer cannot be on both queues at the same time, the
<constant>V4L2_BUF_FLAG_QUEUED</constant> and
<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
They can be both cleared however, then the buffer is in "dequeued"
state, in the application domain to say so.</entry>
state, in the application domain so to say.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
<entry>0x0040</entry>
<entry>0x00000040</entry>
<entry>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
@@ -1063,35 +1053,43 @@ state, in the application domain to say so.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
<entry>0x0008</entry>
<entry>0x00000008</entry>
<entry>Drivers set or clear this flag when calling the
<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
capture devices when the buffer contains a compressed image which is a
key frame (or field), &ie; can be decompressed on its own.</entry>
key frame (or field), &ie; can be decompressed on its own. Also know as
an I-frame. Applications can set this bit when <structfield>type</structfield>
refers to an output stream.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
<entry>0x0010</entry>
<entry>0x00000010</entry>
<entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
this flags predicted frames or fields which contain only differences to a
previous key frame.</entry>
previous key frame. Applications can set this bit when <structfield>type</structfield>
refers to an output stream.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
<entry>0x0020</entry>
<entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
this is a bidirectional predicted frame or field. [ooc tbd]</entry>
<entry>0x00000020</entry>
<entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
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
<structfield>type</structfield> refers to an output stream.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
<entry>0x0100</entry>
<entry>0x00000100</entry>
<entry>The <structfield>timecode</structfield> field is valid.
Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
ioctl is called.</entry>
ioctl is called. Applications can set this bit and the corresponding
<structfield>timecode</structfield> structure when <structfield>type</structfield>
refers to an output stream.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
<entry>0x0400</entry>
<entry>0x00000400</entry>
<entry>The buffer has been prepared for I/O and can be queued by the
application. Drivers set or clear this flag when the
<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
@@ -1101,7 +1099,7 @@ application. Drivers set or clear this flag when the
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>
<entry>0x0800</entry>
<entry>0x00000800</entry>
<entry>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
@@ -1110,7 +1108,7 @@ passed on to a DMA-capable hardware unit for further processing or output.
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>
<entry>0x1000</entry>
<entry>0x00001000</entry>
<entry>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,
@@ -1118,7 +1116,7 @@ in which case caches have not been used.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry>
<entry>0xe000</entry>
<entry>0x0000e000</entry>
<entry>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
@@ -1126,7 +1124,7 @@ in which case caches have not been used.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry>
<entry>0x0000</entry>
<entry>0x00000000</entry>
<entry>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
@@ -1139,7 +1137,7 @@ in which case caches have not been used.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry>
<entry>0x2000</entry>
<entry>0x00002000</entry>
<entry>The buffer timestamp has been taken from the
<constant>CLOCK_MONOTONIC</constant> clock. To access the
same clock outside V4L2, use
@@ -1147,10 +1145,42 @@ in which case caches have not been used.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry>
<entry>0x4000</entry>
<entry>0x00004000</entry>
<entry>The CAPTURE buffer timestamp has been taken from the
corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry>
<entry>0x00070000</entry>
<entry>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
<structfield>flags</structfield> field and
<constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the
value of the timestamp source. Applications must set the timestamp
source when <structfield>type</structfield> refers to an output stream
and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>
<entry>0x00000000</entry>
<entry>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.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry>
<entry>0x00010000</entry>
<entry>Start Of Exposure. The buffer timestamp has been
taken when the exposure of the frame has begun. This is
only valid for the
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer
type.</entry>
</row>
</tbody>
</tgroup>
</table>
@@ -1440,10 +1470,9 @@ or application, depending on data direction, must set &v4l2-buffer;
<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
to build a frame. If fields are successive, without any dropped fields
between them (fields can drop individually), can be determined from
the &v4l2-buffer; <structfield>sequence</structfield> field. Image
sizes refer to the frame, not fields. This format cannot be selected
when using the read/write I/O method.<!-- Where it's indistinguishable
from V4L2_FIELD_SEQ_*. --></entry>
the &v4l2-buffer; <structfield>sequence</structfield> field. This format
cannot be selected when using the read/write I/O method since there
is no way to communicate if a field was a top or bottom field.</entry>
</row>
<row>
<entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>

9
Documentation/DocBook/media/v4l/pixfmt-nv16m.xml
View File

@@ -12,18 +12,17 @@
<refsect1>
<title>Description</title>
<para>This is a multi-planar, two-plane version of the YUV 4:2:0 format.
<para>This is a multi-planar, two-plane version of the YUV 4:2:2 format.
The three components are separated into two sub-images or planes.
<constant>V4L2_PIX_FMT_NV16M</constant> differs from <constant>V4L2_PIX_FMT_NV16
</constant> in that the two planes are non-contiguous in memory, i.e. the chroma
plane does not necessarily immediately follows the luma plane.
plane does not necessarily immediately follow the luma plane.
The luminance data occupies the first plane. The Y plane has one byte per pixel.
In the second plane there is chrominance data with alternating chroma samples.
The CbCr plane is the same width and height, in bytes, as the Y plane.
Each CbCr pair belongs to four pixels. For example,
Each CbCr pair belongs to two pixels. For example,
Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.
Y'<subscript>00</subscript>, Y'<subscript>01</subscript>.
<constant>V4L2_PIX_FMT_NV61M</constant> is the same as <constant>V4L2_PIX_FMT_NV16M</constant>
except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>

513
Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
View File

@@ -121,14 +121,14 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
<entry>'RGB1'</entry>
<entry></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB444">
<entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
@@ -159,18 +159,18 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>a</entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>a</entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
</row>
@@ -181,17 +181,17 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
@@ -201,32 +201,32 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry>'RGBQ'</entry>
<entry></entry>
<entry>a</entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB565X">
<entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
<entry>'RGBR'</entry>
<entry></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB565X">
<entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
<entry>'RGBR'</entry>
<entry></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
@@ -234,11 +234,11 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-BGR666">
<entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
@@ -385,6 +385,15 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
<entry>'RGB4'</entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
@@ -411,25 +420,16 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
</row>
</tbody>
</tgroup>
</table>
<para>Bit 7 is the most significant bit. The value of a = alpha
<para>Bit 7 is the most significant bit. The value of the a = alpha
bits is undefined when reading from the driver, ignored when writing
to the driver, except when alpha blending has been negotiated for a
<link linkend="overlay">Video Overlay</link> or <link linkend="osd">
Video Output Overlay</link> or when alpha component has been configured
Video Output Overlay</link> or when the alpha component has been configured
for a <link linkend="capture">Video Capture</link> by means of <link
linkend="v4l2-alpha-component"> <constant>V4L2_CID_ALPHA_COMPONENT
</constant> </link> control.</para>
@@ -512,421 +512,6 @@ image</title>
</formalpara>
</example>
<important>
<para>Drivers may interpret these formats differently.</para>
</important>
<para>Some RGB formats above are uncommon and were probably
defined in error. Drivers may interpret them as in <xref
linkend="rgb-formats-corrected" />.</para>
<table pgwide="1" frame="none" id="rgb-formats-corrected">
<title>Packed RGB Image Formats (corrected)</title>
<tgroup cols="37" align="center">
<colspec colname="id" align="left" />
<colspec colname="fourcc" />
<colspec colname="bit" />
<colspec colnum="4" colname="b07" align="center" />
<colspec colnum="5" colname="b06" align="center" />
<colspec colnum="6" colname="b05" align="center" />
<colspec colnum="7" colname="b04" align="center" />
<colspec colnum="8" colname="b03" align="center" />
<colspec colnum="9" colname="b02" align="center" />
<colspec colnum="10" colname="b01" align="center" />
<colspec colnum="11" colname="b00" align="center" />
<colspec colnum="13" colname="b17" align="center" />
<colspec colnum="14" colname="b16" align="center" />
<colspec colnum="15" colname="b15" align="center" />
<colspec colnum="16" colname="b14" align="center" />
<colspec colnum="17" colname="b13" align="center" />
<colspec colnum="18" colname="b12" align="center" />
<colspec colnum="19" colname="b11" align="center" />
<colspec colnum="20" colname="b10" align="center" />
<colspec colnum="22" colname="b27" align="center" />
<colspec colnum="23" colname="b26" align="center" />
<colspec colnum="24" colname="b25" align="center" />
<colspec colnum="25" colname="b24" align="center" />
<colspec colnum="26" colname="b23" align="center" />
<colspec colnum="27" colname="b22" align="center" />
<colspec colnum="28" colname="b21" align="center" />
<colspec colnum="29" colname="b20" align="center" />
<colspec colnum="31" colname="b37" align="center" />
<colspec colnum="32" colname="b36" align="center" />
<colspec colnum="33" colname="b35" align="center" />
<colspec colnum="34" colname="b34" align="center" />
<colspec colnum="35" colname="b33" align="center" />
<colspec colnum="36" colname="b32" align="center" />
<colspec colnum="37" colname="b31" align="center" />
<colspec colnum="38" colname="b30" align="center" />
<spanspec namest="b07" nameend="b00" spanname="b0" />
<spanspec namest="b17" nameend="b10" spanname="b1" />
<spanspec namest="b27" nameend="b20" spanname="b2" />
<spanspec namest="b37" nameend="b30" spanname="b3" />
<thead>
<row>
<entry>Identifier</entry>
<entry>Code</entry>
<entry>&nbsp;</entry>
<entry spanname="b0">Byte&nbsp;0 in memory</entry>
<entry spanname="b1">Byte&nbsp;1</entry>
<entry spanname="b2">Byte&nbsp;2</entry>
<entry spanname="b3">Byte&nbsp;3</entry>
</row>
<row>
<entry>&nbsp;</entry>
<entry>&nbsp;</entry>
<entry>Bit</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
</row>
</thead>
<tbody valign="top">
<row><!-- id="V4L2-PIX-FMT-RGB332" -->
<entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
<entry>'RGB1'</entry>
<entry></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB444" -->
<entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
<entry>'R444'</entry>
<entry></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB555" -->
<entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
<entry>'RGBO'</entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>a</entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB565" -->
<entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
<entry>'RGBP'</entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB555X" -->
<entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry>
<entry>'RGBQ'</entry>
<entry></entry>
<entry>a</entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB565X" -->
<entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
<entry>'RGBR'</entry>
<entry></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-BGR666" -->
<entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
<entry>'BGRH'</entry>
<entry></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-BGR24" -->
<entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
<entry>'BGR3'</entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB24" -->
<entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
<entry>'RGB3'</entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-BGR32" -->
<entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
<entry>'BGR4'</entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB32" -->
<entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
<entry>'RGB4'</entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
</tbody>
</tgroup>
</table>
<para>A test utility to determine which RGB formats a driver
actually supports is available from the LinuxTV v4l-dvb repository.
See &v4l-dvb; for access instructions.</para>

44
Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml Normal file
View File

@@ -0,0 +1,44 @@
<refentry id="V4L2-SDR-FMT-CU08">
<refmeta>
<refentrytitle>V4L2_SDR_FMT_CU8 ('CU08')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>
<constant>V4L2_SDR_FMT_CU8</constant>
</refname>
<refpurpose>Complex unsigned 8-bit IQ sample</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
This format contains sequence of complex number samples. Each complex number
consist two parts, called In-phase and Quadrature (IQ). Both I and Q are
represented as a 8 bit unsigned number. I value comes first and Q value after
that.
</para>
<example>
<title><constant>V4L2_SDR_FMT_CU8</constant> 1 sample</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="2" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>I'<subscript>0</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;1:</entry>
<entry>Q'<subscript>0</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>

46
Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml Normal file
View File

@@ -0,0 +1,46 @@
<refentry id="V4L2-SDR-FMT-CU16LE">
<refmeta>
<refentrytitle>V4L2_SDR_FMT_CU16LE ('CU16')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>
<constant>V4L2_SDR_FMT_CU16LE</constant>
</refname>
<refpurpose>Complex unsigned 16-bit little endian IQ sample</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
This format contains sequence of complex number samples. Each complex number
consist two parts, called In-phase and Quadrature (IQ). Both I and Q are
represented as a 16 bit unsigned little endian number. I value comes first
and Q value after that.
</para>
<example>
<title><constant>V4L2_SDR_FMT_CU16LE</constant> 1 sample</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="3" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>I'<subscript>0[7:0]</subscript></entry>
<entry>I'<subscript>0[15:8]</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;2:</entry>
<entry>Q'<subscript>0[7:0]</subscript></entry>
<entry>Q'<subscript>0[15:8]</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>

34
Documentation/DocBook/media/v4l/pixfmt.xml
View File

@@ -25,7 +25,12 @@ capturing and output, for overlay frame buffer formats see also
<row>
<entry>__u32</entry>
<entry><structfield>height</structfield></entry>
<entry>Image height in pixels.</entry>
<entry>Image height in pixels. If <structfield>field</structfield> is
one of <constant>V4L2_FIELD_TOP</constant>, <constant>V4L2_FIELD_BOTTOM</constant>
or <constant>V4L2_FIELD_ALTERNATE</constant> then height refers to the
number of lines in the field, otherwise it refers to the number of
lines in the frame (which is twice the field height for interlaced
formats).</entry>
</row>
<row>
<entry spanname="hspan">Applications set these fields to
@@ -54,7 +59,7 @@ linkend="reserved-formats" /></entry>
can request to capture or output only the top or bottom field, or both
fields interlaced or sequentially stored in one buffer or alternating
in separate buffers. Drivers return the actual field order selected.
For details see <xref linkend="field-order" />.</entry>
For more details on fields see <xref linkend="field-order" />.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -81,7 +86,10 @@ plane and is divided by the same factor as the
example the Cb and Cr planes of a YUV 4:2:0 image have half as many
padding bytes following each line as the Y plane. To avoid ambiguities
drivers must return a <structfield>bytesperline</structfield> value
rounded up to a multiple of the scale factor.</para></entry>
rounded up to a multiple of the scale factor.</para>
<para>For compressed formats the <structfield>bytesperline</structfield>
value makes no sense. Applications and drivers must set this to 0 in
that case.</para></entry>
</row>
<row>
<entry>__u32</entry>
@@ -97,7 +105,8 @@ hold an image.</entry>
<entry>&v4l2-colorspace;</entry>
<entry><structfield>colorspace</structfield></entry>
<entry>This information supplements the
<structfield>pixelformat</structfield> and must be set by the driver,
<structfield>pixelformat</structfield> and must be set by the driver for
capture streams and by the application for output streams,
see <xref linkend="colorspaces" />.</entry>
</row>
<row>
@@ -135,7 +144,7 @@ set this field to zero.</entry>
<entry>__u16</entry>
<entry><structfield>bytesperline</structfield></entry>
<entry>Distance in bytes between the leftmost pixels in two adjacent
lines.</entry>
lines. See &v4l2-pix-format;.</entry>
</row>
<row>
<entry>__u16</entry>
@@ -154,12 +163,12 @@ set this field to zero.</entry>
<row>
<entry>__u32</entry>
<entry><structfield>width</structfield></entry>
<entry>Image width in pixels.</entry>
<entry>Image width in pixels. See &v4l2-pix-format;.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>height</structfield></entry>
<entry>Image height in pixels.</entry>
<entry>Image height in pixels. See &v4l2-pix-format;.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -811,6 +820,17 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
</table>
</section>
<section id="sdr-formats">
<title>SDR Formats</title>
<para>These formats are used for <link linkend="sdr">SDR Capture</link>
interface only.</para>
&sub-sdr-cu08;
&sub-sdr-cu16le;
</section>
<section id="pixfmt-reserved">
<title>Reserved Format Identifiers</title>

143
Documentation/DocBook/media/v4l/remote_controllers.xml
View File

@@ -1,10 +1,152 @@
<partinfo>
<authorgroup>
<author>
<firstname>Mauro</firstname>
<surname>Chehab</surname>
<othername role="mi">Carvalho</othername>
<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation>
<contrib>Initial version.</contrib>
</author>
</authorgroup>
<copyright>
<year>2009-2014</year>
<holder>Mauro Carvalho Chehab</holder>
</copyright>
<revhistory>
<!-- Put document revisions here, newest first. -->
<revision>
<revnumber>3.15</revnumber>
<date>2014-02-06</date>
<authorinitials>mcc</authorinitials>
<revremark>Added the interface description and the RC sysfs class description.</revremark>
</revision>
<revision>
<revnumber>1.0</revnumber>
<date>2009-09-06</date>
<authorinitials>mcc</authorinitials>
<revremark>Initial revision</revremark>
</revision>
</revhistory>
</partinfo>
<title>Remote Controller API</title>
<chapter id="remote_controllers">
<title>Remote Controllers</title>
<section id="Remote_controllers_Intro">
<title>Introduction</title>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>In order to allow flexibility, the Remote Controller subsystem allows controlling the
RC-specific attributes via <link linkend="remote_controllers_sysfs_nodes">the sysfs class nodes</link>.</para>
</section>
<section id="remote_controllers_sysfs_nodes">
<title>Remote Controller's sysfs nodes</title>
<para>As defined at <constant>Documentation/ABI/testing/sysfs-class-rc</constant>, those are the sysfs nodes that control the Remote Controllers:</para>
<section id="sys_class_rc">
<title>/sys/class/rc/</title>
<para>The <constant>/sys/class/rc/</constant> class sub-directory belongs to the Remote Controller
core and provides a sysfs interface for configuring infrared remote controller receivers.
</para>
</section>
<section id="sys_class_rc_rcN">
<title>/sys/class/rc/rcN/</title>
<para>A <constant>/sys/class/rc/rcN</constant> directory is created for each remote
control receiver device where N is the number of the receiver.</para>
</section>
<section id="sys_class_rc_rcN_protocols">
<title>/sys/class/rc/rcN/protocols</title>
<para>Reading this file returns a list of available protocols, something like:</para>
<para><constant>rc5 [rc6] nec jvc [sony]</constant></para>
<para>Enabled protocols are shown in [] brackets.</para>
<para>Writing "+proto" will add a protocol to the list of enabled protocols.</para>
<para>Writing "-proto" will remove a protocol from the list of enabled protocols.</para>
<para>Writing "proto" will enable only "proto".</para>
<para>Writing "none" will disable all protocols.</para>
<para>Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used.</para>
</section>
<section id="sys_class_rc_rcN_filter">
<title>/sys/class/rc/rcN/filter</title>
<para>Sets the scancode filter expected value.</para>
<para>Use in combination with <constant>/sys/class/rc/rcN/filter_mask</constant> to set the
expected value of the bits set in the filter mask.
If the hardware supports it then scancodes which do not match
the filter will be ignored. Otherwise the write will fail with
an error.</para>
<para>This value may be reset to 0 if the current protocol is altered.</para>
</section>
<section id="sys_class_rc_rcN_filter_mask">
<title>/sys/class/rc/rcN/filter_mask</title>
<para>Sets the scancode filter mask of bits to compare.
Use in combination with <constant>/sys/class/rc/rcN/filter</constant> to set the bits
of the scancode which should be compared against the expected
value. A value of 0 disables the filter to allow all valid
scancodes to be processed.</para>
<para>If the hardware supports it then scancodes which do not match
the filter will be ignored. Otherwise the write will fail with
an error.</para>
<para>This value may be reset to 0 if the current protocol is altered.</para>
</section>
<section id="sys_class_rc_rcN_wakeup_protocols">
<title>/sys/class/rc/rcN/wakeup_protocols</title>
<para>Reading this file returns a list of available protocols to use for the
wakeup filter, something like:</para>
<para><constant>rc5 rc6 nec jvc [sony]</constant></para>
<para>The enabled wakeup protocol is shown in [] brackets.</para>
<para>Writing "+proto" will add a protocol to the list of enabled wakeup
protocols.</para>
<para>Writing "-proto" will remove a protocol from the list of enabled wakeup
protocols.</para>
<para>Writing "proto" will use "proto" for wakeup events.</para>
<para>Writing "none" will disable wakeup.</para>
<para>Write fails with EINVAL if an invalid protocol combination or unknown
protocol name is used, or if wakeup is not supported by the hardware.</para>
</section>
<section id="sys_class_rc_rcN_wakeup_filter">
<title>/sys/class/rc/rcN/wakeup_filter</title>
<para>Sets the scancode wakeup filter expected value.
Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter_mask</constant> to
set the expected value of the bits set in the wakeup filter mask
to trigger a system wake event.</para>
<para>If the hardware supports it and wakeup_filter_mask is not 0 then
scancodes which match the filter will wake the system from e.g.
suspend to RAM or power off.
Otherwise the write will fail with an error.</para>
<para>This value may be reset to 0 if the wakeup protocol is altered.</para>
</section>
<section id="sys_class_rc_rcN_wakeup_filter_mask">
<title>/sys/class/rc/rcN/wakeup_filter_mask</title>
<para>Sets the scancode wakeup filter mask of bits to compare.
Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter</constant> to set
the bits of the scancode which should be compared against the
expected value to trigger a system wake event.</para>
<para>If the hardware supports it and wakeup_filter_mask is not 0 then
scancodes which match the filter will wake the system from e.g.
suspend to RAM or power off.
Otherwise the write will fail with an error.</para>
<para>This value may be reset to 0 if the wakeup protocol is altered.</para>
</section>
</section>
<section id="Remote_controllers_tables">
<title>Remote controller tables</title>
<para>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
@@ -175,3 +317,4 @@ keymapping.</para>
</section>
&sub-lirc_device_interface;
</chapter>

26
Documentation/DocBook/media/v4l/v4l2.xml
View File

@@ -70,7 +70,7 @@ MPEG stream embedded, sliced VBI data format in this specification.
Remote Controller chapter.</contrib>
<affiliation>
<address>
<email>mchehab@redhat.com</email>
<email>m.chehab@samsung.com</email>
</address>
</affiliation>
</author>
@@ -107,6 +107,16 @@ Remote Controller chapter.</contrib>
</address>
</affiliation>
</author>
<author>
<firstname>Antti</firstname>
<surname>Palosaari</surname>
<contrib>SDR API.</contrib>
<affiliation>
<address>
<email>crope@iki.fi</email>
</address>
</affiliation>
</author>
</authorgroup>
<copyright>
@@ -125,6 +135,7 @@ Remote Controller chapter.</contrib>
<year>2011</year>
<year>2012</year>
<year>2013</year>
<year>2014</year>
<holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
Pawel Osciak</holder>
@@ -140,6 +151,16 @@ structs, ioctls) must be noted in more detail in the history chapter
(compat.xml), along with the possible impact on existing drivers and
applications. -->
<revision>
<revnumber>3.15</revnumber>
<date>2014-02-03</date>
<authorinitials>hv, ap</authorinitials>
<revremark>Update several sections of "Common API Elements": "Opening and Closing Devices"
"Querying Capabilities", "Application Priority", "Video Inputs and Outputs", "Audio Inputs and Outputs"
"Tuners and Modulators", "Video Standards" and "Digital Video (DV) Timings". Added SDR API.
</revremark>
</revision>
<revision>
<revnumber>3.14</revnumber>
<date>2013-11-25</date>
@@ -537,6 +558,7 @@ and discussions on the V4L mailing list.</revremark>
<section id="ttx"> &sub-dev-teletext; </section>
<section id="radio"> &sub-dev-radio; </section>
<section id="rds"> &sub-dev-rds; </section>
<section id="sdr"> &sub-dev-sdr; </section>
<section id="event"> &sub-dev-event; </section>
<section id="subdev"> &sub-dev-subdev; </section>
</chapter>
@@ -585,6 +607,7 @@ and discussions on the V4L mailing list.</revremark>
&sub-g-crop;
&sub-g-ctrl;
&sub-g-dv-timings;
&sub-g-edid;
&sub-g-enc-index;
&sub-g-ext-ctrls;
&sub-g-fbuf;
@@ -616,7 +639,6 @@ and discussions on the V4L mailing list.</revremark>
&sub-subdev-enum-frame-size;
&sub-subdev-enum-mbus-code;
&sub-subdev-g-crop;
&sub-subdev-g-edid;
&sub-subdev-g-fmt;
&sub-subdev-g-frame-interval;
&sub-subdev-g-selection;

8
Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml
View File

@@ -100,7 +100,7 @@ See <xref linkend="v4l2-tuner-type" /></entry>
<entry><structfield>capability</structfield></entry>
<entry spanname="hspan">The tuner/modulator capability flags for
this frequency band, see <xref linkend="tuner-capability" />. The <constant>V4L2_TUNER_CAP_LOW</constant>
capability must be the same for all frequency bands of the selected tuner/modulator.
or <constant>V4L2_TUNER_CAP_1HZ</constant> capability must be the same for all frequency bands of the selected tuner/modulator.
So either all bands have that capability set, or none of them have that capability.</entry>
</row>
<row>
@@ -109,7 +109,8 @@ So either all bands have that capability set, or none of them have that capabili
<entry spanname="hspan">The lowest tunable frequency in
units of 62.5 kHz, or if the <structfield>capability</structfield>
flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz, for this frequency band.</entry>
Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -117,7 +118,8 @@ Hz, for this frequency band.</entry>
<entry spanname="hspan">The highest tunable frequency in
units of 62.5 kHz, or if the <structfield>capability</structfield>
flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz, for this frequency band.</entry>
Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
</row>
<row>
<entry>__u32</entry>

36
Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml → Documentation/DocBook/media/v4l/vidioc-g-edid.xml
View File

@@ -1,12 +1,12 @@
<refentry id="vidioc-subdev-g-edid">
<refentry id="vidioc-g-edid">
<refmeta>
<refentrytitle>ioctl VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</refentrytitle>
<refentrytitle>ioctl VIDIOC_G_EDID, VIDIOC_S_EDID</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_SUBDEV_G_EDID</refname>
<refname>VIDIOC_SUBDEV_S_EDID</refname>
<refname>VIDIOC_G_EDID</refname>
<refname>VIDIOC_S_EDID</refname>
<refpurpose>Get or set the EDID of a video receiver/transmitter</refpurpose>
</refnamediv>
@@ -16,7 +16,7 @@
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_subdev_edid *<parameter>argp</parameter></paramdef>
<paramdef>struct v4l2_edid *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
@@ -24,7 +24,7 @@
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>const struct v4l2_subdev_edid *<parameter>argp</parameter></paramdef>
<paramdef>const struct v4l2_edid *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@@ -42,7 +42,7 @@
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</para>
<para>VIDIOC_G_EDID, VIDIOC_S_EDID</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -56,12 +56,20 @@
<refsect1>
<title>Description</title>
<para>These ioctls can be used to get or set an EDID associated with an input pad
from a receiver or an output pad of a transmitter subdevice.</para>
<para>These ioctls can be used to get or set an EDID associated with an input
from a receiver or an output of a transmitter device. They can be
used with subdevice nodes (/dev/v4l-subdevX) or with video nodes (/dev/videoX).</para>
<para>When used with video nodes the <structfield>pad</structfield> field represents the
input (for video capture devices) or output (for video output devices) index as
is returned by &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively. When used
with subdevice nodes the <structfield>pad</structfield> field represents the
input or output pad of the subdevice. If there is no EDID support for the given
<structfield>pad</structfield> value, then the &EINVAL; will be returned.</para>
<para>To get the EDID data the application has to fill in the <structfield>pad</structfield>,
<structfield>start_block</structfield>, <structfield>blocks</structfield> and <structfield>edid</structfield>
fields and call <constant>VIDIOC_SUBDEV_G_EDID</constant>. The current EDID from block
fields and call <constant>VIDIOC_G_EDID</constant>. The current EDID from block
<structfield>start_block</structfield> and of size <structfield>blocks</structfield>
will be placed in the memory <structfield>edid</structfield> points to. The <structfield>edid</structfield>
pointer must point to memory at least <structfield>blocks</structfield>&nbsp;*&nbsp;128 bytes
@@ -91,15 +99,17 @@
data in some way. In any case, the end result is the same: the EDID is no longer available.
</para>
<table pgwide="1" frame="none" id="v4l2-subdev-edid">
<title>struct <structname>v4l2_subdev_edid</structname></title>
<table pgwide="1" frame="none" id="v4l2-edid">
<title>struct <structname>v4l2_edid</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>pad</structfield></entry>
<entry>Pad for which to get/set the EDID blocks.</entry>
<entry>Pad for which to get/set the EDID blocks. When used with a video device
node the pad represents the input or output index as returned by
&VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively.</entry>
</row>
<row>
<entry>__u32</entry>

7
Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
View File

@@ -327,7 +327,12 @@ These controls are described in <xref
These controls are described in <xref
linkend="fm-rx-controls" />.</entry>
</row>
<row>
<entry><constant>V4L2_CTRL_CLASS_RF_TUNER</constant></entry>
<entry>0xa20000</entry>
<entry>The class containing RF tuner controls.
These controls are described in <xref linkend="rf-tuner-controls" />.</entry>
</row>
</tbody>
</tgroup>
</table>

7
Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
View File

@@ -169,6 +169,13 @@ capture and output devices.</entry>
<entry>Sliced VBI capture or output parameters. See
<xref linkend="sliced" /> for details. Used by sliced VBI
capture and output devices.</entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-sdr-format;</entry>
<entry><structfield>sdr</structfield></entry>
<entry>Definition of a data format, see
<xref linkend="pixfmt" />, used by SDR capture devices.</entry>
</row>
<row>
<entry></entry>

5
Documentation/DocBook/media/v4l/vidioc-g-frequency.xml
View File

@@ -109,9 +109,10 @@ See <xref linkend="v4l2-tuner-type" /></entry>
<entry>__u32</entry>
<entry><structfield>frequency</structfield></entry>
<entry>Tuning frequency in units of 62.5 kHz, or if the
&v4l2-tuner; or &v4l2-modulator; <structfield>capabilities</structfield> flag
&v4l2-tuner; or &v4l2-modulator; <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz.</entry>
Hz. A 1 Hz unit is used when the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
</row>
<row>
<entry>__u32</entry>

6
Documentation/DocBook/media/v4l/vidioc-g-modulator.xml
View File

@@ -113,7 +113,8 @@ change for example with the current video standard.</entry>
<entry>The lowest tunable frequency in units of 62.5
KHz, or if the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz.</entry>
Hz, or if the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -121,7 +122,8 @@ Hz.</entry>
<entry>The highest tunable frequency in units of 62.5
KHz, or if the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz.</entry>
Hz, or if the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry>
</row>
<row>
<entry>__u32</entry>

15
Documentation/DocBook/media/v4l/vidioc-g-tuner.xml
View File

@@ -134,7 +134,9 @@ the structure refers to a radio tuner the
<entry spanname="hspan">The lowest tunable frequency in
units of 62.5 kHz, or if the <structfield>capability</structfield>
flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz. If multiple frequency bands are supported, then
Hz, or if the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.
If multiple frequency bands are supported, then
<structfield>rangelow</structfield> is the lowest frequency
of all the frequency bands.</entry>
</row>
@@ -144,7 +146,9 @@ of all the frequency bands.</entry>
<entry spanname="hspan">The highest tunable frequency in
units of 62.5 kHz, or if the <structfield>capability</structfield>
flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz. If multiple frequency bands are supported, then
Hz, or if the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.
If multiple frequency bands are supported, then
<structfield>rangehigh</structfield> is the highest frequency
of all the frequency bands.</entry>
</row>
@@ -270,7 +274,7 @@ applications must set the array to zero.</entry>
<entry><constant>V4L2_TUNER_CAP_LOW</constant></entry>
<entry>0x0001</entry>
<entry>When set, tuning frequencies are expressed in units of
62.5&nbsp;Hz, otherwise in units of 62.5&nbsp;kHz.</entry>
62.5 Hz instead of 62.5 kHz.</entry>
</row>
<row>
<entry><constant>V4L2_TUNER_CAP_NORM</constant></entry>
@@ -360,6 +364,11 @@ radio tuners.</entry>
<entry>The range to search when using the hardware seek functionality
is programmable, see &VIDIOC-S-HW-FREQ-SEEK; for details.</entry>
</row>
<row>
<entry><constant>V4L2_TUNER_CAP_1HZ</constant></entry>
<entry>0x1000</entry>
<entry>When set, tuning frequencies are expressed in units of 1 Hz instead of 62.5 kHz.</entry>
</row>
</tbody>
</tgroup>
</table>

6
Documentation/DocBook/media/v4l/vidioc-querycap.xml
View File

@@ -294,6 +294,12 @@ interface. For more information on audio inputs and outputs see <xref
emit RF-modulated video/audio signals. For more information about
modulator programming see
<xref linkend="tuner" />.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_SDR_CAPTURE</constant></entry>
<entry>0x00100000</entry>
<entry>The device supports the
<link linkend="sdr">SDR Capture</link> interface.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_READWRITE</constant></entry>

8
Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml
View File

@@ -121,7 +121,9 @@ field and the &v4l2-tuner; <structfield>index</structfield> field.</entry>
<entry>If non-zero, the lowest tunable frequency of the band to
search in units of 62.5 kHz, or if the &v4l2-tuner;
<structfield>capability</structfield> field has the
<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz.
<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz or if the &v4l2-tuner;
<structfield>capability</structfield> field has the
<constant>V4L2_TUNER_CAP_1HZ</constant> flag set, in units of 1 Hz.
If <structfield>rangelow</structfield> is zero a reasonable default value
is used.</entry>
</row>
@@ -131,7 +133,9 @@ is used.</entry>
<entry>If non-zero, the highest tunable frequency of the band to
search in units of 62.5 kHz, or if the &v4l2-tuner;
<structfield>capability</structfield> field has the
<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz.
<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz or if the &v4l2-tuner;
<structfield>capability</structfield> field has the
<constant>V4L2_TUNER_CAP_1HZ</constant> flag set, in units of 1 Hz.
If <structfield>rangehigh</structfield> is zero a reasonable default value
is used.</entry>
</row>

28
Documentation/DocBook/media/v4l/vidioc-streamon.xml
View File

@@ -52,16 +52,24 @@
<para>The <constant>VIDIOC_STREAMON</constant> and
<constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture
or output process during streaming (<link linkend="mmap">memory
mapping</link> or <link linkend="userp">user pointer</link>) I/O.</para>
mapping</link>, <link linkend="userp">user pointer</link> or
<link linkend="dmabuf">DMABUF</link>) I/O.</para>
<para>Specifically the capture hardware is disabled and no input
<para>Capture hardware is disabled and no input
buffers are filled (if there are any empty buffers in the incoming
queue) until <constant>VIDIOC_STREAMON</constant> has been called.
Accordingly the output hardware is disabled, no video signal is
Output hardware is disabled and no video signal is
produced until <constant>VIDIOC_STREAMON</constant> has been called.
The ioctl will succeed when at least one output buffer is in the
incoming queue.</para>
<para>Memory-to-memory devices will not start until
<constant>VIDIOC_STREAMON</constant> has been called for both the capture
and output stream types.</para>
<para>If <constant>VIDIOC_STREAMON</constant> fails then any already
queued buffers will remain queued.</para>
<para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of
aborting or finishing any DMA in progress, unlocks any user pointer
buffers locked in physical memory, and it removes all buffers from the
@@ -70,14 +78,22 @@ dequeued yet will be lost, likewise all images enqueued for output but
not transmitted yet. I/O returns to the same state as after calling
&VIDIOC-REQBUFS; and can be restarted accordingly.</para>
<para>If buffers have been queued with &VIDIOC-QBUF; and
<constant>VIDIOC_STREAMOFF</constant> is called without ever having
called <constant>VIDIOC_STREAMON</constant>, then those queued buffers
will also be removed from the incoming queue and all are returned to the
same state as after calling &VIDIOC-REQBUFS; and can be restarted
accordingly.</para>
<para>Both ioctls take a pointer to an integer, the desired buffer or
stream type. This is the same as &v4l2-requestbuffers;
<structfield>type</structfield>.</para>
<para>If <constant>VIDIOC_STREAMON</constant> is called when streaming
is already in progress, or if <constant>VIDIOC_STREAMOFF</constant> is called
when streaming is already stopped, then the ioctl does nothing and 0 is
returned.</para>
when streaming is already stopped, then 0 is returned. Nothing happens in the
case of <constant>VIDIOC_STREAMON</constant>, but <constant>VIDIOC_STREAMOFF</constant>
will return queued buffers to their starting state as mentioned above.</para>
<para>Note that applications can be preempted for unknown periods right
before or after the <constant>VIDIOC_STREAMON</constant> or
@@ -93,7 +109,7 @@ synchronize with other events.</para>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The buffer<structfield>type</structfield> is not supported,
<para>The buffer <structfield>type</structfield> is not supported,
or no buffers have been allocated (memory mapping) or enqueued
(output) yet.</para>
</listitem>

84
Documentation/DocBook/media_api.tmpl
View File

@@ -34,22 +34,20 @@
<book id="media_api">
<bookinfo>
<title>LINUX MEDIA INFRASTRUCTURE API</title>
<title>LINUX MEDIA INFRASTRUCTURE API</title>
<copyright>
<year>2009-2012</year>
<holder>LinuxTV Developers</holder>
</copyright>
<legalnotice>
<para>Permission is granted to copy, distribute and/or modify
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"</para>
</legalnotice>
<copyright>
<year>2009-2014</year>
<holder>LinuxTV Developers</holder>
</copyright>
<legalnotice>
<para>Permission is granted to copy, distribute and/or modify
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"</para>
</legalnotice>
</bookinfo>
<toc></toc> <!-- autogenerated -->
@@ -60,10 +58,11 @@ Foundation. A copy of the license is included in the chapter entitled
<para>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 devices.</para>
streaming capture and output devices, codec devices and remote
controllers.</para>
<para>It is divided into four parts.</para>
<para>The first part covers radio, capture,
cameras and analog TV devices.</para>
<para>The first part covers radio, video capture and output,
cameras, analog TV devices and codecs.</para>
<para>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,
@@ -75,55 +74,14 @@ Foundation. A copy of the license is included in the chapter entitled
<para>For additional information and for the latest development code,
see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
<para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para>
</preface>
<part id="v4l2spec">
&sub-v4l2;
</part>
<part id="dvbapi">
&sub-dvbapi;
</part>
<part id="v4ldvb_common">
<partinfo>
<authorgroup>
<author>
<firstname>Mauro</firstname>
<surname>Chehab</surname>
<othername role="mi">Carvalho</othername>
<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
<contrib>Initial version.</contrib>
</author>
</authorgroup>
<copyright>
<year>2009-2012</year>
<holder>Mauro Carvalho Chehab</holder>
</copyright>
<revhistory>
<!-- Put document revisions here, newest first. -->
<revision>
<revnumber>1.0.0</revnumber>
<date>2009-09-06</date>
<authorinitials>mcc</authorinitials>
<revremark>Initial revision</revremark>
</revision>
</revhistory>
</partinfo>
<title>Remote Controller API</title>
<chapter id="remote_controllers">
&sub-remote_controllers;
</chapter>
</part>
<part id="media_common">
&sub-media-controller;
</part>
<chapter id="gen_errors">
&sub-gen-errors;
</chapter>
<part id="v4l2spec">&sub-v4l2;</part>
<part id="dvbapi">&sub-dvbapi;</part>
<part id="remotes">&sub-remote_controllers;</part>
<part id="media_common">&sub-media-controller;</part>
<chapter id="gen_errors">&sub-gen-errors;</chapter>
&sub-fdl-appendix;