aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media')
-rw-r--r--Documentation/DocBook/media/Makefile2
-rw-r--r--Documentation/DocBook/media/dvb/dvbproperty.xml44
-rw-r--r--Documentation/DocBook/media/v4l/controls.xml408
-rw-r--r--Documentation/DocBook/media/v4l/dev-raw-vbi.xml12
-rw-r--r--Documentation/DocBook/media/v4l/dev-sdr.xml18
-rw-r--r--Documentation/DocBook/media/v4l/dev-sliced-vbi.xml9
-rw-r--r--Documentation/DocBook/media/v4l/io.xml9
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml418
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml44
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml47
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml40
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb12.xml2
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt.xml61
-rw-r--r--Documentation/DocBook/media/v4l/selection-api.xml95
-rw-r--r--Documentation/DocBook/media/v4l/v4l2.xml8
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dqevent.xml50
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml51
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml12
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-selection.xml40
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querycap.xml6
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-queryctrl.xml234
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml8
22 files changed, 1378 insertions, 240 deletions
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile
index 639e74857968..df2962d9e11e 100644
--- a/Documentation/DocBook/media/Makefile
+++ b/Documentation/DocBook/media/Makefile
@@ -174,7 +174,7 @@ FILENAME = \
174DOCUMENTED = \ 174DOCUMENTED = \
175 -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \ 175 -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \
176 -e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \ 176 -e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \
177 -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \ 177 -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\)\(\s\+v4l2_fourcc\)/<link linkend=\"\1\">\1<\/link>\2/g" \
178 -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \ 178 -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \
179 -e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g" 179 -e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g"
180 180
diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml
index 24c22cabc668..948ddaab592e 100644
--- a/Documentation/DocBook/media/dvb/dvbproperty.xml
+++ b/Documentation/DocBook/media/dvb/dvbproperty.xml
@@ -555,10 +555,46 @@ typedef enum fe_delivery_system {
555 </section> 555 </section>
556 <section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING"> 556 <section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING">
557 <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title> 557 <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title>
558 <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para> 558 <para>Valid values: 0, 1, 2, 4, -1 (AUTO)</para>
559 <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values 559 <para>when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.</para>
560 here are referring to what can be found in the TMCC-structure - 560 <para>Note: The real time interleaving length depends on the mode (fft-size). The values
561 independent of the mode.</para> 561 here are referring to what can be found in the TMCC-structure, as shown in the table below.</para>
562 <informaltable id="isdbt-layer-interleaving-table">
563 <tgroup cols="4" align="center">
564 <tbody>
565 <row>
566 <entry>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</entry>
567 <entry>Mode 1 (2K FFT)</entry>
568 <entry>Mode 2 (4K FFT)</entry>
569 <entry>Mode 3 (8K FFT)</entry>
570 </row>
571 <row>
572 <entry>0</entry>
573 <entry>0</entry>
574 <entry>0</entry>
575 <entry>0</entry>
576 </row>
577 <row>
578 <entry>1</entry>
579 <entry>4</entry>
580 <entry>2</entry>
581 <entry>1</entry>
582 </row>
583 <row>
584 <entry>2</entry>
585 <entry>8</entry>
586 <entry>4</entry>
587 <entry>2</entry>
588 </row>
589 <row>
590 <entry>4</entry>
591 <entry>16</entry>
592 <entry>8</entry>
593 <entry>4</entry>
594 </row>
595 </tbody>
596 </tgroup>
597 </informaltable>
562 </section> 598 </section>
563 <section id="DTV-ATSCMH-FIC-VER"> 599 <section id="DTV-ATSCMH-FIC-VER">
564 <title><constant>DTV_ATSCMH_FIC_VER</constant></title> 600 <title><constant>DTV_ATSCMH_FIC_VER</constant></title>
diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml
index 47198eef75a4..9f5ffd85560b 100644
--- a/Documentation/DocBook/media/v4l/controls.xml
+++ b/Documentation/DocBook/media/v4l/controls.xml
@@ -13,6 +13,19 @@ correctly with any device.</para>
13 <para>All controls are accessed using an ID value. V4L2 defines 13 <para>All controls are accessed using an ID value. V4L2 defines
14several IDs for specific purposes. Drivers can also implement their 14several IDs for specific purposes. Drivers can also implement their
15own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant> 15own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant>
16<footnote><para>The use of <constant>V4L2_CID_PRIVATE_BASE</constant>
17is problematic because different drivers may use the same
18<constant>V4L2_CID_PRIVATE_BASE</constant> ID for different controls.
19This makes it hard to programatically set such controls since the meaning
20of the control with that ID is driver dependent. In order to resolve this
21drivers use unique IDs and the <constant>V4L2_CID_PRIVATE_BASE</constant>
22IDs are mapped to those unique IDs by the kernel. Consider these
23<constant>V4L2_CID_PRIVATE_BASE</constant> IDs as aliases to the real
24IDs.</para>
25<para>Many applications today still use the <constant>V4L2_CID_PRIVATE_BASE</constant>
26IDs instead of using &VIDIOC-QUERYCTRL; with the <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>
27flag to enumerate all IDs, so support for <constant>V4L2_CID_PRIVATE_BASE</constant>
28is still around.</para></footnote>
16and higher values. The pre-defined control IDs have the prefix 29and higher values. The pre-defined control IDs have the prefix
17<constant>V4L2_CID_</constant>, and are listed in <xref 30<constant>V4L2_CID_</constant>, and are listed in <xref
18linkend="control-id" />. The ID is used when querying the attributes of 31linkend="control-id" />. The ID is used when querying the attributes of
@@ -31,25 +44,22 @@ the current video input or output, tuner or modulator, or audio input
31or output. Different in the sense of other bounds, another default and 44or output. Different in the sense of other bounds, another default and
32current value, step size or other menu items. A control with a certain 45current value, step size or other menu items. A control with a certain
33<emphasis>custom</emphasis> ID can also change name and 46<emphasis>custom</emphasis> ID can also change name and
34type.<footnote> 47type.</para>
35 <para>It will be more convenient for applications if drivers 48
36make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but 49 <para>If a control is not applicable to the current configuration
37that was never required.</para> 50of the device (for example, it doesn't apply to the current video input)
38 </footnote> Control values are stored globally, they do not 51drivers set the <constant>V4L2_CTRL_FLAG_INACTIVE</constant> flag.</para>
52
53 <para>Control values are stored globally, they do not
39change when switching except to stay within the reported bounds. They 54change when switching except to stay within the reported bounds. They
40also do not change &eg; when the device is opened or closed, when the 55also do not change &eg; when the device is opened or closed, when the
41tuner radio frequency is changed or generally never without 56tuner radio frequency is changed or generally never without
42application request. Since V4L2 specifies no event mechanism, panel 57application request.</para>
43applications intended to cooperate with other panel applications (be 58
44they built into a larger application, as a TV viewer) may need to 59 <para>V4L2 specifies an event mechanism to notify applications
45regularly poll control values to update their user 60when controls change value (see &VIDIOC-SUBSCRIBE-EVENT;, event
46interface.<footnote> 61<constant>V4L2_EVENT_CTRL</constant>), panel applications might want to make
47 <para>Applications could call an ioctl to request events. 62use of that in order to always reflect the correct control value.</para>
48After another process called &VIDIOC-S-CTRL; or another ioctl changing
49shared properties the &func-select; function would indicate
50readability until any ioctl (querying the properties) is
51called.</para>
52 </footnote></para>
53 63
54 <para> 64 <para>
55 All controls use machine endianness. 65 All controls use machine endianness.
@@ -398,14 +408,17 @@ to work.</entry>
398 <row id="v4l2-alpha-component"> 408 <row id="v4l2-alpha-component">
399 <entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry> 409 <entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry>
400 <entry>integer</entry> 410 <entry>integer</entry>
401 <entry> Sets the alpha color component on the capture device or on 411 <entry>Sets the alpha color component. When a capture device (or
402 the capture buffer queue of a mem-to-mem device. When a mem-to-mem 412 capture queue of a mem-to-mem device) produces a frame format that
403 device produces frame format that includes an alpha component 413 includes an alpha component
404 (e.g. <link linkend="rgb-formats">packed RGB image formats</link>) 414 (e.g. <link linkend="rgb-formats">packed RGB image formats</link>)
405 and the alpha value is not defined by the mem-to-mem input data 415 and the alpha value is not defined by the device or the mem-to-mem
406 this control lets you select the alpha component value of all 416 input data this control lets you select the alpha component value of
407 pixels. It is applicable to any pixel format that contains an alpha 417 all pixels. When an output device (or output queue of a mem-to-mem
408 component. 418 device) consumes a frame format that doesn't include an alpha
419 component and the device supports alpha channel processing this
420 control lets you set the alpha component value of all pixels for
421 further processing in the device.
409 </entry> 422 </entry>
410 </row> 423 </row>
411 <row> 424 <row>
@@ -434,127 +447,152 @@ Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>,
434controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or 447controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or
435more menu type controls.</para> 448more menu type controls.</para>
436 449
437 <example> 450 <example id="enum_all_controls">
438 <title>Enumerating all controls</title> 451 <title>Enumerating all user controls</title>
439 452
440 <programlisting> 453 <programlisting>
441&v4l2-queryctrl; queryctrl; 454&v4l2-queryctrl; queryctrl;
442&v4l2-querymenu; querymenu; 455&v4l2-querymenu; querymenu;
443 456
444static void 457static void enumerate_menu(void)
445enumerate_menu (void)
446{ 458{
447 printf (" Menu items:\n"); 459 printf(" Menu items:\n");
448 460
449 memset (&amp;querymenu, 0, sizeof (querymenu)); 461 memset(&amp;querymenu, 0, sizeof(querymenu));
450 querymenu.id = queryctrl.id; 462 querymenu.id = queryctrl.id;
451 463
452 for (querymenu.index = queryctrl.minimum; 464 for (querymenu.index = queryctrl.minimum;
453 querymenu.index &lt;= queryctrl.maximum; 465 querymenu.index &lt;= queryctrl.maximum;
454 querymenu.index++) { 466 querymenu.index++) {
455 if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) { 467 if (0 == ioctl(fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {
456 printf (" %s\n", querymenu.name); 468 printf(" %s\n", querymenu.name);
457 } 469 }
458 } 470 }
459} 471}
460 472
461memset (&amp;queryctrl, 0, sizeof (queryctrl)); 473memset(&amp;queryctrl, 0, sizeof(queryctrl));
462 474
463for (queryctrl.id = V4L2_CID_BASE; 475for (queryctrl.id = V4L2_CID_BASE;
464 queryctrl.id &lt; V4L2_CID_LASTP1; 476 queryctrl.id &lt; V4L2_CID_LASTP1;
465 queryctrl.id++) { 477 queryctrl.id++) {
466 if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) { 478 if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
467 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) 479 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
468 continue; 480 continue;
469 481
470 printf ("Control %s\n", queryctrl.name); 482 printf("Control %s\n", queryctrl.name);
471 483
472 if (queryctrl.type == V4L2_CTRL_TYPE_MENU) 484 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
473 enumerate_menu (); 485 enumerate_menu();
474 } else { 486 } else {
475 if (errno == EINVAL) 487 if (errno == EINVAL)
476 continue; 488 continue;
477 489
478 perror ("VIDIOC_QUERYCTRL"); 490 perror("VIDIOC_QUERYCTRL");
479 exit (EXIT_FAILURE); 491 exit(EXIT_FAILURE);
480 } 492 }
481} 493}
482 494
483for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; 495for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
484 queryctrl.id++) { 496 queryctrl.id++) {
485 if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) { 497 if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
486 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) 498 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
487 continue; 499 continue;
488 500
489 printf ("Control %s\n", queryctrl.name); 501 printf("Control %s\n", queryctrl.name);
490 502
491 if (queryctrl.type == V4L2_CTRL_TYPE_MENU) 503 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
492 enumerate_menu (); 504 enumerate_menu();
493 } else { 505 } else {
494 if (errno == EINVAL) 506 if (errno == EINVAL)
495 break; 507 break;
496 508
497 perror ("VIDIOC_QUERYCTRL"); 509 perror("VIDIOC_QUERYCTRL");
498 exit (EXIT_FAILURE); 510 exit(EXIT_FAILURE);
499 } 511 }
500} 512}
501</programlisting> 513</programlisting>
502 </example> 514 </example>
503 515
504 <example> 516 <example>
517 <title>Enumerating all user controls (alternative)</title>
518 <programlisting>
519memset(&amp;queryctrl, 0, sizeof(queryctrl));
520
521queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
522while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
523 if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
524 break;
525 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
526 continue;
527
528 printf("Control %s\n", queryctrl.name);
529
530 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
531 enumerate_menu();
532
533 queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
534}
535if (errno != EINVAL) {
536 perror("VIDIOC_QUERYCTRL");
537 exit(EXIT_FAILURE);
538}
539</programlisting>
540 </example>
541
542 <example>
505 <title>Changing controls</title> 543 <title>Changing controls</title>
506 544
507 <programlisting> 545 <programlisting>
508&v4l2-queryctrl; queryctrl; 546&v4l2-queryctrl; queryctrl;
509&v4l2-control; control; 547&v4l2-control; control;
510 548
511memset (&amp;queryctrl, 0, sizeof (queryctrl)); 549memset(&amp;queryctrl, 0, sizeof(queryctrl));
512queryctrl.id = V4L2_CID_BRIGHTNESS; 550queryctrl.id = V4L2_CID_BRIGHTNESS;
513 551
514if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) { 552if (-1 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
515 if (errno != EINVAL) { 553 if (errno != EINVAL) {
516 perror ("VIDIOC_QUERYCTRL"); 554 perror("VIDIOC_QUERYCTRL");
517 exit (EXIT_FAILURE); 555 exit(EXIT_FAILURE);
518 } else { 556 } else {
519 printf ("V4L2_CID_BRIGHTNESS is not supported\n"); 557 printf("V4L2_CID_BRIGHTNESS is not supported\n");
520 } 558 }
521} else if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) { 559} else if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) {
522 printf ("V4L2_CID_BRIGHTNESS is not supported\n"); 560 printf("V4L2_CID_BRIGHTNESS is not supported\n");
523} else { 561} else {
524 memset (&amp;control, 0, sizeof (control)); 562 memset(&amp;control, 0, sizeof (control));
525 control.id = V4L2_CID_BRIGHTNESS; 563 control.id = V4L2_CID_BRIGHTNESS;
526 control.value = queryctrl.default_value; 564 control.value = queryctrl.default_value;
527 565
528 if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)) { 566 if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &amp;control)) {
529 perror ("VIDIOC_S_CTRL"); 567 perror("VIDIOC_S_CTRL");
530 exit (EXIT_FAILURE); 568 exit(EXIT_FAILURE);
531 } 569 }
532} 570}
533 571
534memset (&amp;control, 0, sizeof (control)); 572memset(&amp;control, 0, sizeof(control));
535control.id = V4L2_CID_CONTRAST; 573control.id = V4L2_CID_CONTRAST;
536 574
537if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &amp;control)) { 575if (0 == ioctl(fd, &VIDIOC-G-CTRL;, &amp;control)) {
538 control.value += 1; 576 control.value += 1;
539 577
540 /* The driver may clamp the value or return ERANGE, ignored here */ 578 /* The driver may clamp the value or return ERANGE, ignored here */
541 579
542 if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control) 580 if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &amp;control)
543 &amp;&amp; errno != ERANGE) { 581 &amp;&amp; errno != ERANGE) {
544 perror ("VIDIOC_S_CTRL"); 582 perror("VIDIOC_S_CTRL");
545 exit (EXIT_FAILURE); 583 exit(EXIT_FAILURE);
546 } 584 }
547/* Ignore if V4L2_CID_CONTRAST is unsupported */ 585/* Ignore if V4L2_CID_CONTRAST is unsupported */
548} else if (errno != EINVAL) { 586} else if (errno != EINVAL) {
549 perror ("VIDIOC_G_CTRL"); 587 perror("VIDIOC_G_CTRL");
550 exit (EXIT_FAILURE); 588 exit(EXIT_FAILURE);
551} 589}
552 590
553control.id = V4L2_CID_AUDIO_MUTE; 591control.id = V4L2_CID_AUDIO_MUTE;
554control.value = TRUE; /* silence */ 592control.value = 1; /* silence */
555 593
556/* Errors ignored */ 594/* Errors ignored */
557ioctl (fd, VIDIOC_S_CTRL, &amp;control); 595ioctl(fd, VIDIOC_S_CTRL, &amp;control);
558</programlisting> 596</programlisting>
559 </example> 597 </example>
560 </section> 598 </section>
@@ -625,16 +663,29 @@ supported.</para>
625&v4l2-control;, except for the fact that it also allows for 64-bit 663&v4l2-control;, except for the fact that it also allows for 64-bit
626values and pointers to be passed.</para> 664values and pointers to be passed.</para>
627 665
666 <para>Since the &v4l2-ext-control; supports pointers it is now
667also possible to have controls with compound types such as N-dimensional arrays
668and/or structures. You need to specify the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant>
669when enumerating controls to actually be able to see such compound controls.
670In other words, these controls with compound types should only be used
671programmatically.</para>
672
673 <para>Since such compound controls need to expose more information
674about themselves than is possible with &VIDIOC-QUERYCTRL; the
675&VIDIOC-QUERY-EXT-CTRL; ioctl was added. In particular, this ioctl gives
676the dimensions of the N-dimensional array if this control consists of more than
677one element.</para>
678
628 <para>It is important to realize that due to the flexibility of 679 <para>It is important to realize that due to the flexibility of
629controls it is necessary to check whether the control you want to set 680controls it is necessary to check whether the control you want to set
630actually is supported in the driver and what the valid range of values 681actually is supported in the driver and what the valid range of values
631is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to 682is. So use the &VIDIOC-QUERYCTRL; (or &VIDIOC-QUERY-EXT-CTRL;) and
632check this. Also note that it is possible that some of the menu 683&VIDIOC-QUERYMENU; ioctls to check this. Also note that it is possible
633indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant> 684that some of the menu indices in a control of type
634may not be supported (<constant>VIDIOC_QUERYMENU</constant> will 685<constant>V4L2_CTRL_TYPE_MENU</constant> may not be supported
635return an error). A good example is the list of supported MPEG audio 686(<constant>VIDIOC_QUERYMENU</constant> will return an error). A good
636bitrates. Some drivers only support one or two bitrates, others 687example is the list of supported MPEG audio bitrates. Some drivers only
637support a wider range.</para> 688support one or two bitrates, others support a wider range.</para>
638 689
639 <para> 690 <para>
640 All controls use machine endianness. 691 All controls use machine endianness.
@@ -675,12 +726,12 @@ control class is found:</para>
675 <informalexample> 726 <informalexample>
676 <programlisting> 727 <programlisting>
677qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; 728qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
678while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) { 729while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
679 if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG) 730 if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
680 break; 731 break;
681 /* ... */ 732 /* ... */
682 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; 733 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
683 } 734}
684</programlisting> 735</programlisting>
685 </informalexample> 736 </informalexample>
686 737
@@ -700,7 +751,7 @@ ID based on a control ID.</para>
700<constant>VIDIOC_QUERYCTRL</constant> will fail when used in 751<constant>VIDIOC_QUERYCTRL</constant> will fail when used in
701combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In 752combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In
702that case the old method of enumerating control should be used (see 753that case the old method of enumerating control should be used (see
7031.8). But if it is supported, then it is guaranteed to enumerate over 754<xref linkend="enum_all_controls" />). But if it is supported, then it is guaranteed to enumerate over
704all controls, including driver-private controls.</para> 755all controls, including driver-private controls.</para>
705 </section> 756 </section>
706 757
@@ -4000,6 +4051,68 @@ to find receivers which can scroll strings sized as 32 x N or 64 x N characters.
4000with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry> 4051with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
4001 </row> 4052 </row>
4002 <row> 4053 <row>
4054 <entry spanname="id"><constant>V4L2_CID_RDS_TX_MONO_STEREO</constant>&nbsp;</entry>
4055 <entry>boolean</entry>
4056 </row>
4057 <row><entry spanname="descr">Sets the Mono/Stereo bit of the Decoder Identification code. If set,
4058then the audio was recorded as stereo.</entry>
4059 </row>
4060 <row>
4061 <entry spanname="id"><constant>V4L2_CID_RDS_TX_ARTIFICIAL_HEAD</constant>&nbsp;</entry>
4062 <entry>boolean</entry>
4063 </row>
4064 <row><entry spanname="descr">Sets the
4065<ulink url="http://en.wikipedia.org/wiki/Artificial_head">Artificial Head</ulink> bit of the Decoder
4066Identification code. If set, then the audio was recorded using an artificial head.</entry>
4067 </row>
4068 <row>
4069 <entry spanname="id"><constant>V4L2_CID_RDS_TX_COMPRESSED</constant>&nbsp;</entry>
4070 <entry>boolean</entry>
4071 </row>
4072 <row><entry spanname="descr">Sets the Compressed bit of the Decoder Identification code. If set,
4073then the audio is compressed.</entry>
4074 </row>
4075 <row>
4076 <entry spanname="id"><constant>V4L2_CID_RDS_TX_DYNAMIC_PTY</constant>&nbsp;</entry>
4077 <entry>boolean</entry>
4078 </row>
4079 <row><entry spanname="descr">Sets the Dynamic PTY bit of the Decoder Identification code. If set,
4080then the PTY code is dynamically switched.</entry>
4081 </row>
4082 <row>
4083 <entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT</constant>&nbsp;</entry>
4084 <entry>boolean</entry>
4085 </row>
4086 <row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry>
4087 </row>
4088 <row>
4089 <entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_PROGRAM</constant>&nbsp;</entry>
4090 <entry>boolean</entry>
4091 </row>
4092 <row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry>
4093 </row>
4094 <row>
4095 <entry spanname="id"><constant>V4L2_CID_RDS_TX_MUSIC_SPEECH</constant>&nbsp;</entry>
4096 <entry>boolean</entry>
4097 </row>
4098 <row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it
4099broadcasts speech. If the transmitter doesn't make this distinction, then it should be set.</entry>
4100 </row>
4101 <row>
4102 <entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS_ENABLE</constant>&nbsp;</entry>
4103 <entry>boolean</entry>
4104 </row>
4105 <row><entry spanname="descr">If set, then transmit alternate frequencies.</entry>
4106 </row>
4107 <row>
4108 <entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS</constant>&nbsp;</entry>
4109 <entry>__u32 array</entry>
4110 </row>
4111 <row><entry spanname="descr">The alternate frequencies in kHz units. The RDS standard allows
4112for up to 25 frequencies to be defined. Drivers may support fewer frequencies so check
4113the array size.</entry>
4114 </row>
4115 <row>
4003 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant>&nbsp;</entry> 4116 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant>&nbsp;</entry>
4004 <entry>boolean</entry> 4117 <entry>boolean</entry>
4005 </row> 4118 </row>
@@ -4976,6 +5089,57 @@ description of this control class.</entry>
4976 </row><row><entry spanname="descr">Enables/disables RDS 5089 </row><row><entry spanname="descr">Enables/disables RDS
4977 reception by the radio tuner</entry> 5090 reception by the radio tuner</entry>
4978 </row> 5091 </row>
5092 <row>
5093 <entry spanname="id"><constant>V4L2_CID_RDS_RX_PTY</constant>&nbsp;</entry>
5094 <entry>integer</entry>
5095 </row>
5096 <row><entry spanname="descr">Gets RDS Programme Type field.
5097This encodes up to 31 pre-defined programme types.</entry>
5098 </row>
5099 <row>
5100 <entry spanname="id"><constant>V4L2_CID_RDS_RX_PS_NAME</constant>&nbsp;</entry>
5101 <entry>string</entry>
5102 </row>
5103 <row><entry spanname="descr">Gets the Programme Service name (PS_NAME).
5104It is intended for static display on a receiver. It is the primary aid to listeners in programme service
5105identification and selection. In Annex E of <xref linkend="iec62106" />, the RDS specification,
5106there is a full description of the correct character encoding for Programme Service name strings.
5107Also from RDS specification, PS is usually a single eight character text. However, it is also possible
5108to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
5109with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>
5110 </row>
5111 <row>
5112 <entry spanname="id"><constant>V4L2_CID_RDS_RX_RADIO_TEXT</constant>&nbsp;</entry>
5113 <entry>string</entry>
5114 </row>
5115 <row><entry spanname="descr">Gets the Radio Text info. It is a textual description of
5116what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
5117programme-related information or any other text. In these cases, RadioText can be used in addition to
5118<constant>V4L2_CID_RDS_RX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described
5119in Annex E of <xref linkend="iec62106" />. The length of Radio Text strings depends on which RDS Block is being
5120used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
5121to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
5122with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
5123 </row>
5124 <row>
5125 <entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT</constant>&nbsp;</entry>
5126 <entry>boolean</entry>
5127 </row>
5128 <row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry>
5129 </row>
5130 <row>
5131 <entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_PROGRAM</constant>&nbsp;</entry>
5132 <entry>boolean</entry>
5133 </row>
5134 <row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry>
5135 </row>
5136 <row>
5137 <entry spanname="id"><constant>V4L2_CID_RDS_RX_MUSIC_SPEECH</constant>&nbsp;</entry>
5138 <entry>boolean</entry>
5139 </row>
5140 <row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it
5141broadcasts speech. If the transmitter doesn't make this distinction, then it will be set.</entry>
5142 </row>
4979 <row> 5143 <row>
4980 <entry spanname="id"><constant>V4L2_CID_TUNE_DEEMPHASIS</constant>&nbsp;</entry> 5144 <entry spanname="id"><constant>V4L2_CID_TUNE_DEEMPHASIS</constant>&nbsp;</entry>
4981 <entry>enum v4l2_deemphasis</entry> 5145 <entry>enum v4l2_deemphasis</entry>
@@ -5007,6 +5171,102 @@ defines possible values for de-emphasis. Here they are:</entry>
5007 </tbody> 5171 </tbody>
5008 </tgroup> 5172 </tgroup>
5009 </table> 5173 </table>
5174 </section>
5175
5176 <section id="detect-controls">
5177 <title>Detect Control Reference</title>
5178
5179 <para>The Detect class includes controls for common features of
5180 various motion or object detection capable devices.</para>
5181
5182 <table pgwide="1" frame="none" id="detect-control-id">
5183 <title>Detect Control IDs</title>
5184
5185 <tgroup cols="4">
5186 <colspec colname="c1" colwidth="1*" />
5187 <colspec colname="c2" colwidth="6*" />
5188 <colspec colname="c3" colwidth="2*" />
5189 <colspec colname="c4" colwidth="6*" />
5190 <spanspec namest="c1" nameend="c2" spanname="id" />
5191 <spanspec namest="c2" nameend="c4" spanname="descr" />
5192 <thead>
5193 <row>
5194 <entry spanname="id" align="left">ID</entry>
5195 <entry align="left">Type</entry>
5196 </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
5197 </row>
5198 </thead>
5199 <tbody valign="top">
5200 <row><entry></entry></row>
5201 <row>
5202 <entry spanname="id"><constant>V4L2_CID_DETECT_CLASS</constant>&nbsp;</entry>
5203 <entry>class</entry>
5204 </row><row><entry spanname="descr">The Detect class
5205descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
5206description of this control class.</entry>
5207 </row>
5208 <row>
5209 <entry spanname="id"><constant>V4L2_CID_DETECT_MD_MODE</constant>&nbsp;</entry>
5210 <entry>menu</entry>
5211 </row><row><entry spanname="descr">Sets the motion detection mode.</entry>
5212 </row>
5213 <row>
5214 <entrytbl spanname="descr" cols="2">
5215 <tbody valign="top">
5216 <row>
5217 <entry><constant>V4L2_DETECT_MD_MODE_DISABLED</constant>
5218 </entry><entry>Disable motion detection.</entry>
5219 </row>
5220 <row>
5221 <entry><constant>V4L2_DETECT_MD_MODE_GLOBAL</constant>
5222 </entry><entry>Use a single motion detection threshold.</entry>
5223 </row>
5224 <row>
5225 <entry><constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant>
5226 </entry><entry>The image is divided into a grid, each cell with its own
5227 motion detection threshold. These thresholds are set through the
5228 <constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant> matrix control.</entry>
5229 </row>
5230 <row>
5231 <entry><constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant>
5232 </entry><entry>The image is divided into a grid, each cell with its own
5233 region value that specifies which per-region motion detection thresholds
5234 should be used. Each region has its own thresholds. How these per-region
5235 thresholds are set up is driver-specific. The region values for the grid are set
5236 through the <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> matrix
5237 control.</entry>
5238 </row>
5239 </tbody>
5240 </entrytbl>
5241 </row>
5242 <row>
5243 <entry spanname="id"><constant>V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD</constant>&nbsp;</entry>
5244 <entry>integer</entry>
5245 </row>
5246 <row><entry spanname="descr">Sets the global motion detection threshold to be
5247 used with the <constant>V4L2_DETECT_MD_MODE_GLOBAL</constant> motion detection mode.</entry>
5248 </row>
5249 <row>
5250 <entry spanname="id"><constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant>&nbsp;</entry>
5251 <entry>__u16 matrix</entry>
5252 </row>
5253 <row><entry spanname="descr">Sets the motion detection thresholds for each cell in the grid.
5254 To be used with the <constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant>
5255 motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the
5256 grid.</entry>
5257 </row>
5258 <row>
5259 <entry spanname="id"><constant>V4L2_CID_DETECT_MD_REGION_GRID</constant>&nbsp;</entry>
5260 <entry>__u8 matrix</entry>
5261 </row>
5262 <row><entry spanname="descr">Sets the motion detection region value for each cell in the grid.
5263 To be used with the <constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant>
5264 motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the
5265 grid.</entry>
5266 </row>
5267 </tbody>
5268 </tgroup>
5269 </table>
5010 5270
5011 </section> 5271 </section>
5012 5272
diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
index b788c72c885e..f4b61b6ce3c2 100644
--- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
+++ b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
@@ -150,9 +150,15 @@ signal. Drivers shall not convert the sample format by software.</para></entry>
150 <entry>This is the scanning system line number 150 <entry>This is the scanning system line number
151associated with the first line of the VBI image, of the first and the 151associated with the first line of the VBI image, of the first and the
152second field respectively. See <xref linkend="vbi-525" /> and 152second field respectively. See <xref linkend="vbi-525" /> and
153<xref linkend="vbi-625" /> for valid values. VBI input drivers can 153<xref linkend="vbi-625" /> for valid values.
154return start values 0 if the hardware cannot reliable identify 154The <constant>V4L2_VBI_ITU_525_F1_START</constant>,
155scanning lines, VBI acquisition may not require this 155<constant>V4L2_VBI_ITU_525_F2_START</constant>,
156<constant>V4L2_VBI_ITU_625_F1_START</constant> and
157<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start line
158numbers for each field for each 525 or 625 line format as a convenience.
159Don't forget that ITU line numbering starts at 1, not 0.
160VBI input drivers can return start values 0 if the hardware cannot
161reliable identify scanning lines, VBI acquisition may not require this
156information.</entry> 162information.</entry>
157 </row> 163 </row>
158 <row> 164 <row>
diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml
index dc14804f5436..f8903568a243 100644
--- a/Documentation/DocBook/media/v4l/dev-sdr.xml
+++ b/Documentation/DocBook/media/v4l/dev-sdr.xml
@@ -72,9 +72,12 @@ To use the <link linkend="format">format</link> ioctls applications set the
72<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-sdr-format; 72<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-sdr-format;
73<structfield>sdr</structfield> member of the <structfield>fmt</structfield> 73<structfield>sdr</structfield> member of the <structfield>fmt</structfield>
74union as needed per the desired operation. 74union as needed per the desired operation.
75Currently only the <structfield>pixelformat</structfield> field of 75Currently there is two fields, <structfield>pixelformat</structfield> and
76&v4l2-sdr-format; is used. The content of that field is the V4L2 fourcc code 76<structfield>buffersize</structfield>, of struct &v4l2-sdr-format; which are
77of the data format. 77used. Content of the <structfield>pixelformat</structfield> is V4L2 FourCC
78code of the data format. The <structfield>buffersize</structfield> field is
79maximum buffer size in bytes required for data transfer, set by the driver in
80order to inform application.
78 </para> 81 </para>
79 82
80 <table pgwide="1" frame="none" id="v4l2-sdr-format"> 83 <table pgwide="1" frame="none" id="v4l2-sdr-format">
@@ -92,8 +95,15 @@ V4L2 defines SDR formats in <xref linkend="sdr-formats" />.
92 </entry> 95 </entry>
93 </row> 96 </row>
94 <row> 97 <row>
98 <entry>__u32</entry>
99 <entry><structfield>buffersize</structfield></entry>
100 <entry>
101Maximum size in bytes required for data. Value is set by the driver.
102 </entry>
103 </row>
104 <row>
95 <entry>__u8</entry> 105 <entry>__u8</entry>
96 <entry><structfield>reserved[28]</structfield></entry> 106 <entry><structfield>reserved[24]</structfield></entry>
97 <entry>This array is reserved for future extensions. 107 <entry>This array is reserved for future extensions.
98Drivers and applications must set it to zero.</entry> 108Drivers and applications must set it to zero.</entry>
99 </row> 109 </row>
diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
index 548f8ea28dee..7a8bf3011ee9 100644
--- a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
+++ b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
@@ -185,7 +185,14 @@ tables, sigh. --></para></entry>
185 <entry></entry> 185 <entry></entry>
186 <entry spanname="hspan">Drivers must set 186 <entry spanname="hspan">Drivers must set
187<structfield>service_lines</structfield>[0][0] and 187<structfield>service_lines</structfield>[0][0] and
188<structfield>service_lines</structfield>[1][0] to zero.</entry> 188<structfield>service_lines</structfield>[1][0] to zero.
189The <constant>V4L2_VBI_ITU_525_F1_START</constant>,
190<constant>V4L2_VBI_ITU_525_F2_START</constant>,
191<constant>V4L2_VBI_ITU_625_F1_START</constant> and
192<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start
193line numbers for each field for each 525 or 625 line format as a
194convenience. Don't forget that ITU line numbering starts at 1, not 0.
195</entry>
189 </row> 196 </row>
190 <row> 197 <row>
191 <entry>__u32</entry> 198 <entry>__u32</entry>
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index a086a5db7a18..e5e8325aa3d7 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -870,7 +870,8 @@ should set this to 0.</entry>
870 If the application sets this to 0 for an output stream, then 870 If the application sets this to 0 for an output stream, then
871 <structfield>bytesused</structfield> will be set to the size of the 871 <structfield>bytesused</structfield> will be set to the size of the
872 plane (see the <structfield>length</structfield> field of this struct) 872 plane (see the <structfield>length</structfield> field of this struct)
873 by the driver.</entry> 873 by the driver. Note that the actual image data starts at
874 <structfield>data_offset</structfield> which may not be 0.</entry>
874 </row> 875 </row>
875 <row> 876 <row>
876 <entry>__u32</entry> 877 <entry>__u32</entry>
@@ -919,6 +920,10 @@ should set this to 0.</entry>
919 <entry>Offset in bytes to video data in the plane. 920 <entry>Offset in bytes to video data in the plane.
920 Drivers must set this field when <structfield>type</structfield> 921 Drivers must set this field when <structfield>type</structfield>
921 refers to an input stream, applications when it refers to an output stream. 922 refers to an input stream, applications when it refers to an output stream.
923 Note that data_offset is included in <structfield>bytesused</structfield>.
924 So the size of the image in the plane is
925 <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
926 offset <structfield>data_offset</structfield> from the start of the plane.
922 </entry> 927 </entry>
923 </row> 928 </row>
924 <row> 929 <row>
@@ -1066,7 +1071,7 @@ state, in the application domain so to say.</entry>
1066 <entry>Drivers set or clear this flag when calling the 1071 <entry>Drivers set or clear this flag when calling the
1067<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video 1072<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
1068capture devices when the buffer contains a compressed image which is a 1073capture devices when the buffer contains a compressed image which is a
1069key frame (or field), &ie; can be decompressed on its own. Also know as 1074key frame (or field), &ie; can be decompressed on its own. Also known as
1070an I-frame. Applications can set this bit when <structfield>type</structfield> 1075an I-frame. Applications can set this bit when <structfield>type</structfield>
1071refers to an output stream.</entry> 1076refers to an output stream.</entry>
1072 </row> 1077 </row>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
index e1c4f8b4c0b3..2aae8e9452a4 100644
--- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
+++ b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
@@ -15,9 +15,6 @@ typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits
15per pixel. These are all packed-pixel formats, meaning all the data 15per pixel. These are all packed-pixel formats, meaning all the data
16for a pixel lie next to each other in memory.</para> 16for a pixel lie next to each other in memory.</para>
17 17
18 <para>When one of these formats is used, drivers shall report the
19colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
20
21 <table pgwide="1" frame="none" id="rgb-formats"> 18 <table pgwide="1" frame="none" id="rgb-formats">
22 <title>Packed RGB Image Formats</title> 19 <title>Packed RGB Image Formats</title>
23 <tgroup cols="37" align="center"> 20 <tgroup cols="37" align="center">
@@ -130,9 +127,9 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
130 <entry>b<subscript>1</subscript></entry> 127 <entry>b<subscript>1</subscript></entry>
131 <entry>b<subscript>0</subscript></entry> 128 <entry>b<subscript>0</subscript></entry>
132 </row> 129 </row>
133 <row id="V4L2-PIX-FMT-RGB444"> 130 <row id="V4L2-PIX-FMT-ARGB444">
134 <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> 131 <entry><constant>V4L2_PIX_FMT_ARGB444</constant></entry>
135 <entry>'R444'</entry> 132 <entry>'AR12'</entry>
136 <entry></entry> 133 <entry></entry>
137 <entry>g<subscript>3</subscript></entry> 134 <entry>g<subscript>3</subscript></entry>
138 <entry>g<subscript>2</subscript></entry> 135 <entry>g<subscript>2</subscript></entry>
@@ -152,9 +149,31 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
152 <entry>r<subscript>1</subscript></entry> 149 <entry>r<subscript>1</subscript></entry>
153 <entry>r<subscript>0</subscript></entry> 150 <entry>r<subscript>0</subscript></entry>
154 </row> 151 </row>
155 <row id="V4L2-PIX-FMT-RGB555"> 152 <row id="V4L2-PIX-FMT-XRGB444">
156 <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> 153 <entry><constant>V4L2_PIX_FMT_XRGB444</constant></entry>
157 <entry>'RGBO'</entry> 154 <entry>'XR12'</entry>
155 <entry></entry>
156 <entry>g<subscript>3</subscript></entry>
157 <entry>g<subscript>2</subscript></entry>
158 <entry>g<subscript>1</subscript></entry>
159 <entry>g<subscript>0</subscript></entry>
160 <entry>b<subscript>3</subscript></entry>
161 <entry>b<subscript>2</subscript></entry>
162 <entry>b<subscript>1</subscript></entry>
163 <entry>b<subscript>0</subscript></entry>
164 <entry></entry>
165 <entry>-</entry>
166 <entry>-</entry>
167 <entry>-</entry>
168 <entry>-</entry>
169 <entry>r<subscript>3</subscript></entry>
170 <entry>r<subscript>2</subscript></entry>
171 <entry>r<subscript>1</subscript></entry>
172 <entry>r<subscript>0</subscript></entry>
173 </row>
174 <row id="V4L2-PIX-FMT-ARGB555">
175 <entry><constant>V4L2_PIX_FMT_ARGB555</constant></entry>
176 <entry>'AR15'</entry>
158 <entry></entry> 177 <entry></entry>
159 <entry>g<subscript>2</subscript></entry> 178 <entry>g<subscript>2</subscript></entry>
160 <entry>g<subscript>1</subscript></entry> 179 <entry>g<subscript>1</subscript></entry>
@@ -174,6 +193,28 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
174 <entry>g<subscript>4</subscript></entry> 193 <entry>g<subscript>4</subscript></entry>
175 <entry>g<subscript>3</subscript></entry> 194 <entry>g<subscript>3</subscript></entry>
176 </row> 195 </row>
196 <row id="V4L2-PIX-FMT-XRGB555">
197 <entry><constant>V4L2_PIX_FMT_XRGB555</constant></entry>
198 <entry>'XR15'</entry>
199 <entry></entry>
200 <entry>g<subscript>2</subscript></entry>
201 <entry>g<subscript>1</subscript></entry>
202 <entry>g<subscript>0</subscript></entry>
203 <entry>b<subscript>4</subscript></entry>
204 <entry>b<subscript>3</subscript></entry>
205 <entry>b<subscript>2</subscript></entry>
206 <entry>b<subscript>1</subscript></entry>
207 <entry>b<subscript>0</subscript></entry>
208 <entry></entry>
209 <entry>-</entry>
210 <entry>r<subscript>4</subscript></entry>
211 <entry>r<subscript>3</subscript></entry>
212 <entry>r<subscript>2</subscript></entry>
213 <entry>r<subscript>1</subscript></entry>
214 <entry>r<subscript>0</subscript></entry>
215 <entry>g<subscript>4</subscript></entry>
216 <entry>g<subscript>3</subscript></entry>
217 </row>
177 <row id="V4L2-PIX-FMT-RGB565"> 218 <row id="V4L2-PIX-FMT-RGB565">
178 <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry> 219 <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
179 <entry>'RGBP'</entry> 220 <entry>'RGBP'</entry>
@@ -341,9 +382,9 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
341 <entry>b<subscript>1</subscript></entry> 382 <entry>b<subscript>1</subscript></entry>
342 <entry>b<subscript>0</subscript></entry> 383 <entry>b<subscript>0</subscript></entry>
343 </row> 384 </row>
344 <row id="V4L2-PIX-FMT-BGR32"> 385 <row id="V4L2-PIX-FMT-ABGR32">
345 <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> 386 <entry><constant>V4L2_PIX_FMT_ABGR32</constant></entry>
346 <entry>'BGR4'</entry> 387 <entry>'AR24'</entry>
347 <entry></entry> 388 <entry></entry>
348 <entry>b<subscript>7</subscript></entry> 389 <entry>b<subscript>7</subscript></entry>
349 <entry>b<subscript>6</subscript></entry> 390 <entry>b<subscript>6</subscript></entry>
@@ -381,9 +422,49 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
381 <entry>a<subscript>1</subscript></entry> 422 <entry>a<subscript>1</subscript></entry>
382 <entry>a<subscript>0</subscript></entry> 423 <entry>a<subscript>0</subscript></entry>
383 </row> 424 </row>
384 <row id="V4L2-PIX-FMT-RGB32"> 425 <row id="V4L2-PIX-FMT-XBGR32">
385 <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> 426 <entry><constant>V4L2_PIX_FMT_XBGR32</constant></entry>
386 <entry>'RGB4'</entry> 427 <entry>'XR24'</entry>
428 <entry></entry>
429 <entry>b<subscript>7</subscript></entry>
430 <entry>b<subscript>6</subscript></entry>
431 <entry>b<subscript>5</subscript></entry>
432 <entry>b<subscript>4</subscript></entry>
433 <entry>b<subscript>3</subscript></entry>
434 <entry>b<subscript>2</subscript></entry>
435 <entry>b<subscript>1</subscript></entry>
436 <entry>b<subscript>0</subscript></entry>
437 <entry></entry>
438 <entry>g<subscript>7</subscript></entry>
439 <entry>g<subscript>6</subscript></entry>
440 <entry>g<subscript>5</subscript></entry>
441 <entry>g<subscript>4</subscript></entry>
442 <entry>g<subscript>3</subscript></entry>
443 <entry>g<subscript>2</subscript></entry>
444 <entry>g<subscript>1</subscript></entry>
445 <entry>g<subscript>0</subscript></entry>
446 <entry></entry>
447 <entry>r<subscript>7</subscript></entry>
448 <entry>r<subscript>6</subscript></entry>
449 <entry>r<subscript>5</subscript></entry>
450 <entry>r<subscript>4</subscript></entry>
451 <entry>r<subscript>3</subscript></entry>
452 <entry>r<subscript>2</subscript></entry>
453 <entry>r<subscript>1</subscript></entry>
454 <entry>r<subscript>0</subscript></entry>
455 <entry></entry>
456 <entry>-</entry>
457 <entry>-</entry>
458 <entry>-</entry>
459 <entry>-</entry>
460 <entry>-</entry>
461 <entry>-</entry>
462 <entry>-</entry>
463 <entry>-</entry>
464 </row>
465 <row id="V4L2-PIX-FMT-ARGB32">
466 <entry><constant>V4L2_PIX_FMT_ARGB32</constant></entry>
467 <entry>'AX24'</entry>
387 <entry></entry> 468 <entry></entry>
388 <entry>a<subscript>7</subscript></entry> 469 <entry>a<subscript>7</subscript></entry>
389 <entry>a<subscript>6</subscript></entry> 470 <entry>a<subscript>6</subscript></entry>
@@ -421,18 +502,76 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
421 <entry>b<subscript>1</subscript></entry> 502 <entry>b<subscript>1</subscript></entry>
422 <entry>b<subscript>0</subscript></entry> 503 <entry>b<subscript>0</subscript></entry>
423 </row> 504 </row>
505 <row id="V4L2-PIX-FMT-XRGB32">
506 <entry><constant>V4L2_PIX_FMT_XRGB32</constant></entry>
507 <entry>'BX24'</entry>
508 <entry></entry>
509 <entry>-</entry>
510 <entry>-</entry>
511 <entry>-</entry>
512 <entry>-</entry>
513 <entry>-</entry>
514 <entry>-</entry>
515 <entry>-</entry>
516 <entry>-</entry>
517 <entry></entry>
518 <entry>r<subscript>7</subscript></entry>
519 <entry>r<subscript>6</subscript></entry>
520 <entry>r<subscript>5</subscript></entry>
521 <entry>r<subscript>4</subscript></entry>
522 <entry>r<subscript>3</subscript></entry>
523 <entry>r<subscript>2</subscript></entry>
524 <entry>r<subscript>1</subscript></entry>
525 <entry>r<subscript>0</subscript></entry>
526 <entry></entry>
527 <entry>g<subscript>7</subscript></entry>
528 <entry>g<subscript>6</subscript></entry>
529 <entry>g<subscript>5</subscript></entry>
530 <entry>g<subscript>4</subscript></entry>
531 <entry>g<subscript>3</subscript></entry>
532 <entry>g<subscript>2</subscript></entry>
533 <entry>g<subscript>1</subscript></entry>
534 <entry>g<subscript>0</subscript></entry>
535 <entry></entry>
536 <entry>b<subscript>7</subscript></entry>
537 <entry>b<subscript>6</subscript></entry>
538 <entry>b<subscript>5</subscript></entry>
539 <entry>b<subscript>4</subscript></entry>
540 <entry>b<subscript>3</subscript></entry>
541 <entry>b<subscript>2</subscript></entry>
542 <entry>b<subscript>1</subscript></entry>
543 <entry>b<subscript>0</subscript></entry>
544 </row>
424 </tbody> 545 </tbody>
425 </tgroup> 546 </tgroup>
426 </table> 547 </table>
427 548
428 <para>Bit 7 is the most significant bit. The value of the a = alpha 549 <para>Bit 7 is the most significant bit.</para>
429bits is undefined when reading from the driver, ignored when writing 550
430to the driver, except when alpha blending has been negotiated for a 551 <para>The usage and value of the alpha bits (a) in the ARGB and ABGR formats
431<link linkend="overlay">Video Overlay</link> or <link linkend="osd"> 552 (collectively referred to as alpha formats) depend on the device type and
432Video Output Overlay</link> or when the alpha component has been configured 553 hardware operation. <link linkend="capture">Capture</link> devices
433for a <link linkend="capture">Video Capture</link> by means of <link 554 (including capture queues of mem-to-mem devices) fill the alpha component in
434linkend="v4l2-alpha-component"> <constant>V4L2_CID_ALPHA_COMPONENT 555 memory. When the device outputs an alpha channel the alpha component will
435</constant> </link> control.</para> 556 have a meaningful value. Otherwise, when the device doesn't output an alpha
557 channel but can set the alpha bit to a user-configurable value, the <link
558 linkend="v4l2-alpha-component"><constant>V4L2_CID_ALPHA_COMPONENT</constant>
559 </link> control is used to specify that alpha value, and the alpha component
560 of all pixels will be set to the value specified by that control. Otherwise
561 a corresponding format without an alpha component (XRGB or XBGR) must be
562 used instead of an alpha format.</para>
563
564 <para><link linkend="output">Output</link> devices (including output queues
565 of mem-to-mem devices and <link linkend="osd">video output overlay</link>
566 devices) read the alpha component from memory. When the device processes the
567 alpha channel the alpha component must be filled with meaningful values by
568 applications. Otherwise a corresponding format without an alpha component
569 (XRGB or XBGR) must be used instead of an alpha format.</para>
570
571 <para>The XRGB and XBGR formats contain undefined bits (-). Applications,
572 devices and drivers must ignore those bits, for both <link
573 linkend="capture">capture</link> and <link linkend="output">output</link>
574 devices.</para>
436 575
437 <example> 576 <example>
438 <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel 577 <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel
@@ -512,6 +651,239 @@ image</title>
512 </formalpara> 651 </formalpara>
513 </example> 652 </example>
514 653
654 <para>Formats defined in <xref linkend="rgb-formats-deprecated"/> are
655 deprecated and must not be used by new drivers. They are documented here for
656 reference. The meaning of their alpha bits (a) is ill-defined and
657 interpreted as in either the corresponding ARGB or XRGB format, depending on
658 the driver.</para>
659
660 <table pgwide="1" frame="none" id="rgb-formats-deprecated">
661 <title>Deprecated Packed RGB Image Formats</title>
662 <tgroup cols="37" align="center">
663 <colspec colname="id" align="left" />
664 <colspec colname="fourcc" />
665 <colspec colname="bit" />
666
667 <colspec colnum="4" colname="b07" align="center" />
668 <colspec colnum="5" colname="b06" align="center" />
669 <colspec colnum="6" colname="b05" align="center" />
670 <colspec colnum="7" colname="b04" align="center" />
671 <colspec colnum="8" colname="b03" align="center" />
672 <colspec colnum="9" colname="b02" align="center" />
673 <colspec colnum="10" colname="b01" align="center" />
674 <colspec colnum="11" colname="b00" align="center" />
675
676 <colspec colnum="13" colname="b17" align="center" />
677 <colspec colnum="14" colname="b16" align="center" />
678 <colspec colnum="15" colname="b15" align="center" />
679 <colspec colnum="16" colname="b14" align="center" />
680 <colspec colnum="17" colname="b13" align="center" />
681 <colspec colnum="18" colname="b12" align="center" />
682 <colspec colnum="19" colname="b11" align="center" />
683 <colspec colnum="20" colname="b10" align="center" />
684
685 <colspec colnum="22" colname="b27" align="center" />
686 <colspec colnum="23" colname="b26" align="center" />
687 <colspec colnum="24" colname="b25" align="center" />
688 <colspec colnum="25" colname="b24" align="center" />
689 <colspec colnum="26" colname="b23" align="center" />
690 <colspec colnum="27" colname="b22" align="center" />
691 <colspec colnum="28" colname="b21" align="center" />
692 <colspec colnum="29" colname="b20" align="center" />
693
694 <colspec colnum="31" colname="b37" align="center" />
695 <colspec colnum="32" colname="b36" align="center" />
696 <colspec colnum="33" colname="b35" align="center" />
697 <colspec colnum="34" colname="b34" align="center" />
698 <colspec colnum="35" colname="b33" align="center" />
699 <colspec colnum="36" colname="b32" align="center" />
700 <colspec colnum="37" colname="b31" align="center" />
701 <colspec colnum="38" colname="b30" align="center" />
702
703 <spanspec namest="b07" nameend="b00" spanname="b0" />
704 <spanspec namest="b17" nameend="b10" spanname="b1" />
705 <spanspec namest="b27" nameend="b20" spanname="b2" />
706 <spanspec namest="b37" nameend="b30" spanname="b3" />
707 <thead>
708 <row>
709 <entry>Identifier</entry>
710 <entry>Code</entry>
711 <entry>&nbsp;</entry>
712 <entry spanname="b0">Byte&nbsp;0 in memory</entry>
713 <entry spanname="b1">Byte&nbsp;1</entry>
714 <entry spanname="b2">Byte&nbsp;2</entry>
715 <entry spanname="b3">Byte&nbsp;3</entry>
716 </row>
717 <row>
718 <entry>&nbsp;</entry>
719 <entry>&nbsp;</entry>
720 <entry>Bit</entry>
721 <entry>7</entry>
722 <entry>6</entry>
723 <entry>5</entry>
724 <entry>4</entry>
725 <entry>3</entry>
726 <entry>2</entry>
727 <entry>1</entry>
728 <entry>0</entry>
729 <entry>&nbsp;</entry>
730 <entry>7</entry>
731 <entry>6</entry>
732 <entry>5</entry>
733 <entry>4</entry>
734 <entry>3</entry>
735 <entry>2</entry>
736 <entry>1</entry>
737 <entry>0</entry>
738 <entry>&nbsp;</entry>
739 <entry>7</entry>
740 <entry>6</entry>
741 <entry>5</entry>
742 <entry>4</entry>
743 <entry>3</entry>
744 <entry>2</entry>
745 <entry>1</entry>
746 <entry>0</entry>
747 <entry>&nbsp;</entry>
748 <entry>7</entry>
749 <entry>6</entry>
750 <entry>5</entry>
751 <entry>4</entry>
752 <entry>3</entry>
753 <entry>2</entry>
754 <entry>1</entry>
755 <entry>0</entry>
756 </row>
757 </thead>
758 <tbody>
759 <row id="V4L2-PIX-FMT-RGB444">
760 <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
761 <entry>'R444'</entry>
762 <entry></entry>
763 <entry>g<subscript>3</subscript></entry>
764 <entry>g<subscript>2</subscript></entry>
765 <entry>g<subscript>1</subscript></entry>
766 <entry>g<subscript>0</subscript></entry>
767 <entry>b<subscript>3</subscript></entry>
768 <entry>b<subscript>2</subscript></entry>
769 <entry>b<subscript>1</subscript></entry>
770 <entry>b<subscript>0</subscript></entry>
771 <entry></entry>
772 <entry>a<subscript>3</subscript></entry>
773 <entry>a<subscript>2</subscript></entry>
774 <entry>a<subscript>1</subscript></entry>
775 <entry>a<subscript>0</subscript></entry>
776 <entry>r<subscript>3</subscript></entry>
777 <entry>r<subscript>2</subscript></entry>
778 <entry>r<subscript>1</subscript></entry>
779 <entry>r<subscript>0</subscript></entry>
780 </row>
781 <row id="V4L2-PIX-FMT-RGB555">
782 <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
783 <entry>'RGBO'</entry>
784 <entry></entry>
785 <entry>g<subscript>2</subscript></entry>
786 <entry>g<subscript>1</subscript></entry>
787 <entry>g<subscript>0</subscript></entry>
788 <entry>b<subscript>4</subscript></entry>
789 <entry>b<subscript>3</subscript></entry>
790 <entry>b<subscript>2</subscript></entry>
791 <entry>b<subscript>1</subscript></entry>
792 <entry>b<subscript>0</subscript></entry>
793 <entry></entry>
794 <entry>a</entry>
795 <entry>r<subscript>4</subscript></entry>
796 <entry>r<subscript>3</subscript></entry>
797 <entry>r<subscript>2</subscript></entry>
798 <entry>r<subscript>1</subscript></entry>
799 <entry>r<subscript>0</subscript></entry>
800 <entry>g<subscript>4</subscript></entry>
801 <entry>g<subscript>3</subscript></entry>
802 </row>
803 <row id="V4L2-PIX-FMT-BGR32">
804 <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
805 <entry>'BGR4'</entry>
806 <entry></entry>
807 <entry>b<subscript>7</subscript></entry>
808 <entry>b<subscript>6</subscript></entry>
809 <entry>b<subscript>5</subscript></entry>
810 <entry>b<subscript>4</subscript></entry>
811 <entry>b<subscript>3</subscript></entry>
812 <entry>b<subscript>2</subscript></entry>
813 <entry>b<subscript>1</subscript></entry>
814 <entry>b<subscript>0</subscript></entry>
815 <entry></entry>
816 <entry>g<subscript>7</subscript></entry>
817 <entry>g<subscript>6</subscript></entry>
818 <entry>g<subscript>5</subscript></entry>
819 <entry>g<subscript>4</subscript></entry>
820 <entry>g<subscript>3</subscript></entry>
821 <entry>g<subscript>2</subscript></entry>
822 <entry>g<subscript>1</subscript></entry>
823 <entry>g<subscript>0</subscript></entry>
824 <entry></entry>
825 <entry>r<subscript>7</subscript></entry>
826 <entry>r<subscript>6</subscript></entry>
827 <entry>r<subscript>5</subscript></entry>
828 <entry>r<subscript>4</subscript></entry>
829 <entry>r<subscript>3</subscript></entry>
830 <entry>r<subscript>2</subscript></entry>
831 <entry>r<subscript>1</subscript></entry>
832 <entry>r<subscript>0</subscript></entry>
833 <entry></entry>
834 <entry>a<subscript>7</subscript></entry>
835 <entry>a<subscript>6</subscript></entry>
836 <entry>a<subscript>5</subscript></entry>
837 <entry>a<subscript>4</subscript></entry>
838 <entry>a<subscript>3</subscript></entry>
839 <entry>a<subscript>2</subscript></entry>
840 <entry>a<subscript>1</subscript></entry>
841 <entry>a<subscript>0</subscript></entry>
842 </row>
843 <row id="V4L2-PIX-FMT-RGB32">
844 <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
845 <entry>'RGB4'</entry>
846 <entry></entry>
847 <entry>a<subscript>7</subscript></entry>
848 <entry>a<subscript>6</subscript></entry>
849 <entry>a<subscript>5</subscript></entry>
850 <entry>a<subscript>4</subscript></entry>
851 <entry>a<subscript>3</subscript></entry>
852 <entry>a<subscript>2</subscript></entry>
853 <entry>a<subscript>1</subscript></entry>
854 <entry>a<subscript>0</subscript></entry>
855 <entry></entry>
856 <entry>r<subscript>7</subscript></entry>
857 <entry>r<subscript>6</subscript></entry>
858 <entry>r<subscript>5</subscript></entry>
859 <entry>r<subscript>4</subscript></entry>
860 <entry>r<subscript>3</subscript></entry>
861 <entry>r<subscript>2</subscript></entry>
862 <entry>r<subscript>1</subscript></entry>
863 <entry>r<subscript>0</subscript></entry>
864 <entry></entry>
865 <entry>g<subscript>7</subscript></entry>
866 <entry>g<subscript>6</subscript></entry>
867 <entry>g<subscript>5</subscript></entry>
868 <entry>g<subscript>4</subscript></entry>
869 <entry>g<subscript>3</subscript></entry>
870 <entry>g<subscript>2</subscript></entry>
871 <entry>g<subscript>1</subscript></entry>
872 <entry>g<subscript>0</subscript></entry>
873 <entry></entry>
874 <entry>b<subscript>7</subscript></entry>
875 <entry>b<subscript>6</subscript></entry>
876 <entry>b<subscript>5</subscript></entry>
877 <entry>b<subscript>4</subscript></entry>
878 <entry>b<subscript>3</subscript></entry>
879 <entry>b<subscript>2</subscript></entry>
880 <entry>b<subscript>1</subscript></entry>
881 <entry>b<subscript>0</subscript></entry>
882 </row>
883 </tbody>
884 </tgroup>
885 </table>
886
515 <para>A test utility to determine which RGB formats a driver 887 <para>A test utility to determine which RGB formats a driver
516actually supports is available from the LinuxTV v4l-dvb repository. 888actually supports is available from the LinuxTV v4l-dvb repository.
517See &v4l-dvb; for access instructions.</para> 889See &v4l-dvb; for access instructions.</para>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml
new file mode 100644
index 000000000000..6118d8f7a20c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml
@@ -0,0 +1,44 @@
1<refentry id="V4L2-SDR-FMT-CS08">
2 <refmeta>
3 <refentrytitle>V4L2_SDR_FMT_CS8 ('CS08')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname>
8 <constant>V4L2_SDR_FMT_CS8</constant>
9 </refname>
10 <refpurpose>Complex signed 8-bit IQ sample</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14 <para>
15This format contains sequence of complex number samples. Each complex number
16consist two parts, called In-phase and Quadrature (IQ). Both I and Q are
17represented as a 8 bit signed number. I value comes first and Q value after
18that.
19 </para>
20 <example>
21 <title><constant>V4L2_SDR_FMT_CS8</constant> 1 sample</title>
22 <formalpara>
23 <title>Byte Order.</title>
24 <para>Each cell is one byte.
25 <informaltable frame="none">
26 <tgroup cols="2" align="center">
27 <colspec align="left" colwidth="2*" />
28 <tbody valign="top">
29 <row>
30 <entry>start&nbsp;+&nbsp;0:</entry>
31 <entry>I'<subscript>0</subscript></entry>
32 </row>
33 <row>
34 <entry>start&nbsp;+&nbsp;1:</entry>
35 <entry>Q'<subscript>0</subscript></entry>
36 </row>
37 </tbody>
38 </tgroup>
39 </informaltable>
40 </para>
41 </formalpara>
42 </example>
43 </refsect1>
44</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml
new file mode 100644
index 000000000000..e4b494ce1369
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml
@@ -0,0 +1,47 @@
1<refentry id="V4L2-SDR-FMT-CS14LE">
2 <refmeta>
3 <refentrytitle>V4L2_SDR_FMT_CS14LE ('CS14')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname>
8 <constant>V4L2_SDR_FMT_CS14LE</constant>
9 </refname>
10 <refpurpose>Complex signed 14-bit little endian IQ sample</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14 <para>
15This format contains sequence of complex number samples. Each complex number
16consist two parts, called In-phase and Quadrature (IQ). Both I and Q are
17represented as a 14 bit signed little endian number. I value comes first
18and Q value after that. 14 bit value is stored in 16 bit space with unused
19high bits padded with 0.
20 </para>
21 <example>
22 <title><constant>V4L2_SDR_FMT_CS14LE</constant> 1 sample</title>
23 <formalpara>
24 <title>Byte Order.</title>
25 <para>Each cell is one byte.
26 <informaltable frame="none">
27 <tgroup cols="3" align="center">
28 <colspec align="left" colwidth="2*" />
29 <tbody valign="top">
30 <row>
31 <entry>start&nbsp;+&nbsp;0:</entry>
32 <entry>I'<subscript>0[7:0]</subscript></entry>
33 <entry>I'<subscript>0[13:8]</subscript></entry>
34 </row>
35 <row>
36 <entry>start&nbsp;+&nbsp;2:</entry>
37 <entry>Q'<subscript>0[7:0]</subscript></entry>
38 <entry>Q'<subscript>0[13:8]</subscript></entry>
39 </row>
40 </tbody>
41 </tgroup>
42 </informaltable>
43 </para>
44 </formalpara>
45 </example>
46 </refsect1>
47</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml
new file mode 100644
index 000000000000..3df076b99f94
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml
@@ -0,0 +1,40 @@
1<refentry id="V4L2-SDR-FMT-RU12LE">
2 <refmeta>
3 <refentrytitle>V4L2_SDR_FMT_RU12LE ('RU12')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname>
8 <constant>V4L2_SDR_FMT_RU12LE</constant>
9 </refname>
10 <refpurpose>Real unsigned 12-bit little endian sample</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14 <para>
15This format contains sequence of real number samples. Each sample is
16represented as a 12 bit unsigned little endian number. Sample is stored
17in 16 bit space with unused high bits padded with 0.
18 </para>
19 <example>
20 <title><constant>V4L2_SDR_FMT_RU12LE</constant> 1 sample</title>
21 <formalpara>
22 <title>Byte Order.</title>
23 <para>Each cell is one byte.
24 <informaltable frame="none">
25 <tgroup cols="3" align="center">
26 <colspec align="left" colwidth="2*" />
27 <tbody valign="top">
28 <row>
29 <entry>start&nbsp;+&nbsp;0:</entry>
30 <entry>I'<subscript>0[7:0]</subscript></entry>
31 <entry>I'<subscript>0[11:8]</subscript></entry>
32 </row>
33 </tbody>
34 </tgroup>
35 </informaltable>
36 </para>
37 </formalpara>
38 </example>
39 </refsect1>
40</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml
index 9ba4fb690bc0..96947f17fca1 100644
--- a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml
+++ b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml
@@ -18,7 +18,7 @@
18 <title>Description</title> 18 <title>Description</title>
19 19
20 <para>The following four pixel formats are raw sRGB / Bayer formats with 20 <para>The following four pixel formats are raw sRGB / Bayer formats with
2112 bits per colour. Each colour component is stored in a 16-bit word, with 6 2112 bits per colour. Each colour component is stored in a 16-bit word, with 4
22unused high bits filled with zeros. Each n-pixel row contains n/2 green samples 22unused high bits filled with zeros. Each n-pixel row contains n/2 green samples
23and n/2 blue or red samples, with alternating red and blue rows. Bytes are 23and n/2 blue or red samples, with alternating red and blue rows. Bytes are
24stored in memory in little endian order. They are conventionally described 24stored in memory in little endian order. They are conventionally described
diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml
index 91dcbc84f3f8..df5b23d46552 100644
--- a/Documentation/DocBook/media/v4l/pixfmt.xml
+++ b/Documentation/DocBook/media/v4l/pixfmt.xml
@@ -112,9 +112,34 @@ see <xref linkend="colorspaces" />.</entry>
112 <row> 112 <row>
113 <entry>__u32</entry> 113 <entry>__u32</entry>
114 <entry><structfield>priv</structfield></entry> 114 <entry><structfield>priv</structfield></entry>
115 <entry>Reserved for custom (driver defined) additional 115 <entry><para>This field indicates whether the remaining fields of the
116information about formats. When not used drivers and applications must 116<structname>v4l2_pix_format</structname> structure, also called the extended
117set this field to zero.</entry> 117fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it
118indicates that the extended fields have been correctly initialized. When set to
119any other value it indicates that the extended fields contain undefined values.
120</para>
121<para>Applications that wish to use the pixel format extended fields must first
122ensure that the feature is supported by querying the device for the
123<link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link>
124capability. If the capability isn't set the pixel format extended fields are not
125supported and using the extended fields will lead to undefined results.</para>
126<para>To use the extended fields, applications must set the
127<structfield>priv</structfield> field to
128<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, initialize all the extended fields
129and zero the unused bytes of the <structname>v4l2_format</structname>
130<structfield>raw_data</structfield> field.</para>
131<para>When the <structfield>priv</structfield> field isn't set to
132<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> drivers must act as if all the
133extended fields were set to zero. On return drivers must set the
134<structfield>priv</structfield> field to
135<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> and all the extended fields to
136applicable values.</para></entry>
137 </row>
138 <row>
139 <entry>__u32</entry>
140 <entry><structfield>flags</structfield></entry>
141 <entry>Flags set by the application or driver, see <xref
142linkend="format-flags" />.</entry>
118 </row> 143 </row>
119 </tbody> 144 </tbody>
120 </tgroup> 145 </tgroup>
@@ -201,9 +226,15 @@ codes can be used.</entry>
201 and the number of valid entries in the 226 and the number of valid entries in the
202 <structfield>plane_fmt</structfield> array.</entry> 227 <structfield>plane_fmt</structfield> array.</entry>
203 </row> 228 </row>
229 <row>
230 <entry>__u8</entry>
231 <entry><structfield>flags</structfield></entry>
232 <entry>Flags set by the application or driver, see <xref
233linkend="format-flags" />.</entry>
234 </row>
204 <row> 235 <row>
205 <entry>__u8</entry> 236 <entry>__u8</entry>
206 <entry><structfield>reserved[11]</structfield></entry> 237 <entry><structfield>reserved[10]</structfield></entry>
207 <entry>Reserved for future extensions. Should be zeroed by the 238 <entry>Reserved for future extensions. Should be zeroed by the
208 application.</entry> 239 application.</entry>
209 </row> 240 </row>
@@ -248,7 +279,7 @@ has just as many pad bytes after it as the other rows.</para>
248 279
249 <para>In V4L2 each format has an identifier which looks like 280 <para>In V4L2 each format has an identifier which looks like
250<constant>PIX_FMT_XXX</constant>, defined in the <link 281<constant>PIX_FMT_XXX</constant>, defined in the <link
251linkend="videodev">videodev.h</link> header file. These identifiers 282linkend="videodev">videodev2.h</link> header file. These identifiers
252represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link> 283represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link>
253which are also listed below, however they are not the same as those 284which are also listed below, however they are not the same as those
254used in the Windows world.</para> 285used in the Windows world.</para>
@@ -828,6 +859,9 @@ interface only.</para>
828 859
829 &sub-sdr-cu08; 860 &sub-sdr-cu08;
830 &sub-sdr-cu16le; 861 &sub-sdr-cu16le;
862 &sub-sdr-cs08;
863 &sub-sdr-cs14le;
864 &sub-sdr-ru12le;
831 865
832 </section> 866 </section>
833 867
@@ -1060,4 +1094,21 @@ concatenated to form the JPEG stream. </para>
1060 </tbody> 1094 </tbody>
1061 </tgroup> 1095 </tgroup>
1062 </table> 1096 </table>
1097
1098 <table frame="none" pgwide="1" id="format-flags">
1099 <title>Format Flags</title>
1100 <tgroup cols="3">
1101 &cs-def;
1102 <tbody valign="top">
1103 <row>
1104 <entry><constant>V4L2_PIX_FMT_FLAG_PREMUL_ALPHA</constant></entry>
1105 <entry>0x00000001</entry>
1106 <entry>The color values are premultiplied by the alpha channel
1107value. For example, if a light blue pixel with 50% transparency was described by
1108RGBA values (128, 192, 255, 128), the same pixel described with premultiplied
1109colors would be described by RGBA values (64, 96, 128, 128) </entry>
1110 </row>
1111 </tbody>
1112 </tgroup>
1113 </table>
1063 </section> 1114 </section>
diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml
index 4c238ce068b0..28cbded766c9 100644
--- a/Documentation/DocBook/media/v4l/selection-api.xml
+++ b/Documentation/DocBook/media/v4l/selection-api.xml
@@ -86,47 +86,47 @@ selection targets available for a video capture device. It is recommended to
86configure the cropping targets before to the composing targets.</para> 86configure the cropping targets before to the composing targets.</para>
87 87
88<para>The range of coordinates of the top left corner, width and height of 88<para>The range of coordinates of the top left corner, width and height of
89areas that can be sampled is given by the <constant> V4L2_SEL_TGT_CROP_BOUNDS 89areas that can be sampled is given by the <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>
90</constant> target. It is recommended for the driver developers to put the 90target. It is recommended for the driver developers to put the
91top/left corner at position <constant> (0,0) </constant>. The rectangle's 91top/left corner at position <constant>(0,0)</constant>. The rectangle's
92coordinates are expressed in pixels.</para> 92coordinates are expressed in pixels.</para>
93 93
94<para>The top left corner, width and height of the source rectangle, that is 94<para>The top left corner, width and height of the source rectangle, that is
95the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP 95the area actually sampled, is given by the <constant>V4L2_SEL_TGT_CROP</constant>
96</constant> target. It uses the same coordinate system as <constant> 96target. It uses the same coordinate system as <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>.
97V4L2_SEL_TGT_CROP_BOUNDS </constant>. The active cropping area must lie 97The active cropping area must lie completely inside the capture boundaries. The
98completely inside the capture boundaries. The driver may further adjust the 98driver may further adjust the requested size and/or position according to hardware
99requested size and/or position according to hardware limitations.</para> 99limitations.</para>
100 100
101<para>Each capture device has a default source rectangle, given by the 101<para>Each capture device has a default source rectangle, given by the
102<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant> target. This rectangle shall 102<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant> target. This rectangle shall
103over what the driver writer considers the complete picture. Drivers shall set 103over what the driver writer considers the complete picture. Drivers shall set
104the active crop rectangle to the default when the driver is first loaded, but 104the active crop rectangle to the default when the driver is first loaded, but
105not later.</para> 105not later.</para>
106 106
107<para>The composing targets refer to a memory buffer. The limits of composing 107<para>The composing targets refer to a memory buffer. The limits of composing
108coordinates are obtained using <constant> V4L2_SEL_TGT_COMPOSE_BOUNDS 108coordinates are obtained using <constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant>.
109</constant>. All coordinates are expressed in pixels. The rectangle's top/left 109All coordinates are expressed in pixels. The rectangle's top/left
110corner must be located at position <constant> (0,0) </constant>. The width and 110corner must be located at position <constant>(0,0)</constant>. The width and
111height are equal to the image size set by <constant> VIDIOC_S_FMT </constant>. 111height are equal to the image size set by <constant>VIDIOC_S_FMT</constant>.
112</para> 112</para>
113 113
114<para>The part of a buffer into which the image is inserted by the hardware is 114<para>The part of a buffer into which the image is inserted by the hardware is
115controlled by the <constant> V4L2_SEL_TGT_COMPOSE </constant> target. 115controlled by the <constant>V4L2_SEL_TGT_COMPOSE</constant> target.
116The rectangle's coordinates are also expressed in the same coordinate system as 116The rectangle's coordinates are also expressed in the same coordinate system as
117the bounds rectangle. The composing rectangle must lie completely inside bounds 117the bounds rectangle. The composing rectangle must lie completely inside bounds
118rectangle. The driver must adjust the composing rectangle to fit to the 118rectangle. The driver must adjust the composing rectangle to fit to the
119bounding limits. Moreover, the driver can perform other adjustments according 119bounding limits. Moreover, the driver can perform other adjustments according
120to hardware limitations. The application can control rounding behaviour using 120to hardware limitations. The application can control rounding behaviour using
121<link linkend="v4l2-selection-flags"> constraint flags </link>.</para> 121<link linkend="v4l2-selection-flags"> constraint flags</link>.</para>
122 122
123<para>For capture devices the default composing rectangle is queried using 123<para>For capture devices the default composing rectangle is queried using
124<constant> V4L2_SEL_TGT_COMPOSE_DEFAULT </constant>. It is usually equal to the 124<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant>. It is usually equal to the
125bounding rectangle.</para> 125bounding rectangle.</para>
126 126
127<para>The part of a buffer that is modified by the hardware is given by 127<para>The part of a buffer that is modified by the hardware is given by
128<constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant>. It contains all pixels 128<constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>. It contains all pixels
129defined using <constant> V4L2_SEL_TGT_COMPOSE </constant> plus all 129defined using <constant>V4L2_SEL_TGT_COMPOSE</constant> plus all
130padding data modified by hardware during insertion process. All pixels outside 130padding data modified by hardware during insertion process. All pixels outside
131this rectangle <emphasis>must not</emphasis> be changed by the hardware. The 131this rectangle <emphasis>must not</emphasis> be changed by the hardware. The
132content of pixels that lie inside the padded area but outside active area is 132content of pixels that lie inside the padded area but outside active area is
@@ -140,52 +140,51 @@ where the rubbish pixels are located and remove them if needed.</para>
140 <title>Configuration of video output</title> 140 <title>Configuration of video output</title>
141 141
142<para>For output devices targets and ioctls are used similarly to the video 142<para>For output devices targets and ioctls are used similarly to the video
143capture case. The <emphasis> composing </emphasis> rectangle refers to the 143capture case. The <emphasis>composing</emphasis> rectangle refers to the
144insertion of an image into a video signal. The cropping rectangles refer to a 144insertion of an image into a video signal. The cropping rectangles refer to a
145memory buffer. It is recommended to configure the composing targets before to 145memory buffer. It is recommended to configure the composing targets before to
146the cropping targets.</para> 146the cropping targets.</para>
147 147
148<para>The cropping targets refer to the memory buffer that contains an image to 148<para>The cropping targets refer to the memory buffer that contains an image to
149be inserted into a video signal or graphical screen. The limits of cropping 149be inserted into a video signal or graphical screen. The limits of cropping
150coordinates are obtained using <constant> V4L2_SEL_TGT_CROP_BOUNDS </constant>. 150coordinates are obtained using <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>.
151All coordinates are expressed in pixels. The top/left corner is always point 151All coordinates are expressed in pixels. The top/left corner is always point
152<constant> (0,0) </constant>. The width and height is equal to the image size 152<constant>(0,0)</constant>. The width and height is equal to the image size
153specified using <constant> VIDIOC_S_FMT </constant> ioctl.</para> 153specified using <constant>VIDIOC_S_FMT</constant> ioctl.</para>
154 154
155<para>The top left corner, width and height of the source rectangle, that is 155<para>The top left corner, width and height of the source rectangle, that is
156the area from which image date are processed by the hardware, is given by the 156the area from which image date are processed by the hardware, is given by the
157<constant> V4L2_SEL_TGT_CROP </constant>. Its coordinates are expressed 157<constant>V4L2_SEL_TGT_CROP</constant>. Its coordinates are expressed
158in in the same coordinate system as the bounds rectangle. The active cropping 158in in the same coordinate system as the bounds rectangle. The active cropping
159area must lie completely inside the crop boundaries and the driver may further 159area must lie completely inside the crop boundaries and the driver may further
160adjust the requested size and/or position according to hardware 160adjust the requested size and/or position according to hardware
161limitations.</para> 161limitations.</para>
162 162
163<para>For output devices the default cropping rectangle is queried using 163<para>For output devices the default cropping rectangle is queried using
164<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant>. It is usually equal to the 164<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant>. It is usually equal to the
165bounding rectangle.</para> 165bounding rectangle.</para>
166 166
167<para>The part of a video signal or graphics display where the image is 167<para>The part of a video signal or graphics display where the image is
168inserted by the hardware is controlled by <constant> 168inserted by the hardware is controlled by <constant>V4L2_SEL_TGT_COMPOSE</constant>
169V4L2_SEL_TGT_COMPOSE </constant> target. The rectangle's coordinates 169target. The rectangle's coordinates are expressed in pixels. The composing
170are expressed in pixels. The composing rectangle must lie completely inside the 170rectangle must lie completely inside the bounds rectangle. The driver must
171bounds rectangle. The driver must adjust the area to fit to the bounding 171adjust the area to fit to the bounding limits. Moreover, the driver can
172limits. Moreover, the driver can perform other adjustments according to 172perform other adjustments according to hardware limitations.</para>
173hardware limitations. </para> 173
174 174<para>The device has a default composing rectangle, given by the
175<para>The device has a default composing rectangle, given by the <constant> 175<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant> target. This rectangle shall cover what
176V4L2_SEL_TGT_COMPOSE_DEFAULT </constant> target. This rectangle shall cover what
177the driver writer considers the complete picture. It is recommended for the 176the driver writer considers the complete picture. It is recommended for the
178driver developers to put the top/left corner at position <constant> (0,0) 177driver developers to put the top/left corner at position <constant>(0,0)</constant>.
179</constant>. Drivers shall set the active composing rectangle to the default 178Drivers shall set the active composing rectangle to the default
180one when the driver is first loaded.</para> 179one when the driver is first loaded.</para>
181 180
182<para>The devices may introduce additional content to video signal other than 181<para>The devices may introduce additional content to video signal other than
183an image from memory buffers. It includes borders around an image. However, 182an image from memory buffers. It includes borders around an image. However,
184such a padded area is driver-dependent feature not covered by this document. 183such a padded area is driver-dependent feature not covered by this document.
185Driver developers are encouraged to keep padded rectangle equal to active one. 184Driver developers are encouraged to keep padded rectangle equal to active one.
186The padded target is accessed by the <constant> V4L2_SEL_TGT_COMPOSE_PADDED 185The padded target is accessed by the <constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>
187</constant> identifier. It must contain all pixels from the <constant> 186identifier. It must contain all pixels from the <constant>V4L2_SEL_TGT_COMPOSE</constant>
188V4L2_SEL_TGT_COMPOSE </constant> target.</para> 187target.</para>
189 188
190 </section> 189 </section>
191 190
@@ -194,8 +193,8 @@ V4L2_SEL_TGT_COMPOSE </constant> target.</para>
194 <title>Scaling control</title> 193 <title>Scaling control</title>
195 194
196<para>An application can detect if scaling is performed by comparing the width 195<para>An application can detect if scaling is performed by comparing the width
197and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP 196and the height of rectangles obtained using <constant>V4L2_SEL_TGT_CROP</constant>
198</constant> and <constant> V4L2_SEL_TGT_COMPOSE </constant> targets. If 197and <constant>V4L2_SEL_TGT_COMPOSE</constant> targets. If
199these are not equal then the scaling is applied. The application can compute 198these are not equal then the scaling is applied. The application can compute
200the scaling ratios using these values.</para> 199the scaling ratios using these values.</para>
201 200
@@ -208,7 +207,7 @@ the scaling ratios using these values.</para>
208 <title>Comparison with old cropping API</title> 207 <title>Comparison with old cropping API</title>
209 208
210<para>The selection API was introduced to cope with deficiencies of previous 209<para>The selection API was introduced to cope with deficiencies of previous
211<link linkend="crop"> API </link>, that was designed to control simple capture 210<link linkend="crop"> API</link>, that was designed to control simple capture
212devices. Later the cropping API was adopted by video output drivers. The ioctls 211devices. Later the cropping API was adopted by video output drivers. The ioctls
213are used to select a part of the display were the video signal is inserted. It 212are used to select a part of the display were the video signal is inserted. It
214should be considered as an API abuse because the described operation is 213should be considered as an API abuse because the described operation is
@@ -220,7 +219,7 @@ part of an image by abusing V4L2 API. Cropping a smaller image from a larger
220one is achieved by setting the field 219one is achieved by setting the field
221&v4l2-pix-format;<structfield>::bytesperline</structfield>. Introducing an image offsets 220&v4l2-pix-format;<structfield>::bytesperline</structfield>. Introducing an image offsets
222could be done by modifying field &v4l2-buffer;<structfield>::m_userptr</structfield> 221could be done by modifying field &v4l2-buffer;<structfield>::m_userptr</structfield>
223before calling <constant> VIDIOC_QBUF </constant>. Those 222before calling <constant>VIDIOC_QBUF</constant>. Those
224operations should be avoided because they are not portable (endianness), and do 223operations should be avoided because they are not portable (endianness), and do
225not work for macroblock and Bayer formats and mmap buffers. The selection API 224not work for macroblock and Bayer formats and mmap buffers. The selection API
226deals with configuration of buffer cropping/composing in a clear, intuitive and 225deals with configuration of buffer cropping/composing in a clear, intuitive and
@@ -229,7 +228,7 @@ and constraints flags are introduced. Finally, &v4l2-crop; and &v4l2-cropcap;
229have no reserved fields. Therefore there is no way to extend their functionality. 228have no reserved fields. Therefore there is no way to extend their functionality.
230The new &v4l2-selection; provides a lot of place for future 229The new &v4l2-selection; provides a lot of place for future
231extensions. Driver developers are encouraged to implement only selection API. 230extensions. Driver developers are encouraged to implement only selection API.
232The former cropping API would be simulated using the new one. </para> 231The former cropping API would be simulated using the new one.</para>
233 232
234 </section> 233 </section>
235 234
@@ -238,9 +237,9 @@ The former cropping API would be simulated using the new one. </para>
238 <example> 237 <example>
239 <title>Resetting the cropping parameters</title> 238 <title>Resetting the cropping parameters</title>
240 239
241 <para>(A video capture device is assumed; change <constant> 240 <para>(A video capture device is assumed; change
242V4L2_BUF_TYPE_VIDEO_CAPTURE </constant> for other devices; change target to 241<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other devices; change target to
243<constant> V4L2_SEL_TGT_COMPOSE_* </constant> family to configure composing 242<constant>V4L2_SEL_TGT_COMPOSE_*</constant> family to configure composing
244area)</para> 243area)</para>
245 244
246 <programlisting> 245 <programlisting>
@@ -292,8 +291,8 @@ area)</para>
292 291
293 <example> 292 <example>
294 <title>Querying for scaling factors</title> 293 <title>Querying for scaling factors</title>
295 <para>A video output device is assumed; change <constant> 294 <para>A video output device is assumed; change
296V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> for other devices</para> 295<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> for other devices</para>
297 <programlisting> 296 <programlisting>
298 297
299 &v4l2-selection; compose = { 298 &v4l2-selection; compose = {
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index b445161b912c..f2f81f06a17b 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -152,6 +152,14 @@ structs, ioctls) must be noted in more detail in the history chapter
152applications. --> 152applications. -->
153 153
154 <revision> 154 <revision>
155 <revnumber>3.16</revnumber>
156 <date>2014-05-27</date>
157 <authorinitials>lp</authorinitials>
158 <revremark>Extended &v4l2-pix-format;. Added format flags.
159 </revremark>
160 </revision>
161
162 <revision>
155 <revnumber>3.15</revnumber> 163 <revnumber>3.15</revnumber>
156 <date>2014-02-03</date> 164 <date>2014-02-03</date>
157 <authorinitials>hv, ap</authorinitials> 165 <authorinitials>hv, ap</authorinitials>
diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
index 820f86e8744b..cb7732582f03 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -94,6 +94,18 @@
94 </row> 94 </row>
95 <row> 95 <row>
96 <entry></entry> 96 <entry></entry>
97 <entry>&v4l2-event-motion-det;</entry>
98 <entry><structfield>motion_det</structfield></entry>
99 <entry>Event data for event V4L2_EVENT_MOTION_DET.</entry>
100 </row>
101 <row>
102 <entry></entry>
103 <entry>&v4l2-event-src-change;</entry>
104 <entry><structfield>src_change</structfield></entry>
105 <entry>Event data for event V4L2_EVENT_SOURCE_CHANGE.</entry>
106 </row>
107 <row>
108 <entry></entry>
97 <entry>__u8</entry> 109 <entry>__u8</entry>
98 <entry><structfield>data</structfield>[64]</entry> 110 <entry><structfield>data</structfield>[64]</entry>
99 <entry>Event data. Defined by the event type. The union 111 <entry>Event data. Defined by the event type. The union
@@ -258,6 +270,44 @@
258 </tgroup> 270 </tgroup>
259 </table> 271 </table>
260 272
273 <table frame="none" pgwide="1" id="v4l2-event-motion-det">
274 <title>struct <structname>v4l2_event_motion_det</structname></title>
275 <tgroup cols="3">
276 &cs-str;
277 <tbody valign="top">
278 <row>
279 <entry>__u32</entry>
280 <entry><structfield>flags</structfield></entry>
281 <entry>
282 Currently only one flag is available: if <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant>
283 is set, then the <structfield>frame_sequence</structfield> field is valid,
284 otherwise that field should be ignored.
285 </entry>
286 </row>
287 <row>
288 <entry>__u32</entry>
289 <entry><structfield>frame_sequence</structfield></entry>
290 <entry>
291 The sequence number of the frame being received. Only valid if the
292 <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> flag was set.
293 </entry>
294 </row>
295 <row>
296 <entry>__u32</entry>
297 <entry><structfield>region_mask</structfield></entry>
298 <entry>
299 The bitmask of the regions that reported motion. There is at least one
300 region. If this field is 0, then no motion was detected at all.
301 If there is no <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> control
302 (see <xref linkend="detect-controls" />) to assign a different region
303 to each cell in the motion detection grid, then that all cells
304 are automatically assigned to the default region 0.
305 </entry>
306 </row>
307 </tbody>
308 </tgroup>
309 </table>
310
261 <table pgwide="1" frame="none" id="changes-flags"> 311 <table pgwide="1" frame="none" id="changes-flags">
262 <title>Changes</title> 312 <title>Changes</title>
263 <tgroup cols="3"> 313 <tgroup cols="3">
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
index e9f6735c0823..c5bdbfcc42b3 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
@@ -72,23 +72,30 @@ initialize the <structfield>id</structfield>,
72<structfield>size</structfield> and <structfield>reserved2</structfield> fields 72<structfield>size</structfield> and <structfield>reserved2</structfield> fields
73of each &v4l2-ext-control; and call the 73of each &v4l2-ext-control; and call the
74<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls 74<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls
75must also set the <structfield>string</structfield> field.</para> 75must also set the <structfield>string</structfield> field. Controls
76of compound types (<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set)
77must set the <structfield>ptr</structfield> field.</para>
76 78
77 <para>If the <structfield>size</structfield> is too small to 79 <para>If the <structfield>size</structfield> is too small to
78receive the control result (only relevant for pointer-type controls 80receive the control result (only relevant for pointer-type controls
79like strings), then the driver will set <structfield>size</structfield> 81like strings), then the driver will set <structfield>size</structfield>
80to a valid value and return an &ENOSPC;. You should re-allocate the 82to a valid value and return an &ENOSPC;. You should re-allocate the
81string memory to this new size and try again. It is possible that the 83memory to this new size and try again. For the string type it is possible that
82same issue occurs again if the string has grown in the meantime. It is 84the same issue occurs again if the string has grown in the meantime. It is
83recommended to call &VIDIOC-QUERYCTRL; first and use 85recommended to call &VIDIOC-QUERYCTRL; first and use
84<structfield>maximum</structfield>+1 as the new <structfield>size</structfield> 86<structfield>maximum</structfield>+1 as the new <structfield>size</structfield>
85value. It is guaranteed that that is sufficient memory. 87value. It is guaranteed that that is sufficient memory.
86</para> 88</para>
87 89
90 <para>N-dimensional arrays are set and retrieved row-by-row. You cannot set a partial
91array, all elements have to be set or retrieved. The total size is calculated
92as <structfield>elems</structfield> * <structfield>elem_size</structfield>.
93These values can be obtained by calling &VIDIOC-QUERY-EXT-CTRL;.</para>
94
88 <para>To change the value of a set of controls applications 95 <para>To change the value of a set of controls applications
89initialize the <structfield>id</structfield>, <structfield>size</structfield>, 96initialize the <structfield>id</structfield>, <structfield>size</structfield>,
90<structfield>reserved2</structfield> and 97<structfield>reserved2</structfield> and
91<structfield>value/string</structfield> fields of each &v4l2-ext-control; and 98<structfield>value/value64/string/ptr</structfield> fields of each &v4l2-ext-control; and
92call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls 99call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls
93will only be set if <emphasis>all</emphasis> control values are 100will only be set if <emphasis>all</emphasis> control values are
94valid.</para> 101valid.</para>
@@ -96,7 +103,7 @@ valid.</para>
96 <para>To check if a set of controls have correct values applications 103 <para>To check if a set of controls have correct values applications
97initialize the <structfield>id</structfield>, <structfield>size</structfield>, 104initialize the <structfield>id</structfield>, <structfield>size</structfield>,
98<structfield>reserved2</structfield> and 105<structfield>reserved2</structfield> and
99<structfield>value/string</structfield> fields of each &v4l2-ext-control; and 106<structfield>value/value64/string/ptr</structfield> fields of each &v4l2-ext-control; and
100call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to 107call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to
101the driver whether wrong values are automatically adjusted to a valid 108the driver whether wrong values are automatically adjusted to a valid
102value or if an error is returned.</para> 109value or if an error is returned.</para>
@@ -158,19 +165,47 @@ applications must set the array to zero.</entry>
158 <entry></entry> 165 <entry></entry>
159 <entry>__s32</entry> 166 <entry>__s32</entry>
160 <entry><structfield>value</structfield></entry> 167 <entry><structfield>value</structfield></entry>
161 <entry>New value or current value.</entry> 168 <entry>New value or current value. Valid if this control is not of
169type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
170<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
162 </row> 171 </row>
163 <row> 172 <row>
164 <entry></entry> 173 <entry></entry>
165 <entry>__s64</entry> 174 <entry>__s64</entry>
166 <entry><structfield>value64</structfield></entry> 175 <entry><structfield>value64</structfield></entry>
167 <entry>New value or current value.</entry> 176 <entry>New value or current value. Valid if this control is of
177type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
178<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
168 </row> 179 </row>
169 <row> 180 <row>
170 <entry></entry> 181 <entry></entry>
171 <entry>char *</entry> 182 <entry>char *</entry>
172 <entry><structfield>string</structfield></entry> 183 <entry><structfield>string</structfield></entry>
173 <entry>A pointer to a string.</entry> 184 <entry>A pointer to a string. Valid if this control is of
185type <constant>V4L2_CTRL_TYPE_STRING</constant>.</entry>
186 </row>
187 <row>
188 <entry></entry>
189 <entry>__u8 *</entry>
190 <entry><structfield>p_u8</structfield></entry>
191 <entry>A pointer to a matrix control of unsigned 8-bit values.
192Valid if this control is of type <constant>V4L2_CTRL_TYPE_U8</constant>.</entry>
193 </row>
194 <row>
195 <entry></entry>
196 <entry>__u16 *</entry>
197 <entry><structfield>p_u16</structfield></entry>
198 <entry>A pointer to a matrix control of unsigned 16-bit values.
199Valid if this control is of type <constant>V4L2_CTRL_TYPE_U16</constant>.</entry>
200 </row>
201 <row>
202 <entry></entry>
203 <entry>void *</entry>
204 <entry><structfield>ptr</structfield></entry>
205 <entry>A pointer to a compound type which can be an N-dimensional array and/or a
206compound type (the control's type is >= <constant>V4L2_CTRL_COMPOUND_TYPES</constant>).
207Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control.
208</entry>
174 </row> 209 </row>
175 </tbody> 210 </tbody>
176 </tgroup> 211 </tgroup>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
index 7c63815e7afd..20460730b02c 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
@@ -152,13 +152,10 @@ a valid base address, so applications can find the corresponding Linux
152framebuffer device (see <xref linkend="osd" />).</entry> 152framebuffer device (see <xref linkend="osd" />).</entry>
153 </row> 153 </row>
154 <row> 154 <row>
155 <entry>&v4l2-pix-format;</entry> 155 <entry>struct</entry>
156 <entry><structfield>fmt</structfield></entry> 156 <entry><structfield>fmt</structfield></entry>
157 <entry></entry> 157 <entry></entry>
158 <entry>Layout of the frame buffer. The 158 <entry>Layout of the frame buffer.</entry>
159<structname>v4l2_pix_format</structname> structure is defined in <xref
160linkend="pixfmt" />, for clarification the fields and acceptable values
161 are listed below:</entry>
162 </row> 159 </row>
163 <row> 160 <row>
164 <entry></entry> 161 <entry></entry>
@@ -276,9 +273,8 @@ see <xref linkend="colorspaces" />.</entry>
276 <entry></entry> 273 <entry></entry>
277 <entry>__u32</entry> 274 <entry>__u32</entry>
278 <entry><structfield>priv</structfield></entry> 275 <entry><structfield>priv</structfield></entry>
279 <entry>Reserved for additional information about custom 276 <entry>Reserved. Drivers and applications must set this field to
280(driver defined) formats. When not used drivers and applications must 277zero.</entry>
281set this field to zero.</entry>
282 </row> 278 </row>
283 </tbody> 279 </tbody>
284 </tgroup> 280 </tgroup>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
index b11ec75e21a1..9c04ac8661b1 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
@@ -58,17 +58,16 @@
58 58
59 <para>The ioctls are used to query and configure selection rectangles.</para> 59 <para>The ioctls are used to query and configure selection rectangles.</para>
60 60
61<para> To query the cropping (composing) rectangle set &v4l2-selection; 61<para>To query the cropping (composing) rectangle set &v4l2-selection;
62<structfield> type </structfield> field to the respective buffer type. 62<structfield> type </structfield> field to the respective buffer type.
63Do not use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE 63Do not use multiplanar buffers. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
64</constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE 64instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. Use
65</constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of 65<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
66<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is 66<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is
67setting the value of &v4l2-selection; <structfield>target</structfield> field 67setting the value of &v4l2-selection; <structfield>target</structfield> field
68to <constant> V4L2_SEL_TGT_CROP </constant> (<constant> 68to <constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>).
69V4L2_SEL_TGT_COMPOSE </constant>). Please refer to table <xref 69Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" />
70linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> for additional 70for additional targets. The <structfield>flags</structfield> and <structfield>reserved
71targets. The <structfield>flags</structfield> and <structfield>reserved
72</structfield> fields of &v4l2-selection; are ignored and they must be filled 71</structfield> fields of &v4l2-selection; are ignored and they must be filled
73with zeros. The driver fills the rest of the structure or 72with zeros. The driver fills the rest of the structure or
74returns &EINVAL; if incorrect buffer type or target was used. If cropping 73returns &EINVAL; if incorrect buffer type or target was used. If cropping
@@ -77,19 +76,18 @@ always equal to the bounds rectangle. Finally, the &v4l2-rect;
77<structfield>r</structfield> rectangle is filled with the current cropping 76<structfield>r</structfield> rectangle is filled with the current cropping
78(composing) coordinates. The coordinates are expressed in driver-dependent 77(composing) coordinates. The coordinates are expressed in driver-dependent
79units. The only exception are rectangles for images in raw formats, whose 78units. The only exception are rectangles for images in raw formats, whose
80coordinates are always expressed in pixels. </para> 79coordinates are always expressed in pixels.</para>
81 80
82<para> To change the cropping (composing) rectangle set the &v4l2-selection; 81<para>To change the cropping (composing) rectangle set the &v4l2-selection;
83<structfield>type</structfield> field to the respective buffer type. Do not 82<structfield>type</structfield> field to the respective buffer type. Do not
84use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE 83use multiplanar buffers. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
85</constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE 84instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. Use
86</constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of 85<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
87<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is 86<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is
88setting the value of &v4l2-selection; <structfield>target</structfield> to 87setting the value of &v4l2-selection; <structfield>target</structfield> to
89<constant>V4L2_SEL_TGT_CROP</constant> (<constant> 88<constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>).
90V4L2_SEL_TGT_COMPOSE </constant>). Please refer to table <xref 89Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" />
91linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> for additional 90for additional targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be
92targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be
93set to the desired active area. Field &v4l2-selection; <structfield> reserved 91set to the desired active area. Field &v4l2-selection; <structfield> reserved
94</structfield> is ignored and must be filled with zeros. The driver may adjust 92</structfield> is ignored and must be filled with zeros. The driver may adjust
95coordinates of the requested rectangle. An application may 93coordinates of the requested rectangle. An application may
@@ -149,8 +147,8 @@ On success the &v4l2-rect; <structfield>r</structfield> field contains
149the adjusted rectangle. When the parameters are unsuitable the application may 147the adjusted rectangle. When the parameters are unsuitable the application may
150modify the cropping (composing) or image parameters and repeat the cycle until 148modify the cropping (composing) or image parameters and repeat the cycle until
151satisfactory parameters have been negotiated. If constraints flags have to be 149satisfactory parameters have been negotiated. If constraints flags have to be
152violated at then ERANGE is returned. The error indicates that <emphasis> there 150violated at then ERANGE is returned. The error indicates that <emphasis>there
153exist no rectangle </emphasis> that satisfies the constraints.</para> 151exist no rectangle</emphasis> that satisfies the constraints.</para>
154 152
155 <para>Selection targets and flags are documented in <xref 153 <para>Selection targets and flags are documented in <xref
156 linkend="v4l2-selections-common"/>.</para> 154 linkend="v4l2-selections-common"/>.</para>
diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml
index 370d49d6fb64..d0c5e604f014 100644
--- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml
@@ -302,6 +302,12 @@ modulator programming see
302<link linkend="sdr">SDR Capture</link> interface.</entry> 302<link linkend="sdr">SDR Capture</link> interface.</entry>
303 </row> 303 </row>
304 <row> 304 <row>
305 <entry><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></entry>
306 <entry>0x00200000</entry>
307 <entry>The device supports the &v4l2-pix-format; extended
308fields.</entry>
309 </row>
310 <row>
305 <entry><constant>V4L2_CAP_READWRITE</constant></entry> 311 <entry><constant>V4L2_CAP_READWRITE</constant></entry>
306 <entry>0x01000000</entry> 312 <entry>0x01000000</entry>
307 <entry>The device supports the <link 313 <entry>The device supports the <link
diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
index e6645b996558..2bd98fd7a4e5 100644
--- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
@@ -1,11 +1,12 @@
1<refentry id="vidioc-queryctrl"> 1<refentry id="vidioc-queryctrl">
2 <refmeta> 2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle> 3 <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</refentrytitle>
4 &manvol; 4 &manvol;
5 </refmeta> 5 </refmeta>
6 6
7 <refnamediv> 7 <refnamediv>
8 <refname>VIDIOC_QUERYCTRL</refname> 8 <refname>VIDIOC_QUERYCTRL</refname>
9 <refname>VIDIOC_QUERY_EXT_CTRL</refname>
9 <refname>VIDIOC_QUERYMENU</refname> 10 <refname>VIDIOC_QUERYMENU</refname>
10 <refpurpose>Enumerate controls and menu control items</refpurpose> 11 <refpurpose>Enumerate controls and menu control items</refpurpose>
11 </refnamediv> 12 </refnamediv>
@@ -24,6 +25,14 @@
24 <funcdef>int <function>ioctl</function></funcdef> 25 <funcdef>int <function>ioctl</function></funcdef>
25 <paramdef>int <parameter>fd</parameter></paramdef> 26 <paramdef>int <parameter>fd</parameter></paramdef>
26 <paramdef>int <parameter>request</parameter></paramdef> 27 <paramdef>int <parameter>request</parameter></paramdef>
28 <paramdef>struct v4l2_query_ext_ctrl *<parameter>argp</parameter></paramdef>
29 </funcprototype>
30 </funcsynopsis>
31 <funcsynopsis>
32 <funcprototype>
33 <funcdef>int <function>ioctl</function></funcdef>
34 <paramdef>int <parameter>fd</parameter></paramdef>
35 <paramdef>int <parameter>request</parameter></paramdef>
27 <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef> 36 <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef>
28 </funcprototype> 37 </funcprototype>
29 </funcsynopsis> 38 </funcsynopsis>
@@ -42,7 +51,7 @@
42 <varlistentry> 51 <varlistentry>
43 <term><parameter>request</parameter></term> 52 <term><parameter>request</parameter></term>
44 <listitem> 53 <listitem>
45 <para>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</para> 54 <para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para>
46 </listitem> 55 </listitem>
47 </varlistentry> 56 </varlistentry>
48 <varlistentry> 57 <varlistentry>
@@ -67,7 +76,7 @@ structure. The driver fills the rest of the structure or returns an
67<constant>VIDIOC_QUERYCTRL</constant> with successive 76<constant>VIDIOC_QUERYCTRL</constant> with successive
68<structfield>id</structfield> values starting from 77<structfield>id</structfield> values starting from
69<constant>V4L2_CID_BASE</constant> up to and exclusive 78<constant>V4L2_CID_BASE</constant> up to and exclusive
70<constant>V4L2_CID_BASE_LASTP1</constant>. Drivers may return 79<constant>V4L2_CID_LASTP1</constant>. Drivers may return
71<errorcode>EINVAL</errorcode> if a control in this range is not 80<errorcode>EINVAL</errorcode> if a control in this range is not
72supported. Further applications can enumerate private controls, which 81supported. Further applications can enumerate private controls, which
73are not defined in this specification, by starting at 82are not defined in this specification, by starting at
@@ -89,9 +98,23 @@ prematurely end the enumeration).</para></footnote></para>
89 98
90 <para>When the application ORs <structfield>id</structfield> with 99 <para>When the application ORs <structfield>id</structfield> with
91<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the 100<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the
92next supported control, or <errorcode>EINVAL</errorcode> if there is 101next supported non-compound control, or <errorcode>EINVAL</errorcode>
93none. Drivers which do not support this flag yet always return 102if there is none. In addition, the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant>
94<errorcode>EINVAL</errorcode>.</para> 103flag can be specified to enumerate all compound controls (i.e. controls
104with type &ge; <constant>V4L2_CTRL_COMPOUND_TYPES</constant>). Specify both
105<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and
106<constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> in order to enumerate
107all controls, compound or not. Drivers which do not support these flags yet
108always return <errorcode>EINVAL</errorcode>.</para>
109
110 <para>The <constant>VIDIOC_QUERY_EXT_CTRL</constant> ioctl was
111introduced in order to better support controls that can use compound
112types, and to expose additional control information that cannot be
113returned in &v4l2-queryctrl; since that structure is full.</para>
114
115 <para><constant>VIDIOC_QUERY_EXT_CTRL</constant> is used in the
116same way as <constant>VIDIOC_QUERYCTRL</constant>, except that the
117<structfield>reserved</structfield> array must be zeroed as well.</para>
95 118
96 <para>Additional information is required for menu controls: the 119 <para>Additional information is required for menu controls: the
97names of the menu items. To query them applications set the 120names of the menu items. To query them applications set the
@@ -142,38 +165,23 @@ string. This information is intended for the user.</entry>
142 <entry>__s32</entry> 165 <entry>__s32</entry>
143 <entry><structfield>minimum</structfield></entry> 166 <entry><structfield>minimum</structfield></entry>
144 <entry>Minimum value, inclusive. This field gives a lower 167 <entry>Minimum value, inclusive. This field gives a lower
145bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the 168bound for the control. See &v4l2-ctrl-type; how the minimum value is to
146lowest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. 169be used for each possible control type. Note that this a signed 32-bit value.</entry>
147For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value
148gives the minimum length of the string. This length <emphasis>does not include the terminating
149zero</emphasis>. It may not be valid for any other type of control, including
150<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
151signed value.</entry>
152 </row> 170 </row>
153 <row> 171 <row>
154 <entry>__s32</entry> 172 <entry>__s32</entry>
155 <entry><structfield>maximum</structfield></entry> 173 <entry><structfield>maximum</structfield></entry>
156 <entry>Maximum value, inclusive. This field gives an upper 174 <entry>Maximum value, inclusive. This field gives an upper
157bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the 175bound for the control. See &v4l2-ctrl-type; how the maximum value is to
158highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> 176be used for each possible control type. Note that this a signed 32-bit value.</entry>
159controls. For <constant>V4L2_CTRL_TYPE_BITMASK</constant> controls it is the
160set of usable bits.
161For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value
162gives the maximum length of the string. This length <emphasis>does not include the terminating
163zero</emphasis>. It may not be valid for any other type of control, including
164<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
165signed value.</entry>
166 </row> 177 </row>
167 <row> 178 <row>
168 <entry>__s32</entry> 179 <entry>__s32</entry>
169 <entry><structfield>step</structfield></entry> 180 <entry><structfield>step</structfield></entry>
170 <entry><para>This field gives a step size for 181 <entry><para>This field gives a step size for the control.
171<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For 182See &v4l2-ctrl-type; how the step value is to be used for each possible
172<constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to 183control type. Note that this an unsigned 32-bit value.
173the string length that has to be a multiple of this step size. 184</para><para>Generally drivers should not scale hardware
174It may not be valid for any other type of control, including
175<constant>V4L2_CTRL_TYPE_INTEGER64</constant>
176controls.</para><para>Generally drivers should not scale hardware
177control values. It may be necessary for example when the 185control values. It may be necessary for example when the
178<structfield>name</structfield> or <structfield>id</structfield> imply 186<structfield>name</structfield> or <structfield>id</structfield> imply
179a particular unit and the hardware actually accepts only multiples of 187a particular unit and the hardware actually accepts only multiples of
@@ -192,10 +200,11 @@ be always positive.</para></entry>
192 <entry><structfield>default_value</structfield></entry> 200 <entry><structfield>default_value</structfield></entry>
193 <entry>The default value of a 201 <entry>The default value of a
194<constant>V4L2_CTRL_TYPE_INTEGER</constant>, 202<constant>V4L2_CTRL_TYPE_INTEGER</constant>,
195<constant>_BOOLEAN</constant> or <constant>_MENU</constant> control. 203<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>,
196Not valid for other types of controls. Drivers reset controls only 204<constant>_MENU</constant> or <constant>_INTEGER_MENU</constant> control.
197when the driver is loaded, not later, in particular not when the 205Not valid for other types of controls.
198func-open; is called.</entry> 206Note that drivers reset controls to their default value only when the
207driver is first loaded, never afterwards.</entry>
199 </row> 208 </row>
200 <row> 209 <row>
201 <entry>__u32</entry> 210 <entry>__u32</entry>
@@ -213,6 +222,126 @@ the array to zero.</entry>
213 </tgroup> 222 </tgroup>
214 </table> 223 </table>
215 224
225 <table pgwide="1" frame="none" id="v4l2-query-ext-ctrl">
226 <title>struct <structname>v4l2_query_ext_ctrl</structname></title>
227 <tgroup cols="3">
228 &cs-str;
229 <tbody valign="top">
230 <row>
231 <entry>__u32</entry>
232 <entry><structfield>id</structfield></entry>
233 <entry>Identifies the control, set by the application. See
234<xref linkend="control-id" /> for predefined IDs. When the ID is ORed
235with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver clears the
236flag and returns the first non-compound control with a higher ID. When the
237ID is ORed with <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> the driver
238clears the flag and returns the first compound control with a higher ID.
239Set both to get the first control (compound or not) with a higher ID.</entry>
240 </row>
241 <row>
242 <entry>__u32</entry>
243 <entry><structfield>type</structfield></entry>
244 <entry>Type of control, see <xref
245 linkend="v4l2-ctrl-type" />.</entry>
246 </row>
247 <row>
248 <entry>char</entry>
249 <entry><structfield>name</structfield>[32]</entry>
250 <entry>Name of the control, a NUL-terminated ASCII
251string. This information is intended for the user.</entry>
252 </row>
253 <row>
254 <entry>__s64</entry>
255 <entry><structfield>minimum</structfield></entry>
256 <entry>Minimum value, inclusive. This field gives a lower
257bound for the control. See &v4l2-ctrl-type; how the minimum value is to
258be used for each possible control type. Note that this a signed 64-bit value.</entry>
259 </row>
260 <row>
261 <entry>__s64</entry>
262 <entry><structfield>maximum</structfield></entry>
263 <entry>Maximum value, inclusive. This field gives an upper
264bound for the control. See &v4l2-ctrl-type; how the maximum value is to
265be used for each possible control type. Note that this a signed 64-bit value.</entry>
266 </row>
267 <row>
268 <entry>__u64</entry>
269 <entry><structfield>step</structfield></entry>
270 <entry><para>This field gives a step size for the control.
271See &v4l2-ctrl-type; how the step value is to be used for each possible
272control type. Note that this an unsigned 64-bit value.
273</para><para>Generally drivers should not scale hardware
274control values. It may be necessary for example when the
275<structfield>name</structfield> or <structfield>id</structfield> imply
276a particular unit and the hardware actually accepts only multiples of
277said unit. If so, drivers must take care values are properly rounded
278when scaling, such that errors will not accumulate on repeated
279read-write cycles.</para><para>This field gives the smallest change of
280an integer control actually affecting hardware. Often the information
281is needed when the user can change controls by keyboard or GUI
282buttons, rather than a slider. When for example a hardware register
283accepts values 0-511 and the driver reports 0-65535, step should be
284128.</para></entry>
285 </row>
286 <row>
287 <entry>__s64</entry>
288 <entry><structfield>default_value</structfield></entry>
289 <entry>The default value of a
290<constant>V4L2_CTRL_TYPE_INTEGER</constant>, <constant>_INTEGER64</constant>,
291<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>,
292<constant>_MENU</constant>, <constant>_INTEGER_MENU</constant>,
293<constant>_U8</constant> or <constant>_U16</constant> control.
294Not valid for other types of controls.
295Note that drivers reset controls to their default value only when the
296driver is first loaded, never afterwards.
297</entry>
298 </row>
299 <row>
300 <entry>__u32</entry>
301 <entry><structfield>flags</structfield></entry>
302 <entry>Control flags, see <xref
303 linkend="control-flags" />.</entry>
304 </row>
305 <row>
306 <entry>__u32</entry>
307 <entry><structfield>elem_size</structfield></entry>
308 <entry>The size in bytes of a single element of the array.
309Given a char pointer <constant>p</constant> to a 3-dimensional array you can find the
310position of cell <constant>(z, y, x)</constant> as follows:
311<constant>p + ((z * dims[1] + y) * dims[0] + x) * elem_size</constant>. <structfield>elem_size</structfield>
312is always valid, also when the control isn't an array. For string controls
313<structfield>elem_size</structfield> is equal to <structfield>maximum + 1</structfield>.
314</entry>
315 </row>
316 <row>
317 <entry>__u32</entry>
318 <entry><structfield>elems</structfield></entry>
319 <entry>The number of elements in the N-dimensional array. If this control
320is not an array, then <structfield>elems</structfield> is 1. The <structfield>elems</structfield>
321field can never be 0.</entry>
322 </row>
323 <row>
324 <entry>__u32</entry>
325 <entry><structfield>nr_of_dims</structfield></entry>
326 <entry>The number of dimension in the N-dimensional array. If this control
327is not an array, then this field is 0.</entry>
328 </row>
329 <row>
330 <entry>__u32</entry>
331 <entry><structfield>dims[V4L2_CTRL_MAX_DIMS]</structfield></entry>
332 <entry>The size of each dimension. The first <structfield>nr_of_dims</structfield>
333elements of this array must be non-zero, all remaining elements must be zero.</entry>
334 </row>
335 <row>
336 <entry>__u32</entry>
337 <entry><structfield>reserved</structfield>[32]</entry>
338 <entry>Reserved for future extensions. Applications and drivers
339must set the array to zero.</entry>
340 </row>
341 </tbody>
342 </tgroup>
343 </table>
344
216 <table pgwide="1" frame="none" id="v4l2-querymenu"> 345 <table pgwide="1" frame="none" id="v4l2-querymenu">
217 <title>struct <structname>v4l2_querymenu</structname></title> 346 <title>struct <structname>v4l2_querymenu</structname></title>
218 <tgroup cols="4"> 347 <tgroup cols="4">
@@ -347,11 +476,14 @@ Drivers must ignore the value passed with
347 </row> 476 </row>
348 <row> 477 <row>
349 <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry> 478 <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry>
350 <entry>n/a</entry> 479 <entry>any</entry>
351 <entry>n/a</entry> 480 <entry>any</entry>
352 <entry>n/a</entry> 481 <entry>any</entry>
353 <entry>A 64-bit integer valued control. Minimum, maximum 482 <entry>A 64-bit integer valued control. Minimum, maximum
354and step size cannot be queried.</entry> 483and step size cannot be queried using <constant>VIDIOC_QUERYCTRL</constant>.
484Only <constant>VIDIOC_QUERY_EXT_CTRL</constant> can retrieve the 64-bit
485min/max/step values, they should be interpreted as n/a when using
486<constant>VIDIOC_QUERYCTRL</constant>.</entry>
355 </row> 487 </row>
356 <row> 488 <row>
357 <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> 489 <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry>
@@ -379,6 +511,26 @@ ioctl returns the name of the control class and this control type.
379Older drivers which do not support this feature return an 511Older drivers which do not support this feature return an
380&EINVAL;.</entry> 512&EINVAL;.</entry>
381 </row> 513 </row>
514 <row>
515 <entry><constant>V4L2_CTRL_TYPE_U8</constant></entry>
516 <entry>any</entry>
517 <entry>any</entry>
518 <entry>any</entry>
519 <entry>An unsigned 8-bit valued control ranging from minimum to
520maximum inclusive. The step value indicates the increment between
521values which are actually different on the hardware.
522</entry>
523 </row>
524 <row>
525 <entry><constant>V4L2_CTRL_TYPE_U16</constant></entry>
526 <entry>any</entry>
527 <entry>any</entry>
528 <entry>any</entry>
529 <entry>An unsigned 16-bit valued control ranging from minimum to
530maximum inclusive. The step value indicates the increment between
531values which are actually different on the hardware.
532</entry>
533 </row>
382 </tbody> 534 </tbody>
383 </tgroup> 535 </tgroup>
384 </table> 536 </table>
@@ -450,6 +602,14 @@ is in auto-gain mode. In such a case the hardware calculates the gain value base
450the lighting conditions which can change over time. Note that setting a new value for 602the lighting conditions which can change over time. Note that setting a new value for
451a volatile control will have no effect. The new value will just be ignored.</entry> 603a volatile control will have no effect. The new value will just be ignored.</entry>
452 </row> 604 </row>
605 <row>
606 <entry><constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant></entry>
607 <entry>0x0100</entry>
608 <entry>This control has a pointer type, so its value has to be accessed
609using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls
610that are an array, string, or have a compound type. In all cases you have to set a
611pointer to memory containing the payload of the control.</entry>
612 </row>
453 </tbody> 613 </tbody>
454 </tgroup> 614 </tgroup>
455 </table> 615 </table>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
index 17efa870d4d2..9f6095608837 100644
--- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
@@ -175,6 +175,14 @@
175 </entry> 175 </entry>
176 </row> 176 </row>
177 <row> 177 <row>
178 <entry><constant>V4L2_EVENT_MOTION_DET</constant></entry>
179 <entry>5</entry>
180 <entry>
181 <para>Triggered whenever the motion detection state for one or more of the regions
182 changes. This event has a &v4l2-event-motion-det; associated with it.</para>
183 </entry>
184 </row>
185 <row>
178 <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry> 186 <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
179 <entry>0x08000000</entry> 187 <entry>0x08000000</entry>
180 <entry>Base event number for driver-private events.</entry> 188 <entry>Base event number for driver-private events.</entry>
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-12 06:38:00 -0500