1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_DBG_G_CHIP_INFO:
5
6 ****************************
7 ioctl VIDIOC_DBG_G_CHIP_INFO
8 ****************************
9
10 Name
11 ====
12
13 VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card
14
15 Synopsis
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
22 Arguments
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
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 .. 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
147 Return Value
148 ============
149
150 On success 0 is returned, on error -1 and the ``errno`` variable is set
151 appropriately. The generic error codes are described at the
152 :ref:`Generic Error Codes <gen-errors>` chapter.
153
154 EINVAL
155 The ``match_type`` is invalid or no device could be matched.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.