123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227 |
- <refentry id="vidioc-dbg-g-register">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname>VIDIOC_DBG_G_REGISTER</refname>
- <refname>VIDIOC_DBG_S_REGISTER</refname>
- <refpurpose>Read or write hardware registers</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_register *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_dbg_register
- *<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_REGISTER, VIDIOC_DBG_S_REGISTER</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 these ioctls allow test
- applications to access hardware registers directly. Regular
- applications must not use them.</para>
- <para>Since writing or even reading registers can jeopardize the
- system security, its stability and damage the hardware, both ioctls
- require superuser privileges. Additionally the Linux kernel must be
- compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option
- to enable these ioctls.</para>
- <para>To write a register applications must initialize all fields
- of a &v4l2-dbg-register; except for <structfield>size</structfield> and call
- <constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this
- structure. The <structfield>match.type</structfield> and
- <structfield>match.addr</structfield> or <structfield>match.name</structfield>
- fields select a chip on the TV
- card, the <structfield>reg</structfield> field specifies a register
- number and the <structfield>val</structfield> field the value to be
- written into the register.</para>
- <para>To read a register applications must initialize the
- <structfield>match.type</structfield>,
- <structfield>match.addr</structfield> or <structfield>match.name</structfield> and
- <structfield>reg</structfield> fields, and call
- <constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this
- structure. On success the driver stores the register value in the
- <structfield>val</structfield> field and the size (in bytes) of the
- value in <structfield>size</structfield>.</para>
- <para>When <structfield>match.type</structfield> is
- <constant>V4L2_CHIP_MATCH_BRIDGE</constant>,
- <structfield>match.addr</structfield> selects the nth non-sub-device chip
- on the TV card. The number zero always selects the host chip, ⪚ the
- chip connected to the PCI or USB bus. You can find out which chips are
- present with the &VIDIOC-DBG-G-CHIP-INFO; ioctl.</para>
- <para>When <structfield>match.type</structfield> is
- <constant>V4L2_CHIP_MATCH_SUBDEV</constant>,
- <structfield>match.addr</structfield> selects the nth sub-device.</para>
- <para>These ioctls are optional, not all drivers may support them.
- However when a driver supports these ioctls it must also support
- &VIDIOC-DBG-G-CHIP-INFO;. Conversely it may support
- <constant>VIDIOC_DBG_G_CHIP_INFO</constant> but not these ioctls.</para>
- <para><constant>VIDIOC_DBG_G_REGISTER</constant> and
- <constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux
- 2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para>
- <para>We recommended the <application>v4l2-dbg</application>
- utility over calling these ioctls 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-chip-info.sgml
- contains a duplicate of this table. -->
- <table pgwide="1" frame="none" id="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="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. Currently unused.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table pgwide="1" frame="none" id="v4l2-dbg-register">
- <title>struct <structname>v4l2_dbg_register</structname></title>
- <tgroup cols="4">
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c4" />
- <tbody valign="top">
- <row>
- <entry>struct v4l2_dbg_match</entry>
- <entry><structfield>match</structfield></entry>
- <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>size</structfield></entry>
- <entry>The register size in bytes.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>reg</structfield></entry>
- <entry>A register number.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>val</structfield></entry>
- <entry>The value read from, or to be written into the
- register.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <!-- Note for convenience vidioc-dbg-g-chip-info.sgml
- contains a duplicate of this table. -->
- <table pgwide="1" frame="none" id="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_SUBDEV</constant></entry>
- <entry>4</entry>
- <entry>Match the nth sub-device.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
- <refsect1>
- &return-value;
- <variablelist>
- <varlistentry>
- <term><errorcode>EPERM</errorcode></term>
- <listitem>
- <para>Insufficient permissions. Root privileges are required
- to execute these ioctls.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- </refentry>
|