1<html><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.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="user-func.html" title="Appendix A. Function Reference"><link rel="prev" href="vidioc-dbg-g-chip-info.html" title="ioctl VIDIOC_DBG_G_CHIP_INFO"><link rel="next" href="vidioc-decoder-cmd.html" title="ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><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="vidioc-dbg-g-chip-info.html">Prev</a> </td><th width="60%" align="center">Appendix A. Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="vidioc-decoder-cmd.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="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"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><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" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><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 2*<var class="pdparam">argp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1112147420"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>fd</code></em></span></dt><dd><p>File descriptor returned by <a class="link" href="func-open.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"><a name="idp1112151540"></a><h2>Description</h2><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Experimental</h3><p>This is an <a class="link" href="hist-v4l2.html#experimental" title="Experimental API Elements">experimental</a> 3interface and may change in the future.</p></div><p>For driver debugging purposes these ioctls allow test 4applications to access hardware registers directly. Regular 5applications must not use them.</p><p>Since writing or even reading registers can jeopardize the 6system security, its stability and damage the hardware, both ioctls 7require superuser privileges. Additionally the Linux kernel must be 8compiled with the <code class="constant">CONFIG_VIDEO_ADV_DEBUG</code> option 9to enable these ioctls.</p><p>To write a register applications must initialize all fields 10of a struct <a class="link" href="vidioc-dbg-g-register.html#v4l2-dbg-register" title="Table A.8. struct v4l2_dbg_register">v4l2_dbg_register</a> except for <em class="structfield"><code>size</code></em> and call 11<code class="constant">VIDIOC_DBG_S_REGISTER</code> with a pointer to this 12structure. The <em class="structfield"><code>match.type</code></em> and 13<em class="structfield"><code>match.addr</code></em> or <em class="structfield"><code>match.name</code></em> 14fields select a chip on the TV 15card, the <em class="structfield"><code>reg</code></em> field specifies a register 16number and the <em class="structfield"><code>val</code></em> field the value to be 17written into the register.</p><p>To read a register applications must initialize the 18<em class="structfield"><code>match.type</code></em>, 19<em class="structfield"><code>match.addr</code></em> or <em class="structfield"><code>match.name</code></em> and 20<em class="structfield"><code>reg</code></em> fields, and call 21<code class="constant">VIDIOC_DBG_G_REGISTER</code> with a pointer to this 22structure. On success the driver stores the register value in the 23<em class="structfield"><code>val</code></em> field and the size (in bytes) of the 24value in <em class="structfield"><code>size</code></em>.</p><p>When <em class="structfield"><code>match.type</code></em> is 25<code class="constant">V4L2_CHIP_MATCH_BRIDGE</code>, 26<em class="structfield"><code>match.addr</code></em> selects the nth non-sub-device chip 27on the TV card. The number zero always selects the host chip, e. g. the 28chip connected to the PCI or USB bus. You can find out which chips are 29present with the <a class="link" href="vidioc-dbg-g-chip-info.html" title="ioctl VIDIOC_DBG_G_CHIP_INFO"><code class="constant">VIDIOC_DBG_G_CHIP_INFO</code></a> ioctl.</p><p>When <em class="structfield"><code>match.type</code></em> is 30<code class="constant">V4L2_CHIP_MATCH_SUBDEV</code>, 31<em class="structfield"><code>match.addr</code></em> selects the nth sub-device.</p><p>These ioctls are optional, not all drivers may support them. 32However when a driver supports these ioctls it must also support 33<a class="link" href="vidioc-dbg-g-chip-info.html" title="ioctl VIDIOC_DBG_G_CHIP_INFO"><code class="constant">VIDIOC_DBG_G_CHIP_INFO</code></a>. Conversely it may support 34<code class="constant">VIDIOC_DBG_G_CHIP_INFO</code> but not these ioctls.</p><p><code class="constant">VIDIOC_DBG_G_REGISTER</code> and 35<code class="constant">VIDIOC_DBG_S_REGISTER</code> were introduced in Linux 362.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> 37utility over calling these ioctls directly. It is available from the 38LinuxTV v4l-dvb repository; see <a class="ulink" href="http://linuxtv.org/repo/" target="_top">http://linuxtv.org/repo/</a> for 39access instructions.</p><div class="table"><a name="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 class="c1"><col class="c2"><col class="c3"><col class="c4"></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="vidioc-dbg-g-register.html#chip-match-types" title="Table A.9. Chip Match Types">Table A.9, “Chip Match Types”</a> for a list of 40possible 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 41to 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 42to the <em class="structfield"><code>type</code></em> field. Currently unused.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="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 class="c1"><col class="c2"><col class="c4"><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="vidioc-dbg-g-register.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">__u32</td><td valign="top"><em class="structfield"><code>size</code></em></td><td valign="top">The register size in bytes.</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 43register.</td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="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 class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_CHIP_MATCH_BRIDGE</code></td><td valign="top">0</td><td valign="top">Match the nth chip on the card, zero for the 44 bridge chip. Does not match sub-devices.</td></tr><tr><td valign="top"><code class="constant">V4L2_CHIP_MATCH_SUBDEV</code></td><td valign="top">4</td><td valign="top">Match the nth sub-device.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="idp1112183940"></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. The generic error codes are described at the <a class="link" href="gen_errors.html#gen-errors" title="Table 19.1. Generic error codes">Generic Error Codes</a> chapter.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorcode">EPERM</span></span></dt><dd><p>Insufficient permissions. Root privileges are required 45to 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="vidioc-dbg-g-chip-info.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-func.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="vidioc-decoder-cmd.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ioctl VIDIOC_DBG_G_CHIP_INFO </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD</td></tr></table></div></body></html> 46