-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[media] DocBook media: add VIDIOC_DBG_G_CHIP_NAME documentation
And update the other debug ioctls accordingly. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
- Loading branch information
Hans Verkuil
authored and
Mauro Carvalho Chehab
committed
Mar 25, 2013
1 parent
3b2d17b
commit b5958dc
Showing
4 changed files
with
280 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
234 changes: 234 additions & 0 deletions
234
Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-name.xml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,234 @@ | ||
| <refentry id="vidioc-dbg-g-chip-name"> | ||
| <refmeta> | ||
| <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_NAME</refentrytitle> | ||
| &manvol; | ||
| </refmeta> | ||
|
|
||
| <refnamediv> | ||
| <refname>VIDIOC_DBG_G_CHIP_NAME</refname> | ||
| <refpurpose>Identify the chips on a TV card</refpurpose> | ||
| </refnamediv> | ||
|
|
||
| <refsynopsisdiv> | ||
| <funcsynopsis> | ||
| <funcprototype> | ||
| <funcdef>int <function>ioctl</function></funcdef> | ||
| <paramdef>int <parameter>fd</parameter></paramdef> | ||
| <paramdef>int <parameter>request</parameter></paramdef> | ||
| <paramdef>struct v4l2_dbg_chip_name | ||
| *<parameter>argp</parameter></paramdef> | ||
| </funcprototype> | ||
| </funcsynopsis> | ||
| </refsynopsisdiv> | ||
|
|
||
| <refsect1> | ||
| <title>Arguments</title> | ||
|
|
||
| <variablelist> | ||
| <varlistentry> | ||
| <term><parameter>fd</parameter></term> | ||
| <listitem> | ||
| <para>&fd;</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term><parameter>request</parameter></term> | ||
| <listitem> | ||
| <para>VIDIOC_DBG_G_CHIP_NAME</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term><parameter>argp</parameter></term> | ||
| <listitem> | ||
| <para></para> | ||
| </listitem> | ||
| </varlistentry> | ||
| </variablelist> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>Description</title> | ||
|
|
||
| <note> | ||
| <title>Experimental</title> | ||
|
|
||
| <para>This is an <link | ||
| linkend="experimental">experimental</link> interface and may change in | ||
| the future.</para> | ||
| </note> | ||
|
|
||
| <para>For driver debugging purposes this ioctl allows test | ||
| applications to query the driver about the chips present on the TV | ||
| card. Regular applications must not use it. When you found a chip | ||
| specific bug, please contact the linux-media mailing list (&v4l-ml;) | ||
| so it can be fixed.</para> | ||
|
|
||
| <para>To query the driver applications must initialize the | ||
| <structfield>match.type</structfield> and | ||
| <structfield>match.addr</structfield> or <structfield>match.name</structfield> | ||
| fields of a &v4l2-dbg-chip-name; | ||
| and call <constant>VIDIOC_DBG_G_CHIP_NAME</constant> with a pointer to | ||
| this structure. On success the driver stores information about the | ||
| selected chip in the <structfield>name</structfield> and | ||
| <structfield>flags</structfield> fields. On failure the structure | ||
| remains unchanged.</para> | ||
|
|
||
| <para>When <structfield>match.type</structfield> is | ||
| <constant>V4L2_CHIP_MATCH_BRIDGE</constant>, | ||
| <structfield>match.addr</structfield> selects the nth bridge 'chip' | ||
| on the TV card. You can enumerate all chips by starting at zero and | ||
| incrementing <structfield>match.addr</structfield> by one until | ||
| <constant>VIDIOC_DBG_G_CHIP_NAME</constant> fails with an &EINVAL;. | ||
| The number zero always selects the bridge chip itself, ⪚ the chip | ||
| connected to the PCI or USB bus. Non-zero numbers identify specific | ||
| parts of the bridge chip such as an AC97 register block.</para> | ||
|
|
||
| <para>When <structfield>match.type</structfield> is | ||
| <constant>V4L2_CHIP_MATCH_SUBDEV_NAME</constant>, | ||
| <structfield>match.name</structfield> contains the name of a sub-device. | ||
| For instance | ||
| <constant>"saa7127 6-0044"</constant> will match the saa7127 sub-device | ||
| at the given i2c bus. This match type is not very useful for this ioctl | ||
| and is here only for consistency. | ||
| </para> | ||
|
|
||
| <para>When <structfield>match.type</structfield> is | ||
| <constant>V4L2_CHIP_MATCH_SUBDEV_IDX</constant>, | ||
| <structfield>match.addr</structfield> selects the nth sub-device. This | ||
| allows you to enumerate over all sub-devices.</para> | ||
|
|
||
| <para>On success, the <structfield>name</structfield> field will | ||
| contain a chip name and the <structfield>flags</structfield> field will | ||
| contain <constant>V4L2_CHIP_FL_READABLE</constant> if the driver supports | ||
| reading registers from the device or <constant>V4L2_CHIP_FL_WRITABLE</constant> | ||
| if the driver supports writing registers to the device.</para> | ||
|
|
||
| <para>We recommended the <application>v4l2-dbg</application> | ||
| utility over calling this ioctl directly. It is available from the | ||
| LinuxTV v4l-dvb repository; see <ulink | ||
| url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for | ||
| access instructions.</para> | ||
|
|
||
| <!-- Note for convenience vidioc-dbg-g-register.sgml | ||
| contains a duplicate of this table. --> | ||
| <table pgwide="1" frame="none" id="name-v4l2-dbg-match"> | ||
| <title>struct <structname>v4l2_dbg_match</structname></title> | ||
| <tgroup cols="4"> | ||
| &cs-ustr; | ||
| <tbody valign="top"> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>type</structfield></entry> | ||
| <entry>See <xref linkend="name-chip-match-types" /> for a list of | ||
| possible types.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>union</entry> | ||
| <entry>(anonymous)</entry> | ||
| </row> | ||
| <row> | ||
| <entry></entry> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>addr</structfield></entry> | ||
| <entry>Match a chip by this number, interpreted according | ||
| to the <structfield>type</structfield> field.</entry> | ||
| </row> | ||
| <row> | ||
| <entry></entry> | ||
| <entry>char</entry> | ||
| <entry><structfield>name[32]</structfield></entry> | ||
| <entry>Match a chip by this name, interpreted according | ||
| to the <structfield>type</structfield> field.</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </table> | ||
|
|
||
| <table pgwide="1" frame="none" id="v4l2-dbg-chip-name"> | ||
| <title>struct <structname>v4l2_dbg_chip_name</structname></title> | ||
| <tgroup cols="3"> | ||
| &cs-str; | ||
| <tbody valign="top"> | ||
| <row> | ||
| <entry>struct v4l2_dbg_match</entry> | ||
| <entry><structfield>match</structfield></entry> | ||
| <entry>How to match the chip, see <xref linkend="name-v4l2-dbg-match" />.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>char</entry> | ||
| <entry><structfield>name[32]</structfield></entry> | ||
| <entry>The name of the chip.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>flags</structfield></entry> | ||
| <entry>Set by the driver. If <constant>V4L2_CHIP_FL_READABLE</constant> | ||
| is set, then the driver supports reading registers from the device. If | ||
| <constant>V4L2_CHIP_FL_WRITABLE</constant> is set, then it supports writing registers.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>reserved[8]</structfield></entry> | ||
| <entry>Reserved fields, both application and driver must set these to 0.</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </table> | ||
|
|
||
| <!-- Note for convenience vidioc-dbg-g-register.sgml | ||
| contains a duplicate of this table. --> | ||
| <table pgwide="1" frame="none" id="name-chip-match-types"> | ||
| <title>Chip Match Types</title> | ||
| <tgroup cols="3"> | ||
| &cs-def; | ||
| <tbody valign="top"> | ||
| <row> | ||
| <entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry> | ||
| <entry>0</entry> | ||
| <entry>Match the nth chip on the card, zero for the | ||
| bridge chip. Does not match sub-devices.</entry> | ||
| </row> | ||
| <row> | ||
| <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry> | ||
| <entry>1</entry> | ||
| <entry>Match an &i2c; chip by its driver name. Can't be used with this ioctl.</entry> | ||
| </row> | ||
| <row> | ||
| <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry> | ||
| <entry>2</entry> | ||
| <entry>Match a chip by its 7 bit &i2c; bus address. Can't be used with this ioctl.</entry> | ||
| </row> | ||
| <row> | ||
| <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry> | ||
| <entry>3</entry> | ||
| <entry>Match the nth anciliary AC97 chip. Can't be used with this ioctl.</entry> | ||
| </row> | ||
| <row> | ||
| <entry><constant>V4L2_CHIP_MATCH_SUBDEV_NAME</constant></entry> | ||
| <entry>4</entry> | ||
| <entry>Match the sub-device by name.</entry> | ||
| </row> | ||
| <row> | ||
| <entry><constant>V4L2_CHIP_MATCH_SUBDEV_IDX</constant></entry> | ||
| <entry>5</entry> | ||
| <entry>Match the nth sub-device.</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </table> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| &return-value; | ||
|
|
||
| <variablelist> | ||
| <varlistentry> | ||
| <term><errorcode>EINVAL</errorcode></term> | ||
| <listitem> | ||
| <para>The <structfield>match_type</structfield> is invalid or | ||
| no device could be matched.</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| </variablelist> | ||
| </refsect1> | ||
| </refentry> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters