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

Merge remote-tracking branch 'airlied/drm-next' into topic/vblank-rework

Browse Source 
Dave asked me to do the backmerge before sending him the revised pull
request, so here we go. Nothing fancy in the conflicts, just a few
things changed right next to each another.

Conflicts:
	drivers/gpu/drm/drm_irq.c

Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
This commit is contained in:
Daniel Vetter
2014-09-11 14:46:53 +02:00
parent 3d3cbd8430 fdcaa1dbb7
commit 336879b1da
9622 changed files with 417627 additions and 449481 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
Documentation/DocBook/device-drivers.tmpl
View File

@@ -54,7 +54,7 @@
!Ikernel/sched/cpupri.c
!Ikernel/sched/fair.c
!Iinclude/linux/completion.h
!Ekernel/timer.c
!Ekernel/time/timer.c
</sect1>
<sect1><title>Wait queues and Wake events</title>
!Iinclude/linux/wait.h
@@ -63,7 +63,7 @@
<sect1><title>High-resolution timers</title>
!Iinclude/linux/ktime.h
!Iinclude/linux/hrtimer.h
!Ekernel/hrtimer.c
!Ekernel/time/hrtimer.c
</sect1>
<sect1><title>Workqueues and Kevents</title>
!Ekernel/workqueue.c
@@ -128,8 +128,12 @@ X!Edrivers/base/interface.c
!Edrivers/base/bus.c
</sect1>
<sect1><title>Device Drivers DMA Management</title>
!Edrivers/base/dma-buf.c
!Edrivers/base/reservation.c
!Edrivers/dma-buf/dma-buf.c
!Edrivers/dma-buf/fence.c
!Edrivers/dma-buf/seqno-fence.c
!Iinclude/linux/fence.h
!Iinclude/linux/seqno-fence.h
!Edrivers/dma-buf/reservation.c
!Iinclude/linux/reservation.h
!Edrivers/base/dma-coherent.c
!Edrivers/base/dma-mapping.c

11
Documentation/DocBook/drm.tmpl
View File

@@ -291,10 +291,9 @@ char *date;</synopsis>
<title>Device Registration</title>
<para>
A number of functions are provided to help with device registration.
The functions deal with PCI, USB and platform devices, respectively.
The functions deal with PCI and platform devices, respectively.
</para>
!Edrivers/gpu/drm/drm_pci.c
!Edrivers/gpu/drm/drm_usb.c
!Edrivers/gpu/drm/drm_platform.c
<para>
New drivers that no longer rely on the services provided by the
@@ -315,7 +314,7 @@ char *date;</synopsis>
<function>drm_dev_unregister()</function> followed by a call to
<function>drm_dev_unref()</function>.
</para>
!Edrivers/gpu/drm/drm_stub.c
!Edrivers/gpu/drm/drm_drv.c
</sect2>
<sect2>
<title>Driver Load</title>
@@ -3407,6 +3406,7 @@ void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis>
<sect2>
<title>Vertical Blanking and Interrupt Handling Functions Reference</title>
!Edrivers/gpu/drm/drm_irq.c
!Iinclude/drm/drmP.h drm_crtc_vblank_waitqueue
</sect2>
</sect1>
@@ -3925,6 +3925,11 @@ int num_ioctls;</synopsis>
!Pdrivers/gpu/drm/i915/i915_cmd_parser.c batch buffer command parser
!Idrivers/gpu/drm/i915/i915_cmd_parser.c
</sect2>
<sect2>
<title>Logical Rings, Logical Ring Contexts and Execlists</title>
!Pdrivers/gpu/drm/i915/intel_lrc.c Logical Rings, Logical Ring Contexts and Execlists
!Idrivers/gpu/drm/i915/intel_lrc.c
</sect2>
</sect1>
</chapter>
</part>

10
Documentation/DocBook/gadget.tmpl
View File

@@ -556,11 +556,11 @@ been converted to this framework.
Near-term plans include converting all of them, except for "gadgetfs".
</para>
!Edrivers/usb/gadget/f_acm.c
!Edrivers/usb/gadget/f_ecm.c
!Edrivers/usb/gadget/f_subset.c
!Edrivers/usb/gadget/f_obex.c
!Edrivers/usb/gadget/f_serial.c
!Edrivers/usb/gadget/function/f_acm.c
!Edrivers/usb/gadget/function/f_ecm.c
!Edrivers/usb/gadget/function/f_subset.c
!Edrivers/usb/gadget/function/f_obex.c
!Edrivers/usb/gadget/function/f_serial.c
</sect1>

2
Documentation/DocBook/media/Makefile
View File

@@ -174,7 +174,7 @@ FILENAME = \
DOCUMENTED = \
-e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \
-e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \
-e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \
-e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\)\(\s\+v4l2_fourcc\)/<link linkend=\"\1\">\1<\/link>\2/g" \
-e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \
-e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g"

44
Documentation/DocBook/media/dvb/dvbproperty.xml
View File

