File descriptor returned by
Experimental: This is an experimental interface and may change in the future.
For driver debugging purposes these ioctls allow test applications to access hardware registers directly. Regular applications should not use them.
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
to enable these ioctls.
To write a register applications must initialize all fields
of a struct v4l2_register and call
VIDIOC_DBG_S_REGISTER with a pointer to this
match_chip fields select a chip on the TV
reg field specifies a register
number and the
val field the value to be
written into the register.
To read a register applications must initialize the
reg fields, and call
VIDIOC_DBG_G_REGISTER with a pointer to this
structure. On success the driver stores the register value in the
val field. On failure the structure remains
match_chip selects the nth non-I2C chip
on the TV card. Drivers may also interpret
match_chip 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
match_chip contains a driver ID as defined
in the linux/i2c-id.h header file. For instance
I2C_DRIVERID_SAA7127 will match any chip
supported by the saa7127 driver, regardless of its I2C bus address.
When multiple chips supported by the same driver are present, the
effect of these ioctls is undefined. Again with the
VIDIOC_G_CHIP_IDENT ioctl you can find out which I2C chips are
match_chip selects a chip by its 7 bit I2C
Success not guaranteed: Due to a flaw in the Linux I2C bus driver these ioctls may return successfully without actually reading or writing a register. To catch the most likely failure we recommend a
VIDIOC_G_CHIP_IDENTcall confirming the presence of the selected I2C chip.
These ioctls are optional, not all drivers may support them.
However when a driver supports these ioctls it must also support
VIDIOC_G_CHIP_IDENT. Conversely it may support
VIDIOC_G_CHIP_IDENT but not these ioctls.
VIDIOC_DBG_S_REGISTER were introduced in Linux
We recommended the v4l2-dbg utility over calling these ioctls directly. It is available from the LinuxTV v4l-dvb repository; see http://linuxtv.org/repo/ for access instructions.
Table 1. struct
|__u32||See Table 2 for a list of possible types.|
|__u32||Match a chip by this number, interpreted according
to the |
|__u64||A register number.|
|__u64||The value read from, or to be written into the register.|
On success 0 is returned, on error -1 and the
errno variable is set appropriately:
The driver does not support this ioctl, or the kernel
was not compiled with the
option, or the
match_type is invalid, or the
selected chip or register does not exist.
Insufficient permissions. Root privileges are required to execute these ioctls.