1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> 2<HTML 3><HEAD 4><TITLE 5>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</TITLE 6><META 7NAME="GENERATOR" 8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 9REL="HOME" 10TITLE="Video for Linux Two API Specification" 11HREF="book1.htm"><LINK 12REL="UP" 13TITLE="Function Reference" 14HREF="r7624.htm"><LINK 15REL="PREVIOUS" 16TITLE="ioctl VIDIOC_CROPCAP" 17HREF="r7771.htm"><LINK 18REL="NEXT" 19TITLE="ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD" 20HREF="r8087.htm"></HEAD 21><BODY 22CLASS="REFENTRY" 23BGCOLOR="#FFFFFF" 24TEXT="#000000" 25LINK="#0000FF" 26VLINK="#840084" 27ALINK="#0000FF" 28><DIV 29CLASS="NAVHEADER" 30><TABLE 31SUMMARY="Header navigation table" 32WIDTH="100%" 33BORDER="0" 34CELLPADDING="0" 35CELLSPACING="0" 36><TR 37><TH 38COLSPAN="3" 39ALIGN="center" 40>Video for Linux Two API Specification: Revision 0.24</TH 41></TR 42><TR 43><TD 44WIDTH="10%" 45ALIGN="left" 46VALIGN="bottom" 47><A 48HREF="r7771.htm" 49ACCESSKEY="P" 50>Prev</A 51></TD 52><TD 53WIDTH="80%" 54ALIGN="center" 55VALIGN="bottom" 56></TD 57><TD 58WIDTH="10%" 59ALIGN="right" 60VALIGN="bottom" 61><A 62HREF="r8087.htm" 63ACCESSKEY="N" 64>Next</A 65></TD 66></TR 67></TABLE 68><HR 69ALIGN="LEFT" 70WIDTH="100%"></DIV 71><H1 72><A 73NAME="VIDIOC-DBG-G-REGISTER" 74></A 75>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</H1 76><DIV 77CLASS="REFNAMEDIV" 78><A 79NAME="AEN7904" 80></A 81><H2 82>Name</H2 83>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER -- Read or write hardware registers</DIV 84><DIV 85CLASS="REFSYNOPSISDIV" 86><A 87NAME="AEN7908" 88></A 89><H2 90>Synopsis</H2 91><DIV 92CLASS="FUNCSYNOPSIS" 93><P 94></P 95><A 96NAME="AEN7909" 97></A 98><P 99><CODE 100><CODE 101CLASS="FUNCDEF" 102>int ioctl</CODE 103>(int fd, int request, struct v4l2_register *argp);</CODE 104></P 105><P 106></P 107></DIV 108><DIV 109CLASS="FUNCSYNOPSIS" 110><P 111></P 112><A 113NAME="AEN7919" 114></A 115><P 116><CODE 117><CODE 118CLASS="FUNCDEF" 119>int ioctl</CODE 120>(int fd, int request, const struct v4l2_register 121*argp);</CODE 122></P 123><P 124></P 125></DIV 126></DIV 127><DIV 128CLASS="REFSECT1" 129><A 130NAME="AEN7929" 131></A 132><H2 133>Arguments</H2 134><P 135></P 136><DIV 137CLASS="VARIABLELIST" 138><DL 139><DT 140><CODE 141CLASS="PARAMETER" 142>fd</CODE 143></DT 144><DD 145><P 146>File descriptor returned by <A 147HREF="r14090.htm" 148><CODE 149CLASS="FUNCTION" 150>open()</CODE 151></A 152>.</P 153></DD 154><DT 155><CODE 156CLASS="PARAMETER" 157>request</CODE 158></DT 159><DD 160><P 161>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</P 162></DD 163><DT 164><CODE 165CLASS="PARAMETER" 166>argp</CODE 167></DT 168><DD 169><P 170></P 171></DD 172></DL 173></DIV 174></DIV 175><DIV 176CLASS="REFSECT1" 177><A 178NAME="AEN7949" 179></A 180><H2 181>Description</H2 182><DIV 183CLASS="NOTE" 184><BLOCKQUOTE 185CLASS="NOTE" 186><P 187><B 188>Experimental: </B 189>This is an <A 190HREF="x16453.htm" 191>experimental</A 192> 193interface and may change in the future.</P 194></BLOCKQUOTE 195></DIV 196><P 197>For driver debugging purposes these ioctls allow test 198applications to access hardware registers directly. Regular 199applications should not use them.</P 200><P 201>Since writing or even reading registers can jeopardize the 202system security, its stability and damage the hardware, both ioctls 203require superuser privileges. Additionally the Linux kernel must be 204compiled with the <CODE 205CLASS="CONSTANT" 206>CONFIG_VIDEO_ADV_DEBUG</CODE 207> option 208to enable these ioctls.</P 209><P 210>To write a register applications must initialize all fields 211of a struct <A 212HREF="r7900.htm#V4L2-REGISTER" 213>v4l2_register</A 214> and call 215<CODE 216CLASS="CONSTANT" 217>VIDIOC_DBG_S_REGISTER</CODE 218> with a pointer to this 219structure. The <CODE 220CLASS="STRUCTFIELD" 221>match_type</CODE 222> and 223<CODE 224CLASS="STRUCTFIELD" 225>match_chip</CODE 226> fields select a chip on the TV 227card, the <CODE 228CLASS="STRUCTFIELD" 229>reg</CODE 230> field specifies a register 231number and the <CODE 232CLASS="STRUCTFIELD" 233>val</CODE 234> field the value to be 235written into the register.</P 236><P 237>To read a register applications must initialize the 238<CODE 239CLASS="STRUCTFIELD" 240>match_type</CODE 241>, 242<CODE 243CLASS="STRUCTFIELD" 244>match_chip</CODE 245> and 246<CODE 247CLASS="STRUCTFIELD" 248>reg</CODE 249> fields, and call 250<CODE 251CLASS="CONSTANT" 252>VIDIOC_DBG_G_REGISTER</CODE 253> with a pointer to this 254structure. On success the driver stores the register value in the 255<CODE 256CLASS="STRUCTFIELD" 257>val</CODE 258> field. On failure the structure remains 259unchanged.</P 260><P 261>When <CODE 262CLASS="STRUCTFIELD" 263>match_type</CODE 264> is 265<CODE 266CLASS="CONSTANT" 267>V4L2_CHIP_MATCH_HOST</CODE 268>, 269<CODE 270CLASS="STRUCTFIELD" 271>match_chip</CODE 272> selects the nth non-I<SUP 273>2</SUP 274>C chip 275on the TV card. Drivers may also interpret 276<CODE 277CLASS="STRUCTFIELD" 278>match_chip</CODE 279> as a random ID, but we recommend 280against that. The number zero always selects the host chip, e. g. the 281chip connected to the PCI bus. You can find out which chips are 282present with the <A 283HREF="r9804.htm" 284><CODE 285CLASS="CONSTANT" 286>VIDIOC_G_CHIP_IDENT</CODE 287></A 288> ioctl.</P 289><P 290>When <CODE 291CLASS="STRUCTFIELD" 292>match_type</CODE 293> is 294<CODE 295CLASS="CONSTANT" 296>V4L2_CHIP_MATCH_I2C_DRIVER</CODE 297>, 298<CODE 299CLASS="STRUCTFIELD" 300>match_chip</CODE 301> contains a driver ID as defined 302in the <TT 303CLASS="FILENAME" 304>linux/i2c-id.h</TT 305> header file. For instance 306<CODE 307CLASS="CONSTANT" 308>I2C_DRIVERID_SAA7127</CODE 309> will match any chip 310supported by the saa7127 driver, regardless of its I<SUP 311>2</SUP 312>C bus address. 313When multiple chips supported by the same driver are present, the 314effect of these ioctls is undefined. Again with the 315<A 316HREF="r9804.htm" 317><CODE 318CLASS="CONSTANT" 319>VIDIOC_G_CHIP_IDENT</CODE 320></A 321> ioctl you can find out which I<SUP 322>2</SUP 323>C chips are 324present.</P 325><P 326>When <CODE 327CLASS="STRUCTFIELD" 328>match_type</CODE 329> is 330<CODE 331CLASS="CONSTANT" 332>V4L2_CHIP_MATCH_I2C_ADDR</CODE 333>, 334<CODE 335CLASS="STRUCTFIELD" 336>match_chip</CODE 337> selects a chip by its 7 bit I<SUP 338>2</SUP 339>C 340bus address.</P 341><DIV 342CLASS="NOTE" 343><BLOCKQUOTE 344CLASS="NOTE" 345><P 346><B 347>Success not guaranteed: </B 348>Due to a flaw in the Linux I<SUP 349>2</SUP 350>C bus driver these ioctls may 351return successfully without actually reading or writing a register. To 352catch the most likely failure we recommend a <A 353HREF="r9804.htm" 354><CODE 355CLASS="CONSTANT" 356>VIDIOC_G_CHIP_IDENT</CODE 357></A 358> 359call confirming the presence of the selected I<SUP 360>2</SUP 361>C chip.</P 362></BLOCKQUOTE 363></DIV 364><P 365>These ioctls are optional, not all drivers may support them. 366However when a driver supports these ioctls it must also support 367<A 368HREF="r9804.htm" 369><CODE 370CLASS="CONSTANT" 371>VIDIOC_G_CHIP_IDENT</CODE 372></A 373>. Conversely it may support 374<CODE 375CLASS="CONSTANT" 376>VIDIOC_G_CHIP_IDENT</CODE 377> but not these ioctls.</P 378><P 379><CODE 380CLASS="CONSTANT" 381>VIDIOC_DBG_G_REGISTER</CODE 382> and 383<CODE 384CLASS="CONSTANT" 385>VIDIOC_DBG_S_REGISTER</CODE 386> were introduced in Linux 3872.6.21.</P 388><P 389>We recommended the <SPAN 390CLASS="APPLICATION" 391>v4l2-dbg</SPAN 392> 393utility over calling these ioctls directly. It is available from the 394LinuxTV v4l-dvb repository; see <A 395HREF="http://linuxtv.org/repo/" 396TARGET="_top" 397>http://linuxtv.org/repo/</A 398> for 399access instructions.</P 400><DIV 401CLASS="TABLE" 402><A 403NAME="V4L2-REGISTER" 404></A 405><P 406><B 407>Table 1. struct <CODE 408CLASS="STRUCTNAME" 409>v4l2_register</CODE 410></B 411></P 412><TABLE 413BORDER="0" 414FRAME="void" 415WIDTH="100%" 416CLASS="CALSTABLE" 417><COL 418WIDTH="33%" 419TITLE="C1"><COL 420WIDTH="33%" 421TITLE="C2"><COL 422WIDTH="33%" 423TITLE="C4"><COL><TBODY 424VALIGN="TOP" 425><TR 426><TD 427>__u32</TD 428><TD 429><CODE 430CLASS="STRUCTFIELD" 431>match_type</CODE 432></TD 433><TD 434>See <A 435HREF="r7900.htm#CHIP-MATCH-TYPES" 436>Table 2</A 437> for a list of 438 possible types.</TD 439><TD 440> </TD 441></TR 442><TR 443><TD 444>__u32</TD 445><TD 446><CODE 447CLASS="STRUCTFIELD" 448>match_chip</CODE 449></TD 450><TD 451>Match a chip by this number, interpreted according 452to the <CODE 453CLASS="STRUCTFIELD" 454>match_type</CODE 455> field.</TD 456><TD 457> </TD 458></TR 459><TR 460><TD 461>__u64</TD 462><TD 463><CODE 464CLASS="STRUCTFIELD" 465>reg</CODE 466></TD 467><TD 468>A register number.</TD 469><TD 470> </TD 471></TR 472><TR 473><TD 474>__u64</TD 475><TD 476><CODE 477CLASS="STRUCTFIELD" 478>val</CODE 479></TD 480><TD 481>The value read from, or to be written into the 482register.</TD 483><TD 484> </TD 485></TR 486></TBODY 487></TABLE 488></DIV 489><DIV 490CLASS="TABLE" 491><A 492NAME="CHIP-MATCH-TYPES" 493></A 494><P 495><B 496>Table 2. Chip Match Types</B 497></P 498><TABLE 499BORDER="0" 500FRAME="void" 501WIDTH="100%" 502CLASS="CALSTABLE" 503><COL 504WIDTH="38%" 505TITLE="C1"><COL 506WIDTH="12%" 507TITLE="C2"><COL 508WIDTH="50%" 509TITLE="C3"><TBODY 510VALIGN="TOP" 511><TR 512><TD 513><CODE 514CLASS="CONSTANT" 515>V4L2_CHIP_MATCH_HOST</CODE 516></TD 517><TD 518>0</TD 519><TD 520>Match the nth chip on the card, zero for the 521 host chip. Does not match I<SUP 522>2</SUP 523>C chips.</TD 524></TR 525><TR 526><TD 527><CODE 528CLASS="CONSTANT" 529>V4L2_CHIP_MATCH_I2C_DRIVER</CODE 530></TD 531><TD 532>1</TD 533><TD 534>Match an I<SUP 535>2</SUP 536>C chip by its driver ID from the 537<TT 538CLASS="FILENAME" 539>linux/i2c-id.h</TT 540> header file.</TD 541></TR 542><TR 543><TD 544><CODE 545CLASS="CONSTANT" 546>V4L2_CHIP_MATCH_I2C_ADDR</CODE 547></TD 548><TD 549>2</TD 550><TD 551>Match a chip by its 7 bit I<SUP 552>2</SUP 553>C bus address.</TD 554></TR 555></TBODY 556></TABLE 557></DIV 558></DIV 559><DIV 560CLASS="REFSECT1" 561><A 562NAME="AEN8068" 563></A 564><H2 565>Return Value</H2 566><P 567>On success <SPAN 568CLASS="RETURNVALUE" 569>0</SPAN 570> is returned, on error <SPAN 571CLASS="RETURNVALUE" 572>-1</SPAN 573> and the <CODE 574CLASS="VARNAME" 575>errno</CODE 576> variable is set appropriately:</P 577><P 578></P 579><DIV 580CLASS="VARIABLELIST" 581><DL 582><DT 583><SPAN 584CLASS="ERRORCODE" 585>EINVAL</SPAN 586></DT 587><DD 588><P 589>The driver does not support this ioctl, or the kernel 590was not compiled with the <CODE 591CLASS="CONSTANT" 592>CONFIG_VIDEO_ADV_DEBUG</CODE 593> 594option, or the <CODE 595CLASS="STRUCTFIELD" 596>match_type</CODE 597> is invalid, or the 598selected chip or register does not exist.</P 599></DD 600><DT 601><SPAN 602CLASS="ERRORCODE" 603>EPERM</SPAN 604></DT 605><DD 606><P 607>Insufficient permissions. Root privileges are required 608to execute these ioctls.</P 609></DD 610></DL 611></DIV 612></DIV 613><DIV 614CLASS="NAVFOOTER" 615><HR 616ALIGN="LEFT" 617WIDTH="100%"><TABLE 618SUMMARY="Footer navigation table" 619WIDTH="100%" 620BORDER="0" 621CELLPADDING="0" 622CELLSPACING="0" 623><TR 624><TD 625WIDTH="33%" 626ALIGN="left" 627VALIGN="top" 628><A 629HREF="r7771.htm" 630ACCESSKEY="P" 631>Prev</A 632></TD 633><TD 634WIDTH="34%" 635ALIGN="center" 636VALIGN="top" 637><A 638HREF="book1.htm" 639ACCESSKEY="H" 640>Home</A 641></TD 642><TD 643WIDTH="33%" 644ALIGN="right" 645VALIGN="top" 646><A 647HREF="r8087.htm" 648ACCESSKEY="N" 649>Next</A 650></TD 651></TR 652><TR 653><TD 654WIDTH="33%" 655ALIGN="left" 656VALIGN="top" 657>ioctl VIDIOC_CROPCAP</TD 658><TD 659WIDTH="34%" 660ALIGN="center" 661VALIGN="top" 662><A 663HREF="r7624.htm" 664ACCESSKEY="U" 665>Up</A 666></TD 667><TD 668WIDTH="33%" 669ALIGN="right" 670VALIGN="top" 671>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</TD 672></TR 673></TABLE 674></DIV 675></BODY 676></HTML 677> 678