Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_DBG_G_REGISTER:
   5
   6 **************************************************
   7 ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
   8 **************************************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_DBG_G_REGISTER
  19
  20 ``int ioctl(int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp)``
  21
  22 .. c:macro:: VIDIOC_DBG_S_REGISTER
  23
  24 ``int ioctl(int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp)``
  25
  26 Arguments
  27 =========
  28
  29 ``fd``
  30     File descriptor returned by :c:func:`open()`.
  31
  32 ``argp``
  33     Pointer to struct :c:type:`v4l2_dbg_register`.
  34
  35 Description
  36 ===========
  37
  38 .. note::
  39
  40     This is an :ref:`experimental` interface and may
  41     change in the future.
  42
  43 For driver debugging purposes these ioctls allow test applications to
  44 access hardware registers directly. Regular applications must not use
  45 them.
  46
  47 Since writing or even reading registers can jeopardize the system
  48 security, its stability and damage the hardware, both ioctls require
  49 superuser privileges. Additionally the Linux kernel must be compiled
  50 with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.
  51
  52 To write a register applications must initialize all fields of a struct
  53 :c:type:`v4l2_dbg_register` except for ``size`` and
  54 call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
  55 ``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
  56 on the TV card, the ``reg`` field specifies a register number and the
  57 ``val`` field the value to be written into the register.
  58
  59 To read a register applications must initialize the ``match.type``,
  60 ``match.addr`` or ``match.name`` and ``reg`` fields, and call
  61 ``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success
  62 the driver stores the register value in the ``val`` field and the size
  63 (in bytes) of the value in ``size``.
  64
  65 When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
  66 selects the nth non-sub-device chip on the TV card. The number zero
  67 always selects the host chip, e. g. the chip connected to the PCI or USB
  68 bus. You can find out which chips are present with the
  69 :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
  70
  71 When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
  72 selects the nth sub-device.
  73
  74 These ioctls are optional, not all drivers may support them. However
  75 when a driver supports these ioctls it must also support
  76 :ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely
  77 it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.
  78
  79 ``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
  80 in Linux 2.6.21, but their API was changed to the one described here in
  81 kernel 2.6.29.
  82
  83 We recommended the v4l2-dbg utility over calling these ioctls directly.
  84 It is available from the LinuxTV v4l-dvb repository; see
  85 `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
  86 instructions.
  87
  88 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}|
  89
  90 .. c:type:: v4l2_dbg_match
  91
  92 .. flat-table:: struct v4l2_dbg_match
  93     :header-rows:  0
  94     :stub-columns: 0
  95     :widths:       1 1 2
  96
  97     * - __u32
  98       - ``type``
  99       - See :ref:`chip-match-types` for a list of possible types.
 100     * - union {
 101       - (anonymous)
 102     * - __u32
 103       - ``addr``
 104       - Match a chip by this number, interpreted according to the ``type``
 105         field.
 106     * - char
 107       - ``name[32]``
 108       - Match a chip by this name, interpreted according to the ``type``
 109         field. Currently unused.
 110     * - }
 111       -
 112
 113
 114 .. c:type:: v4l2_dbg_register
 115
 116 .. flat-table:: struct v4l2_dbg_register
 117     :header-rows:  0
 118     :stub-columns: 0
 119
 120     * - struct v4l2_dbg_match
 121       - ``match``
 122       - How to match the chip, see :c:type:`v4l2_dbg_match`.
 123     * - __u32
 124       - ``size``
 125       - The register size in bytes.
 126     * - __u64
 127       - ``reg``
 128       - A register number.
 129     * - __u64
 130       - ``val``
 131       - The value read from, or to be written into the register.
 132
 133
 134 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
 135
 136 .. _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 Return Value
 152 ============
 153
 154 On success 0 is returned, on error -1 and the ``errno`` variable is set
 155 appropriately. The generic error codes are described at the
 156 :ref:`Generic Error Codes <gen-errors>` chapter.
 157
 158 EPERM
 159     Insufficient permissions. Root privileges are required to execute
 160     these ioctls.