@@ -555,10 +555,46 @@ typedef enum fe_delivery_system {
</section>
<section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING">
<title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title>
<para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para>
<para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values
here are referring to what can be found in the TMCC-structure -
independent of the mode.</para>
<para>Valid values: 0, 1, 2, 4, -1 (AUTO)</para>
<para>when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.</para>
<para>Note: The real time interleaving length depends on the mode (fft-size). The values
here are referring to what can be found in the TMCC-structure, as shown in the table below.</para>
<informaltable id="isdbt-layer-interleaving-table">
<tgroup cols="4" align="center">
<tbody>
<row>
<entry>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</entry>
<entry>Mode 1 (2K FFT)</entry>
<entry>Mode 2 (4K FFT)</entry>
<entry>Mode 3 (8K FFT)</entry>
</row>
<row>
<entry>0</entry>
<entry>0</entry>
<entry>0</entry>
<entry>0</entry>
</row>
<row>
<entry>1</entry>
<entry>4</entry>
<entry>2</entry>
<entry>1</entry>
</row>
<row>
<entry>2</entry>
<entry>8</entry>
<entry>4</entry>
<entry>2</entry>
</row>
<row>
<entry>4</entry>
<entry>16</entry>
<entry>8</entry>
<entry>4</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="DTV-ATSCMH-FIC-VER">
<title><constant>DTV_ATSCMH_FIC_VER</constant></title>

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

@@ -13,6 +13,19 @@ correctly with any device.</para>
<para>All controls are accessed using an ID value. V4L2 defines
several IDs for specific purposes. Drivers can also implement their
own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant>
<footnote><para>The use of <constant>V4L2_CID_PRIVATE_BASE</constant>
is problematic because different drivers may use the same
<constant>V4L2_CID_PRIVATE_BASE</constant> ID for different controls.
This makes it hard to programatically set such controls since the meaning
of the control with that ID is driver dependent. In order to resolve this
drivers use unique IDs and the <constant>V4L2_CID_PRIVATE_BASE</constant>
IDs are mapped to those unique IDs by the kernel. Consider these
<constant>V4L2_CID_PRIVATE_BASE</constant> IDs as aliases to the real
IDs.</para>
<para>Many applications today still use the <constant>V4L2_CID_PRIVATE_BASE</constant>
IDs instead of using &VIDIOC-QUERYCTRL; with the <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>
flag to enumerate all IDs, so support for <constant>V4L2_CID_PRIVATE_BASE</constant>
is still around.</para></footnote>
and higher values. The pre-defined control IDs have the prefix
<constant>V4L2_CID_</constant>, and are listed in <xref
linkend="control-id" />. The ID is used when querying the attributes of
@@ -31,25 +44,22 @@ the current video input or output, tuner or modulator, or audio input
or output. Different in the sense of other bounds, another default and
current value, step size or other menu items. A control with a certain
<emphasis>custom</emphasis> ID can also change name and
type.<footnote>
<para>It will be more convenient for applications if drivers
make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but
that was never required.</para>
</footnote> Control values are stored globally, they do not
type.</para>
<para>If a control is not applicable to the current configuration
of the device (for example, it doesn't apply to the current video input)
drivers set the <constant>V4L2_CTRL_FLAG_INACTIVE</constant> flag.</para>
<para>Control values are stored globally, they do not
change when switching except to stay within the reported bounds. They
also do not change &eg; when the device is opened or closed, when the
tuner radio frequency is changed or generally never without
application request. Since V4L2 specifies no event mechanism, panel
applications intended to cooperate with other panel applications (be
they built into a larger application, as a TV viewer) may need to
regularly poll control values to update their user
interface.<footnote>
<para>Applications could call an ioctl to request events.
After another process called &VIDIOC-S-CTRL; or another ioctl changing
shared properties the &func-select; function would indicate
readability until any ioctl (querying the properties) is
called.</para>
</footnote></para>
application request.</para>
<para>V4L2 specifies an event mechanism to notify applications
when controls change value (see &VIDIOC-SUBSCRIBE-EVENT;, event
<constant>V4L2_EVENT_CTRL</constant>), panel applications might want to make
use of that in order to always reflect the correct control value.</para>
<para>
All controls use machine endianness.
@@ -398,14 +408,17 @@ to work.</entry>
<row id="v4l2-alpha-component">
<entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry>
<entry>integer</entry>
<entry> Sets the alpha color component on the capture device or on
the capture buffer queue of a mem-to-mem device. When a mem-to-mem
device produces frame format that includes an alpha component
<entry>Sets the alpha color component. When a capture device (or
capture queue of a mem-to-mem device) produces a frame format that
includes an alpha component
(e.g. <link linkend="rgb-formats">packed RGB image formats</link>)
and the alpha value is not defined by the mem-to-mem input data
this control lets you select the alpha component value of all
pixels. It is applicable to any pixel format that contains an alpha
component.
and the alpha value is not defined by the device or the mem-to-mem
input data this control lets you select the alpha component value of
all pixels. When an output device (or output queue of a mem-to-mem
device) consumes a frame format that doesn't include an alpha
component and the device supports alpha channel processing this
control lets you set the alpha component value of all pixels for
further processing in the device.
</entry>
</row>
<row>
@@ -434,73 +447,98 @@ Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>,
controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or
more menu type controls.</para>
<example>
<title>Enumerating all controls</title>
<example id="enum_all_controls">
<title>Enumerating all user controls</title>
<programlisting>
&v4l2-queryctrl; queryctrl;
&v4l2-querymenu; querymenu;
static void
enumerate_menu (void)
static void enumerate_menu(void)
{
printf (" Menu items:\n");
printf(" Menu items:\n");
memset (&amp;querymenu, 0, sizeof (querymenu));
memset(&amp;querymenu, 0, sizeof(querymenu));
querymenu.id = queryctrl.id;
for (querymenu.index = queryctrl.minimum;
querymenu.index &lt;= queryctrl.maximum;
querymenu.index++) {
if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {
printf (" %s\n", querymenu.name);
querymenu.index++) {
if (0 == ioctl(fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {
printf(" %s\n", querymenu.name);
}
}
}
memset (&amp;queryctrl, 0, sizeof (queryctrl));
memset(&amp;queryctrl, 0, sizeof(queryctrl));
for (queryctrl.id = V4L2_CID_BASE;
queryctrl.id &lt; V4L2_CID_LASTP1;
queryctrl.id++) {
if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
continue;
printf ("Control %s\n", queryctrl.name);
printf("Control %s\n", queryctrl.name);
if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
enumerate_menu ();
enumerate_menu();
} else {
if (errno == EINVAL)
continue;
perror ("VIDIOC_QUERYCTRL");
exit (EXIT_FAILURE);
perror("VIDIOC_QUERYCTRL");
exit(EXIT_FAILURE);
}
}
for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
queryctrl.id++) {
if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
continue;
printf ("Control %s\n", queryctrl.name);
printf("Control %s\n", queryctrl.name);
if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
enumerate_menu ();
enumerate_menu();
} else {
if (errno == EINVAL)
break;
perror ("VIDIOC_QUERYCTRL");
exit (EXIT_FAILURE);
perror("VIDIOC_QUERYCTRL");
exit(EXIT_FAILURE);
}
}
</programlisting>
</example>
<example>
<title>Enumerating all user controls (alternative)</title>
<programlisting>
memset(&amp;queryctrl, 0, sizeof(queryctrl));
queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
break;
if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
continue;
printf("Control %s\n", queryctrl.name);
if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
enumerate_menu();
queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
}
if (errno != EINVAL) {
perror("VIDIOC_QUERYCTRL");
exit(EXIT_FAILURE);
}
</programlisting>
</example>
<example>
<title>Changing controls</title>
@@ -508,53 +546,53 @@ for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
&v4l2-queryctrl; queryctrl;
&v4l2-control; control;
memset (&amp;queryctrl, 0, sizeof (queryctrl));
memset(&amp;queryctrl, 0, sizeof(queryctrl));
queryctrl.id = V4L2_CID_BRIGHTNESS;
if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
if (-1 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
if (errno != EINVAL) {
perror ("VIDIOC_QUERYCTRL");
exit (EXIT_FAILURE);
perror("VIDIOC_QUERYCTRL");
exit(EXIT_FAILURE);
} else {
printf ("V4L2_CID_BRIGHTNESS is not supported\n");
printf("V4L2_CID_BRIGHTNESS is not supported\n");
}
} else if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) {
printf ("V4L2_CID_BRIGHTNESS is not supported\n");
printf("V4L2_CID_BRIGHTNESS is not supported\n");
} else {
memset (&amp;control, 0, sizeof (control));
memset(&amp;control, 0, sizeof (control));
control.id = V4L2_CID_BRIGHTNESS;
control.value = queryctrl.default_value;
if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)) {
perror ("VIDIOC_S_CTRL");
exit (EXIT_FAILURE);
if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &amp;control)) {
perror("VIDIOC_S_CTRL");
exit(EXIT_FAILURE);
}
}
memset (&amp;control, 0, sizeof (control));
memset(&amp;control, 0, sizeof(control));
control.id = V4L2_CID_CONTRAST;
if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &amp;control)) {
if (0 == ioctl(fd, &VIDIOC-G-CTRL;, &amp;control)) {
control.value += 1;
/* The driver may clamp the value or return ERANGE, ignored here */
if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)
if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &amp;control)
&amp;&amp; errno != ERANGE) {
perror ("VIDIOC_S_CTRL");
exit (EXIT_FAILURE);
perror("VIDIOC_S_CTRL");
exit(EXIT_FAILURE);
}
/* Ignore if V4L2_CID_CONTRAST is unsupported */
} else if (errno != EINVAL) {
perror ("VIDIOC_G_CTRL");
exit (EXIT_FAILURE);
perror("VIDIOC_G_CTRL");
exit(EXIT_FAILURE);
}
control.id = V4L2_CID_AUDIO_MUTE;
control.value = TRUE; /* silence */
control.value = 1; /* silence */
/* Errors ignored */
ioctl (fd, VIDIOC_S_CTRL, &amp;control);
ioctl(fd, VIDIOC_S_CTRL, &amp;control);
</programlisting>
</example>
</section>
@@ -625,16 +663,29 @@ supported.</para>
&v4l2-control;, except for the fact that it also allows for 64-bit
values and pointers to be passed.</para>
<para>Since the &v4l2-ext-control; supports pointers it is now
also possible to have controls with compound types such as N-dimensional arrays
and/or structures. You need to specify the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant>
when enumerating controls to actually be able to see such compound controls.
In other words, these controls with compound types should only be used
programmatically.</para>
<para>Since such compound controls need to expose more information
about themselves than is possible with &VIDIOC-QUERYCTRL; the
&VIDIOC-QUERY-EXT-CTRL; ioctl was added. In particular, this ioctl gives
the dimensions of the N-dimensional array if this control consists of more than
one element.</para>
<para>It is important to realize that due to the flexibility of
controls it is necessary to check whether the control you want to set
actually is supported in the driver and what the valid range of values
is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to
check this. Also note that it is possible that some of the menu
indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant>
may not be supported (<constant>VIDIOC_QUERYMENU</constant> will
return an error). A good example is the list of supported MPEG audio
bitrates. Some drivers only support one or two bitrates, others
support a wider range.</para>
is. So use the &VIDIOC-QUERYCTRL; (or &VIDIOC-QUERY-EXT-CTRL;) and
&VIDIOC-QUERYMENU; ioctls to check this. Also note that it is possible
that some of the menu indices in a control of type
<constant>V4L2_CTRL_TYPE_MENU</constant> may not be supported
(<constant>VIDIOC_QUERYMENU</constant> will return an error). A good
example is the list of supported MPEG audio bitrates. Some drivers only
support one or two bitrates, others support a wider range.</para>
<para>
All controls use machine endianness.
@@ -675,12 +726,12 @@ control class is found:</para>
<informalexample>
<programlisting>
qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)
while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
break;
/* ... */
qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
}
qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
}
</programlisting>
</informalexample>
@@ -700,7 +751,7 @@ ID based on a control ID.</para>
<constant>VIDIOC_QUERYCTRL</constant> will fail when used in
combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In
that case the old method of enumerating control should be used (see
1.8). But if it is supported, then it is guaranteed to enumerate over
<xref linkend="enum_all_controls" />). But if it is supported, then it is guaranteed to enumerate over
all controls, including driver-private controls.</para>
</section>
@@ -3998,6 +4049,68 @@ in Annex E of <xref linkend="iec62106" />. The length of Radio Text strings depe
used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_MONO_STEREO</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">Sets the Mono/Stereo bit of the Decoder Identification code. If set,
then the audio was recorded as stereo.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_ARTIFICIAL_HEAD</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">Sets the
<ulink url="http://en.wikipedia.org/wiki/Artificial_head">Artificial Head</ulink> bit of the Decoder
Identification code. If set, then the audio was recorded using an artificial head.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_COMPRESSED</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">Sets the Compressed bit of the Decoder Identification code. If set,
then the audio is compressed.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_DYNAMIC_PTY</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">Sets the Dynamic PTY bit of the Decoder Identification code. If set,
then the PTY code is dynamically switched.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_PROGRAM</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_MUSIC_SPEECH</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it
broadcasts speech. If the transmitter doesn't make this distinction, then it should be set.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS_ENABLE</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">If set, then transmit alternate frequencies.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS</constant>&nbsp;</entry>
<entry>__u32 array</entry>
</row>
<row><entry spanname="descr">The alternate frequencies in kHz units. The RDS standard allows
for up to 25 frequencies to be defined. Drivers may support fewer frequencies so check
the array size.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant>&nbsp;</entry>
@@ -4976,6 +5089,57 @@ description of this control class.</entry>
</row><row><entry spanname="descr">Enables/disables RDS
reception by the radio tuner</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_RX_PTY</constant>&nbsp;</entry>
<entry>integer</entry>
</row>
<row><entry spanname="descr">Gets RDS Programme Type field.
This encodes up to 31 pre-defined programme types.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_RX_PS_NAME</constant>&nbsp;</entry>
<entry>string</entry>
</row>
<row><entry spanname="descr">Gets the Programme Service name (PS_NAME).
It is intended for static display on a receiver. It is the primary aid to listeners in programme service
identification and selection. In Annex E of <xref linkend="iec62106" />, the RDS specification,
there is a full description of the correct character encoding for Programme Service name strings.
Also from RDS specification, PS is usually a single eight character text. However, it is also possible
to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_RX_RADIO_TEXT</constant>&nbsp;</entry>
<entry>string</entry>
</row>
<row><entry spanname="descr">Gets the Radio Text info. It is a textual description of
what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
programme-related information or any other text. In these cases, RadioText can be used in addition to
<constant>V4L2_CID_RDS_RX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described
in Annex E of <xref linkend="iec62106" />. The length of Radio Text strings depends on which RDS Block is being
used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_PROGRAM</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_RDS_RX_MUSIC_SPEECH</constant>&nbsp;</entry>
<entry>boolean</entry>
</row>
<row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it
broadcasts speech. If the transmitter doesn't make this distinction, then it will be set.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_TUNE_DEEMPHASIS</constant>&nbsp;</entry>
<entry>enum v4l2_deemphasis</entry>
@@ -5007,6 +5171,102 @@ defines possible values for de-emphasis. Here they are:</entry>
</tbody>
</tgroup>
</table>
</section>
<section id="detect-controls">
<title>Detect Control Reference</title>
<para>The Detect class includes controls for common features of
various motion or object detection capable devices.</para>
<table pgwide="1" frame="none" id="detect-control-id">
<title>Detect 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_DETECT_CLASS</constant>&nbsp;</entry>
<entry>class</entry>
</row><row><entry spanname="descr">The Detect 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_DETECT_MD_MODE</constant>&nbsp;</entry>
<entry>menu</entry>
</row><row><entry spanname="descr">Sets the motion detection mode.</entry>
</row>
<row>
<entrytbl spanname="descr" cols="2">
<tbody valign="top">
<row>
<entry><constant>V4L2_DETECT_MD_MODE_DISABLED</constant>
</entry><entry>Disable motion detection.</entry>
</row>
<row>
<entry><constant>V4L2_DETECT_MD_MODE_GLOBAL</constant>
</entry><entry>Use a single motion detection threshold.</entry>
</row>
<row>
<entry><constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant>
</entry><entry>The image is divided into a grid, each cell with its own
motion detection threshold. These thresholds are set through the
<constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant> matrix control.</entry>
</row>
<row>
<entry><constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant>
</entry><entry>The image is divided into a grid, each cell with its own
region value that specifies which per-region motion detection thresholds
should be used. Each region has its own thresholds. How these per-region
thresholds are set up is driver-specific. The region values for the grid are set
through the <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> matrix
control.</entry>
</row>
</tbody>
</entrytbl>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD</constant>&nbsp;</entry>
<entry>integer</entry>
</row>
<row><entry spanname="descr">Sets the global motion detection threshold to be
used with the <constant>V4L2_DETECT_MD_MODE_GLOBAL</constant> motion detection mode.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant>&nbsp;</entry>
<entry>__u16 matrix</entry>
</row>
<row><entry spanname="descr">Sets the motion detection thresholds for each cell in the grid.
To be used with the <constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant>
motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the
grid.</entry>
</row>
<row>
<entry spanname="id"><constant>V4L2_CID_DETECT_MD_REGION_GRID</constant>&nbsp;</entry>
<entry>__u8 matrix</entry>
</row>
<row><entry spanname="descr">Sets the motion detection region value for each cell in the grid.
To be used with the <constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant>
motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the
grid.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>

