vidioc-dbg-g-chip-info.rst

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