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/userspace-api/media/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****************************
13ioctl VIDIOC_DBG_G_CHIP_INFO
14****************************
15
16Name
17====
18
19VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card
20
21
22Synopsis
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
29Arguments
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
39Description
40===========
41
42.. note::
43
44    This is an :ref:`experimental` interface and may
45    change in the future.
46
47For driver debugging purposes this ioctl allows test applications to
48query the driver about the chips present on the TV card. Regular
49applications must not use it. When you found a chip specific bug, please
50contact the linux-media mailing list
51(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
52so it can be fixed.
53
54Additionally the Linux kernel must be compiled with the
55``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl.
56
57To 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
61the driver stores information about the selected chip in the ``name``
62and ``flags`` fields.
63
64When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
65selects the nth bridge 'chip' on the TV card. You can enumerate all
66chips 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
68zero always selects the bridge chip itself, e. g. the chip connected to
69the PCI or USB bus. Non-zero numbers identify specific parts of the
70bridge chip such as an AC97 register block.
71
72When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
73selects the nth sub-device. This allows you to enumerate over all
74sub-devices.
75
76On success, the ``name`` field will contain a chip name and the
77``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver
78supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE``
79if the driver supports writing registers to the device.
80
81We recommended the v4l2-dbg utility over calling this ioctl directly. It
82is available from the LinuxTV v4l-dvb repository; see
83`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
84instructions.
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 2
95
96    * - __u32
97      - ``type``
98      - See :ref:`name-chip-match-types` for a list of possible types.
99    * - union {
100      - (anonymous)
101    * - __u32
102      - ``addr``
103      - Match a chip by this number, interpreted according to the ``type``
104	field.
105    * - char
106      - ``name[32]``
107      - Match a chip by this name, interpreted according to the ``type``
108	field. Currently unused.
109    * - }
110      -
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
159Return Value
160============
161
162On success 0 is returned, on error -1 and the ``errno`` variable is set
163appropriately. The generic error codes are described at the
164:ref:`Generic Error Codes <gen-errors>` chapter.
165
166EINVAL
167    The ``match_type`` is invalid or no device could be matched.
168