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