<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API" /><link rel="up" href="apa.html" title="Appendix A. Function Reference" /><link rel="prev" href="re23.html" title="ioctl VIDIOC_DBG_G_CHIP_IDENT" /><link rel="next" href="re25.html" title="ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re23.html">Prev</a> </td><th width="60%" align="center">Appendix A. Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="re25.html">Next</a></td></tr></table><hr /></div><div class="refentry" title="ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER"><a id="vidioc-dbg-g-register"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER — Read or write hardware registers</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ioctl</b>(</code></td><td>int <var class="pdparam">fd</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">request</var>, </td></tr><tr><td> </td><td>struct v4l2_dbg_register *<var class="pdparam">argp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ioctl</b>(</code></td><td>int <var class="pdparam">fd</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">request</var>, </td></tr><tr><td> </td><td>const struct v4l2_dbg_register *<var class="pdparam">argp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Arguments"><a id="id2688373"></a><h2>Arguments</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>fd</code></em></span></dt><dd><p>File descriptor returned by <a class="link" href="re64.html" title="V4L2 open()"><code class="function">open()</code></a>.</p></dd><dt><span class="term"><em class="parameter"><code>request</code></em></span></dt><dd><p>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</p></dd><dt><span class="term"><em class="parameter"><code>argp</code></em></span></dt><dd><p></p></dd></dl></div></div><div class="refsect1" title="Description"><a id="id2688442"></a><h2>Description</h2><div class="note" title="Experimental" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Experimental</h3><p>This is an <a class="link" href="ch07s04.html" title="Experimental API Elements">experimental</a> interface and may change in the future.</p></div><p>For driver debugging purposes these ioctls allow test applications to access hardware registers directly. Regular applications must not use them.</p><p>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 <code class="constant">CONFIG_VIDEO_ADV_DEBUG</code> option to enable these ioctls.</p><p>To write a register applications must initialize all fields of a struct <a class="link" href="re24.html#v4l2-dbg-register" title="Table A.8. struct v4l2_dbg_register">v4l2_dbg_register</a> and call <code class="constant">VIDIOC_DBG_S_REGISTER</code> with a pointer to this structure. The <em class="structfield"><code>match.type</code></em> and <em class="structfield"><code>match.addr</code></em> or <em class="structfield"><code>match.name</code></em> fields select a chip on the TV card, the <em class="structfield"><code>reg</code></em> field specifies a register number and the <em class="structfield"><code>val</code></em> field the value to be written into the register.</p><p>To read a register applications must initialize the <em class="structfield"><code>match.type</code></em>, <em class="structfield"><code>match.chip</code></em> or <em class="structfield"><code>match.name</code></em> and <em class="structfield"><code>reg</code></em> fields, and call <code class="constant">VIDIOC_DBG_G_REGISTER</code> with a pointer to this structure. On success the driver stores the register value in the <em class="structfield"><code>val</code></em> field. On failure the structure remains unchanged.</p><p>When <em class="structfield"><code>match.type</code></em> is <code class="constant">V4L2_CHIP_MATCH_HOST</code>, <em class="structfield"><code>match.addr</code></em> selects the nth non-I<sup>2</sup>C chip on the TV card. The number zero always selects the host chip, e. g. the chip connected to the PCI or USB bus. You can find out which chips are present with the <a class="link" href="re23.html" title="ioctl VIDIOC_DBG_G_CHIP_IDENT"><code class="constant">VIDIOC_DBG_G_CHIP_IDENT</code></a> ioctl.</p><p>When <em class="structfield"><code>match.type</code></em> is <code class="constant">V4L2_CHIP_MATCH_I2C_DRIVER</code>, <em class="structfield"><code>match.name</code></em> contains the I2C driver name. For instance <code class="constant">"saa7127"</code> will match any chip supported by the saa7127 driver, regardless of its I<sup>2</sup>C bus address. When multiple chips supported by the same driver are present, the effect of these ioctls is undefined. Again with the <a class="link" href="re23.html" title="ioctl VIDIOC_DBG_G_CHIP_IDENT"><code class="constant">VIDIOC_DBG_G_CHIP_IDENT</code></a> ioctl you can find out which I<sup>2</sup>C chips are present.</p><p>When <em class="structfield"><code>match.type</code></em> is <code class="constant">V4L2_CHIP_MATCH_I2C_ADDR</code>, <em class="structfield"><code>match.addr</code></em> selects a chip by its 7 bit I<sup>2</sup>C bus address.</p><p>When <em class="structfield"><code>match.type</code></em> is <code class="constant">V4L2_CHIP_MATCH_AC97</code>, <em class="structfield"><code>match.addr</code></em> selects the nth AC97 chip on the TV card.</p><div class="note" title="Success not guaranteed" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Success not guaranteed</h3><p>Due to a flaw in the Linux I<sup>2</sup>C bus driver these ioctls may return successfully without actually reading or writing a register. To catch the most likely failure we recommend a <a class="link" href="re23.html" title="ioctl VIDIOC_DBG_G_CHIP_IDENT"><code class="constant">VIDIOC_DBG_G_CHIP_IDENT</code></a> call confirming the presence of the selected I<sup>2</sup>C chip.</p></div><p>These ioctls are optional, not all drivers may support them. However when a driver supports these ioctls it must also support <a class="link" href="re23.html" title="ioctl VIDIOC_DBG_G_CHIP_IDENT"><code class="constant">VIDIOC_DBG_G_CHIP_IDENT</code></a>. Conversely it may support <code class="constant">VIDIOC_DBG_G_CHIP_IDENT</code> but not these ioctls.</p><p><code class="constant">VIDIOC_DBG_G_REGISTER</code> and <code class="constant">VIDIOC_DBG_S_REGISTER</code> were introduced in Linux 2.6.21, but their API was changed to the one described here in kernel 2.6.29.</p><p>We recommended the <span class="application">v4l2-dbg</span> utility over calling these ioctls directly. It is available from the LinuxTV v4l-dvb repository; see <a class="ulink" href="http://linuxtv.org/repo/" target="_top">http://linuxtv.org/repo/</a> for access instructions.</p><div class="table"><a id="v4l2-dbg-match"></a><p class="title"><b>Table A.7. struct <span class="structname">v4l2_dbg_match</span></b></p><div class="table-contents"><table summary="struct v4l2_dbg_match" width="100%" border="0"><colgroup><col /><col /><col /><col /></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>type</code></em></td><td valign="top">See <a class="xref" href="re23.html#ident-chip-match-types" title="Table A.5. Chip Match Types">Table A.5, “Chip Match Types”</a> for a list of possible types.</td><td class="auto-generated"> </td></tr><tr><td valign="top">union</td><td valign="top">(anonymous)</td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td valign="top"> </td><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>addr</code></em></td><td valign="top">Match a chip by this number, interpreted according to the <em class="structfield"><code>type</code></em> field.</td></tr><tr><td valign="top"> </td><td valign="top">char</td><td valign="top"><em class="structfield"><code>name[32]</code></em></td><td valign="top">Match a chip by this name, interpreted according to the <em class="structfield"><code>type</code></em> field.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="v4l2-dbg-register"></a><p class="title"><b>Table A.8. struct <span class="structname">v4l2_dbg_register</span></b></p><div class="table-contents"><table summary="struct v4l2_dbg_register" width="100%" border="0"><colgroup><col /><col /><col /><col /></colgroup><tbody valign="top"><tr><td valign="top">struct v4l2_dbg_match</td><td valign="top"><em class="structfield"><code>match</code></em></td><td valign="top">How to match the chip, see <a class="xref" href="re24.html#v4l2-dbg-match" title="Table A.7. struct v4l2_dbg_match">Table A.7, “struct <span class="structname">v4l2_dbg_match</span>”</a>.</td><td class="auto-generated"> </td></tr><tr><td valign="top">__u64</td><td valign="top"><em class="structfield"><code>reg</code></em></td><td valign="top">A register number.</td><td class="auto-generated"> </td></tr><tr><td valign="top">__u64</td><td valign="top"><em class="structfield"><code>val</code></em></td><td valign="top">The value read from, or to be written into the register.</td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="chip-match-types"></a><p class="title"><b>Table A.9. Chip Match Types</b></p><div class="table-contents"><table summary="Chip Match Types" width="100%" border="0"><colgroup><col /><col /><col /></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_CHIP_MATCH_HOST</code></td><td valign="top">0</td><td valign="top">Match the nth chip on the card, zero for the host chip. Does not match I<sup>2</sup>C chips.</td></tr><tr><td valign="top"><code class="constant">V4L2_CHIP_MATCH_I2C_DRIVER</code></td><td valign="top">1</td><td valign="top">Match an I<sup>2</sup>C chip by its driver name.</td></tr><tr><td valign="top"><code class="constant">V4L2_CHIP_MATCH_I2C_ADDR</code></td><td valign="top">2</td><td valign="top">Match a chip by its 7 bit I<sup>2</sup>C bus address.</td></tr><tr><td valign="top"><code class="constant">V4L2_CHIP_MATCH_AC97</code></td><td valign="top">3</td><td valign="top">Match the nth anciliary AC97 chip.</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="refsect1" title="Return Value"><a id="id2689105"></a><h2>Return Value</h2><p>On success <span class="returnvalue">0</span> is returned, on error <span class="returnvalue">-1</span> and the <code class="varname">errno</code> variable is set appropriately:</p><div class="variablelist"><dl><dt><span class="term"><span class="errorcode">EINVAL</span></span></dt><dd><p>The driver does not support this ioctl, or the kernel was not compiled with the <code class="constant">CONFIG_VIDEO_ADV_DEBUG</code> option, or the <em class="structfield"><code>match_type</code></em> is invalid, or the selected chip or register does not exist.</p></dd><dt><span class="term"><span class="errorcode">EPERM</span></span></dt><dd><p>Insufficient permissions. Root privileges are required to execute these ioctls.</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re23.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="apa.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="re25.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ioctl VIDIOC_DBG_G_CHIP_IDENT </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</td></tr></table></div></body></html>
