From b5958dc329f0e4584511c5d8a177122e3d23a657 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 18 Mar 2013 13:28:12 -0300 Subject: [PATCH] [media] DocBook media: add VIDIOC_DBG_G_CHIP_NAME documentation And update the other debug ioctls accordingly. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/v4l2.xml | 4 +- .../media/v4l/vidioc-dbg-g-chip-ident.xml | 14 +- .../media/v4l/vidioc-dbg-g-chip-name.xml | 234 ++++++++++++++++++ .../media/v4l/vidioc-dbg-g-register.xml | 42 +++- 4 files changed, 280 insertions(+), 14 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-name.xml diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index dae009aa2440..ec3a0c7276df 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -156,8 +156,7 @@ applications. --> 2012-12-03 sa, sn Added timestamp types to v4l2_buffer. - Added V4L2_EVENT_CTRL_CH_RANGE control - event changes flag, see . + Added V4L2_EVENT_CTRL_CH_RANGE control event changes flag. @@ -549,6 +548,7 @@ and discussions on the V4L mailing list. &sub-create-bufs; &sub-cropcap; &sub-dbg-g-chip-ident; + &sub-dbg-g-chip-name; &sub-dbg-g-register; &sub-decoder-cmd; &sub-dqevent; diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml index 4ecd966808de..82e43c6c72b8 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml @@ -200,10 +200,10 @@ the values from . &cs-def; - V4L2_CHIP_MATCH_HOST + V4L2_CHIP_MATCH_BRIDGE 0 Match the nth chip on the card, zero for the - host chip. Does not match &i2c; chips. + bridge chip. Does not match sub-devices. V4L2_CHIP_MATCH_I2C_DRIVER @@ -220,6 +220,16 @@ the values from . 3 Match the nth anciliary AC97 chip. + + V4L2_CHIP_MATCH_SUBDEV_NAME + 4 + Match the sub-device by name. Can't be used with this ioctl. + + + V4L2_CHIP_MATCH_SUBDEV_IDX + 5 + Match the nth sub-device. Can't be used with this ioctl. + diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-name.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-name.xml new file mode 100644 index 000000000000..4921346fabd7 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-name.xml @@ -0,0 +1,234 @@ + + + ioctl VIDIOC_DBG_G_CHIP_NAME + &manvol; + + + + VIDIOC_DBG_G_CHIP_NAME + Identify the chips on a TV card + + + + + + int ioctl + int fd + int request + struct v4l2_dbg_chip_name +*argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_DBG_G_CHIP_NAME + + + + 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-name; +and call VIDIOC_DBG_G_CHIP_NAME with a pointer to +this structure. On success the driver stores information about the +selected chip in the name and +flags fields. On failure the structure +remains unchanged. + + When match.type is +V4L2_CHIP_MATCH_BRIDGE, +match.addr selects the nth bridge '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_NAME fails with an &EINVAL;. +The number zero always selects the bridge chip itself, ⪚ the chip +connected to the PCI or USB bus. Non-zero numbers identify specific +parts of the bridge chip such as an AC97 register block. + + When match.type is +V4L2_CHIP_MATCH_SUBDEV_NAME, +match.name contains the name of a sub-device. +For instance +"saa7127 6-0044" will match the saa7127 sub-device +at the given i2c bus. This match type is not very useful for this ioctl +and is here only for consistency. + + + When match.type is +V4L2_CHIP_MATCH_SUBDEV_IDX, +match.addr selects the nth sub-device. This +allows you to enumerate over all sub-devices. + + On success, the name field will +contain a chip name and the flags field will +contain V4L2_CHIP_FL_READABLE if the driver supports +reading registers from the device or V4L2_CHIP_FL_WRITABLE +if the driver supports writing registers to the device. + + 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-ustr; + + + __u32 + 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_name</structname> + + &cs-str; + + + struct v4l2_dbg_match + match + How to match the chip, see . + + + char + name[32] + The name of the chip. + + + __u32 + flags + Set by the driver. If V4L2_CHIP_FL_READABLE +is set, then the driver supports reading registers from the device. If +V4L2_CHIP_FL_WRITABLE is set, then it supports writing registers. + + + __u32 + reserved[8] + Reserved fields, both application and driver must set these to 0. + + + +
+ + + + Chip Match Types + + &cs-def; + + + V4L2_CHIP_MATCH_BRIDGE + 0 + Match the nth chip on the card, zero for the + bridge chip. Does not match sub-devices. + + + V4L2_CHIP_MATCH_I2C_DRIVER + 1 + Match an &i2c; chip by its driver name. Can't be used with this ioctl. + + + V4L2_CHIP_MATCH_I2C_ADDR + 2 + Match a chip by its 7 bit &i2c; bus address. Can't be used with this ioctl. + + + V4L2_CHIP_MATCH_AC97 + 3 + Match the nth anciliary AC97 chip. Can't be used with this ioctl. + + + V4L2_CHIP_MATCH_SUBDEV_NAME + 4 + Match the sub-device by name. + + + V4L2_CHIP_MATCH_SUBDEV_IDX + 5 + Match the nth sub-device. + + + +
+ + + + &return-value; + + + + EINVAL + + The match_type is invalid or +no device could be matched. + + + + + diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml index a44aebc7997a..3082b4149dbe 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml @@ -87,7 +87,7 @@ written into the register. To read a register applications must initialize the match.type, -match.chip or match.name and +match.addr 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 @@ -95,11 +95,11 @@ structure. On success the driver stores the register value in the unchanged. When match.type is -V4L2_CHIP_MATCH_HOST, -match.addr selects the nth non-&i2c; chip +V4L2_CHIP_MATCH_BRIDGE, +match.addr selects the nth non-sub-device 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. +present with the &VIDIOC-DBG-G-CHIP-NAME; ioctl. When match.type is V4L2_CHIP_MATCH_I2C_DRIVER, @@ -109,7 +109,7 @@ For instance 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-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are +&VIDIOC-DBG-G-CHIP-NAME; ioctl you can find out which &i2c; chips are present. When match.type is @@ -122,19 +122,31 @@ bus address. match.addr selects the nth AC97 chip on the TV card. + When match.type is +V4L2_CHIP_MATCH_SUBDEV_NAME, +match.name contains the sub-device name. +For instance +"saa7127 6-0044" will match this specific saa7127 +sub-device. Again with the &VIDIOC-DBG-G-CHIP-NAME; ioctl you can find +out which sub-devices are present. + + When match.type is +V4L2_CHIP_MATCH_SUBDEV_IDX, +match.addr selects the nth sub-device. + 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-DBG-G-CHIP-IDENT; +catch the most likely failure we recommend a &VIDIOC-DBG-G-CHIP-NAME; 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-DBG-G-CHIP-IDENT;. Conversely it may support -VIDIOC_DBG_G_CHIP_IDENT but not these ioctls. +&VIDIOC-DBG-G-CHIP-NAME;. Conversely it may support +VIDIOC_DBG_G_CHIP_NAME but not these ioctls. VIDIOC_DBG_G_REGISTER and VIDIOC_DBG_S_REGISTER were introduced in Linux @@ -217,10 +229,10 @@ register. &cs-def; - V4L2_CHIP_MATCH_HOST + V4L2_CHIP_MATCH_BRIDGE 0 Match the nth chip on the card, zero for the - host chip. Does not match &i2c; chips. + bridge chip. Does not match sub-devices. V4L2_CHIP_MATCH_I2C_DRIVER @@ -237,6 +249,16 @@ register. 3 Match the nth anciliary AC97 chip. + + V4L2_CHIP_MATCH_SUBDEV_NAME + 4 + Match the sub-device by name. + + + V4L2_CHIP_MATCH_SUBDEV_IDX + 5 + Match the nth sub-device. + -- 2.30.2