Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_DBG_G_CHIP_INFO:
   4
   5 ****************************
   6 ioctl VIDIOC_DBG_G_CHIP_INFO
   7 ****************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, int request, struct v4l2_dbg_chip_info *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_DBG_G_CHIP_INFO
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 .. note::
  37
  38     This is an :ref:`experimental` interface and may
  39     change in the future.
  40
  41 For driver debugging purposes this ioctl allows test applications to
  42 query the driver about the chips present on the TV card. Regular
  43 applications must not use it. When you found a chip specific bug, please
  44 contact the linux-media mailing list
  45 (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
  46 so it can be fixed.
  47
  48 Additionally the Linux kernel must be compiled with the
  49 ``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl.
  50
  51 To query the driver applications must initialize the ``match.type`` and
  52 ``match.addr`` or ``match.name`` fields of a struct
  53 :ref:`v4l2_dbg_chip_info <v4l2-dbg-chip-info>` and call
  54 :ref:`VIDIOC_DBG_G_CHIP_INFO` with a pointer to this structure. On success
  55 the driver stores information about the selected chip in the ``name``
  56 and ``flags`` fields.
  57
  58 When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
  59 selects the nth bridge 'chip' on the TV card. You can enumerate all
  60 chips by starting at zero and incrementing ``match.addr`` by one until
  61 :ref:`VIDIOC_DBG_G_CHIP_INFO` fails with an ``EINVAL`` error code. The number
  62 zero always selects the bridge chip itself, e. g. the chip connected to
  63 the PCI or USB bus. Non-zero numbers identify specific parts of the
  64 bridge chip such as an AC97 register block.
  65
  66 When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
  67 selects the nth sub-device. This allows you to enumerate over all
  68 sub-devices.
  69
  70 On success, the ``name`` field will contain a chip name and the
  71 ``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver
  72 supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE``
  73 if the driver supports writing registers to the device.
  74
  75 We recommended the v4l2-dbg utility over calling this ioctl directly. It
  76 is available from the LinuxTV v4l-dvb repository; see
  77 `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
  78 instructions.
  79
  80
  81 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
  82
  83 .. _name-v4l2-dbg-match:
  84
  85 .. flat-table:: struct v4l2_dbg_match
  86     :header-rows:  0
  87     :stub-columns: 0
  88     :widths:       1 1 1 2
  89
  90
  91     -  .. row 1
  92
  93        -  __u32
  94
  95        -  ``type``
  96
  97        -  See :ref:`name-chip-match-types` for a list of possible types.
  98
  99     -  .. row 2
 100
 101        -  union
 102
 103        -  (anonymous)
 104
 105     -  .. row 3
 106
 107        -
 108        -  __u32
 109
 110        -  ``addr``
 111
 112        -  Match a chip by this number, interpreted according to the ``type``
 113           field.
 114
 115     -  .. row 4
 116
 117        -
 118        -  char
 119
 120        -  ``name[32]``
 121
 122        -  Match a chip by this name, interpreted according to the ``type``
 123           field. Currently unused.
 124
 125
 126
 127 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 128
 129 .. _v4l2-dbg-chip-info:
 130
 131 .. flat-table:: struct v4l2_dbg_chip_info
 132     :header-rows:  0
 133     :stub-columns: 0
 134     :widths:       1 1 2
 135
 136
 137     -  .. row 1
 138
 139        -  struct v4l2_dbg_match
 140
 141        -  ``match``
 142
 143        -  How to match the chip, see :ref:`name-v4l2-dbg-match`.
 144
 145     -  .. row 2
 146
 147        -  char
 148
 149        -  ``name[32]``
 150
 151        -  The name of the chip.
 152
 153     -  .. row 3
 154
 155        -  __u32
 156
 157        -  ``flags``
 158
 159        -  Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the
 160           driver supports reading registers from the device. If
 161           ``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing
 162           registers.
 163
 164     -  .. row 4
 165
 166        -  __u32
 167
 168        -  ``reserved[8]``
 169
 170        -  Reserved fields, both application and driver must set these to 0.
 171
 172
 173
 174 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 175
 176 .. _name-chip-match-types:
 177
 178 .. flat-table:: Chip Match Types
 179     :header-rows:  0
 180     :stub-columns: 0
 181     :widths:       3 1 4
 182
 183
 184     -  .. row 1
 185
 186        -  ``V4L2_CHIP_MATCH_BRIDGE``
 187
 188        -  0
 189
 190        -  Match the nth chip on the card, zero for the bridge chip. Does not
 191           match sub-devices.
 192
 193     -  .. row 2
 194
 195        -  ``V4L2_CHIP_MATCH_SUBDEV``
 196
 197        -  4
 198
 199        -  Match the nth sub-device.
 200
 201
 202 Return Value
 203 ============
 204
 205 On success 0 is returned, on error -1 and the ``errno`` variable is set
 206 appropriately. The generic error codes are described at the
 207 :ref:`Generic Error Codes <gen-errors>` chapter.
 208
 209 EINVAL
 210     The ``match_type`` is invalid or no device could be matched.