<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REL="HOME" TITLE="Video for Linux Two API Specification" HREF="book1.htm"><LINK REL="UP" TITLE="Function Reference" HREF="r7624.htm"><LINK REL="PREVIOUS" TITLE="ioctl VIDIOC_CROPCAP" HREF="r7771.htm"><LINK REL="NEXT" TITLE="ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD" HREF="r8087.htm"></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >Video for Linux Two API Specification: Revision 0.24</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="r7771.htm" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="r8087.htm" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="VIDIOC-DBG-G-REGISTER" ></A >ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN7904" ></A ><H2 >Name</H2 >VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER -- Read or write hardware registers</DIV ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN7908" ></A ><H2 >Synopsis</H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN7909" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int ioctl</CODE >(int fd, int request, struct v4l2_register *argp);</CODE ></P ><P ></P ></DIV ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN7919" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int ioctl</CODE >(int fd, int request, const struct v4l2_register *argp);</CODE ></P ><P ></P ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN7929" ></A ><H2 >Arguments</H2 ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="PARAMETER" >fd</CODE ></DT ><DD ><P >File descriptor returned by <A HREF="r14090.htm" ><CODE CLASS="FUNCTION" >open()</CODE ></A >.</P ></DD ><DT ><CODE CLASS="PARAMETER" >request</CODE ></DT ><DD ><P >VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</P ></DD ><DT ><CODE CLASS="PARAMETER" >argp</CODE ></DT ><DD ><P ></P ></DD ></DL ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN7949" ></A ><H2 >Description</H2 ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Experimental: </B >This is an <A HREF="x16453.htm" >experimental</A > interface and may change in the future.</P ></BLOCKQUOTE ></DIV ><P >For driver debugging purposes these ioctls allow test applications to access hardware registers directly. Regular applications should 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 HREF="r7900.htm#V4L2-REGISTER" >v4l2_register</A > and call <CODE CLASS="CONSTANT" >VIDIOC_DBG_S_REGISTER</CODE > with a pointer to this structure. The <CODE CLASS="STRUCTFIELD" >match_type</CODE > and <CODE CLASS="STRUCTFIELD" >match_chip</CODE > fields select a chip on the TV card, the <CODE CLASS="STRUCTFIELD" >reg</CODE > field specifies a register number and the <CODE CLASS="STRUCTFIELD" >val</CODE > field the value to be written into the register.</P ><P >To read a register applications must initialize the <CODE CLASS="STRUCTFIELD" >match_type</CODE >, <CODE CLASS="STRUCTFIELD" >match_chip</CODE > and <CODE CLASS="STRUCTFIELD" >reg</CODE > 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 <CODE CLASS="STRUCTFIELD" >val</CODE > field. On failure the structure remains unchanged.</P ><P >When <CODE CLASS="STRUCTFIELD" >match_type</CODE > is <CODE CLASS="CONSTANT" >V4L2_CHIP_MATCH_HOST</CODE >, <CODE CLASS="STRUCTFIELD" >match_chip</CODE > selects the nth non-I<SUP >2</SUP >C chip on the TV card. Drivers may also interpret <CODE CLASS="STRUCTFIELD" >match_chip</CODE > as a random ID, but we recommend against that. The number zero always selects the host chip, e. g. the chip connected to the PCI bus. You can find out which chips are present with the <A HREF="r9804.htm" ><CODE CLASS="CONSTANT" >VIDIOC_G_CHIP_IDENT</CODE ></A > ioctl.</P ><P >When <CODE CLASS="STRUCTFIELD" >match_type</CODE > is <CODE CLASS="CONSTANT" >V4L2_CHIP_MATCH_I2C_DRIVER</CODE >, <CODE CLASS="STRUCTFIELD" >match_chip</CODE > contains a driver ID as defined in the <TT CLASS="FILENAME" >linux/i2c-id.h</TT > header file. For instance <CODE CLASS="CONSTANT" >I2C_DRIVERID_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 HREF="r9804.htm" ><CODE CLASS="CONSTANT" >VIDIOC_G_CHIP_IDENT</CODE ></A > ioctl you can find out which I<SUP >2</SUP >C chips are present.</P ><P >When <CODE CLASS="STRUCTFIELD" >match_type</CODE > is <CODE CLASS="CONSTANT" >V4L2_CHIP_MATCH_I2C_ADDR</CODE >, <CODE CLASS="STRUCTFIELD" >match_chip</CODE > selects a chip by its 7 bit I<SUP >2</SUP >C bus address.</P ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Success not guaranteed: </B >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 HREF="r9804.htm" ><CODE CLASS="CONSTANT" >VIDIOC_G_CHIP_IDENT</CODE ></A > call confirming the presence of the selected I<SUP >2</SUP >C chip.</P ></BLOCKQUOTE ></DIV ><P >These ioctls are optional, not all drivers may support them. However when a driver supports these ioctls it must also support <A HREF="r9804.htm" ><CODE CLASS="CONSTANT" >VIDIOC_G_CHIP_IDENT</CODE ></A >. Conversely it may support <CODE CLASS="CONSTANT" >VIDIOC_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.</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 HREF="http://linuxtv.org/repo/" TARGET="_top" >http://linuxtv.org/repo/</A > for access instructions.</P ><DIV CLASS="TABLE" ><A NAME="V4L2-REGISTER" ></A ><P ><B >Table 1. struct <CODE CLASS="STRUCTNAME" >v4l2_register</CODE ></B ></P ><TABLE BORDER="0" FRAME="void" WIDTH="100%" CLASS="CALSTABLE" ><COL WIDTH="33%" TITLE="C1"><COL WIDTH="33%" TITLE="C2"><COL WIDTH="33%" TITLE="C4"><COL><TBODY VALIGN="TOP" ><TR ><TD >__u32</TD ><TD ><CODE CLASS="STRUCTFIELD" >match_type</CODE ></TD ><TD >See <A HREF="r7900.htm#CHIP-MATCH-TYPES" >Table 2</A > for a list of possible types.</TD ><TD > </TD ></TR ><TR ><TD >__u32</TD ><TD ><CODE CLASS="STRUCTFIELD" >match_chip</CODE ></TD ><TD >Match a chip by this number, interpreted according to the <CODE CLASS="STRUCTFIELD" >match_type</CODE > field.</TD ><TD > </TD ></TR ><TR ><TD >__u64</TD ><TD ><CODE CLASS="STRUCTFIELD" >reg</CODE ></TD ><TD >A register number.</TD ><TD > </TD ></TR ><TR ><TD >__u64</TD ><TD ><CODE CLASS="STRUCTFIELD" >val</CODE ></TD ><TD >The value read from, or to be written into the register.</TD ><TD > </TD ></TR ></TBODY ></TABLE ></DIV ><DIV CLASS="TABLE" ><A NAME="CHIP-MATCH-TYPES" ></A ><P ><B >Table 2. Chip Match Types</B ></P ><TABLE BORDER="0" FRAME="void" WIDTH="100%" CLASS="CALSTABLE" ><COL WIDTH="38%" TITLE="C1"><COL WIDTH="12%" TITLE="C2"><COL WIDTH="50%" TITLE="C3"><TBODY VALIGN="TOP" ><TR ><TD ><CODE CLASS="CONSTANT" >V4L2_CHIP_MATCH_HOST</CODE ></TD ><TD >0</TD ><TD >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 ><CODE CLASS="CONSTANT" >V4L2_CHIP_MATCH_I2C_DRIVER</CODE ></TD ><TD >1</TD ><TD >Match an I<SUP >2</SUP >C chip by its driver ID from the <TT CLASS="FILENAME" >linux/i2c-id.h</TT > header file.</TD ></TR ><TR ><TD ><CODE CLASS="CONSTANT" >V4L2_CHIP_MATCH_I2C_ADDR</CODE ></TD ><TD >2</TD ><TD >Match a chip by its 7 bit I<SUP >2</SUP >C bus address.</TD ></TR ></TBODY ></TABLE ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN8068" ></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 ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><SPAN CLASS="ERRORCODE" >EINVAL</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 <CODE CLASS="STRUCTFIELD" >match_type</CODE > is invalid, or the selected chip or register does not exist.</P ></DD ><DT ><SPAN CLASS="ERRORCODE" >EPERM</SPAN ></DT ><DD ><P >Insufficient permissions. Root privileges are required to execute these ioctls.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="r7771.htm" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="book1.htm" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="r8087.htm" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >ioctl VIDIOC_CROPCAP</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="r7624.htm" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</TD ></TR ></TABLE ></DIV ></BODY ></HTML >