diff options
Diffstat (limited to 'Documentation/DocBook')
33 files changed, 1419 insertions, 277 deletions
diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index cc63f30de16..f2130586ef5 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -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 diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index 4017f147ba2..64162922117 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -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> @@ -708,7 +708,7 @@ hardware level details could be very different. <para>Systems need specialized hardware support to implement OTG, notably including a special <emphasis>Mini-AB</emphasis> jack -and associated transciever to support <emphasis>Dual-Role</emphasis> +and associated transceiver to support <emphasis>Dual-Role</emphasis> operation: they can act either as a host, using the standard Linux-USB host side driver stack, diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl index 46347f60335..59fb5c07754 100644 --- a/Documentation/DocBook/genericirq.tmpl +++ b/Documentation/DocBook/genericirq.tmpl @@ -182,7 +182,7 @@ <para> Each interrupt is described by an interrupt descriptor structure irq_desc. The interrupt is referenced by an 'unsigned int' numeric - value which selects the corresponding interrupt decription structure + value which selects the corresponding interrupt description structure in the descriptor structures array. The descriptor structure contains status information and pointers to the interrupt flow method and the interrupt chip structure @@ -470,7 +470,7 @@ if (desc->irq_data.chip->irq_eoi) <para> To avoid copies of identical implementations of IRQ chips the core provides a configurable generic interrupt chip - implementation. Developers should check carefuly whether the + implementation. Developers should check carefully whether the generic chip fits their needs before implementing the same functionality slightly differently themselves. </para> diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index 19f2a5a5a5b..e584ee12a1e 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl @@ -1760,7 +1760,7 @@ as it would be on UP. </para> <para> -There is a furthur optimization possible here: remember our original +There is a further optimization possible here: remember our original cache code, where there were no reference counts and the caller simply held the lock whenever using the object? This is still possible: if you hold the lock, no one can delete the object, so you don't need to diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index deb71baed32..d7fcdc5a437 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -677,7 +677,7 @@ and other resources, etc. <listitem> <para> - ATA_QCFLAG_ACTIVE is clared from qc->flags. + ATA_QCFLAG_ACTIVE is cleared from qc->flags. </para> </listitem> @@ -708,7 +708,7 @@ and other resources, etc. <listitem> <para> - qc->waiting is claread & completed (in that order). + qc->waiting is cleared & completed (in that order). </para> </listitem> @@ -1163,7 +1163,7 @@ and other resources, etc. <para> Once sense data is acquired, this type of errors can be - handled similary to other SCSI errors. Note that sense data + handled similarly to other SCSI errors. Note that sense data may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such cases, the error should be considered as an ATA bus error and diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 639e7485796..df2962d9e11 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -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" diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 24c22cabc66..948ddaab592 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -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> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 47198eef75a..9f5ffd85560 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -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 ⪚ 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,127 +447,152 @@ 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 (&querymenu, 0, sizeof (querymenu)); + memset(&querymenu, 0, sizeof(querymenu)); querymenu.id = queryctrl.id; for (querymenu.index = queryctrl.minimum; querymenu.index <= queryctrl.maximum; - querymenu.index++) { - if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &querymenu)) { - printf (" %s\n", querymenu.name); + querymenu.index++) { + if (0 == ioctl(fd, &VIDIOC-QUERYMENU;, &querymenu)) { + printf(" %s\n", querymenu.name); } } } -memset (&queryctrl, 0, sizeof (queryctrl)); +memset(&queryctrl, 0, sizeof(queryctrl)); for (queryctrl.id = V4L2_CID_BASE; queryctrl.id < V4L2_CID_LASTP1; queryctrl.id++) { - if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { + if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { if (queryctrl.flags & 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;, &queryctrl)) { + if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { if (queryctrl.flags & 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(&queryctrl, 0, sizeof(queryctrl)); + +queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL; +while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { + if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER) + break; + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf("Control %s\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(); + + queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; +} +if (errno != EINVAL) { + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); +} +</programlisting> + </example> + + <example> <title>Changing controls</title> <programlisting> &v4l2-queryctrl; queryctrl; &v4l2-control; control; -memset (&queryctrl, 0, sizeof (queryctrl)); +memset(&queryctrl, 0, sizeof(queryctrl)); queryctrl.id = V4L2_CID_BRIGHTNESS; -if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { +if (-1 == ioctl(fd, &VIDIOC-QUERYCTRL;, &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 & V4L2_CTRL_FLAG_DISABLED) { - printf ("V4L2_CID_BRIGHTNESS is not supported\n"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } else { - memset (&control, 0, sizeof (control)); + memset(&control, 0, sizeof (control)); control.id = V4L2_CID_BRIGHTNESS; control.value = queryctrl.default_value; - if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control)) { - perror ("VIDIOC_S_CTRL"); - exit (EXIT_FAILURE); + if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &control)) { + perror("VIDIOC_S_CTRL"); + exit(EXIT_FAILURE); } } -memset (&control, 0, sizeof (control)); +memset(&control, 0, sizeof(control)); control.id = V4L2_CID_CONTRAST; -if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &control)) { +if (0 == ioctl(fd, &VIDIOC-G-CTRL;, &control)) { control.value += 1; /* The driver may clamp the value or return ERANGE, ignored here */ - if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control) + if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &control) && 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, &control); +ioctl(fd, VIDIOC_S_CTRL, &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;, &qctrl)) { - if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG) +while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &qctrl)) { + if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) break; /* ... */ - qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; - } + 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> @@ -4000,6 +4051,68 @@ to find receivers which can scroll strings sized as 32 x N or 64 x N characters. 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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </entry> <entry>boolean</entry> </row> @@ -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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml index b788c72c885..f4b61b6ce3c 100644 --- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml @@ -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> diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml index dc14804f543..f8903568a24 100644 --- a/Documentation/DocBook/media/v4l/dev-sdr.xml +++ b/Documentation/DocBook/media/v4l/dev-sdr.xml @@ -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"> @@ -92,8 +95,15 @@ 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> diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml index 548f8ea28de..7a8bf3011ee 100644 --- a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml @@ -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> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index a086a5db7a1..e5e8325aa3d 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -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> diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml index e1c4f8b4c0b..2aae8e9452a 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml @@ -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,9 +382,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-BGR32"> - <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> - <entry>'BGR4'</entry> + <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> @@ -381,9 +422,49 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>a<subscript>1</subscript></entry> <entry>a<subscript>0</subscript></entry> </row> - <row id="V4L2-PIX-FMT-RGB32"> - <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> - <entry>'RGB4'</entry> + <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> @@ -421,18 +502,76 @@ 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-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. 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> + <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 × 4 pixel @@ -512,6 +651,239 @@ image</title> </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> </entry> + <entry spanname="b0">Byte 0 in memory</entry> + <entry spanname="b1">Byte 1</entry> + <entry spanname="b2">Byte 2</entry> + <entry spanname="b3">Byte 3</entry> + </row> + <row> + <entry> </entry> + <entry> </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> </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> </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> </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> + <entry></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry></entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry>a<subscript>7</subscript></entry> + <entry>a<subscript>6</subscript></entry> + <entry>a<subscript>5</subscript></entry> + <entry>a<subscript>4</subscript></entry> + <entry>a<subscript>3</subscript></entry> + <entry>a<subscript>2</subscript></entry> + <entry>a<subscript>1</subscript></entry> + <entry>a<subscript>0</subscript></entry> + </row> + <row id="V4L2-PIX-FMT-RGB32"> + <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> + <entry>'RGB4'</entry> + <entry></entry> + <entry>a<subscript>7</subscript></entry> + <entry>a<subscript>6</subscript></entry> + <entry>a<subscript>5</subscript></entry> + <entry>a<subscript>4</subscript></entry> + <entry>a<subscript>3</subscript></entry> + <entry>a<subscript>2</subscript></entry> + <entry>a<subscript>1</subscript></entry> + <entry>a<subscript>0</subscript></entry> + <entry></entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + </row> + </tbody> + </tgroup> + </table> + <para>A test utility to determine which RGB formats a driver actually supports is available from the LinuxTV v4l-dvb repository. See &v4l-dvb; for access instructions.</para> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml new file mode 100644 index 00000000000..6118d8f7a20 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml @@ -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 + 0:</entry> + <entry>I'<subscript>0</subscript></entry> + </row> + <row> + <entry>start + 1:</entry> + <entry>Q'<subscript>0</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml new file mode 100644 index 00000000000..e4b494ce136 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml @@ -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 + 0:</entry> + <entry>I'<subscript>0[7:0]</subscript></entry> + <entry>I'<subscript>0[13:8]</subscript></entry> + </row> + <row> + <entry>start + 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> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml new file mode 100644 index 00000000000..3df076b99f9 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml @@ -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 + 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> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml index 9ba4fb690bc..96947f17fca 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml @@ -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 diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 91dcbc84f3f..df5b23d4655 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -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> diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index 4c238ce068b..28cbded766c 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -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> - -<para>The device has a default composing rectangle, given by the <constant> -V4L2_SEL_TGT_COMPOSE_DEFAULT </constant> target. This rectangle shall cover what +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 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 = { diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index b445161b912..f2f81f06a17 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -152,6 +152,14 @@ structs, ioctls) must be noted in more detail in the history chapter 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> <authorinitials>hv, ap</authorinitials> diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml index 820f86e8744..cb7732582f0 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml @@ -94,6 +94,18 @@ </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> <entry><structfield>data</structfield>[64]</entry> <entry>Event data. Defined by the event type. The union @@ -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"> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index e9f6735c082..c5bdbfcc42b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -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> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml index 7c63815e7af..20460730b02 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml @@ -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> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index b11ec75e21a..9c04ac8661b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -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> diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index 370d49d6fb6..d0c5e604f01 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml @@ -302,6 +302,12 @@ modulator programming see <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> <entry>0x01000000</entry> <entry>The device supports the <link diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index e6645b99655..2bd98fd7a4e 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -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> @@ -24,6 +25,14 @@ <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> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -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 ≥ <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> diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index 17efa870d4d..9f609560883 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml @@ -175,6 +175,14 @@ </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> <entry>Base event number for driver-private events.</entry> diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl index 4decb46bfa7..03f9a1f8d41 100644 --- a/Documentation/DocBook/media_api.tmpl +++ b/Documentation/DocBook/media_api.tmpl @@ -68,7 +68,7 @@ several digital tv standards. While it is called as DVB API, in fact it covers several different video standards including DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated - to documment support also for DVB-S2, ISDB-T and ISDB-S.</para> + to document support also for DVB-S2, ISDB-T and ISDB-S.</para> <para>The third part covers the Remote Controller API.</para> <para>The fourth part covers the Media Controller API.</para> <para>For additional information and for the latest development code, diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index cd11926e07c..7da8f0402af 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl @@ -91,7 +91,7 @@ <listitem><para> [MTD Interface]</para><para> These functions provide the interface to the MTD kernel API. - They are not replacable and provide functionality + They are not replaceable and provide functionality which is complete hardware independent. </para></listitem> <listitem><para> @@ -100,14 +100,14 @@ </para></listitem> <listitem><para> [GENERIC]</para><para> - Generic functions are not replacable and provide functionality + Generic functions are not replaceable and provide functionality which is complete hardware independent. </para></listitem> <listitem><para> [DEFAULT]</para><para> Default functions provide hardware related functionality which is suitable for most of the implementations. These functions can be replaced by the - board driver if neccecary. Those functions are called via pointers in the + board driver if necessary. Those functions are called via pointers in the NAND chip description structure. The board driver can set the functions which should be replaced by board dependent functions before calling nand_scan(). If the function pointer is NULL on entry to nand_scan() then the pointer @@ -264,7 +264,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd) is set up nand_scan() is called. This function tries to detect and identify then chip. If a chip is found all the internal data fields are initialized accordingly. - The structure(s) have to be zeroed out first and then filled with the neccecary + The structure(s) have to be zeroed out first and then filled with the necessary information about the device. </para> <programlisting> @@ -327,7 +327,7 @@ module_init(board_init); <sect1 id="Exit_function"> <title>Exit function</title> <para> - The exit function is only neccecary if the driver is + The exit function is only necessary if the driver is compiled as a module. It releases all resources which are held by the chip driver and unregisters the partitions in the MTD layer. @@ -494,7 +494,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) in this case. See rts_from4.c and diskonchip.c for implementation reference. In those cases we must also use bad block tables on FLASH, because the ECC layout is - interferring with the bad block marker positions. + interfering with the bad block marker positions. See bad block table support for details. </para> </sect2> @@ -542,7 +542,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) <para> nand_scan() calls the function nand_default_bbt(). nand_default_bbt() selects appropriate default - bad block table desriptors depending on the chip information + bad block table descriptors depending on the chip information which was retrieved by nand_scan(). </para> <para> @@ -554,7 +554,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) <sect2 id="Flash_based_tables"> <title>Flash based tables</title> <para> - It may be desired or neccecary to keep a bad block table in FLASH. + It may be desired or necessary to keep a bad block table in FLASH. For AG-AND chips this is mandatory, as they have no factory marked bad blocks. They have factory marked good blocks. The marker pattern is erased when the block is erased to be reused. So in case of @@ -565,10 +565,10 @@ static void board_select_chip (struct mtd_info *mtd, int chip) of the blocks. </para> <para> - The blocks in which the tables are stored are procteted against + The blocks in which the tables are stored are protected against accidental access by marking them bad in the memory bad block table. The bad block table management functions are allowed - to circumvernt this protection. + to circumvent this protection. </para> <para> The simplest way to activate the FLASH based bad block table support @@ -592,7 +592,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) User defined tables are created by filling out a nand_bbt_descr structure and storing the pointer in the nand_chip structure member bbt_td before calling nand_scan(). - If a mirror table is neccecary a second structure must be + If a mirror table is necessary a second structure must be created and a pointer to this structure must be stored in bbt_md inside the nand_chip structure. If the bbt_md member is set to NULL then only the main table is used @@ -666,7 +666,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) <para> For automatic placement some blocks must be reserved for bad block table storage. The number of reserved blocks is defined - in the maxblocks member of the babd block table description structure. + in the maxblocks member of the bad block table description structure. Reserving 4 blocks for mirrored tables should be a reasonable number. This also limits the number of blocks which are scanned for the bad block table ident pattern. @@ -1068,11 +1068,11 @@ in this page</entry> <chapter id="filesystems"> <title>Filesystem support</title> <para> - The NAND driver provides all neccecary functions for a + The NAND driver provides all necessary functions for a filesystem via the MTD interface. </para> <para> - Filesystems must be aware of the NAND pecularities and + Filesystems must be aware of the NAND peculiarities and restrictions. One major restrictions of NAND Flash is, that you cannot write as often as you want to a page. The consecutive writes to a page, before erasing it again, are restricted to 1-3 writes, depending on the @@ -1222,7 +1222,7 @@ in this page</entry> #define NAND_BBT_VERSION 0x00000100 /* Create a bbt if none axists */ #define NAND_BBT_CREATE 0x00000200 -/* Write bbt if neccecary */ +/* Write bbt if necessary */ #define NAND_BBT_WRITE 0x00001000 /* Read and write back block contents when writing bbt */ #define NAND_BBT_SAVECONTENT 0x00002000 diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl index 346e552fa2c..3b08a085d2c 100644 --- a/Documentation/DocBook/regulator.tmpl +++ b/Documentation/DocBook/regulator.tmpl @@ -155,7 +155,7 @@ release regulators. Functions are provided to <link linkend='API-regulator-enable'>enable</link> and <link linkend='API-regulator-disable'>disable</link> the - reguator and to get and set the runtime parameters of the + regulator and to get and set the runtime parameters of the regulator. </para> <para> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index 95618159e29..bbe9c1fd5ce 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -766,10 +766,10 @@ framework to set up sysfs files for this region. Simply leave it alone. <para> The dynamic memory regions will be allocated when the UIO device file, <varname>/dev/uioX</varname> is opened. - Simiar to static memory resources, the memory region information for + Similar to static memory resources, the memory region information for dynamic regions is then visible via sysfs at <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. - The dynmaic memory regions will be freed when the UIO device file is + The dynamic memory regions will be freed when the UIO device file is closed. When no processes are holding the device file open, the address returned to userspace is ~0. </para> diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index 8d57c1888dc..85fc0e28576 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -153,7 +153,7 @@ <listitem><para>The Linux USB API supports synchronous calls for control and bulk messages. - It also supports asynchnous calls for all kinds of data transfer, + It also supports asynchronous calls for all kinds of data transfer, using request structures called "URBs" (USB Request Blocks). </para></listitem> diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index d0056a4e9c5..6f639d9530b 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -5696,7 +5696,7 @@ struct _snd_pcm_runtime { suspending the PCM operations via <function>snd_pcm_suspend_all()</function> or <function>snd_pcm_suspend()</function>. It means that the PCM - streams are already stoppped when the register snapshot is + streams are already stopped when the register snapshot is taken. But, remember that you don't have to restart the PCM stream in the resume callback. It'll be restarted via trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant> |