12
Documentation/DocBook/media/v4l/dev-raw-vbi.xml
View File

@@ -150,9 +150,15 @@ signal. Drivers shall not convert the sample format by software.</para></entry>
<entry>This is the scanning system line number
associated with the first line of the VBI image, of the first and the
second field respectively. See <xref linkend="vbi-525" /> and
<xref linkend="vbi-625" /> for valid values. VBI input drivers can
return start values 0 if the hardware cannot reliable identify
scanning lines, VBI acquisition may not require this
<xref linkend="vbi-625" /> for valid values.
The <constant>V4L2_VBI_ITU_525_F1_START</constant>,
<constant>V4L2_VBI_ITU_525_F2_START</constant>,
<constant>V4L2_VBI_ITU_625_F1_START</constant> and
<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start line
numbers for each field for each 525 or 625 line format as a convenience.
Don't forget that ITU line numbering starts at 1, not 0.
VBI input drivers can return start values 0 if the hardware cannot
reliable identify scanning lines, VBI acquisition may not require this
information.</entry>
</row>
<row>

18
Documentation/DocBook/media/v4l/dev-sdr.xml
View File

@@ -72,9 +72,12 @@ To use the <link linkend="format">format</link> ioctls applications set the
<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.
Currently there is two fields, <structfield>pixelformat</structfield> and
<structfield>buffersize</structfield>, of struct &v4l2-sdr-format; which are
used. Content of the <structfield>pixelformat</structfield> is V4L2 FourCC
code of the data format. The <structfield>buffersize</structfield> field is
maximum buffer size in bytes required for data transfer, set by the driver in
order to inform application.
</para>
<table pgwide="1" frame="none" id="v4l2-sdr-format">
@@ -91,9 +94,16 @@ little endian <link linkend="v4l2-fourcc">four character code</link>.
V4L2 defines SDR formats in <xref linkend="sdr-formats" />.
</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>buffersize</structfield></entry>
<entry>
Maximum size in bytes required for data. Value is set by the driver.
</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>reserved[28]</structfield></entry>
<entry><structfield>reserved[24]</structfield></entry>
<entry>This array is reserved for future extensions.
Drivers and applications must set it to zero.</entry>
</row>

9
Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
View File

@@ -185,7 +185,14 @@ tables, sigh. --></para></entry>
<entry></entry>
<entry spanname="hspan">Drivers must set
<structfield>service_lines</structfield>[0][0] and
<structfield>service_lines</structfield>[1][0] to zero.</entry>
<structfield>service_lines</structfield>[1][0] to zero.
The <constant>V4L2_VBI_ITU_525_F1_START</constant>,
<constant>V4L2_VBI_ITU_525_F2_START</constant>,
<constant>V4L2_VBI_ITU_625_F1_START</constant> and
<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start
line numbers for each field for each 525 or 625 line format as a
convenience. Don't forget that ITU line numbering starts at 1, not 0.
</entry>
</row>
<row>
<entry>__u32</entry>

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

@@ -870,7 +870,8 @@ should set this to 0.</entry>
If the application sets this to 0 for an output stream, then
<structfield>bytesused</structfield> will be set to the size of the
plane (see the <structfield>length</structfield> field of this struct)
by the driver.</entry>
by the driver. Note that the actual image data starts at
<structfield>data_offset</structfield> which may not be 0.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -919,6 +920,10 @@ should set this to 0.</entry>
<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.
Note that data_offset is included in <structfield>bytesused</structfield>.
So the size of the image in the plane is
<structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
offset <structfield>data_offset</structfield> from the start of the plane.
</entry>
</row>
<row>
@@ -1066,7 +1071,7 @@ state, in the application domain so to say.</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. Also know as
key frame (or field), &ie; can be decompressed on its own. Also known as
an I-frame. Applications can set this bit when <structfield>type</structfield>
refers to an output stream.</entry>
</row>

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

