ioctl VIDIOC_G_CHIP_IDENT

Name

VIDIOC_G_CHIP_IDENT -- Identify the chips on a TV card

Synopsis

int ioctl(int fd, int request, struct v4l2_chip_ident *argp);

Arguments

fd

File descriptor returned by open().

request

VIDIOC_G_CHIP_IDENT

argp

Description

Experimental: This is an experimental interface and may change in the future.

For driver debugging purposes this ioctl allows test applications to query the driver about the chips present on the TV card. Regular applications should not use it. When you found a chip specific bug, please contact the Video4Linux mailing list (https://listman.redhat.com/mailman/listinfo/video4linux-list) so it can be fixed.

To query the driver applications must initialize the match_type and match_chip fields of a struct v4l2_chip_ident and call VIDIOC_G_CHIP_IDENT with a pointer to this structure. On success the driver stores information about the selected chip in the ident and revision fields. 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. You can enumerate all chips by starting at zero and incrementing match_chip by one until VIDIOC_G_CHIP_IDENT fails with an EINVAL error code. 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.

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 ioctl will return V4L2_IDENT_AMBIGUOUS in the ident field.

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

On success, the ident field will contain a chip ID from the Linux media/v4l2-chip-ident.h header file, and the revision field will contain a driver specific value, or zero if no particular revision is associated with this chip.

When the driver could not identify the selected chip, ident will contain V4L2_IDENT_UNKNOWN. When no chip matched match_type and match_chip, the ioctl will succeed but the ident field will contain V4L2_IDENT_NONE. If multiple chips matched, ident will contain V4L2_IDENT_AMBIGUOUS. In all these cases the revision field remains unchanged.

This ioctl is optional, not all drivers may support it. It was introduced in Linux 2.6.21.

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

Table 1. struct v4l2_chip_ident

__u32match_typeSee Table 2 for a list of possible types.
__u32match_chipMatch a chip by this number, interpreted according to the match_type field.
__u32identA chip identifier as defined in the Linux media/v4l2-chip-ident.h header file, or one of the values from Table 3.
__u32revisionA chip revision, chip and driver specific.

Table 2. Chip Match Types

V4L2_CHIP_MATCH_HOST0Match the nth chip on the card, zero for the host chip. Does not match I2C chips.
V4L2_CHIP_MATCH_I2C_DRIVER1Match an I2C chip by its driver ID from the linux/i2c-id.h header file.
V4L2_CHIP_MATCH_I2C_ADDR2Match a chip by its 7 bit I2C bus address.

Table 3. Chip Identifiers

V4L2_IDENT_NONE0No chip matched.
V4L2_IDENT_AMBIGUOUS1Multiple chips matched.
V4L2_IDENT_UNKNOWN2A chip is present at this address, but the driver could not identify it.

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 match_type is invalid.