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

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