@@ -15,9 +15,6 @@ typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits
per pixel. These are all packed-pixel formats, meaning all the data
for a pixel lie next to each other in memory.</para>
<para>When one of these formats is used, drivers shall report the
colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<table pgwide="1" frame="none" id="rgb-formats">
<title>Packed RGB Image Formats</title>
<tgroup cols="37" align="center">
@@ -130,9 +127,9 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<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>
<row id="V4L2-PIX-FMT-ARGB444">
<entry><constant>V4L2_PIX_FMT_ARGB444</constant></entry>
<entry>'AR12'</entry>
<entry></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
@@ -152,9 +149,31 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<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>
<row id="V4L2-PIX-FMT-XRGB444">
<entry><constant>V4L2_PIX_FMT_XRGB444</constant></entry>
<entry>'XR12'</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>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</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-ARGB555">
<entry><constant>V4L2_PIX_FMT_ARGB555</constant></entry>
<entry>'AR15'</entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
@@ -174,6 +193,28 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-XRGB555">
<entry><constant>V4L2_PIX_FMT_XRGB555</constant></entry>
<entry>'XR15'</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>-</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>
@@ -341,6 +382,424 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-ABGR32">
<entry><constant>V4L2_PIX_FMT_ABGR32</constant></entry>
<entry>'AR24'</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-XBGR32">
<entry><constant>V4L2_PIX_FMT_XBGR32</constant></entry>
<entry>'XR24'</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>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
</row>
<row id="V4L2-PIX-FMT-ARGB32">
<entry><constant>V4L2_PIX_FMT_ARGB32</constant></entry>
<entry>'AX24'</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>
<row id="V4L2-PIX-FMT-XRGB32">
<entry><constant>V4L2_PIX_FMT_XRGB32</constant></entry>
<entry>'BX24'</entry>
<entry></entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</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>Bit 7 is the most significant bit.</para>
<para>The usage and value of the alpha bits (a) in the ARGB and ABGR formats
(collectively referred to as alpha formats) depend on the device type and
hardware operation. <link linkend="capture">Capture</link> devices
(including capture queues of mem-to-mem devices) fill the alpha component in
memory. When the device outputs an alpha channel the alpha component will
have a meaningful value. Otherwise, when the device doesn't output an alpha
channel but can set the alpha bit to a user-configurable value, the <link
linkend="v4l2-alpha-component"><constant>V4L2_CID_ALPHA_COMPONENT</constant>
</link> control is used to specify that alpha value, and the alpha component
of all pixels will be set to the value specified by that control. Otherwise
a corresponding format without an alpha component (XRGB or XBGR) must be
used instead of an alpha format.</para>
<para><link linkend="output">Output</link> devices (including output queues
of mem-to-mem devices and <link linkend="osd">video output overlay</link>
devices) read the alpha component from memory. When the device processes the
alpha channel the alpha component must be filled with meaningful values by
applications. Otherwise a corresponding format without an alpha component
(XRGB or XBGR) must be used instead of an alpha format.</para>
<para>The XRGB and XBGR formats contain undefined bits (-). Applications,
devices and drivers must ignore those bits, for both <link
linkend="capture">capture</link> and <link linkend="output">output</link>
devices.</para>
<example>
<title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel
image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="13" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>B<subscript>00</subscript></entry>
<entry>G<subscript>00</subscript></entry>
<entry>R<subscript>00</subscript></entry>
<entry>B<subscript>01</subscript></entry>
<entry>G<subscript>01</subscript></entry>
<entry>R<subscript>01</subscript></entry>
<entry>B<subscript>02</subscript></entry>
<entry>G<subscript>02</subscript></entry>
<entry>R<subscript>02</subscript></entry>
<entry>B<subscript>03</subscript></entry>
<entry>G<subscript>03</subscript></entry>
<entry>R<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>B<subscript>10</subscript></entry>
<entry>G<subscript>10</subscript></entry>
<entry>R<subscript>10</subscript></entry>
<entry>B<subscript>11</subscript></entry>
<entry>G<subscript>11</subscript></entry>
<entry>R<subscript>11</subscript></entry>
<entry>B<subscript>12</subscript></entry>
<entry>G<subscript>12</subscript></entry>
<entry>R<subscript>12</subscript></entry>
<entry>B<subscript>13</subscript></entry>
<entry>G<subscript>13</subscript></entry>
<entry>R<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>B<subscript>20</subscript></entry>
<entry>G<subscript>20</subscript></entry>
<entry>R<subscript>20</subscript></entry>
<entry>B<subscript>21</subscript></entry>
<entry>G<subscript>21</subscript></entry>
<entry>R<subscript>21</subscript></entry>
<entry>B<subscript>22</subscript></entry>
<entry>G<subscript>22</subscript></entry>
<entry>R<subscript>22</subscript></entry>
<entry>B<subscript>23</subscript></entry>
<entry>G<subscript>23</subscript></entry>
<entry>R<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;36:</entry>
<entry>B<subscript>30</subscript></entry>
<entry>G<subscript>30</subscript></entry>
<entry>R<subscript>30</subscript></entry>
<entry>B<subscript>31</subscript></entry>
<entry>G<subscript>31</subscript></entry>
<entry>R<subscript>31</subscript></entry>
<entry>B<subscript>32</subscript></entry>
<entry>G<subscript>32</subscript></entry>
<entry>R<subscript>32</subscript></entry>
<entry>B<subscript>33</subscript></entry>
<entry>G<subscript>33</subscript></entry>
<entry>R<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
<para>Formats defined in <xref linkend="rgb-formats-deprecated"/> are
deprecated and must not be used by new drivers. They are documented here for
reference. The meaning of their alpha bits (a) is ill-defined and
interpreted as in either the corresponding ARGB or XRGB format, depending on
the driver.</para>
<table pgwide="1" frame="none" id="rgb-formats-deprecated">
<title>Deprecated Packed RGB Image Formats</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>
<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-BGR32">
<entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
<entry>'BGR4'</entry>
@@ -425,93 +884,6 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
</tgroup>
</table>
<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 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>
<example>
<title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel
image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="13" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>B<subscript>00</subscript></entry>
<entry>G<subscript>00</subscript></entry>
<entry>R<subscript>00</subscript></entry>
<entry>B<subscript>01</subscript></entry>
<entry>G<subscript>01</subscript></entry>
<entry>R<subscript>01</subscript></entry>
<entry>B<subscript>02</subscript></entry>
<entry>G<subscript>02</subscript></entry>
<entry>R<subscript>02</subscript></entry>
<entry>B<subscript>03</subscript></entry>
<entry>G<subscript>03</subscript></entry>
<entry>R<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>B<subscript>10</subscript></entry>
<entry>G<subscript>10</subscript></entry>
<entry>R<subscript>10</subscript></entry>
<entry>B<subscript>11</subscript></entry>
<entry>G<subscript>11</subscript></entry>
<entry>R<subscript>11</subscript></entry>
<entry>B<subscript>12</subscript></entry>
<entry>G<subscript>12</subscript></entry>
<entry>R<subscript>12</subscript></entry>
<entry>B<subscript>13</subscript></entry>
<entry>G<subscript>13</subscript></entry>
<entry>R<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>B<subscript>20</subscript></entry>
<entry>G<subscript>20</subscript></entry>
<entry>R<subscript>20</subscript></entry>
<entry>B<subscript>21</subscript></entry>
<entry>G<subscript>21</subscript></entry>
<entry>R<subscript>21</subscript></entry>
<entry>B<subscript>22</subscript></entry>
<entry>G<subscript>22</subscript></entry>
<entry>R<subscript>22</subscript></entry>
<entry>B<subscript>23</subscript></entry>
<entry>G<subscript>23</subscript></entry>
<entry>R<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;36:</entry>
<entry>B<subscript>30</subscript></entry>
<entry>G<subscript>30</subscript></entry>
<entry>R<subscript>30</subscript></entry>
<entry>B<subscript>31</subscript></entry>
<entry>G<subscript>31</subscript></entry>
<entry>R<subscript>31</subscript></entry>
<entry>B<subscript>32</subscript></entry>
<entry>G<subscript>32</subscript></entry>
<entry>R<subscript>32</subscript></entry>
<entry>B<subscript>33</subscript></entry>
<entry>G<subscript>33</subscript></entry>
<entry>R<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
<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-cs08.xml Normal file
View File

@@ -0,0 +1,44 @@
<refentry id="V4L2-SDR-FMT-CS08">
<refmeta>
<refentrytitle>V4L2_SDR_FMT_CS8 ('CS08')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>
<constant>V4L2_SDR_FMT_CS8</constant>
</refname>
<refpurpose>Complex signed 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 signed number. I value comes first and Q value after
that.
</para>
<example>
<title><constant>V4L2_SDR_FMT_CS8</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>

47
Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml Normal file
View File

@@ -0,0 +1,47 @@
<refentry id="V4L2-SDR-FMT-CS14LE">
<refmeta>
<refentrytitle>V4L2_SDR_FMT_CS14LE ('CS14')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>
<constant>V4L2_SDR_FMT_CS14LE</constant>
</refname>
<refpurpose>Complex signed 14-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 14 bit signed little endian number. I value comes first
and Q value after that. 14 bit value is stored in 16 bit space with unused
high bits padded with 0.
</para>
<example>
<title><constant>V4L2_SDR_FMT_CS14LE</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[13:8]</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;2:</entry>
<entry>Q'<subscript>0[7:0]</subscript></entry>
<entry>Q'<subscript>0[13:8]</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>

