diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2014-04-04 09:50:07 -0700 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2014-04-04 09:50:07 -0700 |
| commit | 3c83e61e67256e0bb08c46cc2db43b58fd617251 (patch) | |
| tree | 0233e1e04e6449c60b01ff5dea8bea85bcf22f08 /Documentation/DocBook/media/v4l | |
| parent | 4a4389abdd9822fdf3cc2ac6ed87eb811fd43acc (diff) | |
| parent | a83b93a7480441a47856dc9104bea970e84cda87 (diff) | |
Merge branch 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab:
"The main set of series of patches for media subsystem, including:
- document RC sysfs class
- added an API to setup scancode to allow waking up systems using the
Remote Controller
- add API for SDR devices. Drivers are still on staging
- some API improvements for getting EDID data from media
inputs/outputs
- new DVB frontend driver for drx-j (ATSC)
- one driver (it913x/it9137) got removed, in favor of an improvement
on another driver (af9035)
- added a skeleton V4L2 PCI driver at documentation
- added a dual flash driver (lm3646)
- added a new IR driver (img-ir)
- added an IR scancode decoder for the Sharp protocol
- some improvements at the usbtv driver, to allow its core to be
reused.
- added a new SDR driver (rtl2832u_sdr)
- added a new tuner driver (msi001)
- several improvements at em28xx driver to fix PM support, device
removal and to split the V4L2 specific bits into a separate
sub-driver
- one driver got converted to videobuf2 (s2255drv)
- the e4000 tuner driver now follows an improved binding model
- some fixes at V4L2 compat32 code
- several fixes and enhancements at videobuf2 code
- some cleanups at V4L2 API documentation
- usual driver enhancements, new board additions and misc fixups"
[ NOTE! This merge effective drops commit 4329b93b283c ("of: Reduce
indentation in of_graph_get_next_endpoint").
The of_graph_get_next_endpoint() function was moved and renamed by
commit fd9fdb78a9bf ("[media] of: move graph helpers from
drivers/media/v4l2-core to drivers/of"). It was originally called
v4l2_of_get_next_endpoint() and lived in the file
drivers/media/v4l2-core/v4l2-of.c.
In that original location, it was then fixed to support empty port
nodes by commit b9db140c1e46 ("[media] v4l: of: Support empty port
nodes"), and that commit clashes badly with the dropped "Reduce
intendation" commit. I had to choose one or the other, and decided
that the "Support empty port nodes" commit was more important ]
* 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (426 commits)
[media] em28xx-dvb: fix PCTV 461e tuner I2C binding
Revert "[media] em28xx-dvb: fix PCTV 461e tuner I2C binding"
[media] em28xx: fix PCTV 290e LNA oops
[media] em28xx-dvb: fix PCTV 461e tuner I2C binding
[media] m88ds3103: fix bug on .set_tone()
[media] saa7134: fix WARN_ON during resume
[media] v4l2-dv-timings: add module name, description, license
[media] videodev2.h: add parenthesis around macro arguments
[media] saa6752hs: depends on CRC32
[media] si4713: fix Kconfig dependencies
[media] Sensoray 2255 uses videobuf2
[media] adv7180: free an interrupt on failure paths in init_device()
[media] e4000: make VIDEO_V4L2 dependency optional
[media] af9033: Don't export functions for the hardware filter
[media] af9035: use af9033 PID filters
[media] af9033: implement PID filter
[media] rtl2832_sdr: do not use dynamic stack allocation
[media] e4000: fix 32-bit build error
[media] em28xx-audio: make sure audio is unmuted on open()
[media] DocBook media: v4l2_format_sdr was renamed to v4l2_sdr_format
...
Diffstat (limited to 'Documentation/DocBook/media/v4l')
23 files changed, 1007 insertions, 856 deletions
diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index 1ddf354aa99..71f6bf9e735 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -38,70 +38,41 @@ the basic concepts applicable to all devices.</para> <para>V4L2 drivers are implemented as kernel modules, loaded manually by the system administrator or automatically when a device is -first opened. The driver modules plug into the "videodev" kernel +first discovered. The driver modules plug into the "videodev" kernel module. It provides helper functions and a common application interface specified in this document.</para> <para>Each driver thus loaded registers one or more device nodes -with major number 81 and a minor number between 0 and 255. Assigning -minor numbers to V4L2 devices is entirely up to the system administrator, -this is primarily intended to solve conflicts between devices.<footnote> - <para>Access permissions are associated with character -device special files, hence we must ensure device numbers cannot -change with the module load order. To this end minor numbers are no -longer automatically assigned by the "videodev" module as in V4L but -requested by the driver. The defaults will suffice for most people -unless two drivers compete for the same minor numbers.</para> - </footnote> The module options to select minor numbers are named -after the device special file with a "_nr" suffix. For example "video_nr" -for <filename>/dev/video</filename> video capture devices. The number is -an offset to the base minor number associated with the device type. -<footnote> - <para>In earlier versions of the V4L2 API the module options -where named after the device special file with a "unit_" prefix, expressing -the minor number itself, not an offset. Rationale for this change is unknown. -Lastly the naming and semantics are just a convention among driver writers, -the point to note is that minor numbers are not supposed to be hardcoded -into drivers.</para> - </footnote> When the driver supports multiple devices of the same -type more than one minor number can be assigned, separated by commas: -<informalexample> +with major number 81 and a minor number between 0 and 255. Minor numbers +are allocated dynamically unless the kernel is compiled with the kernel +option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are +allocated in ranges depending on the device node type (video, radio, etc.).</para> + + <para>Many drivers support "video_nr", "radio_nr" or "vbi_nr" +module options to select specific video/radio/vbi node numbers. This allows +the user to request that the device node is named e.g. /dev/video5 instead +of leaving it to chance. When the driver supports multiple devices of the same +type more than one device node number can be assigned, separated by commas: + <informalexample> <screen> -> insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen> +> modprobe mydriver video_nr=0,1 radio_nr=0,1</screen> </informalexample></para> <para>In <filename>/etc/modules.conf</filename> this may be written as: <informalexample> <screen> -alias char-major-81-0 mydriver -alias char-major-81-1 mydriver -alias char-major-81-64 mydriver <co id="alias" /> -options mydriver video_nr=0,1 radio_nr=0,1 <co id="options" /> +options mydriver video_nr=0,1 radio_nr=0,1 </screen> - <calloutlist> - <callout arearefs="alias"> - <para>When an application attempts to open a device -special file with major number 81 and minor number 0, 1, or 64, load -"mydriver" (and the "videodev" module it depends upon).</para> - </callout> - <callout arearefs="options"> - <para>Register the first two video capture devices with -minor number 0 and 1 (base number is 0), the first two radio device -with minor number 64 and 65 (base 64).</para> - </callout> - </calloutlist> - </informalexample> When no minor number is given as module -option the driver supplies a default. <xref linkend="devices" /> -recommends the base minor numbers to be used for the various device -types. Obviously minor numbers must be unique. When the number is -already in use the <emphasis>offending device</emphasis> will not be -registered. <!-- Blessed by Linus Torvalds on -linux-kernel@vger.kernel.org, 2002-11-20. --></para> - - <para>By convention system administrators create various -character device special files with these major and minor numbers in -the <filename>/dev</filename> directory. The names recommended for the -different V4L2 device types are listed in <xref linkend="devices" />. + </informalexample> When no device node number is given as module +option the driver supplies a default.</para> + + <para>Normally udev will create the device nodes in /dev automatically +for you. If udev is not installed, then you need to enable the +CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly +relate a minor number to a device node number. I.e., you need to be certain +that minor number 5 maps to device node name video5. With this kernel option +different device types have different minor number ranges. These ranges are +listed in <xref linkend="devices" />. </para> <para>The creation of character special files (with @@ -110,85 +81,66 @@ devices cannot be opened by major and minor number. That means applications cannot <emphasis>reliable</emphasis> scan for loaded or installed drivers. The user must enter a device name, or the application can try the conventional device names.</para> - - <para>Under the device filesystem (devfs) the minor number -options are ignored. V4L2 drivers (or by proxy the "videodev" module) -automatically create the required device files in the -<filename>/dev/v4l</filename> directory using the conventional device -names above.</para> </section> <section id="related"> <title>Related Devices</title> - <para>Devices can support several related functions. For example -video capturing, video overlay and VBI capturing are related because -these functions share, amongst other, the same video input and tuner -frequency. V4L and earlier versions of V4L2 used the same device name -and minor number for video capturing and overlay, but different ones -for VBI. Experience showed this approach has several problems<footnote> - <para>Given a device file name one cannot reliable find -related devices. For once names are arbitrary and in a system with -multiple devices, where only some support VBI capturing, a -<filename>/dev/video2</filename> is not necessarily related to -<filename>/dev/vbi2</filename>. The V4L -<constant>VIDIOCGUNIT</constant> ioctl would require a search for a -device file with a particular major and minor number.</para> - </footnote>, and to make things worse the V4L videodev module -used to prohibit multiple opens of a device.</para> - - <para>As a remedy the present version of the V4L2 API relaxed the -concept of device types with specific names and minor numbers. For -compatibility with old applications drivers must still register different -minor numbers to assign a default function to the device. But if related -functions are supported by the driver they must be available under all -registered minor numbers. The desired function can be selected after -opening the device as described in <xref linkend="devices" />.</para> - - <para>Imagine a driver supporting video capturing, video -overlay, raw VBI capturing, and FM radio reception. It registers three -devices with minor number 0, 64 and 224 (this numbering scheme is -inherited from the V4L API). Regardless if -<filename>/dev/video</filename> (81, 0) or -<filename>/dev/vbi</filename> (81, 224) is opened the application can -select any one of the video capturing, overlay or VBI capturing -functions. Without programming (e. g. reading from the device -with <application>dd</application> or <application>cat</application>) -<filename>/dev/video</filename> captures video images, while -<filename>/dev/vbi</filename> captures raw VBI data. -<filename>/dev/radio</filename> (81, 64) is invariable a radio device, -unrelated to the video functions. Being unrelated does not imply the -devices can be used at the same time, however. The &func-open; -function may very well return an &EBUSY;.</para> + <para>Devices can support several functions. For example +video capturing, VBI capturing and radio support.</para> + + <para>The V4L2 API creates different nodes for each of these functions.</para> + + <para>The V4L2 API was designed with the idea that one device node could support +all functions. However, in practice this never worked: this 'feature' +was never used by applications and many drivers did not support it and if +they did it was certainly never tested. In addition, switching a device +node between different functions only works when using the streaming I/O +API, not with the read()/write() API.</para> + + <para>Today each device node supports just one function.</para> <para>Besides video input or output the hardware may also support audio sampling or playback. If so, these functions are -implemented as OSS or ALSA PCM devices and eventually OSS or ALSA -audio mixer. The V4L2 API makes no provisions yet to find these -related devices. If you have an idea please write to the linux-media -mailing list: &v4l-ml;.</para> +implemented as ALSA PCM devices with optional ALSA audio mixer +devices.</para> + + <para>One problem with all these devices is that the V4L2 API +makes no provisions to find these related devices. Some really +complex devices use the Media Controller (see <xref linkend="media_controller" />) +which can be used for this purpose. But most drivers do not use it, +and while some code exists that uses sysfs to discover related devices +(see libmedia_dev in the <ulink url="http://git.linuxtv.org/v4l-utils/">v4l-utils</ulink> +git repository), there is no library yet that can provide a single API towards +both Media Controller-based devices and devices that do not use the Media Controller. +If you want to work on this please write to the linux-media mailing list: &v4l-ml;.</para> </section> <section> <title>Multiple Opens</title> - <para>In general, V4L2 devices can be opened more than once. + <para>V4L2 devices can be opened more than once.<footnote><para> +There are still some old and obscure drivers that have not been updated to +allow for multiple opens. This implies that for such drivers &func-open; can +return an &EBUSY; when the device is already in use.</para></footnote> When this is supported by the driver, users can for example start a "panel" application to change controls like brightness or audio volume, while another application captures video and audio. In other words, panel -applications are comparable to an OSS or ALSA audio mixer application. -When a device supports multiple functions like capturing and overlay -<emphasis>simultaneously</emphasis>, multiple opens allow concurrent -use of the device by forked processes or specialized applications.</para> - - <para>Multiple opens are optional, although drivers should -permit at least concurrent accesses without data exchange, &ie; panel -applications. This implies &func-open; can return an &EBUSY; when the -device is already in use, as well as &func-ioctl; functions initiating -data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read; -and &func-write; functions.</para> - - <para>Mere opening a V4L2 device does not grant exclusive +applications are comparable to an ALSA audio mixer application. +Just opening a V4L2 device should not change the state of the device.<footnote> +<para>Unfortunately, opening a radio device often switches the state of the +device to radio mode in many drivers. This behavior should be fixed eventually +as it violates the V4L2 specification.</para></footnote></para> + + <para>Once an application has allocated the memory buffers needed for +streaming data (by calling the &VIDIOC-REQBUFS; or &VIDIOC-CREATE-BUFS; ioctls, +or implicitly by calling the &func-read; or &func-write; functions) that +application (filehandle) becomes the owner of the device. It is no longer +allowed to make changes that would affect the buffer sizes (e.g. by calling +the &VIDIOC-S-FMT; ioctl) and other applications are no longer allowed to allocate +buffers or start or stop streaming. The &EBUSY; will be returned instead.</para> + + <para>Merely opening a V4L2 device does not grant exclusive access.<footnote> <para>Drivers could recognize the <constant>O_EXCL</constant> open flag. Presently this is not required, @@ -206,12 +158,7 @@ additional access privileges using the priority mechanism described in <para>V4L2 drivers should not support multiple applications reading or writing the same data stream on a device by copying buffers, time multiplexing or similar means. This is better handled by -a proxy application in user space. When the driver supports stream -sharing anyway it must be implemented transparently. The V4L2 API does -not specify how conflicts are solved. <!-- For example O_EXCL when the -application does not want to be preempted, PROT_READ mmapped buffers -which can be mapped twice, what happens when image formats do not -match etc.--></para> +a proxy application in user space.</para> </section> <section> @@ -240,15 +187,15 @@ methods</link> supported by the device.</para> <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the V4L2 API version used by the driver, with generally matches the Kernel version. -There's no need of using &VIDIOC-QUERYCAP; to check if an specific ioctl is -supported, the V4L2 core now returns ENOIOCTLCMD if a driver doesn't provide +There's no need of using &VIDIOC-QUERYCAP; to check if a specific ioctl is +supported, the V4L2 core now returns ENOTTY if a driver doesn't provide support for an ioctl.</para> <para>Other features can be queried by calling the respective ioctl, for example &VIDIOC-ENUMINPUT; to learn about the number, types and names of video connectors on the device. Although abstraction is a major objective of this API, the -ioctl also allows driver specific applications to reliable identify +&VIDIOC-QUERYCAP; ioctl also allows driver specific applications to reliably identify the driver.</para> <para>All V4L2 drivers must support @@ -278,9 +225,7 @@ Applications requiring a different priority will usually call the &VIDIOC-QUERYCAP; ioctl.</para> <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;, -return an &EBUSY; after another application obtained higher priority. -An event mechanism to notify applications about asynchronous property -changes has been proposed but not added yet.</para> +return an &EBUSY; after another application obtained higher priority.</para> </section> <section id="video"> @@ -288,9 +233,9 @@ changes has been proposed but not added yet.</para> <para>Video inputs and outputs are physical connectors of a device. These can be for example RF connectors (antenna/cable), CVBS -a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI -capture devices have inputs, output devices have outputs, at least one -each. Radio devices have no video inputs or outputs.</para> +a.k.a. Composite Video, S-Video or RGB connectors. Video and VBI +capture devices have inputs. Video and VBI output devices have outputs, +at least one each. Radio devices have no video inputs or outputs.</para> <para>To learn about the number and attributes of the available inputs and outputs applications can enumerate them with the @@ -299,30 +244,13 @@ available inputs and outputs applications can enumerate them with the ioctl also contains signal status information applicable when the current video input is queried.</para> - <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the + <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctls return the index of the current video input or output. To select a different input or output applications call the &VIDIOC-S-INPUT; and -&VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls +&VIDIOC-S-OUTPUT; ioctls. Drivers must implement all the input ioctls when the device has one or more inputs, all the output ioctls when the device has one or more outputs.</para> - <!-- - <figure id=io-tree> - <title>Input and output enumeration is the root of most device properties.</title> - <mediaobject> - <imageobject> - <imagedata fileref="links.pdf" format="ps" /> - </imageobject> - <imageobject> - <imagedata fileref="links.gif" format="gif" /> - </imageobject> - <textobject> - <phrase>Links between various device property structures.</phrase> - </textobject> - </mediaobject> - </figure> - --> - <example> <title>Information about the current video input</title> @@ -330,20 +258,20 @@ device has one or more outputs.</para> &v4l2-input; input; int index; -if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &index)) { - perror ("VIDIOC_G_INPUT"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &index)) { + perror("VIDIOC_G_INPUT"); + exit(EXIT_FAILURE); } -memset (&input, 0, sizeof (input)); +memset(&input, 0, sizeof(input)); input.index = index; -if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { - perror ("VIDIOC_ENUMINPUT"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { + perror("VIDIOC_ENUMINPUT"); + exit(EXIT_FAILURE); } -printf ("Current input: %s\n", input.name); +printf("Current input: %s\n", input.name); </programlisting> </example> @@ -355,9 +283,9 @@ int index; index = 0; -if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &index)) { - perror ("VIDIOC_S_INPUT"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-S-INPUT;, &index)) { + perror("VIDIOC_S_INPUT"); + exit(EXIT_FAILURE); } </programlisting> </example> @@ -397,7 +325,7 @@ available inputs and outputs applications can enumerate them with the also contains signal status information applicable when the current audio input is queried.</para> - <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report + <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctls report the current audio input and output, respectively. Note that, unlike &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure as <constant>VIDIOC_ENUMAUDIO</constant> and @@ -408,11 +336,11 @@ applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio output (which presently has no changeable properties) applications call the &VIDIOC-S-AUDOUT; ioctl.</para> - <para>Drivers must implement all input ioctls when the device -has one or more inputs, all output ioctls when the device has one -or more outputs. When the device has any audio inputs or outputs the -driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the -&v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para> + <para>Drivers must implement all audio input ioctls when the device +has multiple selectable audio inputs, all audio output ioctls when the +device has multiple selectable audio outputs. When the device has any +audio inputs or outputs the driver must set the <constant>V4L2_CAP_AUDIO</constant> +flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para> <example> <title>Information about the current audio input</title> @@ -420,14 +348,14 @@ driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the <programlisting> &v4l2-audio; audio; -memset (&audio, 0, sizeof (audio)); +memset(&audio, 0, sizeof(audio)); -if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &audio)) { - perror ("VIDIOC_G_AUDIO"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-G-AUDIO;, &audio)) { + perror("VIDIOC_G_AUDIO"); + exit(EXIT_FAILURE); } -printf ("Current input: %s\n", audio.name); +printf("Current input: %s\n", audio.name); </programlisting> </example> @@ -437,13 +365,13 @@ printf ("Current input: %s\n", audio.name); <programlisting> &v4l2-audio; audio; -memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */ +memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */ audio.index = 0; -if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &audio)) { - perror ("VIDIOC_S_AUDIO"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-S-AUDIO;, &audio)) { + perror("VIDIOC_S_AUDIO"); + exit(EXIT_FAILURE); } </programlisting> </example> @@ -468,7 +396,7 @@ the tuner.</para> video inputs.</para> <para>To query and change tuner properties applications use the -&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The +&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctls, respectively. The &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also contains signal status information applicable when the tuner of the current video or radio input is queried. Note that @@ -533,7 +461,7 @@ standards or variations of standards. Each video input and output may support another set of standards. This set is reported by the <structfield>std</structfield> field of &v4l2-input; and &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and -&VIDIOC-ENUMOUTPUT; ioctl, respectively.</para> +&VIDIOC-ENUMOUTPUT; ioctls, respectively.</para> <para>V4L2 defines one bit for each analog video standard currently in use worldwide, and sets aside bits for driver defined @@ -564,28 +492,10 @@ automatically.</para> <para>To query and select the standard used by the current video input or output applications call the &VIDIOC-G-STD; and &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis> -standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote> - <para>An alternative to the current scheme is to use pointers -to indices as arguments of <constant>VIDIOC_G_STD</constant> and -<constant>VIDIOC_S_STD</constant>, the &v4l2-input; and -&v4l2-output; <structfield>std</structfield> field would be a set of -indices like <structfield>audioset</structfield>.</para> - <para>Indices are consistent with the rest of the API -and identify the standard unambiguously. In the present scheme of -things an enumerated standard is looked up by &v4l2-std-id;. Now the -standards supported by the inputs of a device can overlap. Just -assume the tuner and composite input in the example above both -exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests -a choice which does not exist. We cannot merge or omit sets, because -applications would be unable to find the standards reported by -<constant>VIDIOC_G_STD</constant>. That leaves separate enumerations -for each input. Also selecting a standard by &v4l2-std-id; can be -ambiguous. Advantage of this method is that applications need not -identify the standard indirectly, after enumerating.</para><para>So in -summary, the lookup itself is unavoidable. The difference is only -whether the lookup is necessary to find an enumerated standard or to -switch to a standard by &v4l2-std-id;.</para> - </footnote> Drivers must implement all video standard ioctls +standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the +parameter of all these ioctls is a pointer to a &v4l2-std-id; type +(a standard set), <emphasis>not</emphasis> an index into the standard +enumeration. Drivers must implement all video standard ioctls when the device has one or more video inputs or outputs.</para> <para>Special rules apply to devices such as USB cameras where the notion of video @@ -604,17 +514,10 @@ to zero and the <constant>VIDIOC_G_STD</constant>, <constant>VIDIOC_S_STD</constant>, <constant>VIDIOC_QUERYSTD</constant> and <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the -&ENOTTY;.<footnote> - <para>See <xref linkend="buffer" /> for a rationale.</para> +&ENOTTY; or the &EINVAL;.</para> <para>Applications can make use of the <xref linkend="input-capabilities" /> and <xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls -are available for the device.</para> - - <para>See <xref linkend="buffer" /> for a rationale. Probably -even USB cameras follow some well known video standard. It might have -been better to explicitly indicate elsewhere if a device cannot live -up to normal expectations, instead of this exception.</para> - </footnote></para> +can be used with the given input or output.</para> <example> <title>Information about the current video standard</title> @@ -623,22 +526,22 @@ up to normal expectations, instead of this exception.</para> &v4l2-std-id; std_id; &v4l2-standard; standard; -if (-1 == ioctl (fd, &VIDIOC-G-STD;, &std_id)) { +if (-1 == ioctl(fd, &VIDIOC-G-STD;, &std_id)) { /* Note when VIDIOC_ENUMSTD always returns ENOTTY this is no video device or it falls under the USB exception, and VIDIOC_G_STD returning ENOTTY is no error. */ - perror ("VIDIOC_G_STD"); - exit (EXIT_FAILURE); + perror("VIDIOC_G_STD"); + exit(EXIT_FAILURE); } -memset (&standard, 0, sizeof (standard)); +memset(&standard, 0, sizeof(standard)); standard.index = 0; -while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { +while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &standard)) { if (standard.id & std_id) { - printf ("Current video standard: %s\n", standard.name); - exit (EXIT_SUCCESS); + printf("Current video standard: %s\n", standard.name); + exit(EXIT_SUCCESS); } standard.index++; @@ -648,8 +551,8 @@ while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { empty unless this device falls under the USB exception. */ if (errno == EINVAL || standard.index == 0) { - perror ("VIDIOC_ENUMSTD"); - exit (EXIT_FAILURE); + perror("VIDIOC_ENUMSTD"); + exit(EXIT_FAILURE); } </programlisting> </example> @@ -662,26 +565,26 @@ input</title> &v4l2-input; input; &v4l2-standard; standard; -memset (&input, 0, sizeof (input)); +memset(&input, 0, sizeof(input)); -if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) { - perror ("VIDIOC_G_INPUT"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &input.index)) { + perror("VIDIOC_G_INPUT"); + exit(EXIT_FAILURE); } -if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { - perror ("VIDIOC_ENUM_INPUT"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { + perror("VIDIOC_ENUM_INPUT"); + exit(EXIT_FAILURE); } -printf ("Current input %s supports:\n", input.name); +printf("Current input %s supports:\n", input.name); -memset (&standard, 0, sizeof (standard)); +memset(&standard, 0, sizeof(standard)); standard.index = 0; -while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { +while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &standard)) { if (standard.id & input.std) - printf ("%s\n", standard.name); + printf("%s\n", standard.name); standard.index++; } @@ -690,8 +593,8 @@ while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { empty unless this device falls under the USB exception. */ if (errno != EINVAL || standard.index == 0) { - perror ("VIDIOC_ENUMSTD"); - exit (EXIT_FAILURE); + perror("VIDIOC_ENUMSTD"); + exit(EXIT_FAILURE); } </programlisting> </example> @@ -703,21 +606,21 @@ if (errno != EINVAL || standard.index == 0) { &v4l2-input; input; &v4l2-std-id; std_id; -memset (&input, 0, sizeof (input)); +memset(&input, 0, sizeof(input)); -if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) { - perror ("VIDIOC_G_INPUT"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &input.index)) { + perror("VIDIOC_G_INPUT"); + exit(EXIT_FAILURE); } -if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { - perror ("VIDIOC_ENUM_INPUT"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { + perror("VIDIOC_ENUM_INPUT"); + exit(EXIT_FAILURE); } if (0 == (input.std & V4L2_STD_PAL_BG)) { - fprintf (stderr, "Oops. B/G PAL is not supported.\n"); - exit (EXIT_FAILURE); + fprintf(stderr, "Oops. B/G PAL is not supported.\n"); + exit(EXIT_FAILURE); } /* Note this is also supposed to work when only B @@ -725,9 +628,9 @@ if (0 == (input.std & V4L2_STD_PAL_BG)) { std_id = V4L2_STD_PAL_BG; -if (-1 == ioctl (fd, &VIDIOC-S-STD;, &std_id)) { - perror ("VIDIOC_S_STD"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, &VIDIOC-S-STD;, &std_id)) { + perror("VIDIOC_S_STD"); + exit(EXIT_FAILURE); } </programlisting> </example> @@ -740,26 +643,25 @@ corresponding video timings. Today there are many more different hardware interf such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry video signals and there is a need to extend the API to select the video timings for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to -the limited bits available, a new set of IOCTLs was added to set/get video timings at -the input and output: </para><itemizedlist> - <listitem> - <para>DV Timings: This will allow applications to define detailed -video timings for the interface. This includes parameters such as width, height, -polarities, frontporch, backporch etc. The <filename>linux/v4l2-dv-timings.h</filename> +the limited bits available, a new set of ioctls was added to set/get video timings at +the input and output.</para> + + <para>These ioctls deal with the detailed digital video timings that define +each video format. This includes parameters such as the active video width and height, +signal polarities, frontporches, backporches, sync widths etc. The <filename>linux/v4l2-dv-timings.h</filename> header can be used to get the timings of the formats in the <xref linkend="cea861" /> and <xref linkend="vesadmt" /> standards. </para> - </listitem> - </itemizedlist> - <para>To enumerate and query the attributes of the DV timings supported by a device, + + <para>To enumerate and query the attributes of the DV timings supported by a device applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls. - To set DV timings for the device, applications use the + To set DV timings for the device applications use the &VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the &VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para> <para>Applications can make use of the <xref linkend="input-capabilities" /> and -<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the -video timings for the device.</para> +<xref linkend="output-capabilities"/> flags to determine whether the digital video ioctls +can be used with the given input or output.</para> </section> &sub-controls; diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 86c6dd2f6b8..eee6f0f4aa4 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2535,6 +2535,16 @@ fields changed from _s32 to _u32. </orderedlist> </section> + <section> + <title>V4L2 in Linux 3.15</title> + <orderedlist> + <listitem> + <para>Added Software Defined Radio (SDR) Interface. + </para> + </listitem> + </orderedlist> + </section> + <section id="other"> <title>Relation of V4L2 to other Linux multimedia APIs</title> @@ -2651,6 +2661,9 @@ ioctls.</para> <listitem> <para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para> </listitem> + <listitem> + <para>Software Defined Radio (SDR) Interface, <xref linkend="sdr" />.</para> + </listitem> </itemizedlist> </section> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index a5a3188e5af..47198eef75a 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -2258,6 +2258,26 @@ Applicable to the MPEG1, MPEG2, MPEG4 encoders.</entry> VBV buffer control.</entry> </row> + <row><entry></entry></row> + <row id="v4l2-mpeg-video-hor-search-range"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Horizontal search range defines maximum horizontal search area in pixels +to search and match for the present Macroblock (MB) in the reference picture. This V4L2 control macro is used to set +horizontal search range for motion estimation module in video encoder.</entry> + </row> + + <row><entry></entry></row> + <row id="v4l2-mpeg-video-vert-search-range"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Vertical search range defines maximum vertical search area in pixels +to search and match for the present Macroblock (MB) in the reference picture. This V4L2 control macro is used to set +vertical search range for motion estimation module in video encoder.</entry> + </row> + <row><entry></entry></row> <row> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE</constant> </entry> @@ -4370,6 +4390,24 @@ interface and may change in the future.</para> <entry>The flash controller has detected a short or open circuit condition on the indicator LED.</entry> </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_UNDER_VOLTAGE</constant></entry> + <entry>Flash controller voltage to the flash LED + has been below the minimum limit specific to the flash + controller.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_INPUT_VOLTAGE</constant></entry> + <entry>The input voltage of the flash controller is below + the limit under which strobing the flash at full current + will not be possible.The condition persists until this flag + is no longer set.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE</constant></entry> + <entry>The temperature of the LED has exceeded its + allowed upper limit.</entry> + </row> </tbody> </entrytbl> </row> @@ -4971,4 +5009,142 @@ defines possible values for de-emphasis. Here they are:</entry> </table> </section> + + <section id="rf-tuner-controls"> + <title>RF Tuner Control Reference</title> + + <para> +The RF Tuner (RF_TUNER) class includes controls for common features of devices +having RF tuner. + </para> + <para> +In this context, RF tuner is radio receiver circuit between antenna and +demodulator. It receives radio frequency (RF) from the antenna and converts that +received signal to lower intermediate frequency (IF) or baseband frequency (BB). +Tuners that could do baseband output are often called Zero-IF tuners. Older +tuners were typically simple PLL tuners inside a metal box, whilst newer ones +are highly integrated chips without a metal box "silicon tuners". These controls +are mostly applicable for new feature rich silicon tuners, just because older +tuners does not have much adjustable features. + </para> + <para> +For more information about RF tuners see +<ulink url="http://en.wikipedia.org/wiki/Tuner_%28radio%29">Tuner (radio)</ulink> +and +<ulink url="http://en.wikipedia.org/wiki/RF_front_end">RF front end</ulink> +from Wikipedia. + </para> + + <table pgwide="1" frame="none" id="rf-tuner-control-id"> + <title>RF_TUNER Control IDs</title> + + <tgroup cols="4"> + <colspec colname="c1" colwidth="1*" /> + <colspec colname="c2" colwidth="6*" /> + <colspec colname="c3" colwidth="2*" /> + <colspec colname="c4" colwidth="6*" /> + <spanspec namest="c1" nameend="c2" spanname="id" /> + <spanspec namest="c2" nameend="c4" spanname="descr" /> + <thead> + <row> + <entry spanname="id" align="left">ID</entry> + <entry align="left">Type</entry> + </row> + <row rowsep="1"> + <entry spanname="descr" align="left">Description</entry> + </row> + </thead> + <tbody valign="top"> + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_CLASS</constant> </entry> + <entry>class</entry> + </row><row><entry spanname="descr">The RF_TUNER class +descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a +description of this control class.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_BANDWIDTH_AUTO</constant> </entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Enables/disables tuner radio channel +bandwidth configuration. In automatic mode bandwidth configuration is performed +by the driver.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_BANDWIDTH</constant> </entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Filter(s) on tuner signal path are used to +filter signal according to receiving party needs. Driver configures filters to +fulfill desired bandwidth requirement. Used when V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not +set. Unit is in Hz. The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant> </entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Enables/disables LNA automatic gain control (AGC)</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO</constant> </entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Enables/disables mixer automatic gain control (AGC)</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_IF_GAIN_AUTO</constant> </entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Enables/disables IF automatic gain control (AGC)</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN</constant> </entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">LNA (low noise amplifier) gain is first +gain stage on the RF tuner signal path. It is located very close to tuner +antenna input. Used when <constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant> is not set. +The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_MIXER_GAIN</constant> </entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Mixer gain is second gain stage on the RF +tuner signal path. It is located inside mixer block, where RF signal is +down-converted by the mixer. Used when <constant>V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO</constant> +is not set. The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_IF_GAIN</constant> </entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">IF gain is last gain stage on the RF tuner +signal path. It is located on output of RF tuner. It controls signal level of +intermediate frequency output or baseband output. Used when +<constant>V4L2_CID_RF_TUNER_IF_GAIN_AUTO</constant> is not set. The range and step are +driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_PLL_LOCK</constant> </entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Is synthesizer PLL locked? RF tuner is +receiving given frequency when that control is set. This is a read-only control. +</entry> + </row> + </tbody> + </tgroup> + </table> + </section> </section> diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml index dd91d6134e8..54853329140 100644 --- a/Documentation/DocBook/media/v4l/dev-osd.xml +++ b/Documentation/DocBook/media/v4l/dev-osd.xml @@ -56,18 +56,18 @@ framebuffer device.</para> unsigned int i; int fb_fd; -if (-1 == ioctl (fd, VIDIOC_G_FBUF, &fbuf)) { - perror ("VIDIOC_G_FBUF"); - exit (EXIT_FAILURE); +if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) { + perror("VIDIOC_G_FBUF"); + exit(EXIT_FAILURE); } -for (i = 0; i > 30; ++i) { +for (i = 0; i < 30; i++) { char dev_name[16]; struct fb_fix_screeninfo si; - snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i); + snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i); - fb_fd = open (dev_name, O_RDWR); + fb_fd = open(dev_name, O_RDWR); if (-1 == fb_fd) { switch (errno) { case ENOENT: /* no such file */ @@ -75,19 +75,19 @@ for (i = 0; i > 30; ++i) { continue; default: - perror ("open"); - exit (EXIT_FAILURE); + perror("open"); + exit(EXIT_FAILURE); } } - if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &si)) { - if (si.smem_start == (unsigned long) fbuf.base) + if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) { + if (si.smem_start == (unsigned long)fbuf.base) break; } else { /* Apparently not a framebuffer device. */ } - close (fb_fd); + close(fb_fd); fb_fd = -1; } diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml new file mode 100644 index 00000000000..dc14804f543 --- /dev/null +++ b/Documentation/DocBook/media/v4l/dev-sdr.xml @@ -0,0 +1,110 @@ + <title>Software Defined Radio Interface (SDR)</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental"> experimental </link> + interface and may change in the future.</para> + </note> + + <para> +SDR is an abbreviation of Software Defined Radio, the radio device +which uses application software for modulation or demodulation. This interface +is intended for controlling and data streaming of such devices. + </para> + + <para> +SDR devices are accessed through character device special files named +<filename>/dev/swradio0</filename> to <filename>/dev/swradio255</filename> +with major number 81 and dynamically allocated minor numbers 0 to 255. + </para> + + <section> + <title>Querying Capabilities</title> + + <para> +Devices supporting the SDR receiver interface set the +<constant>V4L2_CAP_SDR_CAPTURE</constant> and +<constant>V4L2_CAP_TUNER</constant> flag in the +<structfield>capabilities</structfield> field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an +Analog to Digital Converter (ADC), which is a mandatory element for the SDR receiver. +At least one of the read/write, streaming or asynchronous I/O methods must +be supported. + </para> + </section> + + <section> + <title>Supplemental Functions</title> + + <para> +SDR devices can support <link linkend="control">controls</link>, and must +support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used +for setting the ADC sampling rate (sampling frequency) and the possible RF tuner +frequency. + </para> + + <para> +The <constant>V4L2_TUNER_ADC</constant> tuner type is used for ADC tuners, and +the <constant>V4L2_TUNER_RF</constant> tuner type is used for RF tuners. The +tuner index of the RF tuner (if any) must always follow the ADC tuner index. +Normally the ADC tuner is #0 and the RF tuner is #1. + </para> + + <para> +The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported. + </para> + </section> + + <section> + <title>Data Format Negotiation</title> + + <para> +The SDR capture device uses the <link linkend="format">format</link> ioctls to +select the capture format. Both the sampling resolution and the data streaming +format are bound to that selectable format. In addition to the basic +<link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl +must be supported as well. + </para> + + <para> +To use the <link linkend="format">format</link> ioctls applications set the +<structfield>type</structfield> field of a &v4l2-format; to +<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-sdr-format; +<structfield>sdr</structfield> member of the <structfield>fmt</structfield> +union as needed per the desired operation. +Currently only the <structfield>pixelformat</structfield> field of +&v4l2-sdr-format; is used. The content of that field is the V4L2 fourcc code +of the data format. + </para> + + <table pgwide="1" frame="none" id="v4l2-sdr-format"> + <title>struct <structname>v4l2_sdr_format</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>pixelformat</structfield></entry> + <entry> +The data format or type of compression, set by the application. This is a +little endian <link linkend="v4l2-fourcc">four character code</link>. +V4L2 defines SDR formats in <xref linkend="sdr-formats" />. + </entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>reserved[28]</structfield></entry> + <entry>This array is reserved for future extensions. +Drivers and applications must set it to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> +An SDR device may support <link linkend="rw">read/write</link> +and/or streaming (<link linkend="mmap">memory mapping</link> +or <link linkend="userp">user pointer</link>) I/O. + </para> + + </section> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 2c4c068dde8..97a69bf6f3e 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -339,8 +339,8 @@ returns immediately with an &EAGAIN; when no buffer is available. The queues as a side effect. Since there is no notion of doing anything "now" on a multitasking system, if an application needs to synchronize with another event it should examine the &v4l2-buffer; -<structfield>timestamp</structfield> of captured buffers, or set the -field before enqueuing buffers for output.</para> +<structfield>timestamp</structfield> of captured or outputted buffers. +</para> <para>Drivers implementing memory mapping I/O must support the <constant>VIDIOC_REQBUFS</constant>, @@ -457,7 +457,7 @@ queues and unlocks all buffers as a side effect. Since there is no notion of doing anything "now" on a multitasking system, if an application needs to synchronize with another event it should examine the &v4l2-buffer; <structfield>timestamp</structfield> of captured -buffers, or set the field before enqueuing buffers for output.</para> +or outputted buffers.</para> <para>Drivers implementing user pointer I/O must support the <constant>VIDIOC_REQBUFS</constant>, @@ -620,8 +620,7 @@ returns immediately with an &EAGAIN; when no buffer is available. The unlocks all buffers as a side effect. Since there is no notion of doing anything "now" on a multitasking system, if an application needs to synchronize with another event it should examine the &v4l2-buffer; -<structfield>timestamp</structfield> of captured buffers, or set the field -before enqueuing buffers for output.</para> +<structfield>timestamp</structfield> of captured or outputted buffers.</para> <para>Drivers implementing DMABUF importing I/O must support the <constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>, @@ -654,38 +653,19 @@ plane, are stored in struct <structname>v4l2_plane</structname> instead. In that case, struct <structname>v4l2_buffer</structname> contains an array of plane structures.</para> - <para>Nominally timestamps refer to the first data byte transmitted. -In practice however the wide range of hardware covered by the V4L2 API -limits timestamp accuracy. Often an interrupt routine will -sample the system clock shortly after the field or frame was stored -completely in memory. So applications must expect a constant -difference up to one field or frame period plus a small (few scan -lines) random error. The delay and error can be much -larger due to compression or transmission over an external bus when -the frames are not properly stamped by the sender. This is frequently -the case with USB cameras. Here timestamps refer to the instant the -field or frame was received by the driver, not the capture time. These -devices identify by not enumerating any video standards, see <xref -linkend="standard" />.</para> - - <para>Similar limitations apply to output timestamps. Typically -the video hardware locks to a clock controlling the video timing, the -horizontal and vertical synchronization pulses. At some point in the -line sequence, possibly the vertical blanking, an interrupt routine -samples the system clock, compares against the timestamp and programs -the hardware to repeat the previous field or frame, or to display the -buffer contents.</para> - - <para>Apart of limitations of the video device and natural -inaccuracies of all clocks, it should be noted system time itself is -not perfectly stable. It can be affected by power saving cycles, -warped to insert leap seconds, or even turned back or forth by the -system administrator affecting long term measurements. <footnote> - <para>Since no other Linux multimedia -API supports unadjusted time it would be foolish to introduce here. We -must use a universally supported clock to synchronize different media, -hence time of day.</para> - </footnote></para> + <para>Dequeued video buffers come with timestamps. The driver + decides at which part of the frame and with which clock the + timestamp is taken. Please see flags in the masks + <constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and + <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref + linkend="buffer-flags" />. These flags are always valid and constant + across all buffers during the whole video stream. Changes in these + flags may take place as a side effect of &VIDIOC-S-INPUT; or + &VIDIOC-S-OUTPUT; however. The + <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> timestamp type + which is used by e.g. on mem-to-mem devices is an exception to the + rule: the timestamp source flags are copied from the OUTPUT video + buffer to the CAPTURE video buffer.</para> <table frame="none" pgwide="1" id="v4l2-buffer"> <title>struct <structname>v4l2_buffer</structname></title> @@ -696,10 +676,11 @@ hence time of day.</para> <entry>__u32</entry> <entry><structfield>index</structfield></entry> <entry></entry> - <entry>Number of the buffer, set by the application. This -field is only used for <link linkend="mmap">memory mapping</link> I/O -and can range from zero to the number of buffers allocated -with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry> + <entry>Number of the buffer, set by the application except +when calling &VIDIOC-DQBUF;, then it is set by the driver. +This field can range from zero to the number of buffers allocated +with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>), +plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry> </row> <row> <entry>__u32</entry> @@ -718,7 +699,7 @@ linkend="v4l2-buf-type" /></entry> buffer. It depends on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when <structfield>type</structfield> -refers to an input stream, applications when an output stream.</entry> +refers to an input stream, applications when it refers to an output stream.</entry> </row> <row> <entry>__u32</entry> @@ -735,7 +716,7 @@ linkend="buffer-flags" />.</entry> buffer, see <xref linkend="v4l2-field" />. This field is not used when the buffer contains VBI data. Drivers must set it when <structfield>type</structfield> refers to an input stream, -applications when an output stream.</entry> +applications when it refers to an output stream.</entry> </row> <row> <entry>struct timeval</entry> @@ -745,15 +726,13 @@ applications when an output stream.</entry> byte was captured, as returned by the <function>clock_gettime()</function> function for the relevant clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in - <xref linkend="buffer-flags" />. For output streams the data - will not be displayed before this time, secondary to the nominal - frame rate determined by the current video standard in enqueued - order. Applications can for example zero this field to display - frames as soon as possible. The driver stores the time at which - the first data byte was actually sent out in the - <structfield>timestamp</structfield> field. This permits + <xref linkend="buffer-flags" />. For output streams the driver + stores the time at which the last data byte was actually sent out + in the <structfield>timestamp</structfield> field. This permits applications to monitor the drift between the video and system - clock.</para></entry> + clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> + the application has to fill in the timestamp which will be copied + by the driver to the capture stream.</para></entry> </row> <row> <entry>&v4l2-timecode;</entry> @@ -846,7 +825,8 @@ is the file descriptor associated with a DMABUF buffer.</entry> <entry><structfield>length</structfield></entry> <entry></entry> <entry>Size of the buffer (not the payload) in bytes for the - single-planar API. For the multi-planar API the application sets + single-planar API. This is set by the driver based on the calls to + &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets this to the number of elements in the <structfield>planes</structfield> array. The driver will fill in the actual number of valid elements in that array. @@ -880,13 +860,15 @@ should set this to 0.</entry> <entry><structfield>bytesused</structfield></entry> <entry></entry> <entry>The number of bytes occupied by data in the plane - (its payload).</entry> + (its payload). Drivers must set this field when <structfield>type</structfield> + refers to an input stream, applications when it refers to an output stream.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>length</structfield></entry> <entry></entry> - <entry>Size in bytes of the plane (not its payload).</entry> + <entry>Size in bytes of the plane (not its payload). This is set by the driver + based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry> </row> <row> <entry>union</entry> @@ -925,7 +907,9 @@ should set this to 0.</entry> <entry>__u32</entry> <entry><structfield>data_offset</structfield></entry> <entry></entry> - <entry>Offset in bytes to video data in the plane, if applicable. + <entry>Offset in bytes to video data in the plane. + Drivers must set this field when <structfield>type</structfield> + refers to an input stream, applications when it refers to an output stream. </entry> </row> <row> @@ -1005,6 +989,12 @@ should set this to 0.</entry> <entry>Buffer for video output overlay (OSD), see <xref linkend="osd" />.</entry> </row> + <row> + <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry> + <entry>11</entry> + <entry>Buffer for Software Defined Radio (SDR), see <xref + linkend="sdr" />.</entry> + </row> </tbody> </tgroup> </table> @@ -1016,7 +1006,7 @@ should set this to 0.</entry> <tbody valign="top"> <row> <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> - <entry>0x0001</entry> + <entry>0x00000001</entry> <entry>The buffer resides in device memory and has been mapped into the application's address space, see <xref linkend="mmap" /> for details. Drivers set or clear this flag when the @@ -1026,7 +1016,7 @@ Drivers set or clear this flag when the </row> <row> <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> - <entry>0x0002</entry> + <entry>0x00000002</entry> <entry>Internally drivers maintain two buffer queues, an incoming and outgoing queue. When this flag is set, the buffer is currently on the incoming queue. It automatically moves to the @@ -1039,7 +1029,7 @@ cleared.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> - <entry>0x0004</entry> + <entry>0x00000004</entry> <entry>When this flag is set, the buffer is currently on the outgoing queue, ready to be dequeued from the driver. Drivers set or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl @@ -1049,11 +1039,11 @@ buffer cannot be on both queues at the same time, the <constant>V4L2_BUF_FLAG_QUEUED</constant> and <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. They can be both cleared however, then the buffer is in "dequeued" -state, in the application domain to say so.</entry> +state, in the application domain so to say.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry> - <entry>0x0040</entry> + <entry>0x00000040</entry> <entry>When this flag is set, the buffer has been dequeued successfully, although the data might have been corrupted. This is recoverable, streaming may continue as normal and @@ -1063,35 +1053,43 @@ state, in the application domain to say so.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> - <entry>0x0008</entry> + <entry>0x00000008</entry> <entry>Drivers set or clear this flag when calling the <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video capture devices when the buffer contains a compressed image which is a -key frame (or field), &ie; can be decompressed on its own.</entry> +key frame (or field), &ie; can be decompressed on its own. Also know as +an I-frame. Applications can set this bit when <structfield>type</structfield> +refers to an output stream.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry> - <entry>0x0010</entry> + <entry>0x00000010</entry> <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> this flags predicted frames or fields which contain only differences to a -previous key frame.</entry> +previous key frame. Applications can set this bit when <structfield>type</structfield> +refers to an output stream.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry> - <entry>0x0020</entry> - <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant> - this is a bidirectional predicted frame or field. [ooc tbd]</entry> + <entry>0x00000020</entry> + <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> +this flags a bi-directional predicted frame or field which contains only +the differences between the current frame and both the preceding and following +key frames to specify its content. Applications can set this bit when +<structfield>type</structfield> refers to an output stream.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry> - <entry>0x0100</entry> + <entry>0x00000100</entry> <entry>The <structfield>timecode</structfield> field is valid. Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> -ioctl is called.</entry> +ioctl is called. Applications can set this bit and the corresponding +<structfield>timecode</structfield> structure when <structfield>type</structfield> +refers to an output stream.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> - <entry>0x0400</entry> + <entry>0x00000400</entry> <entry>The buffer has been prepared for I/O and can be queued by the application. Drivers set or clear this flag when the <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link @@ -1101,7 +1099,7 @@ application. Drivers set or clear this flag when the </row> <row> <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> - <entry>0x0800</entry> + <entry>0x00000800</entry> <entry>Caches do not have to be invalidated for this buffer. Typically applications shall use this flag if the data captured in the buffer is not going to be touched by the CPU, instead the buffer will, probably, be @@ -1110,7 +1108,7 @@ passed on to a DMA-capable hardware unit for further processing or output. </row> <row> <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> - <entry>0x1000</entry> + <entry>0x00001000</entry> <entry>Caches do not have to be cleaned for this buffer. Typically applications shall use this flag for output buffers if the data in this buffer has not been created by the CPU but by some DMA-capable unit, @@ -1118,7 +1116,7 @@ in which case caches have not been used.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry> - <entry>0xe000</entry> + <entry>0x0000e000</entry> <entry>Mask for timestamp types below. To test the timestamp type, mask out bits not belonging to timestamp type by performing a logical and operation with buffer @@ -1126,7 +1124,7 @@ in which case caches have not been used.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry> - <entry>0x0000</entry> + <entry>0x00000000</entry> <entry>Unknown timestamp type. This type is used by drivers before Linux 3.9 and may be either monotonic (see below) or realtime (wall clock). Monotonic clock has been @@ -1139,7 +1137,7 @@ in which case caches have not been used.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry> - <entry>0x2000</entry> + <entry>0x00002000</entry> <entry>The buffer timestamp has been taken from the <constant>CLOCK_MONOTONIC</constant> clock. To access the same clock outside V4L2, use @@ -1147,10 +1145,42 @@ in which case caches have not been used.</entry> </row> <row> <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry> - <entry>0x4000</entry> + <entry>0x00004000</entry> <entry>The CAPTURE buffer timestamp has been taken from the corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry> </row> + <row> + <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry> + <entry>0x00070000</entry> + <entry>Mask for timestamp sources below. The timestamp source + defines the point of time the timestamp is taken in relation to + the frame. Logical 'and' operation between the + <structfield>flags</structfield> field and + <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the + value of the timestamp source. Applications must set the timestamp + source when <structfield>type</structfield> refers to an output stream + and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry> + </row> + <row> + <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry> + <entry>0x00000000</entry> + <entry>End Of Frame. The buffer timestamp has been taken + when the last pixel of the frame has been received or the + last pixel of the frame has been transmitted. In practice, + software generated timestamps will typically be read from + the clock a small amount of time after the last pixel has + been received or transmitten, depending on the system and + other activity in it.</entry> + </row> + <row> + <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry> + <entry>0x00010000</entry> + <entry>Start Of Exposure. The buffer timestamp has been + taken when the exposure of the frame has begun. This is + only valid for the + <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer + type.</entry> + </row> </tbody> </tgroup> </table> @@ -1440,10 +1470,9 @@ or application, depending on data direction, must set &v4l2-buffer; <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair to build a frame. If fields are successive, without any dropped fields between them (fields can drop individually), can be determined from -the &v4l2-buffer; <structfield>sequence</structfield> field. Image -sizes refer to the frame, not fields. This format cannot be selected -when using the read/write I/O method.<!-- Where it's indistinguishable -from V4L2_FIELD_SEQ_*. --></entry> +the &v4l2-buffer; <structfield>sequence</structfield> field. This format +cannot be selected when using the read/write I/O method since there +is no way to communicate if a field was a top or bottom field.</entry> </row> <row> <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml index c51d5a4cda0..fb2b5e35d66 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml @@ -12,18 +12,17 @@ <refsect1> <title>Description</title> - <para>This is a multi-planar, two-plane version of the YUV 4:2:0 format. + <para>This is a multi-planar, two-plane version of the YUV 4:2:2 format. The three components are separated into two sub-images or planes. <constant>V4L2_PIX_FMT_NV16M</constant> differs from <constant>V4L2_PIX_FMT_NV16 </constant> in that the two planes are non-contiguous in memory, i.e. the chroma -plane does not necessarily immediately follows the luma plane. +plane does not necessarily immediately follow the luma plane. The luminance data occupies the first plane. The Y plane has one byte per pixel. In the second plane there is chrominance data with alternating chroma samples. The CbCr plane is the same width and height, in bytes, as the Y plane. -Each CbCr pair belongs to four pixels. For example, +Each CbCr pair belongs to two pixels. For example, Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to -Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, -Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. +Y'<subscript>00</subscript>, Y'<subscript>01</subscript>. <constant>V4L2_PIX_FMT_NV61M</constant> is the same as <constant>V4L2_PIX_FMT_NV16M</constant> except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml index 166c8d65e4f..e1c4f8b4c0b 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml @@ -121,14 +121,14 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry> <entry>'RGB1'</entry> <entry></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> <entry>r<subscript>2</subscript></entry> <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> </row> <row id="V4L2-PIX-FMT-RGB444"> <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> @@ -159,18 +159,18 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>g<subscript>2</subscript></entry> <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>a</entry> <entry>b<subscript>4</subscript></entry> <entry>b<subscript>3</subscript></entry> <entry>b<subscript>2</subscript></entry> <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>a</entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> @@ -181,17 +181,17 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>g<subscript>2</subscript></entry> <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> <entry>b<subscript>4</subscript></entry> <entry>b<subscript>3</subscript></entry> <entry>b<subscript>2</subscript></entry> <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> <entry>g<subscript>5</subscript></entry> <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> @@ -201,32 +201,32 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>'RGBQ'</entry> <entry></entry> <entry>a</entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> <entry>r<subscript>4</subscript></entry> <entry>r<subscript>3</subscript></entry> <entry>r<subscript>2</subscript></entry> <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-RGB565X"> - <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> - <entry>'RGBR'</entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> <entry>b<subscript>4</subscript></entry> <entry>b<subscript>3</subscript></entry> <entry>b<subscript>2</subscript></entry> <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> + </row> + <row id="V4L2-PIX-FMT-RGB565X"> + <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> + <entry>'RGBR'</entry> + <entry></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> <entry>g<subscript>5</subscript></entry> <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> @@ -234,11 +234,11 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>g<subscript>2</subscript></entry> <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> </row> <row id="V4L2-PIX-FMT-BGR666"> <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry> @@ -385,6 +385,15 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> <entry>'RGB4'</entry> <entry></entry> + <entry>a<subscript>7</subscript></entry> + <entry>a<subscript>6</subscript></entry> + <entry>a<subscript>5</subscript></entry> + <entry>a<subscript>4</subscript></entry> + <entry>a<subscript>3</subscript></entry> + <entry>a<subscript>2</subscript></entry> + <entry>a<subscript>1</subscript></entry> + <entry>a<subscript>0</subscript></entry> + <entry></entry> <entry>r<subscript>7</subscript></entry> <entry>r<subscript>6</subscript></entry> <entry>r<subscript>5</subscript></entry> @@ -411,25 +420,16 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>b<subscript>2</subscript></entry> <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> </row> </tbody> </tgroup> </table> - <para>Bit 7 is the most significant bit. The value of a = alpha + <para>Bit 7 is the most significant bit. The value of the a = alpha bits is undefined when reading from the driver, ignored when writing to the driver, except when alpha blending has been negotiated for a <link linkend="overlay">Video Overlay</link> or <link linkend="osd"> -Video Output Overlay</link> or when alpha component has been configured +Video Output Overlay</link> or when the alpha component has been configured for a <link linkend="capture">Video Capture</link> by means of <link linkend="v4l2-alpha-component"> <constant>V4L2_CID_ALPHA_COMPONENT </constant> </link> control.</para> @@ -512,421 +512,6 @@ image</title> </formalpara> </example> - <important> - <para>Drivers may interpret these formats differently.</para> - </important> - - <para>Some RGB formats above are uncommon and were probably -defined in error. Drivers may interpret them as in <xref - linkend="rgb-formats-corrected" />.</para> - - <table pgwide="1" frame="none" id="rgb-formats-corrected"> - <title>Packed RGB Image Formats (corrected)</title> - <tgroup cols="37" align="center"> - <colspec colname="id" align="left" /> - <colspec colname="fourcc" /> - <colspec colname="bit" /> - - <colspec colnum="4" colname="b07" align="center" /> - <colspec colnum="5" colname="b06" align="center" /> - <colspec colnum="6" colname="b05" align="center" /> - <colspec colnum="7" colname="b04" align="center" /> - <colspec colnum="8" colname="b03" align="center" /> - <colspec colnum="9" colname="b02" align="center" /> - <colspec colnum="10" colname="b01" align="center" /> - <colspec colnum="11" colname="b00" align="center" /> - - <colspec colnum="13" colname="b17" align="center" /> - <colspec colnum="14" colname="b16" align="center" /> - <colspec colnum="15" colname="b15" align="center" /> - <colspec colnum="16" colname="b14" align="center" /> - <colspec colnum="17" colname="b13" align="center" /> - <colspec colnum="18" colname="b12" align="center" /> - <colspec colnum="19" colname="b11" align="center" /> - <colspec colnum="20" colname="b10" align="center" /> - - <colspec colnum="22" colname="b27" align="center" /> - <colspec colnum="23" colname="b26" align="center" /> - <colspec colnum="24" colname="b25" align="center" /> - <colspec colnum="25" colname="b24" align="center" /> - <colspec colnum="26" colname="b23" align="center" /> - <colspec colnum="27" colname="b22" align="center" /> - <colspec colnum="28" colname="b21" align="center" /> - <colspec colnum="29" colname="b20" align="center" /> - - <colspec colnum="31" colname="b37" align="center" /> - <colspec colnum="32" colname="b36" align="center" /> - <colspec colnum="33" colname="b35" align="center" /> - <colspec colnum="34" colname="b34" align="center" /> - <colspec colnum="35" colname="b33" align="center" /> - <colspec colnum="36" colname="b32" align="center" /> - <colspec colnum="37" colname="b31" align="center" /> - <colspec colnum="38" colname="b30" align="center" /> - - <spanspec namest="b07" nameend="b00" spanname="b0" /> - <spanspec namest="b17" nameend="b10" spanname="b1" /> - <spanspec namest="b27" nameend="b20" spanname="b2" /> - <spanspec namest="b37" nameend="b30" spanname="b3" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry> </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 valign="top"> - <row><!-- id="V4L2-PIX-FMT-RGB332" --> - <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry> - <entry>'RGB1'</entry> - <entry></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-RGB444" --> - <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> - <entry>'R444'</entry> - <entry></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-RGB555" --> - <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> - <entry>'RGBO'</entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>a</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-RGB565" --> - <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry> - <entry>'RGBP'</entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-RGB555X" --> - <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry> - <entry>'RGBQ'</entry> - <entry></entry> - <entry>a</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-RGB565X" --> - <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> - <entry>'RGBR'</entry> - <entry></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-BGR666" --> - <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry> - <entry>'BGRH'</entry> - <entry></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-BGR24" --> - <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> - <entry>'BGR3'</entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-RGB24" --> - <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> - <entry>'RGB3'</entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-BGR32" --> - <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> - <entry>'BGR4'</entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - </row> - <row><!-- id="V4L2-PIX-FMT-RGB32" --> - <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> - <entry>'RGB4'</entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - <para>A test utility to determine which RGB formats a driver actually supports is available from the LinuxTV v4l-dvb repository. See &v4l-dvb; for access instructions.</para> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml new file mode 100644 index 00000000000..2d80104c178 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml @@ -0,0 +1,44 @@ +<refentry id="V4L2-SDR-FMT-CU08"> + <refmeta> + <refentrytitle>V4L2_SDR_FMT_CU8 ('CU08')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname> + <constant>V4L2_SDR_FMT_CU8</constant> + </refname> + <refpurpose>Complex unsigned 8-bit IQ sample</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <para> +This format contains sequence of complex number samples. Each complex number +consist two parts, called In-phase and Quadrature (IQ). Both I and Q are +represented as a 8 bit unsigned number. I value comes first and Q value after +that. + </para> + <example> + <title><constant>V4L2_SDR_FMT_CU8</constant> 1 sample</title> + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="2" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 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-cu16le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml new file mode 100644 index 00000000000..26288ffa907 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml @@ -0,0 +1,46 @@ +<refentry id="V4L2-SDR-FMT-CU16LE"> + <refmeta> + <refentrytitle>V4L2_SDR_FMT_CU16LE ('CU16')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname> + <constant>V4L2_SDR_FMT_CU16LE</constant> + </refname> + <refpurpose>Complex unsigned 16-bit little endian IQ sample</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <para> +This format contains sequence of complex number samples. Each complex number +consist two parts, called In-phase and Quadrature (IQ). Both I and Q are +represented as a 16 bit unsigned little endian number. I value comes first +and Q value after that. + </para> + <example> + <title><constant>V4L2_SDR_FMT_CU16LE</constant> 1 sample</title> + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="3" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>I'<subscript>0[7:0]</subscript></entry> + <entry>I'<subscript>0[15:8]</subscript></entry> + </row> + <row> + <entry>start + 2:</entry> + <entry>Q'<subscript>0[7:0]</subscript></entry> + <entry>Q'<subscript>0[15:8]</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 72d72bd67d0..ea514d6075c 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -25,7 +25,12 @@ capturing and output, for overlay frame buffer formats see also <row> <entry>__u32</entry> <entry><structfield>height</structfield></entry> - <entry>Image height in pixels.</entry> + <entry>Image height in pixels. If <structfield>field</structfield> is + one of <constant>V4L2_FIELD_TOP</constant>, <constant>V4L2_FIELD_BOTTOM</constant> + or <constant>V4L2_FIELD_ALTERNATE</constant> then height refers to the + number of lines in the field, otherwise it refers to the number of + lines in the frame (which is twice the field height for interlaced + formats).</entry> </row> <row> <entry spanname="hspan">Applications set these fields to @@ -54,7 +59,7 @@ linkend="reserved-formats" /></entry> can request to capture or output only the top or bottom field, or both fields interlaced or sequentially stored in one buffer or alternating in separate buffers. Drivers return the actual field order selected. -For details see <xref linkend="field-order" />.</entry> +For more details on fields see <xref linkend="field-order" />.</entry> </row> <row> <entry>__u32</entry> @@ -81,7 +86,10 @@ plane and is divided by the same factor as the example the Cb and Cr planes of a YUV 4:2:0 image have half as many padding bytes following each line as the Y plane. To avoid ambiguities drivers must return a <structfield>bytesperline</structfield> value -rounded up to a multiple of the scale factor.</para></entry> +rounded up to a multiple of the scale factor.</para> +<para>For compressed formats the <structfield>bytesperline</structfield> +value makes no sense. Applications and drivers must set this to 0 in +that case.</para></entry> </row> <row> <entry>__u32</entry> @@ -97,7 +105,8 @@ hold an image.</entry> <entry>&v4l2-colorspace;</entry> <entry><structfield>colorspace</structfield></entry> <entry>This information supplements the -<structfield>pixelformat</structfield> and must be set by the driver, +<structfield>pixelformat</structfield> and must be set by the driver for +capture streams and by the application for output streams, see <xref linkend="colorspaces" />.</entry> </row> <row> @@ -135,7 +144,7 @@ set this field to zero.</entry> <entry>__u16</entry> <entry><structfield>bytesperline</structfield></entry> <entry>Distance in bytes between the leftmost pixels in two adjacent - lines.</entry> + lines. See &v4l2-pix-format;.</entry> </row> <row> <entry>__u16</entry> @@ -154,12 +163,12 @@ set this field to zero.</entry> <row> <entry>__u32</entry> <entry><structfield>width</structfield></entry> - <entry>Image width in pixels.</entry> + <entry>Image width in pixels. See &v4l2-pix-format;.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>height</structfield></entry> - <entry>Image height in pixels.</entry> + <entry>Image height in pixels. See &v4l2-pix-format;.</entry> </row> <row> <entry>__u32</entry> @@ -811,6 +820,17 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see </table> </section> + <section id="sdr-formats"> + <title>SDR Formats</title> + + <para>These formats are used for <link linkend="sdr">SDR Capture</link> +interface only.</para> + + &sub-sdr-cu08; + &sub-sdr-cu16le; + + </section> + <section id="pixfmt-reserved"> <title>Reserved Format Identifiers</title> diff --git a/Documentation/DocBook/media/v4l/remote_controllers.xml b/Documentation/DocBook/media/v4l/remote_controllers.xml index 160e464d44b..5124a6c4daa 100644 --- a/Documentation/DocBook/media/v4l/remote_controllers.xml +++ b/Documentation/DocBook/media/v4l/remote_controllers.xml @@ -1,10 +1,152 @@ +<partinfo> +<authorgroup> +<author> +<firstname>Mauro</firstname> +<surname>Chehab</surname> +<othername role="mi">Carvalho</othername> +<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation> +<contrib>Initial version.</contrib> +</author> +</authorgroup> +<copyright> + <year>2009-2014</year> + <holder>Mauro Carvalho Chehab</holder> +</copyright> + +<revhistory> +<!-- Put document revisions here, newest first. --> +<revision> +<revnumber>3.15</revnumber> +<date>2014-02-06</date> +<authorinitials>mcc</authorinitials> +<revremark>Added the interface description and the RC sysfs class description.</revremark> +</revision> +<revision> +<revnumber>1.0</revnumber> +<date>2009-09-06</date> +<authorinitials>mcc</authorinitials> +<revremark>Initial revision</revremark> +</revision> +</revhistory> +</partinfo> + + <title>Remote Controller API</title> + <chapter id="remote_controllers"> + <title>Remote Controllers</title> + <section id="Remote_controllers_Intro"> <title>Introduction</title> <para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each manufacturer has their own type of control. It is not rare for the same manufacturer to ship different types of controls, depending on the device.</para> +<para>A Remote Controller interface is mapped as a normal evdev/input interface, just like a keyboard or a mouse. +So, it uses all ioctls already defined for any other input devices.</para> +<para>However, remove controllers are more flexible than a normal input device, as the IR +receiver (and/or transmitter) can be used in conjunction with a wide variety of different IR remotes.</para> +<para>In order to allow flexibility, the Remote Controller subsystem allows controlling the +RC-specific attributes via <link linkend="remote_controllers_sysfs_nodes">the sysfs class nodes</link>.</para> +</section> + +<section id="remote_controllers_sysfs_nodes"> +<title>Remote Controller's sysfs nodes</title> +<para>As defined at <constant>Documentation/ABI/testing/sysfs-class-rc</constant>, those are the sysfs nodes that control the Remote Controllers:</para> + +<section id="sys_class_rc"> +<title>/sys/class/rc/</title> +<para>The <constant>/sys/class/rc/</constant> class sub-directory belongs to the Remote Controller +core and provides a sysfs interface for configuring infrared remote controller receivers. +</para> + +</section> +<section id="sys_class_rc_rcN"> +<title>/sys/class/rc/rcN/</title> +<para>A <constant>/sys/class/rc/rcN</constant> directory is created for each remote + control receiver device where N is the number of the receiver.</para> + +</section> +<section id="sys_class_rc_rcN_protocols"> +<title>/sys/class/rc/rcN/protocols</title> +<para>Reading this file returns a list of available protocols, something like:</para> +<para><constant>rc5 [rc6] nec jvc [sony]</constant></para> +<para>Enabled protocols are shown in [] brackets.</para> +<para>Writing "+proto" will add a protocol to the list of enabled protocols.</para> +<para>Writing "-proto" will remove a protocol from the list of enabled protocols.</para> +<para>Writing "proto" will enable only "proto".</para> +<para>Writing "none" will disable all protocols.</para> +<para>Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used.</para> + +</section> +<section id="sys_class_rc_rcN_filter"> +<title>/sys/class/rc/rcN/filter</title> +<para>Sets the scancode filter expected value.</para> +<para>Use in combination with <constant>/sys/class/rc/rcN/filter_mask</constant> to set the +expected value of the bits set in the filter mask. +If the hardware supports it then scancodes which do not match +the filter will be ignored. Otherwise the write will fail with +an error.</para> +<para>This value may be reset to 0 if the current protocol is altered.</para> + +</section> +<section id="sys_class_rc_rcN_filter_mask"> +<title>/sys/class/rc/rcN/filter_mask</title> +<para>Sets the scancode filter mask of bits to compare. +Use in combination with <constant>/sys/class/rc/rcN/filter</constant> to set the bits +of the scancode which should be compared against the expected +value. A value of 0 disables the filter to allow all valid +scancodes to be processed.</para> +<para>If the hardware supports it then scancodes which do not match +the filter will be ignored. Otherwise the write will fail with +an error.</para> +<para>This value may be reset to 0 if the current protocol is altered.</para> + +</section> +<section id="sys_class_rc_rcN_wakeup_protocols"> +<title>/sys/class/rc/rcN/wakeup_protocols</title> +<para>Reading this file returns a list of available protocols to use for the +wakeup filter, something like:</para> +<para><constant>rc5 rc6 nec jvc [sony]</constant></para> +<para>The enabled wakeup protocol is shown in [] brackets.</para> +<para>Writing "+proto" will add a protocol to the list of enabled wakeup +protocols.</para> +<para>Writing "-proto" will remove a protocol from the list of enabled wakeup +protocols.</para> +<para>Writing "proto" will use "proto" for wakeup events.</para> +<para>Writing "none" will disable wakeup.</para> +<para>Write fails with EINVAL if an invalid protocol combination or unknown +protocol name is used, or if wakeup is not supported by the hardware.</para> + +</section> +<section id="sys_class_rc_rcN_wakeup_filter"> +<title>/sys/class/rc/rcN/wakeup_filter</title> +<para>Sets the scancode wakeup filter expected value. +Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter_mask</constant> to +set the expected value of the bits set in the wakeup filter mask +to trigger a system wake event.</para> +<para>If the hardware supports it and wakeup_filter_mask is not 0 then +scancodes which match the filter will wake the system from e.g. +suspend to RAM or power off. +Otherwise the write will fail with an error.</para> +<para>This value may be reset to 0 if the wakeup protocol is altered.</para> + +</section> +<section id="sys_class_rc_rcN_wakeup_filter_mask"> +<title>/sys/class/rc/rcN/wakeup_filter_mask</title> +<para>Sets the scancode wakeup filter mask of bits to compare. +Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter</constant> to set +the bits of the scancode which should be compared against the +expected value to trigger a system wake event.</para> +<para>If the hardware supports it and wakeup_filter_mask is not 0 then +scancodes which match the filter will wake the system from e.g. +suspend to RAM or power off. +Otherwise the write will fail with an error.</para> +<para>This value may be reset to 0 if the wakeup protocol is altered.</para> +</section> +</section> + +<section id="Remote_controllers_tables"> +<title>Remote controller tables</title> <para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for different devices. This caused the same IR keyname to be mapped completely differently on different IR devices. This resulted that the same IR keyname to be mapped completely different on @@ -175,3 +317,4 @@ keymapping.</para> </section> &sub-lirc_device_interface; +</chapter> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 74b7f27af71..b445161b912 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -70,7 +70,7 @@ MPEG stream embedded, sliced VBI data format in this specification. Remote Controller chapter.</contrib> <affiliation> <address> - <email>mchehab@redhat.com</email> + <email>m.chehab@samsung.com</email> </address> </affiliation> </author> @@ -107,6 +107,16 @@ Remote Controller chapter.</contrib> </address> </affiliation> </author> + <author> + <firstname>Antti</firstname> + <surname>Palosaari</surname> + <contrib>SDR API.</contrib> + <affiliation> + <address> + <email>crope@iki.fi</email> + </address> + </affiliation> + </author> </authorgroup> <copyright> @@ -125,6 +135,7 @@ Remote Controller chapter.</contrib> <year>2011</year> <year>2012</year> <year>2013</year> + <year>2014</year> <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak</holder> @@ -141,6 +152,16 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> + <revnumber>3.15</revnumber> + <date>2014-02-03</date> + <authorinitials>hv, ap</authorinitials> + <revremark>Update several sections of "Common API Elements": "Opening and Closing Devices" +"Querying Capabilities", "Application Priority", "Video Inputs and Outputs", "Audio Inputs and Outputs" +"Tuners and Modulators", "Video Standards" and "Digital Video (DV) Timings". Added SDR API. + </revremark> + </revision> + + <revision> <revnumber>3.14</revnumber> <date>2013-11-25</date> <authorinitials>rr</authorinitials> @@ -537,6 +558,7 @@ and discussions on the V4L mailing list.</revremark> <section id="ttx"> &sub-dev-teletext; </section> <section id="radio"> &sub-dev-radio; </section> <section id="rds"> &sub-dev-rds; </section> + <section id="sdr"> &sub-dev-sdr; </section> <section id="event"> &sub-dev-event; </section> <section id="subdev"> &sub-dev-subdev; </section> </chapter> @@ -585,6 +607,7 @@ and discussions on the V4L mailing list.</revremark> &sub-g-crop; &sub-g-ctrl; &sub-g-dv-timings; + &sub-g-edid; &sub-g-enc-index; &sub-g-ext-ctrls; &sub-g-fbuf; @@ -616,7 +639,6 @@ and discussions on the V4L mailing list.</revremark> &sub-subdev-enum-frame-size; &sub-subdev-enum-mbus-code; &sub-subdev-g-crop; - &sub-subdev-g-edid; &sub-subdev-g-fmt; &sub-subdev-g-frame-interval; &sub-subdev-g-selection; diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml b/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml index 6541ba0175e..4e8ea65f728 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml @@ -100,7 +100,7 @@ See <xref linkend="v4l2-tuner-type" /></entry> <entry><structfield>capability</structfield></entry> <entry spanname="hspan">The tuner/modulator capability flags for this frequency band, see <xref linkend="tuner-capability" />. The <constant>V4L2_TUNER_CAP_LOW</constant> -capability must be the same for all frequency bands of the selected tuner/modulator. +or <constant>V4L2_TUNER_CAP_1HZ</constant> capability must be the same for all frequency bands of the selected tuner/modulator. So either all bands have that capability set, or none of them have that capability.</entry> </row> <row> @@ -109,7 +109,8 @@ So either all bands have that capability set, or none of them have that capabili <entry spanname="hspan">The lowest tunable frequency in units of 62.5 kHz, or if the <structfield>capability</structfield> flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz, for this frequency band.</entry> +Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag +<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry> </row> <row> <entry>__u32</entry> @@ -117,7 +118,8 @@ Hz, for this frequency band.</entry> <entry spanname="hspan">The highest tunable frequency in units of 62.5 kHz, or if the <structfield>capability</structfield> flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz, for this frequency band.</entry> +Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag +<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml index bbd18f0e6ed..ce4563b8713 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml @@ -1,12 +1,12 @@ -<refentry id="vidioc-subdev-g-edid"> +<refentry id="vidioc-g-edid"> <refmeta> - <refentrytitle>ioctl VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</refentrytitle> + <refentrytitle>ioctl VIDIOC_G_EDID, VIDIOC_S_EDID</refentrytitle> &manvol; </refmeta> <refnamediv> - <refname>VIDIOC_SUBDEV_G_EDID</refname> - <refname>VIDIOC_SUBDEV_S_EDID</refname> + <refname>VIDIOC_G_EDID</refname> + <refname>VIDIOC_S_EDID</refname> <refpurpose>Get or set the EDID of a video receiver/transmitter</refpurpose> </refnamediv> @@ -16,7 +16,7 @@ <funcdef>int <function>ioctl</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_subdev_edid *<parameter>argp</parameter></paramdef> + <paramdef>struct v4l2_edid *<parameter>argp</parameter></paramdef> </funcprototype> </funcsynopsis> <funcsynopsis> @@ -24,7 +24,7 @@ <funcdef>int <function>ioctl</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_subdev_edid *<parameter>argp</parameter></paramdef> + <paramdef>const struct v4l2_edid *<parameter>argp</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -42,7 +42,7 @@ <varlistentry> <term><parameter>request</parameter></term> <listitem> - <para>VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</para> + <para>VIDIOC_G_EDID, VIDIOC_S_EDID</para> </listitem> </varlistentry> <varlistentry> @@ -56,12 +56,20 @@ <refsect1> <title>Description</title> - <para>These ioctls can be used to get or set an EDID associated with an input pad - from a receiver or an output pad of a transmitter subdevice.</para> + <para>These ioctls can be used to get or set an EDID associated with an input + from a receiver or an output of a transmitter device. They can be + used with subdevice nodes (/dev/v4l-subdevX) or with video nodes (/dev/videoX).</para> + + <para>When used with video nodes the <structfield>pad</structfield> field represents the + input (for video capture devices) or output (for video output devices) index as + is returned by &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively. When used + with subdevice nodes the <structfield>pad</structfield> field represents the + input or output pad of the subdevice. If there is no EDID support for the given + <structfield>pad</structfield> value, then the &EINVAL; will be returned.</para> <para>To get the EDID data the application has to fill in the <structfield>pad</structfield>, <structfield>start_block</structfield>, <structfield>blocks</structfield> and <structfield>edid</structfield> - fields and call <constant>VIDIOC_SUBDEV_G_EDID</constant>. The current EDID from block + fields and call <constant>VIDIOC_G_EDID</constant>. The current EDID from block <structfield>start_block</structfield> and of size <structfield>blocks</structfield> will be placed in the memory <structfield>edid</structfield> points to. The <structfield>edid</structfield> pointer must point to memory at least <structfield>blocks</structfield> * 128 bytes @@ -91,15 +99,17 @@ data in some way. In any case, the end result is the same: the EDID is no longer available. </para> - <table pgwide="1" frame="none" id="v4l2-subdev-edid"> - <title>struct <structname>v4l2_subdev_edid</structname></title> + <table pgwide="1" frame="none" id="v4l2-edid"> + <title>struct <structname>v4l2_edid</structname></title> <tgroup cols="3"> &cs-str; <tbody valign="top"> <row> <entry>__u32</entry> <entry><structfield>pad</structfield></entry> - <entry>Pad for which to get/set the EDID blocks.</entry> + <entry>Pad for which to get/set the EDID blocks. When used with a video device + node the pad represents the input or output index as returned by + &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively.</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index b3bb9575b2e..e9f6735c082 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -327,7 +327,12 @@ These controls are described in <xref These controls are described in <xref linkend="fm-rx-controls" />.</entry> </row> - + <row> + <entry><constant>V4L2_CTRL_CLASS_RF_TUNER</constant></entry> + <entry>0xa20000</entry> + <entry>The class containing RF tuner controls. +These controls are described in <xref linkend="rf-tuner-controls" />.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml index ee8f56e1bac..4fe19a7a9a3 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml @@ -172,6 +172,13 @@ capture and output devices.</entry> </row> <row> <entry></entry> + <entry>&v4l2-sdr-format;</entry> + <entry><structfield>sdr</structfield></entry> + <entry>Definition of a data format, see +<xref linkend="pixfmt" />, used by SDR capture devices.</entry> + </row> + <row> + <entry></entry> <entry>__u8</entry> <entry><structfield>raw_data</structfield>[200]</entry> <entry>Place holder for future extensions.</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml index c7a1c462e72..d1034fb61d1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml @@ -109,9 +109,10 @@ See <xref linkend="v4l2-tuner-type" /></entry> <entry>__u32</entry> <entry><structfield>frequency</structfield></entry> <entry>Tuning frequency in units of 62.5 kHz, or if the -&v4l2-tuner; or &v4l2-modulator; <structfield>capabilities</structfield> flag +&v4l2-tuner; or &v4l2-modulator; <structfield>capability</structfield> flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz.</entry> +Hz. A 1 Hz unit is used when the <structfield>capability</structfield> flag +<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml index 7f4ac7e41fa..7068b599a00 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml @@ -113,7 +113,8 @@ change for example with the current video standard.</entry> <entry>The lowest tunable frequency in units of 62.5 KHz, or if the <structfield>capability</structfield> flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz.</entry> +Hz, or if the <structfield>capability</structfield> flag +<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry> </row> <row> <entry>__u32</entry> @@ -121,7 +122,8 @@ Hz.</entry> <entry>The highest tunable frequency in units of 62.5 KHz, or if the <structfield>capability</structfield> flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz.</entry> +Hz, or if the <structfield>capability</structfield> flag +<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index 6cc82010c73..b0d865933da 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -134,7 +134,9 @@ the structure refers to a radio tuner the <entry spanname="hspan">The lowest tunable frequency in units of 62.5 kHz, or if the <structfield>capability</structfield> flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz. If multiple frequency bands are supported, then +Hz, or if the <structfield>capability</structfield> flag +<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz. +If multiple frequency bands are supported, then <structfield>rangelow</structfield> is the lowest frequency of all the frequency bands.</entry> </row> @@ -144,7 +146,9 @@ of all the frequency bands.</entry> <entry spanname="hspan">The highest tunable frequency in units of 62.5 kHz, or if the <structfield>capability</structfield> flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz. If multiple frequency bands are supported, then +Hz, or if the <structfield>capability</structfield> flag +<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz. +If multiple frequency bands are supported, then <structfield>rangehigh</structfield> is the highest frequency of all the frequency bands.</entry> </row> @@ -270,7 +274,7 @@ applications must set the array to zero.</entry> <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry> <entry>0x0001</entry> <entry>When set, tuning frequencies are expressed in units of -62.5 Hz, otherwise in units of 62.5 kHz.</entry> +62.5 Hz instead of 62.5 kHz.</entry> </row> <row> <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry> @@ -360,6 +364,11 @@ radio tuners.</entry> <entry>The range to search when using the hardware seek functionality is programmable, see &VIDIOC-S-HW-FREQ-SEEK; for details.</entry> </row> + <row> + <entry><constant>V4L2_TUNER_CAP_1HZ</constant></entry> + <entry>0x1000</entry> + <entry>When set, tuning frequencies are expressed in units of 1 Hz instead of 62.5 kHz.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index d5a3c97b206..370d49d6fb6 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml @@ -296,6 +296,12 @@ modulator programming see <xref linkend="tuner" />.</entry> </row> <row> + <entry><constant>V4L2_CAP_SDR_CAPTURE</constant></entry> + <entry>0x00100000</entry> + <entry>The device supports the +<link linkend="sdr">SDR Capture</link> interface.</entry> + </row> + <row> <entry><constant>V4L2_CAP_READWRITE</constant></entry> <entry>0x01000000</entry> <entry>The device supports the <link diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml index 5b379e75219..a5fc4c4880f 100644 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml @@ -121,7 +121,9 @@ field and the &v4l2-tuner; <structfield>index</structfield> field.</entry> <entry>If non-zero, the lowest tunable frequency of the band to search in units of 62.5 kHz, or if the &v4l2-tuner; <structfield>capability</structfield> field has the -<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz. +<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz or if the &v4l2-tuner; +<structfield>capability</structfield> field has the +<constant>V4L2_TUNER_CAP_1HZ</constant> flag set, in units of 1 Hz. If <structfield>rangelow</structfield> is zero a reasonable default value is used.</entry> </row> @@ -131,7 +133,9 @@ is used.</entry> <entry>If non-zero, the highest tunable frequency of the band to search in units of 62.5 kHz, or if the &v4l2-tuner; <structfield>capability</structfield> field has the -<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz. +<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz or if the &v4l2-tuner; +<structfield>capability</structfield> field has the +<constant>V4L2_TUNER_CAP_1HZ</constant> flag set, in units of 1 Hz. If <structfield>rangehigh</structfield> is zero a reasonable default value is used.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/vidioc-streamon.xml b/Documentation/DocBook/media/v4l/vidioc-streamon.xml index 65dff55079d..df2c63d07ba 100644 --- a/Documentation/DocBook/media/v4l/vidioc-streamon.xml +++ b/Documentation/DocBook/media/v4l/vidioc-streamon.xml @@ -52,16 +52,24 @@ <para>The <constant>VIDIOC_STREAMON</constant> and <constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture or output process during streaming (<link linkend="mmap">memory -mapping</link> or <link linkend="userp">user pointer</link>) I/O.</para> +mapping</link>, <link linkend="userp">user pointer</link> or +<link linkend="dmabuf">DMABUF</link>) I/O.</para> - <para>Specifically the capture hardware is disabled and no input + <para>Capture hardware is disabled and no input buffers are filled (if there are any empty buffers in the incoming queue) until <constant>VIDIOC_STREAMON</constant> has been called. -Accordingly the output hardware is disabled, no video signal is +Output hardware is disabled and no video signal is produced until <constant>VIDIOC_STREAMON</constant> has been called. The ioctl will succeed when at least one output buffer is in the incoming queue.</para> + <para>Memory-to-memory devices will not start until +<constant>VIDIOC_STREAMON</constant> has been called for both the capture +and output stream types.</para> + + <para>If <constant>VIDIOC_STREAMON</constant> fails then any already +queued buffers will remain queued.</para> + <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of aborting or finishing any DMA in progress, unlocks any user pointer buffers locked in physical memory, and it removes all buffers from the @@ -70,14 +78,22 @@ dequeued yet will be lost, likewise all images enqueued for output but not transmitted yet. I/O returns to the same state as after calling &VIDIOC-REQBUFS; and can be restarted accordingly.</para> + <para>If buffers have been queued with &VIDIOC-QBUF; and +<constant>VIDIOC_STREAMOFF</constant> is called without ever having +called <constant>VIDIOC_STREAMON</constant>, then those queued buffers +will also be removed from the incoming queue and all are returned to the +same state as after calling &VIDIOC-REQBUFS; and can be restarted +accordingly.</para> + <para>Both ioctls take a pointer to an integer, the desired buffer or stream type. This is the same as &v4l2-requestbuffers; <structfield>type</structfield>.</para> <para>If <constant>VIDIOC_STREAMON</constant> is called when streaming is already in progress, or if <constant>VIDIOC_STREAMOFF</constant> is called -when streaming is already stopped, then the ioctl does nothing and 0 is -returned.</para> +when streaming is already stopped, then 0 is returned. Nothing happens in the +case of <constant>VIDIOC_STREAMON</constant>, but <constant>VIDIOC_STREAMOFF</constant> +will return queued buffers to their starting state as mentioned above.</para> <para>Note that applications can be preempted for unknown periods right before or after the <constant>VIDIOC_STREAMON</constant> or @@ -93,7 +109,7 @@ synchronize with other events.</para> <varlistentry> <term><errorcode>EINVAL</errorcode></term> <listitem> - <para>The buffer<structfield>type</structfield> is not supported, + <para>The buffer <structfield>type</structfield> is not supported, or no buffers have been allocated (memory mapping) or enqueued (output) yet.</para> </listitem> |