Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst

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