40
Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml Normal file
View File

@@ -0,0 +1,40 @@
<refentry id="V4L2-SDR-FMT-RU12LE">
<refmeta>
<refentrytitle>V4L2_SDR_FMT_RU12LE ('RU12')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>
<constant>V4L2_SDR_FMT_RU12LE</constant>
</refname>
<refpurpose>Real unsigned 12-bit little endian sample</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
This format contains sequence of real number samples. Each sample is
represented as a 12 bit unsigned little endian number. Sample is stored
in 16 bit space with unused high bits padded with 0.
</para>
<example>
<title><constant>V4L2_SDR_FMT_RU12LE</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[11:8]</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>

2
Documentation/DocBook/media/v4l/pixfmt-srggb12.xml
View File

@@ -18,7 +18,7 @@
<title>Description</title>
<para>The following four pixel formats are raw sRGB / Bayer formats with
12 bits per colour. Each colour component is stored in a 16-bit word, with 6
12 bits per colour. Each colour component is stored in a 16-bit word, with 4
unused high bits filled with zeros. Each n-pixel row contains n/2 green samples
and n/2 blue or red samples, with alternating red and blue rows. Bytes are
stored in memory in little endian order. They are conventionally described

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

@@ -112,9 +112,34 @@ see <xref linkend="colorspaces" />.</entry>
<row>
<entry>__u32</entry>
<entry><structfield>priv</structfield></entry>
<entry>Reserved for custom (driver defined) additional
information about formats. When not used drivers and applications must
set this field to zero.</entry>
<entry><para>This field indicates whether the remaining fields of the
<structname>v4l2_pix_format</structname> structure, also called the extended
fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it
indicates that the extended fields have been correctly initialized. When set to
any other value it indicates that the extended fields contain undefined values.
</para>
<para>Applications that wish to use the pixel format extended fields must first
ensure that the feature is supported by querying the device for the
<link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link>
capability. If the capability isn't set the pixel format extended fields are not
supported and using the extended fields will lead to undefined results.</para>
<para>To use the extended fields, applications must set the
<structfield>priv</structfield> field to
<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, initialize all the extended fields
and zero the unused bytes of the <structname>v4l2_format</structname>
<structfield>raw_data</structfield> field.</para>
<para>When the <structfield>priv</structfield> field isn't set to
<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> drivers must act as if all the
extended fields were set to zero. On return drivers must set the
<structfield>priv</structfield> field to
<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> and all the extended fields to
applicable values.</para></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>Flags set by the application or driver, see <xref
linkend="format-flags" />.</entry>
</row>
</tbody>
</tgroup>
@@ -201,9 +226,15 @@ codes can be used.</entry>
and the number of valid entries in the
<structfield>plane_fmt</structfield> array.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>flags</structfield></entry>
<entry>Flags set by the application or driver, see <xref
linkend="format-flags" />.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>reserved[11]</structfield></entry>
<entry><structfield>reserved[10]</structfield></entry>
<entry>Reserved for future extensions. Should be zeroed by the
application.</entry>
</row>
@@ -248,7 +279,7 @@ has just as many pad bytes after it as the other rows.</para>
<para>In V4L2 each format has an identifier which looks like
<constant>PIX_FMT_XXX</constant>, defined in the <link
linkend="videodev">videodev.h</link> header file. These identifiers
linkend="videodev">videodev2.h</link> header file. These identifiers
represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link>
which are also listed below, however they are not the same as those
used in the Windows world.</para>
@@ -828,6 +859,9 @@ interface only.</para>
&sub-sdr-cu08;
&sub-sdr-cu16le;
&sub-sdr-cs08;
&sub-sdr-cs14le;
&sub-sdr-ru12le;
</section>
@@ -1060,4 +1094,21 @@ concatenated to form the JPEG stream. </para>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="format-flags">
<title>Format Flags</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_PIX_FMT_FLAG_PREMUL_ALPHA</constant></entry>
<entry>0x00000001</entry>
<entry>The color values are premultiplied by the alpha channel
value. For example, if a light blue pixel with 50% transparency was described by
RGBA values (128, 192, 255, 128), the same pixel described with premultiplied
colors would be described by RGBA values (64, 96, 128, 128) </entry>
</row>
</tbody>
</tgroup>
</table>
</section>

93
Documentation/DocBook/media/v4l/selection-api.xml
View File

