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 .. cpp: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 .. _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 .. _v4l2-dbg-chip-info:
 126
 127 .. flat-table:: struct v4l2_dbg_chip_info
 128     :header-rows:  0
 129     :stub-columns: 0
 130     :widths:       1 1 2
 131
 132
 133     -  .. row 1
 134
 135        -  struct v4l2_dbg_match
 136
 137        -  ``match``
 138
 139        -  How to match the chip, see :ref:`name-v4l2-dbg-match`.
 140
 141     -  .. row 2
 142
 143        -  char
 144
 145        -  ``name[32]``
 146
 147        -  The name of the chip.
 148
 149     -  .. row 3
 150
 151        -  __u32
 152
 153        -  ``flags``
 154
 155        -  Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the
 156           driver supports reading registers from the device. If
 157           ``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing
 158           registers.
 159
 160     -  .. row 4
 161
 162        -  __u32
 163
 164        -  ``reserved[8]``
 165
 166        -  Reserved fields, both application and driver must set these to 0.
 167
 168
 169
 170 .. _name-chip-match-types:
 171
 172 .. flat-table:: Chip Match Types
 173     :header-rows:  0
 174     :stub-columns: 0
 175     :widths:       3 1 4
 176
 177
 178     -  .. row 1
 179
 180        -  ``V4L2_CHIP_MATCH_BRIDGE``
 181
 182        -  0
 183
 184        -  Match the nth chip on the card, zero for the bridge chip. Does not
 185           match sub-devices.
 186
 187     -  .. row 2
 188
 189        -  ``V4L2_CHIP_MATCH_SUBDEV``
 190
 191        -  4
 192
 193        -  Match the nth sub-device.
 194
 195
 196 Return Value
 197 ============
 198
 199 On success 0 is returned, on error -1 and the ``errno`` variable is set
 200 appropriately. The generic error codes are described at the
 201 :ref:`Generic Error Codes <gen-errors>` chapter.
 202
 203 EINVAL
 204     The ``match_type`` is invalid or no device could be matched.