From 0e5ca174b657de9d1f6c75609c81279cc35e8d49 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sun, 18 Jan 2009 13:51:39 +0100 Subject: v4l2-spec: update the debug ioctls From: Hans Verkuil Priority: normal Signed-off-by: Hans Verkuil --- v4l2-spec/Makefile | 10 +- v4l2-spec/compat.sgml | 15 +- v4l2-spec/v4l2.sgml | 2 +- v4l2-spec/vidioc-dbg-g-chip-ident.sgml | 275 +++++++++++++++++++++++++++++++++ v4l2-spec/vidioc-dbg-g-register.sgml | 117 +++++++++----- v4l2-spec/vidioc-g-chip-ident.sgml | 236 ---------------------------- 6 files changed, 372 insertions(+), 283 deletions(-) create mode 100644 v4l2-spec/vidioc-dbg-g-chip-ident.sgml delete mode 100644 v4l2-spec/vidioc-g-chip-ident.sgml (limited to 'v4l2-spec') diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index db3d71974..d7fed7edd 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -62,7 +62,7 @@ SGMLS = \ vidioc-enumstd.sgml \ vidioc-g-audio.sgml \ vidioc-g-audioout.sgml \ - vidioc-g-chip-ident.sgml \ + vidioc-dbg-g-chip-ident.sgml \ vidioc-g-crop.sgml \ vidioc-g-ctrl.sgml \ vidioc-g-enc-index.sgml \ @@ -134,6 +134,7 @@ FUNCS = \ IOCTLS = \ VIDIOC_CROPCAP \ + VIDIOC_DBG_G_CHIP_IDENT \ VIDIOC_DBG_G_REGISTER \ VIDIOC_DBG_S_REGISTER \ VIDIOC_DQBUF \ @@ -148,7 +149,6 @@ IOCTLS = \ VIDIOC_ENUM_FRAMESIZES \ VIDIOC_G_AUDIO \ VIDIOC_G_AUDOUT \ - VIDIOC_G_CHIP_IDENT \ VIDIOC_G_CROP \ VIDIOC_G_CTRL \ VIDIOC_G_ENC_INDEX \ @@ -218,11 +218,13 @@ STRUCTS = \ v4l2_buffer \ v4l2_capability \ v4l2_captureparm \ - v4l2_chip_ident \ v4l2_clip \ v4l2_control \ v4l2_crop \ v4l2_cropcap \ + v4l2_dbg_chip_ident \ + v4l2_dbg_match \ + v4l2_dbg_register \ v4l2_enc_idx \ v4l2_enc_idx_entry \ v4l2_encoder_cmd \ @@ -247,7 +249,6 @@ STRUCTS = \ v4l2_queryctrl \ v4l2_querymenu \ v4l2_rect \ - v4l2_register \ v4l2_requestbuffers \ v4l2_sliced_vbi_cap \ v4l2_sliced_vbi_data \ @@ -293,6 +294,7 @@ UNDOCUMENTED = \ $(shell for i in \ v4l2_bitrate \ v4l2_bitrate_mode \ + v4l2_chip_ident_old \ v4l2_exposure_auto_type \ v4l2_mpeg_aspectratio \ v4l2_mpeg_aspectratio \ diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml index 3eb873c70..5c1815182 100644 --- a/v4l2-spec/compat.sgml +++ b/v4l2-spec/compat.sgml @@ -2199,7 +2199,18 @@ class was added, with the new controls by the extended controls interface in Linux 2.6.18, where finally removed from the videodev2.h header file. - + + + + +
+ V4L2 in Linux 2.6.29 + + + The VIDIOC_G_CHIP_IDENT ioctl was renamed +to VIDIOC_G_CHIP_IDENT_OLD and &VIDIOC-DBG-G-CHIP-IDENT; +was introduced in its place. +
@@ -2306,7 +2317,7 @@ ioctls. ioctls. - &VIDIOC-G-CHIP-IDENT; ioctl. + &VIDIOC-DBG-G-CHIP-IDENT; ioctl. diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index 710943aac..735ebc320 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -390,6 +390,7 @@ and http://li &sub-ioctl; &sub-cropcap; + &sub-dbg-g-chip-ident; &sub-dbg-g-register; &sub-encoder-cmd; &sub-enumaudio; @@ -402,7 +403,6 @@ and http://li &sub-enumstd; &sub-g-audio; &sub-g-audioout; - &sub-g-chip-ident; &sub-g-crop; &sub-g-ctrl; &sub-g-enc-index; diff --git a/v4l2-spec/vidioc-dbg-g-chip-ident.sgml b/v4l2-spec/vidioc-dbg-g-chip-ident.sgml new file mode 100644 index 000000000..6b13e8188 --- /dev/null +++ b/v4l2-spec/vidioc-dbg-g-chip-ident.sgml @@ -0,0 +1,275 @@ + + + ioctl VIDIOC_DBG_G_CHIP_IDENT + &manvol; + + + + VIDIOC_DBG_G_CHIP_IDENT + Identify the chips on a TV card + + + + + + int ioctl + int fd + int request + struct v4l2_dbg_chip_ident +*argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_DBG_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 must not use it. When you found a chip +specific bug, please contact the linux-media mailing list (&v4l-ml;) +so it can be fixed. + + To query the driver applications must initialize the +match.type and +match.addr or match.name +fields of a &v4l2-dbg-chip-ident; +and call VIDIOC_DBG_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.addr selects the nth non-&i2c; chip +on the TV card. You can enumerate all chips by starting at zero and +incrementing match.addr by one until +VIDIOC_DBG_G_CHIP_IDENT fails with an &EINVAL;. +The number zero always selects the host chip, ⪚ the chip connected +to the PCI or USB bus. + + 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 &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.addr selects a chip by its 7 bit +&i2c; bus address. + + When match.type is +V4L2_CHIP_MATCH_AC97, +match.addr selects the nth AC97 chip +on the TV card. You can enumerate all chips by starting at zero and +incrementing match.addr by one until +VIDIOC_DBG_G_CHIP_IDENT fails with an &EINVAL;. + + 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 +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, but the API was changed to the +one described here in 2.6.29. + + 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. + + + + struct <structname>v4l2_dbg_match</structname> + + &cs-str; + + + __u32 + match_type + See 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. + + + +
+ + + struct <structname>v4l2_dbg_chip_ident</structname> + + &cs-str; + + + struct v4l2_dbg_match + match + How to match the chip, see . + + + __u32 + ident + A chip identifier as defined in the Linux +media/v4l2-chip-ident.h header file, or one of +the values from . + + + __u32 + revision + A chip revision, chip and driver specific. + + + +
+ + + + Chip Match Types + + &cs-def; + + + 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 name. + + + V4L2_CHIP_MATCH_I2C_ADDR + 2 + Match a chip by its 7 bit &i2c; bus address. + + + V4L2_CHIP_MATCH_AC97 + 3 + Match the nth anciliary AC97 chip. + + + +
+ + + + Chip Identifiers + + &cs-def; + + + V4L2_IDENT_NONE + 0 + No chip matched. + + + V4L2_IDENT_AMBIGUOUS + 1 + Multiple chips matched. + + + V4L2_IDENT_UNKNOWN + 2 + A chip is present at this address, but the driver +could not identify it. + + + +
+ + + + &return-value; + + + + EINVAL + + The driver does not support this ioctl, or the +match_type is invalid. + + + + + + + diff --git a/v4l2-spec/vidioc-dbg-g-register.sgml b/v4l2-spec/vidioc-dbg-g-register.sgml index 03f3150d9..a29ff35ad 100644 --- a/v4l2-spec/vidioc-dbg-g-register.sgml +++ b/v4l2-spec/vidioc-dbg-g-register.sgml @@ -16,7 +16,7 @@ int ioctl int fd int request - struct v4l2_register *argp + struct v4l2_dbg_register *argp @@ -24,7 +24,7 @@ int ioctl int fd int request - const struct v4l2_register + const struct v4l2_dbg_register *argp @@ -67,7 +67,7 @@ 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. +applications must not use them. Since writing or even reading registers can jeopardize the system security, its stability and damage the hardware, both ioctls @@ -76,65 +76,69 @@ compiled with the CONFIG_VIDEO_ADV_DEBUG option to enable these ioctls. To write a register applications must initialize all fields -of a &v4l2-register; and call +of a &v4l2-dbg-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 +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 and +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 + 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, ⪚ 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 +match.addr selects the nth non-&i2c; chip +on the TV card. The number zero always selects the host chip, ⪚ 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_chip contains a driver ID as defined -in the linux/i2c-id.h header file. For instance -I2C_DRIVERID_SAA7127 will match any chip +match.name contains the I2C driver name. +For instance +"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 +&VIDIOC-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are present. - When match_type is + When match.type is V4L2_CHIP_MATCH_I2C_ADDR, -match_chip selects a chip by its 7 bit &i2c; +match.addr selects a chip by its 7 bit &i2c; 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 &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; +catch the most likely failure we recommend a &VIDIOC-DBG-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-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. +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 @@ -142,24 +146,53 @@ LinuxTV v4l-dvb repository; see http://linuxtv.org/repo/ for access instructions. - - struct <structname>v4l2_register</structname> - - - - + +
+ struct <structname>v4l2_dbg_match</structname> + + &cs-str; __u32 match_type - See for a list of - possible types. + See for a list of +possible types. + + + union + (anonymous) + __u32 - match_chip + addr Match a chip by this number, interpreted according -to the match_type field. +to the type field. + + + + char + name[32] + Match a chip by this name, interpreted according +to the type field. + + + +
+ + + + struct <structname>v4l2_dbg_register</structname> + + + + + + + struct v4l2_dbg_match + match + How to match the chip, see . __u64 @@ -176,7 +209,7 @@ register.
- Chip Match Types @@ -192,14 +225,18 @@ register. V4L2_CHIP_MATCH_I2C_DRIVER 1 - Match an &i2c; chip by its driver ID from the -linux/i2c-id.h header file. + Match an &i2c; chip by its driver name. V4L2_CHIP_MATCH_I2C_ADDR 2 Match a chip by its 7 bit &i2c; bus address. + + V4L2_CHIP_MATCH_AC97 + 3 + Match the nth anciliary AC97 chip. +
diff --git a/v4l2-spec/vidioc-g-chip-ident.sgml b/v4l2-spec/vidioc-g-chip-ident.sgml deleted file mode 100644 index 4f3cc59a7..000000000 --- a/v4l2-spec/vidioc-g-chip-ident.sgml +++ /dev/null @@ -1,236 +0,0 @@ - - - ioctl VIDIOC_G_CHIP_IDENT - &manvol; - - - - VIDIOC_G_CHIP_IDENT - Identify the chips on a TV card - - - - - - int ioctl - int fd - int request - struct v4l2_chip_ident -*argp - - - - - - Arguments - - - - fd - - &fd; - - - - 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 (&v4l-ml;) -so it can be fixed. - - To query the driver applications must initialize the -match_type and -match_chip fields of a &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;. -Drivers may also interpret match_chip as a -random ID, but we recommend against that. The number zero always -selects the host chip, ⪚ 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. - - - struct <structname>v4l2_chip_ident</structname> - - &cs-str; - - - __u32 - match_type - See for a list of -possible types. - - - __u32 - match_chip - Match a chip by this number, interpreted according -to the match_type field. - - - __u32 - ident - A chip identifier as defined in the Linux -media/v4l2-chip-ident.h header file, or one of -the values from . - - - __u32 - revision - A chip revision, chip and driver specific. - - - -
- - - - Chip Match Types - - &cs-def; - - - 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. - - - -
- - - - Chip Identifiers - - &cs-def; - - - V4L2_IDENT_NONE - 0 - No chip matched. - - - V4L2_IDENT_AMBIGUOUS - 1 - Multiple chips matched. - - - V4L2_IDENT_UNKNOWN - 2 - A chip is present at this address, but the driver -could not identify it. - - - -
- - - - &return-value; - - - - EINVAL - - The driver does not support this ioctl, or the -match_type is invalid. - - - - - - - -- cgit v1.2.3