0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_DBG_G_CHIP_INFO:
0005
0006 ****************************
0007 ioctl VIDIOC_DBG_G_CHIP_INFO
0008 ****************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_DBG_G_CHIP_INFO
0019
0020 ``int ioctl(int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_dbg_chip_info`.
0030
0031 Description
0032 ===========
0033
0034 .. note::
0035
0036 This is an :ref:`experimental` interface and may
0037 change in the future.
0038
0039 For driver debugging purposes this ioctl allows test applications to
0040 query the driver about the chips present on the TV card. Regular
0041 applications must not use it. When you found a chip specific bug, please
0042 contact the linux-media mailing list
0043 (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
0044 so it can be fixed.
0045
0046 Additionally the Linux kernel must be compiled with the
0047 ``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl.
0048
0049 To query the driver applications must initialize the ``match.type`` and
0050 ``match.addr`` or ``match.name`` fields of a struct
0051 :c:type:`v4l2_dbg_chip_info` and call
0052 :ref:`VIDIOC_DBG_G_CHIP_INFO` with a pointer to this structure. On success
0053 the driver stores information about the selected chip in the ``name``
0054 and ``flags`` fields.
0055
0056 When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
0057 selects the nth bridge 'chip' on the TV card. You can enumerate all
0058 chips by starting at zero and incrementing ``match.addr`` by one until
0059 :ref:`VIDIOC_DBG_G_CHIP_INFO` fails with an ``EINVAL`` error code. The number
0060 zero always selects the bridge chip itself, e. g. the chip connected to
0061 the PCI or USB bus. Non-zero numbers identify specific parts of the
0062 bridge chip such as an AC97 register block.
0063
0064 When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
0065 selects the nth sub-device. This allows you to enumerate over all
0066 sub-devices.
0067
0068 On success, the ``name`` field will contain a chip name and the
0069 ``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver
0070 supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE``
0071 if the driver supports writing registers to the device.
0072
0073 We recommended the v4l2-dbg utility over calling this ioctl directly. It
0074 is available from the LinuxTV v4l-dvb repository; see
0075 `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
0076 instructions.
0077
0078 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}|
0079
0080 .. _name-v4l2-dbg-match:
0081
0082 .. flat-table:: struct v4l2_dbg_match
0083 :header-rows: 0
0084 :stub-columns: 0
0085 :widths: 1 1 2
0086
0087 * - __u32
0088 - ``type``
0089 - See :ref:`name-chip-match-types` for a list of possible types.
0090 * - union {
0091 - (anonymous)
0092 * - __u32
0093 - ``addr``
0094 - Match a chip by this number, interpreted according to the ``type``
0095 field.
0096 * - char
0097 - ``name[32]``
0098 - Match a chip by this name, interpreted according to the ``type``
0099 field. Currently unused.
0100 * - }
0101 -
0102
0103
0104 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0105
0106 .. c:type:: v4l2_dbg_chip_info
0107
0108 .. flat-table:: struct v4l2_dbg_chip_info
0109 :header-rows: 0
0110 :stub-columns: 0
0111 :widths: 1 1 2
0112
0113 * - struct v4l2_dbg_match
0114 - ``match``
0115 - How to match the chip, see :ref:`name-v4l2-dbg-match`.
0116 * - char
0117 - ``name[32]``
0118 - The name of the chip.
0119 * - __u32
0120 - ``flags``
0121 - Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the
0122 driver supports reading registers from the device. If
0123 ``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing
0124 registers.
0125 * - __u32
0126 - ``reserved[8]``
0127 - Reserved fields, both application and driver must set these to 0.
0128
0129
0130 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0131
0132 .. _name-chip-match-types:
0133
0134 .. flat-table:: Chip Match Types
0135 :header-rows: 0
0136 :stub-columns: 0
0137 :widths: 3 1 4
0138
0139 * - ``V4L2_CHIP_MATCH_BRIDGE``
0140 - 0
0141 - Match the nth chip on the card, zero for the bridge chip. Does not
0142 match sub-devices.
0143 * - ``V4L2_CHIP_MATCH_SUBDEV``
0144 - 4
0145 - Match the nth sub-device.
0146
0147 Return Value
0148 ============
0149
0150 On success 0 is returned, on error -1 and the ``errno`` variable is set
0151 appropriately. The generic error codes are described at the
0152 :ref:`Generic Error Codes <gen-errors>` chapter.
0153
0154 EINVAL
0155 The ``match_type`` is invalid or no device could be matched.
