Video for Linux Two API Specification: Revision 0.24
Prev |  | Next

# ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER

## Name

VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER -- Read or write hardware registers

## Synopsis

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

``int ioctl`(int fd, int request, const struct v4l2_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 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 `CONFIG_VIDEO_ADV_DEBUG` option 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 structure. The `match_type` and `match_chip` 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` 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_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 `VIDIOC_G_CHIP_IDENT` ioctl.

When `match_type` is `V4L2_CHIP_MATCH_I2C_DRIVER`, `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 present.

When `match_type` is `V4L2_CHIP_MATCH_I2C_ADDR`, `match_chip` selects a chip by its 7 bit I2C bus address.

> 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_IDENT` call 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_G_REGISTER` and `VIDIOC_DBG_S_REGISTER` were introduced in Linux 2.6.21.

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 `v4l2_register`

__u32 | `match_type` | See Table 2 for a list of possible types. |
__u32 | `match_chip` | Match a chip by this number, interpreted according to the `match_type` field. |
__u64 | `reg` | A register number. |
__u64 | `val` | The value read from, or to be written into the register. |

Table 2. Chip Match Types

`V4L2_CHIP_MATCH_HOST` | 0 | Match the nth chip on the card, zero for the host chip. Does not match I2C chips.
`V4L2_CHIP_MATCH_I2C_DRIVER` | 1 | Match an I2C chip by its driver ID from the `linux/i2c-id.h` header file.
`V4L2_CHIP_MATCH_I2C_ADDR` | 2 | Match a chip by its 7 bit I2C bus address.

## 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 | Home | Next
ioctl VIDIOC_CROPCAP | Up | ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD