Commit d7a11e1f18e1b6772af0e7670baa83ce8c3b2674
Committed by
Mauro Carvalho Chehab
Mauro Carvalho Chehab
1 parent
1ff7ebe23d
Exists in
smarc-l5.0.0_1.0.0-ga
and in
5 other branches
[media] DocBook: fix awkward language and fix the documented return value
The Video Standard section contains some awkward language. It also wasn't updated when the error code for unimplemented ioctls changed from EINVAL to ENOTTY. [mchehab@redhat.com: remove a misplaced footnote tag] Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Showing 1 changed file with 14 additions and 16 deletions Side-by-side Diff
Documentation/DocBook/media/v4l/common.xml
| ... | ... | @@ -564,7 +564,7 @@ |
| 564 | 564 | <para>To query and select the standard used by the current video |
| 565 | 565 | input or output applications call the &VIDIOC-G-STD; and |
| 566 | 566 | &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis> |
| 567 | -standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote> | |
| 567 | +standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote> | |
| 568 | 568 | <para>An alternative to the current scheme is to use pointers |
| 569 | 569 | to indices as arguments of <constant>VIDIOC_G_STD</constant> and |
| 570 | 570 | <constant>VIDIOC_S_STD</constant>, the &v4l2-input; and |
| 571 | 571 | |
| 572 | 572 | |
| 573 | 573 | |
| 574 | 574 | |
| ... | ... | @@ -588,30 +588,28 @@ |
| 588 | 588 | </footnote> Drivers must implement all video standard ioctls |
| 589 | 589 | when the device has one or more video inputs or outputs.</para> |
| 590 | 590 | |
| 591 | - <para>Special rules apply to USB cameras where the notion of video | |
| 592 | -standards makes little sense. More generally any capture device, | |
| 593 | -output devices accordingly, which is <itemizedlist> | |
| 591 | + <para>Special rules apply to devices such as USB cameras where the notion of video | |
| 592 | +standards makes little sense. More generally for any capture or output device | |
| 593 | +which is: <itemizedlist> | |
| 594 | 594 | <listitem> |
| 595 | 595 | <para>incapable of capturing fields or frames at the nominal |
| 596 | 596 | rate of the video standard, or</para> |
| 597 | 597 | </listitem> |
| 598 | 598 | <listitem> |
| 599 | - <para>where <link linkend="buffer">timestamps</link> refer | |
| 600 | -to the instant the field or frame was received by the driver, not the | |
| 601 | -capture time, or</para> | |
| 599 | + <para>that does not support the video standard formats at all.</para> | |
| 602 | 600 | </listitem> |
| 603 | - <listitem> | |
| 604 | - <para>where <link linkend="buffer">sequence numbers</link> | |
| 605 | -refer to the frames received by the driver, not the captured | |
| 606 | -frames.</para> | |
| 607 | - </listitem> | |
| 608 | 601 | </itemizedlist> Here the driver shall set the |
| 609 | 602 | <structfield>std</structfield> field of &v4l2-input; and &v4l2-output; |
| 610 | -to zero, the <constant>VIDIOC_G_STD</constant>, | |
| 603 | +to zero and the <constant>VIDIOC_G_STD</constant>, | |
| 611 | 604 | <constant>VIDIOC_S_STD</constant>, |
| 612 | 605 | <constant>VIDIOC_QUERYSTD</constant> and |
| 613 | 606 | <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the |
| 614 | -&EINVAL;.<footnote> | |
| 607 | +&ENOTTY;.<footnote> | |
| 608 | + <para>See <xref linkend="buffer" /> for a rationale.</para> | |
| 609 | + <para>Applications can make use of the <xref linkend="input-capabilities" /> and | |
| 610 | +<xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls | |
| 611 | +are available for the device.</para> | |
| 612 | +&ENOTTY;. | |
| 615 | 613 | <para>See <xref linkend="buffer" /> for a rationale. Probably |
| 616 | 614 | even USB cameras follow some well known video standard. It might have |
| 617 | 615 | been better to explicitly indicate elsewhere if a device cannot live |
| 618 | 616 | |
| ... | ... | @@ -626,9 +624,9 @@ |
| 626 | 624 | &v4l2-standard; standard; |
| 627 | 625 | |
| 628 | 626 | if (-1 == ioctl (fd, &VIDIOC-G-STD;, &std_id)) { |
| 629 | - /* Note when VIDIOC_ENUMSTD always returns EINVAL this | |
| 627 | + /* Note when VIDIOC_ENUMSTD always returns ENOTTY this | |
| 630 | 628 | is no video device or it falls under the USB exception, |
| 631 | - and VIDIOC_G_STD returning EINVAL is no error. */ | |
| 629 | + and VIDIOC_G_STD returning ENOTTY is no error. */ | |
| 632 | 630 | |
| 633 | 631 | perror ("VIDIOC_G_STD"); |
| 634 | 632 | exit (EXIT_FAILURE); |