ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S

ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
Prev	Function Reference	Next

Name

VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER — Read or write hardware registers

Synopsis

`int ioctl(`	int	`fd`,
	int	`request`,
	struct v4l2_dbg_register *	`argp)`;

`int ioctl(`	int	`fd`,
	int	`request`,
	const struct v4l2_dbg_register *	`argp)`;

Arguments

fd: File descriptor returned by open().
request: VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
argp

Description

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 must 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 CONFIG_VIDEO_ADV_DEBUG option to enable these ioctls.

To write a register applications must initialize all fields of a struct v4l2_dbg_register and call VIDIOC_DBG_S_REGISTER with a pointer to this structure. The match.type and match.addr or match.name fields select a chip on the TV card, the 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 match.type, match.chip or match.name and 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 unchanged.

When match.type is V4L2_CHIP_MATCH_HOST, match.addr selects the nth non-I²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 VIDIOC_DBG_G_CHIP_IDENT ioctl.

When match.type is V4L2_CHIP_MATCH_I2C_DRIVER, match.name contains the I2C driver name. For instance "saa7127" will match any chip supported by the saa7127 driver, regardless of its I²C bus address. When multiple chips supported by the same driver are present, the effect of these ioctls is undefined. Again with the VIDIOC_DBG_G_CHIP_IDENT ioctl you can find out which I²C chips are present.

When match.type is V4L2_CHIP_MATCH_I2C_ADDR, match.addr selects a chip by its 7 bit I²C bus address.

When match.type is V4L2_CHIP_MATCH_AC97, match.addr selects the nth AC97 chip on the TV card.

Success not guaranteed

Due to a flaw in the Linux I²C bus driver these ioctls may return successfully without actually reading or writing a register. To catch the most likely failure we recommend a VIDIOC_DBG_G_CHIP_IDENT call confirming the presence of the selected I²C chip.

These ioctls are optional, not all drivers may support them. However when a driver supports these ioctls it must also support VIDIOC_DBG_G_CHIP_IDENT. Conversely it may support VIDIOC_DBG_G_CHIP_IDENT but not these ioctls.

VIDIOC_DBG_G_REGISTER and VIDIOC_DBG_S_REGISTER were introduced in Linux 2.6.21, but their API was changed to the one described here in kernel 2.6.29.

We recommended the v4l2-dbg utility over calling these ioctls directly. It is available from the LinuxTV v4l-dvb repository; see https://linuxtv.org/repo/ for access instructions.

Table 45. struct v4l2_dbg_match

__u32	`type`	See Table 43, “Chip Match Types” for a list of possible types.
union	(anonymous)
	__u32	`addr`	Match a chip by this number, interpreted according to the `type` field.
	char	`name[32]`	Match a chip by this name, interpreted according to the `type` field.

Table 46. struct v4l2_dbg_register

struct v4l2_dbg_match	`match`	How to match the chip, see Table 45, “struct v4l2_dbg_match”.
__u64	`reg`	A register number.
__u64	`val`	The value read from, or to be written into the register.

Table 47. Chip Match Types

`V4L2_CHIP_MATCH_HOST`	0	Match the nth chip on the card, zero for the host chip. Does not match I²C chips.
`V4L2_CHIP_MATCH_I2C_DRIVER`	1	Match an I²C chip by its driver name.
`V4L2_CHIP_MATCH_I2C_ADDR`	2	Match a chip by its 7 bit I²C bus address.
`V4L2_CHIP_MATCH_AC97`	3	Match the nth anciliary AC97 chip.

Return Value

On success 0 is returned, on error -1 and the errno variable is set appropriately:

EINVAL: The driver does not support this ioctl, or the kernel was not compiled with the CONFIG_VIDEO_ADV_DEBUG option, or the match_type is invalid, or the selected chip or register does not exist.
EPERM: Insufficient permissions. Root privileges are required to execute these ioctls.

Prev	Up	Next
ioctl VIDIOC_DBG_G_CHIP_IDENT	Home	ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD