vidioc-dbg-g-register.xml 7.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78
<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
79
of a &v4l2-dbg-register; except for <structfield>size</structfield> and call
80 81 82 83 84 85 86 87 88 89
<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>,
90
<structfield>match.addr</structfield> or <structfield>match.name</structfield> and
91 92 93
<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
94 95
<structfield>val</structfield> field and the size (in bytes) of the
value in <structfield>size</structfield>.</para>
96 97

    <para>When <structfield>match.type</structfield> is
98 99
<constant>V4L2_CHIP_MATCH_BRIDGE</constant>,
<structfield>match.addr</structfield> selects the nth non-sub-device chip
100 101
on the TV card.  The number zero always selects the host chip, &eg; the
chip connected to the PCI or USB bus. You can find out which chips are
102
present with the &VIDIOC-DBG-G-CHIP-INFO; ioctl.</para>
103

104
    <para>When <structfield>match.type</structfield> is
105
<constant>V4L2_CHIP_MATCH_SUBDEV</constant>,
106 107
<structfield>match.addr</structfield> selects the nth sub-device.</para>

108 109
    <para>These ioctls are optional, not all drivers may support them.
However when a driver supports these ioctls it must also support
110 111
&VIDIOC-DBG-G-CHIP-INFO;. Conversely it may support
<constant>VIDIOC_DBG_G_CHIP_INFO</constant> but not these ioctls.</para>
112 113 114 115 116 117 118 119

    <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
120
url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for
121 122
access instructions.</para>

123
    <!-- Note for convenience vidioc-dbg-g-chip-info.sgml
124 125 126 127 128 129 130 131 132
	 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>
133
	    <entry>See <xref linkend="chip-match-types" /> for a list of
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
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
152
to the <structfield>type</structfield> field. Currently unused.</entry>
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
	  </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>
171 172 173 174 175
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>size</structfield></entry>
	    <entry>The register size in bytes.</entry>
	  </row>
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190
	  <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>

191
    <!-- Note for convenience vidioc-dbg-g-chip-info.sgml
192 193 194 195 196 197 198
	 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>
199
	    <entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry>
200 201
	    <entry>0</entry>
	    <entry>Match the nth chip on the card, zero for the
202
	    bridge chip. Does not match sub-devices.</entry>
203
	  </row>
204
	  <row>
205
	    <entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry>
206 207 208
	    <entry>4</entry>
	    <entry>Match the nth sub-device.</entry>
	  </row>
209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
	</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>