@@ -86,47 +86,47 @@ selection targets available for a video capture device. It is recommended to
configure the cropping targets before to the composing targets.</para>
<para>The range of coordinates of the top left corner, width and height of
areas that can be sampled is given by the <constant> V4L2_SEL_TGT_CROP_BOUNDS
</constant> target. It is recommended for the driver developers to put the
top/left corner at position <constant> (0,0) </constant>. The rectangle's
areas that can be sampled is given by the <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>
target. It is recommended for the driver developers to put the
top/left corner at position <constant>(0,0)</constant>. The rectangle's
coordinates are expressed in pixels.</para>
<para>The top left corner, width and height of the source rectangle, that is
the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP
</constant> target. It uses the same coordinate system as <constant>
V4L2_SEL_TGT_CROP_BOUNDS </constant>. The active cropping area must lie
completely inside the capture boundaries. The driver may further adjust the
requested size and/or position according to hardware limitations.</para>
the area actually sampled, is given by the <constant>V4L2_SEL_TGT_CROP</constant>
target. It uses the same coordinate system as <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>.
The active cropping area must lie completely inside the capture boundaries. The
driver may further adjust the requested size and/or position according to hardware
limitations.</para>
<para>Each capture device has a default source rectangle, given by the
<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant> target. This rectangle shall
<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant> target. This rectangle shall
over what the driver writer considers the complete picture. Drivers shall set
the active crop rectangle to the default when the driver is first loaded, but
not later.</para>
<para>The composing targets refer to a memory buffer. The limits of composing
coordinates are obtained using <constant> V4L2_SEL_TGT_COMPOSE_BOUNDS
</constant>. All coordinates are expressed in pixels. The rectangle's top/left
corner must be located at position <constant> (0,0) </constant>. The width and
height are equal to the image size set by <constant> VIDIOC_S_FMT </constant>.
coordinates are obtained using <constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant>.
All coordinates are expressed in pixels. The rectangle's top/left
corner must be located at position <constant>(0,0)</constant>. The width and
height are equal to the image size set by <constant>VIDIOC_S_FMT</constant>.
</para>
<para>The part of a buffer into which the image is inserted by the hardware is
controlled by the <constant> V4L2_SEL_TGT_COMPOSE </constant> target.
controlled by the <constant>V4L2_SEL_TGT_COMPOSE</constant> target.
The rectangle's coordinates are also expressed in the same coordinate system as
the bounds rectangle. The composing rectangle must lie completely inside bounds
rectangle. The driver must adjust the composing rectangle to fit to the
bounding limits. Moreover, the driver can perform other adjustments according
to hardware limitations. The application can control rounding behaviour using
<link linkend="v4l2-selection-flags"> constraint flags </link>.</para>
<link linkend="v4l2-selection-flags"> constraint flags</link>.</para>
<para>For capture devices the default composing rectangle is queried using
<constant> V4L2_SEL_TGT_COMPOSE_DEFAULT </constant>. It is usually equal to the
<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant>. It is usually equal to the
bounding rectangle.</para>
<para>The part of a buffer that is modified by the hardware is given by
<constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant>. It contains all pixels
defined using <constant> V4L2_SEL_TGT_COMPOSE </constant> plus all
<constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>. It contains all pixels
defined using <constant>V4L2_SEL_TGT_COMPOSE</constant> plus all
padding data modified by hardware during insertion process. All pixels outside
this rectangle <emphasis>must not</emphasis> be changed by the hardware. The
content of pixels that lie inside the padded area but outside active area is
@@ -140,52 +140,51 @@ where the rubbish pixels are located and remove them if needed.</para>
<title>Configuration of video output</title>
<para>For output devices targets and ioctls are used similarly to the video
capture case. The <emphasis> composing </emphasis> rectangle refers to the
capture case. The <emphasis>composing</emphasis> rectangle refers to the
insertion of an image into a video signal. The cropping rectangles refer to a
memory buffer. It is recommended to configure the composing targets before to
the cropping targets.</para>
<para>The cropping targets refer to the memory buffer that contains an image to
be inserted into a video signal or graphical screen. The limits of cropping
coordinates are obtained using <constant> V4L2_SEL_TGT_CROP_BOUNDS </constant>.
coordinates are obtained using <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>.
All coordinates are expressed in pixels. The top/left corner is always point
<constant> (0,0) </constant>. The width and height is equal to the image size
specified using <constant> VIDIOC_S_FMT </constant> ioctl.</para>
<constant>(0,0)</constant>. The width and height is equal to the image size
specified using <constant>VIDIOC_S_FMT</constant> ioctl.</para>
<para>The top left corner, width and height of the source rectangle, that is
the area from which image date are processed by the hardware, is given by the
<constant> V4L2_SEL_TGT_CROP </constant>. Its coordinates are expressed
<constant>V4L2_SEL_TGT_CROP</constant>. Its coordinates are expressed
in in the same coordinate system as the bounds rectangle. The active cropping
area must lie completely inside the crop boundaries and the driver may further
adjust the requested size and/or position according to hardware
limitations.</para>
<para>For output devices the default cropping rectangle is queried using
<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant>. It is usually equal to the
<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant>. It is usually equal to the
bounding rectangle.</para>
<para>The part of a video signal or graphics display where the image is
inserted by the hardware is controlled by <constant>
V4L2_SEL_TGT_COMPOSE </constant> target. The rectangle's coordinates
are expressed in pixels. The composing rectangle must lie completely inside the
bounds rectangle. The driver must adjust the area to fit to the bounding
limits. Moreover, the driver can perform other adjustments according to
hardware limitations. </para>
inserted by the hardware is controlled by <constant>V4L2_SEL_TGT_COMPOSE</constant>
target. The rectangle's coordinates are expressed in pixels. The composing
rectangle must lie completely inside the bounds rectangle. The driver must
adjust the area to fit to the bounding limits. Moreover, the driver can
perform other adjustments according to hardware limitations.</para>
<para>The device has a default composing rectangle, given by the <constant>
V4L2_SEL_TGT_COMPOSE_DEFAULT </constant> target. This rectangle shall cover what
<para>The device has a default composing rectangle, given by the
<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant> target. This rectangle shall cover what
the driver writer considers the complete picture. It is recommended for the
driver developers to put the top/left corner at position <constant> (0,0)
</constant>. Drivers shall set the active composing rectangle to the default
driver developers to put the top/left corner at position <constant>(0,0)</constant>.
Drivers shall set the active composing rectangle to the default
one when the driver is first loaded.</para>
<para>The devices may introduce additional content to video signal other than
an image from memory buffers. It includes borders around an image. However,
such a padded area is driver-dependent feature not covered by this document.
Driver developers are encouraged to keep padded rectangle equal to active one.
The padded target is accessed by the <constant> V4L2_SEL_TGT_COMPOSE_PADDED
</constant> identifier. It must contain all pixels from the <constant>
V4L2_SEL_TGT_COMPOSE </constant> target.</para>
The padded target is accessed by the <constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>
identifier. It must contain all pixels from the <constant>V4L2_SEL_TGT_COMPOSE</constant>
target.</para>
</section>
@@ -194,8 +193,8 @@ V4L2_SEL_TGT_COMPOSE </constant> target.</para>
<title>Scaling control</title>
<para>An application can detect if scaling is performed by comparing the width
and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP
</constant> and <constant> V4L2_SEL_TGT_COMPOSE </constant> targets. If
and the height of rectangles obtained using <constant>V4L2_SEL_TGT_CROP</constant>
and <constant>V4L2_SEL_TGT_COMPOSE</constant> targets. If
these are not equal then the scaling is applied. The application can compute
the scaling ratios using these values.</para>
@@ -208,7 +207,7 @@ the scaling ratios using these values.</para>
<title>Comparison with old cropping API</title>
<para>The selection API was introduced to cope with deficiencies of previous
<link linkend="crop"> API </link>, that was designed to control simple capture
<link linkend="crop"> API</link>, that was designed to control simple capture
devices. Later the cropping API was adopted by video output drivers. The ioctls
are used to select a part of the display were the video signal is inserted. It
should be considered as an API abuse because the described operation is
@@ -220,7 +219,7 @@ part of an image by abusing V4L2 API. Cropping a smaller image from a larger
one is achieved by setting the field
&v4l2-pix-format;<structfield>::bytesperline</structfield>. Introducing an image offsets
could be done by modifying field &v4l2-buffer;<structfield>::m_userptr</structfield>
before calling <constant> VIDIOC_QBUF </constant>. Those
before calling <constant>VIDIOC_QBUF</constant>. Those
operations should be avoided because they are not portable (endianness), and do
not work for macroblock and Bayer formats and mmap buffers. The selection API
deals with configuration of buffer cropping/composing in a clear, intuitive and
@@ -229,7 +228,7 @@ and constraints flags are introduced. Finally, &v4l2-crop; and &v4l2-cropcap;
have no reserved fields. Therefore there is no way to extend their functionality.
The new &v4l2-selection; provides a lot of place for future
extensions. Driver developers are encouraged to implement only selection API.
The former cropping API would be simulated using the new one. </para>
The former cropping API would be simulated using the new one.</para>
</section>
@@ -238,9 +237,9 @@ The former cropping API would be simulated using the new one. </para>
<example>
<title>Resetting the cropping parameters</title>
<para>(A video capture device is assumed; change <constant>
V4L2_BUF_TYPE_VIDEO_CAPTURE </constant> for other devices; change target to
<constant> V4L2_SEL_TGT_COMPOSE_* </constant> family to configure composing
<para>(A video capture device is assumed; change
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other devices; change target to
<constant>V4L2_SEL_TGT_COMPOSE_*</constant> family to configure composing
area)</para>
<programlisting>
@@ -292,8 +291,8 @@ area)</para>
<example>
<title>Querying for scaling factors</title>
<para>A video output device is assumed; change <constant>
V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> for other devices</para>
<para>A video output device is assumed; change
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> for other devices</para>
<programlisting>
&v4l2-selection; compose = {

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

@@ -151,6 +151,14 @@ 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.16</revnumber>
<date>2014-05-27</date>
<authorinitials>lp</authorinitials>
<revremark>Extended &v4l2-pix-format;. Added format flags.
</revremark>
</revision>
<revision>
<revnumber>3.15</revnumber>
<date>2014-02-03</date>

50
Documentation/DocBook/media/v4l/vidioc-dqevent.xml
View File

@@ -92,6 +92,18 @@
<entry><structfield>frame_sync</structfield></entry>
<entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-event-motion-det;</entry>
<entry><structfield>motion_det</structfield></entry>
<entry>Event data for event V4L2_EVENT_MOTION_DET.</entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-event-src-change;</entry>
<entry><structfield>src_change</structfield></entry>
<entry>Event data for event V4L2_EVENT_SOURCE_CHANGE.</entry>
</row>
<row>
<entry></entry>
<entry>__u8</entry>
@@ -258,6 +270,44 @@
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-event-motion-det">
<title>struct <structname>v4l2_event_motion_det</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>
Currently only one flag is available: if <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant>
is set, then the <structfield>frame_sequence</structfield> field is valid,
otherwise that field should be ignored.
</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>frame_sequence</structfield></entry>
<entry>
The sequence number of the frame being received. Only valid if the
<constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> flag was set.
</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>region_mask</structfield></entry>
<entry>
The bitmask of the regions that reported motion. There is at least one
region. If this field is 0, then no motion was detected at all.
If there is no <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> control
(see <xref linkend="detect-controls" />) to assign a different region
to each cell in the motion detection grid, then that all cells
are automatically assigned to the default region 0.
</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="changes-flags">
<title>Changes</title>
<tgroup cols="3">

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

@@ -72,23 +72,30 @@ initialize the <structfield>id</structfield>,
<structfield>size</structfield> and <structfield>reserved2</structfield> fields
of each &v4l2-ext-control; and call the
<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls
must also set the <structfield>string</structfield> field.</para>
must also set the <structfield>string</structfield> field. Controls
of compound types (<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set)
must set the <structfield>ptr</structfield> field.</para>
<para>If the <structfield>size</structfield> is too small to
receive the control result (only relevant for pointer-type controls
like strings), then the driver will set <structfield>size</structfield>
to a valid value and return an &ENOSPC;. You should re-allocate the
string memory to this new size and try again. It is possible that the
same issue occurs again if the string has grown in the meantime. It is
memory to this new size and try again. For the string type it is possible that
the same issue occurs again if the string has grown in the meantime. It is
recommended to call &VIDIOC-QUERYCTRL; first and use
<structfield>maximum</structfield>+1 as the new <structfield>size</structfield>
value. It is guaranteed that that is sufficient memory.
</para>
<para>N-dimensional arrays are set and retrieved row-by-row. You cannot set a partial
array, all elements have to be set or retrieved. The total size is calculated
as <structfield>elems</structfield> * <structfield>elem_size</structfield>.
These values can be obtained by calling &VIDIOC-QUERY-EXT-CTRL;.</para>
<para>To change the value of a set of controls applications
initialize the <structfield>id</structfield>, <structfield>size</structfield>,
<structfield>reserved2</structfield> and
<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
<structfield>value/value64/string/ptr</structfield> fields of each &v4l2-ext-control; and
call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls
will only be set if <emphasis>all</emphasis> control values are
valid.</para>
@@ -96,7 +103,7 @@ valid.</para>
<para>To check if a set of controls have correct values applications
initialize the <structfield>id</structfield>, <structfield>size</structfield>,
<structfield>reserved2</structfield> and
<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
<structfield>value/value64/string/ptr</structfield> fields of each &v4l2-ext-control; and
call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to
the driver whether wrong values are automatically adjusted to a valid
value or if an error is returned.</para>
@@ -158,19 +165,47 @@ applications must set the array to zero.</entry>
<entry></entry>
<entry>__s32</entry>
<entry><structfield>value</structfield></entry>
<entry>New value or current value.</entry>
<entry>New value or current value. Valid if this control is not of
type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
</row>
<row>
<entry></entry>
<entry>__s64</entry>
<entry><structfield>value64</structfield></entry>
<entry>New value or current value.</entry>
<entry>New value or current value. Valid if this control is of
type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
</row>
<row>
<entry></entry>
<entry>char *</entry>
<entry><structfield>string</structfield></entry>
<entry>A pointer to a string.</entry>
<entry>A pointer to a string. Valid if this control is of
type <constant>V4L2_CTRL_TYPE_STRING</constant>.</entry>
</row>
<row>
<entry></entry>
<entry>__u8 *</entry>
<entry><structfield>p_u8</structfield></entry>
<entry>A pointer to a matrix control of unsigned 8-bit values.
Valid if this control is of type <constant>V4L2_CTRL_TYPE_U8</constant>.</entry>
</row>
<row>
<entry></entry>
<entry>__u16 *</entry>
<entry><structfield>p_u16</structfield></entry>
<entry>A pointer to a matrix control of unsigned 16-bit values.
Valid if this control is of type <constant>V4L2_CTRL_TYPE_U16</constant>.</entry>
</row>
<row>
<entry></entry>
<entry>void *</entry>
<entry><structfield>ptr</structfield></entry>
<entry>A pointer to a compound type which can be an N-dimensional array and/or a
compound type (the control's type is >= <constant>V4L2_CTRL_COMPOUND_TYPES</constant>).
Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control.
</entry>
</row>
</tbody>
</tgroup>

12
Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
View File

@@ -152,13 +152,10 @@ a valid base address, so applications can find the corresponding Linux
framebuffer device (see <xref linkend="osd" />).</entry>
</row>
<row>
<entry>&v4l2-pix-format;</entry>
<entry>struct</entry>
<entry><structfield>fmt</structfield></entry>
<entry></entry>
<entry>Layout of the frame buffer. The
<structname>v4l2_pix_format</structname> structure is defined in <xref
linkend="pixfmt" />, for clarification the fields and acceptable values
are listed below:</entry>
<entry>Layout of the frame buffer.</entry>
</row>
<row>
<entry></entry>
@@ -276,9 +273,8 @@ see <xref linkend="colorspaces" />.</entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>priv</structfield></entry>
<entry>Reserved for additional information about custom
(driver defined) formats. When not used drivers and applications must
set this field to zero.</entry>
<entry>Reserved. Drivers and applications must set this field to
zero.</entry>
</row>
</tbody>
</tgroup>

40
Documentation/DocBook/media/v4l/vidioc-g-selection.xml
View File

@@ -58,17 +58,16 @@
<para>The ioctls are used to query and configure selection rectangles.</para>
<para> To query the cropping (composing) rectangle set &v4l2-selection;
<para>To query the cropping (composing) rectangle set &v4l2-selection;
<structfield> type </structfield> field to the respective buffer type.
Do not use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE
</constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
</constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of
<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is
Do not use multiplanar buffers. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. Use
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is
setting the value of &v4l2-selection; <structfield>target</structfield> field
to <constant> V4L2_SEL_TGT_CROP </constant> (<constant>
V4L2_SEL_TGT_COMPOSE </constant>). Please refer to table <xref
linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> for additional
targets. The <structfield>flags</structfield> and <structfield>reserved
to <constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>).
Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" />
for additional targets. The <structfield>flags</structfield> and <structfield>reserved
</structfield> fields of &v4l2-selection; are ignored and they must be filled
with zeros. The driver fills the rest of the structure or
returns &EINVAL; if incorrect buffer type or target was used. If cropping
@@ -77,19 +76,18 @@ always equal to the bounds rectangle. Finally, the &v4l2-rect;
<structfield>r</structfield> rectangle is filled with the current cropping
(composing) coordinates. The coordinates are expressed in driver-dependent
units. The only exception are rectangles for images in raw formats, whose
coordinates are always expressed in pixels. </para>
coordinates are always expressed in pixels.</para>
<para> To change the cropping (composing) rectangle set the &v4l2-selection;
<para>To change the cropping (composing) rectangle set the &v4l2-selection;
<structfield>type</structfield> field to the respective buffer type. Do not
use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE
</constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
</constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of
<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is
use multiplanar buffers. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. Use
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is
setting the value of &v4l2-selection; <structfield>target</structfield> to
<constant>V4L2_SEL_TGT_CROP</constant> (<constant>
V4L2_SEL_TGT_COMPOSE </constant>). Please refer to table <xref
linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> for additional
targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be
<constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>).
Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" />
for additional targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be
set to the desired active area. Field &v4l2-selection; <structfield> reserved
</structfield> is ignored and must be filled with zeros. The driver may adjust
coordinates of the requested rectangle. An application may
@@ -149,8 +147,8 @@ On success the &v4l2-rect; <structfield>r</structfield> field contains
the adjusted rectangle. When the parameters are unsuitable the application may
modify the cropping (composing) or image parameters and repeat the cycle until
satisfactory parameters have been negotiated. If constraints flags have to be
violated at then ERANGE is returned. The error indicates that <emphasis> there
exist no rectangle </emphasis> that satisfies the constraints.</para>
violated at then ERANGE is returned. The error indicates that <emphasis>there
exist no rectangle</emphasis> that satisfies the constraints.</para>
<para>Selection targets and flags are documented in <xref
linkend="v4l2-selections-common"/>.</para>

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

