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.
156