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