@@ -300,6 +300,12 @@ modulator programming see
<entry>0x00100000</entry>
<entry>The device supports the
<link linkend="sdr">SDR Capture</link> interface.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></entry>
<entry>0x00200000</entry>
<entry>The device supports the &v4l2-pix-format; extended
fields.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_READWRITE</constant></entry>

234
Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
View File

@@ -1,11 +1,12 @@
<refentry id="vidioc-queryctrl">
<refmeta>
<refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle>
<refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_QUERYCTRL</refname>
<refname>VIDIOC_QUERY_EXT_CTRL</refname>
<refname>VIDIOC_QUERYMENU</refname>
<refpurpose>Enumerate controls and menu control items</refpurpose>
</refnamediv>
@@ -19,6 +20,14 @@
<paramdef>struct v4l2_queryctrl *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_query_ext_ctrl *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
@@ -42,7 +51,7 @@
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</para>
<para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -67,7 +76,7 @@ structure. The driver fills the rest of the structure or returns an
<constant>VIDIOC_QUERYCTRL</constant> with successive
<structfield>id</structfield> values starting from
<constant>V4L2_CID_BASE</constant> up to and exclusive
<constant>V4L2_CID_BASE_LASTP1</constant>. Drivers may return
<constant>V4L2_CID_LASTP1</constant>. Drivers may return
<errorcode>EINVAL</errorcode> if a control in this range is not
supported. Further applications can enumerate private controls, which
are not defined in this specification, by starting at
@@ -89,9 +98,23 @@ prematurely end the enumeration).</para></footnote></para>
<para>When the application ORs <structfield>id</structfield> with
<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the
next supported control, or <errorcode>EINVAL</errorcode> if there is
none. Drivers which do not support this flag yet always return
<errorcode>EINVAL</errorcode>.</para>
next supported non-compound control, or <errorcode>EINVAL</errorcode>
if there is none. In addition, the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant>
flag can be specified to enumerate all compound controls (i.e. controls
with type &ge; <constant>V4L2_CTRL_COMPOUND_TYPES</constant>). Specify both
<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and
<constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> in order to enumerate
all controls, compound or not. Drivers which do not support these flags yet
always return <errorcode>EINVAL</errorcode>.</para>
<para>The <constant>VIDIOC_QUERY_EXT_CTRL</constant> ioctl was
introduced in order to better support controls that can use compound
types, and to expose additional control information that cannot be
returned in &v4l2-queryctrl; since that structure is full.</para>
<para><constant>VIDIOC_QUERY_EXT_CTRL</constant> is used in the
same way as <constant>VIDIOC_QUERYCTRL</constant>, except that the
<structfield>reserved</structfield> array must be zeroed as well.</para>
<para>Additional information is required for menu controls: the
names of the menu items. To query them applications set the
@@ -142,38 +165,23 @@ string. This information is intended for the user.</entry>
<entry>__s32</entry>
<entry><structfield>minimum</structfield></entry>
<entry>Minimum value, inclusive. This field gives a lower
bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
lowest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> controls.
For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value
gives the minimum length of the string. This length <emphasis>does not include the terminating
zero</emphasis>. It may not be valid for any other type of control, including
<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
signed value.</entry>
bound for the control. See &v4l2-ctrl-type; how the minimum value is to
be used for each possible control type. Note that this a signed 32-bit value.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>maximum</structfield></entry>
<entry>Maximum value, inclusive. This field gives an upper
bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant>
controls. For <constant>V4L2_CTRL_TYPE_BITMASK</constant> controls it is the
set of usable bits.
For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value
gives the maximum length of the string. This length <emphasis>does not include the terminating
zero</emphasis>. It may not be valid for any other type of control, including
<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
signed value.</entry>
bound for the control. See &v4l2-ctrl-type; how the maximum value is to
be used for each possible control type. Note that this a signed 32-bit value.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>step</structfield></entry>
<entry><para>This field gives a step size for
<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For
<constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to
the string length that has to be a multiple of this step size.
It may not be valid for any other type of control, including
<constant>V4L2_CTRL_TYPE_INTEGER64</constant>
controls.</para><para>Generally drivers should not scale hardware
<entry><para>This field gives a step size for the control.
See &v4l2-ctrl-type; how the step value is to be used for each possible
control type. Note that this an unsigned 32-bit value.
</para><para>Generally drivers should not scale hardware
control values. It may be necessary for example when the
<structfield>name</structfield> or <structfield>id</structfield> imply
a particular unit and the hardware actually accepts only multiples of
@@ -192,10 +200,11 @@ be always positive.</para></entry>
<entry><structfield>default_value</structfield></entry>
<entry>The default value of a
<constant>V4L2_CTRL_TYPE_INTEGER</constant>,
<constant>_BOOLEAN</constant> or <constant>_MENU</constant> control.
Not valid for other types of controls. Drivers reset controls only
when the driver is loaded, not later, in particular not when the
func-open; is called.</entry>
<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>,
<constant>_MENU</constant> or <constant>_INTEGER_MENU</constant> control.
Not valid for other types of controls.
Note that drivers reset controls to their default value only when the
driver is first loaded, never afterwards.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -213,6 +222,126 @@ the array to zero.</entry>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-query-ext-ctrl">
<title>struct <structname>v4l2_query_ext_ctrl</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>id</structfield></entry>
<entry>Identifies the control, set by the application. See
<xref linkend="control-id" /> for predefined IDs. When the ID is ORed
with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver clears the
flag and returns the first non-compound control with a higher ID. When the
ID is ORed with <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> the driver
clears the flag and returns the first compound control with a higher ID.
Set both to get the first control (compound or not) with a higher ID.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry>Type of control, see <xref
linkend="v4l2-ctrl-type" />.</entry>
</row>
<row>
<entry>char</entry>
<entry><structfield>name</structfield>[32]</entry>
<entry>Name of the control, a NUL-terminated ASCII
string. This information is intended for the user.</entry>
</row>
<row>
<entry>__s64</entry>
<entry><structfield>minimum</structfield></entry>
<entry>Minimum value, inclusive. This field gives a lower
bound for the control. See &v4l2-ctrl-type; how the minimum value is to
be used for each possible control type. Note that this a signed 64-bit value.</entry>
</row>
<row>
<entry>__s64</entry>
<entry><structfield>maximum</structfield></entry>
<entry>Maximum value, inclusive. This field gives an upper
bound for the control. See &v4l2-ctrl-type; how the maximum value is to
be used for each possible control type. Note that this a signed 64-bit value.</entry>
</row>
<row>
<entry>__u64</entry>
<entry><structfield>step</structfield></entry>
<entry><para>This field gives a step size for the control.
See &v4l2-ctrl-type; how the step value is to be used for each possible
control type. Note that this an unsigned 64-bit value.
</para><para>Generally drivers should not scale hardware
control values. It may be necessary for example when the
<structfield>name</structfield> or <structfield>id</structfield> imply
a particular unit and the hardware actually accepts only multiples of
said unit. If so, drivers must take care values are properly rounded
when scaling, such that errors will not accumulate on repeated
read-write cycles.</para><para>This field gives the smallest change of
an integer control actually affecting hardware. Often the information
is needed when the user can change controls by keyboard or GUI
buttons, rather than a slider. When for example a hardware register
accepts values 0-511 and the driver reports 0-65535, step should be
128.</para></entry>
</row>
<row>
<entry>__s64</entry>
<entry><structfield>default_value</structfield></entry>
<entry>The default value of a
<constant>V4L2_CTRL_TYPE_INTEGER</constant>, <constant>_INTEGER64</constant>,
<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>,
<constant>_MENU</constant>, <constant>_INTEGER_MENU</constant>,
<constant>_U8</constant> or <constant>_U16</constant> control.
Not valid for other types of controls.
Note that drivers reset controls to their default value only when the
driver is first loaded, never afterwards.
</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>Control flags, see <xref
linkend="control-flags" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>elem_size</structfield></entry>
<entry>The size in bytes of a single element of the array.
Given a char pointer <constant>p</constant> to a 3-dimensional array you can find the
position of cell <constant>(z, y, x)</constant> as follows:
<constant>p + ((z * dims[1] + y) * dims[0] + x) * elem_size</constant>. <structfield>elem_size</structfield>
is always valid, also when the control isn't an array. For string controls
<structfield>elem_size</structfield> is equal to <structfield>maximum + 1</structfield>.
</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>elems</structfield></entry>
<entry>The number of elements in the N-dimensional array. If this control
is not an array, then <structfield>elems</structfield> is 1. The <structfield>elems</structfield>
field can never be 0.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>nr_of_dims</structfield></entry>
<entry>The number of dimension in the N-dimensional array. If this control
is not an array, then this field is 0.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>dims[V4L2_CTRL_MAX_DIMS]</structfield></entry>
<entry>The size of each dimension. The first <structfield>nr_of_dims</structfield>
elements of this array must be non-zero, all remaining elements must be zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[32]</entry>
<entry>Reserved for future extensions. Applications and drivers
must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-querymenu">
<title>struct <structname>v4l2_querymenu</structname></title>
<tgroup cols="4">
@@ -347,11 +476,14 @@ Drivers must ignore the value passed with
</row>
<row>
<entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry>
<entry>n/a</entry>
<entry>n/a</entry>
<entry>n/a</entry>
<entry>any</entry>
<entry>any</entry>
<entry>any</entry>
<entry>A 64-bit integer valued control. Minimum, maximum
and step size cannot be queried.</entry>
and step size cannot be queried using <constant>VIDIOC_QUERYCTRL</constant>.
Only <constant>VIDIOC_QUERY_EXT_CTRL</constant> can retrieve the 64-bit
min/max/step values, they should be interpreted as n/a when using
<constant>VIDIOC_QUERYCTRL</constant>.</entry>
</row>
<row>
<entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry>
@@ -379,6 +511,26 @@ ioctl returns the name of the control class and this control type.
Older drivers which do not support this feature return an
&EINVAL;.</entry>
</row>
<row>
<entry><constant>V4L2_CTRL_TYPE_U8</constant></entry>
<entry>any</entry>
<entry>any</entry>
<entry>any</entry>
<entry>An unsigned 8-bit valued control ranging from minimum to
maximum inclusive. The step value indicates the increment between
values which are actually different on the hardware.
</entry>
</row>
<row>
<entry><constant>V4L2_CTRL_TYPE_U16</constant></entry>
<entry>any</entry>
<entry>any</entry>
<entry>any</entry>
<entry>An unsigned 16-bit valued control ranging from minimum to
maximum inclusive. The step value indicates the increment between
values which are actually different on the hardware.
</entry>
</row>
</tbody>
</tgroup>
</table>
@@ -450,6 +602,14 @@ is in auto-gain mode. In such a case the hardware calculates the gain value base
the lighting conditions which can change over time. Note that setting a new value for
a volatile control will have no effect. The new value will just be ignored.</entry>
</row>
<row>
<entry><constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant></entry>
<entry>0x0100</entry>
<entry>This control has a pointer type, so its value has to be accessed
using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls
that are an array, string, or have a compound type. In all cases you have to set a
pointer to memory containing the payload of the control.</entry>
</row>
</tbody>
</tgroup>
</table>

8
Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
View File

@@ -174,6 +174,14 @@
will have the ORed value of all the events generated.</para>
</entry>
</row>
<row>
<entry><constant>V4L2_EVENT_MOTION_DET</constant></entry>
<entry>5</entry>
<entry>
<para>Triggered whenever the motion detection state for one or more of the regions
changes. This event has a &v4l2-event-motion-det; associated with it.</para>
</entry>
</row>
<row>
<entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
<entry>0x08000000</entry>