Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_DBG_G_REGISTER:
   4
   5 **************************************************
   6 ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
   7 **************************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_register *argp )
  19
  20 .. cpp:function:: int ioctl( int fd, int request, const struct v4l2_dbg_register *argp )
  21
  22
  23 Arguments
  24 =========
  25
  26 ``fd``
  27     File descriptor returned by :ref:`open() <func-open>`.
  28
  29 ``request``
  30     VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
  31
  32 ``argp``
  33
  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 :ref:`v4l2_dbg_register <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
  89 .. _v4l2-dbg-match:
  90
  91 .. flat-table:: struct v4l2_dbg_match
  92     :header-rows:  0
  93     :stub-columns: 0
  94     :widths:       1 1 1 2
  95
  96
  97     -  .. row 1
  98
  99        -  __u32
 100
 101        -  ``type``
 102
 103        -  See :ref:`chip-match-types` for a list of possible types.
 104
 105     -  .. row 2
 106
 107        -  union
 108
 109        -  (anonymous)
 110
 111     -  .. row 3
 112
 113        -
 114        -  __u32
 115
 116        -  ``addr``
 117
 118        -  Match a chip by this number, interpreted according to the ``type``
 119           field.
 120
 121     -  .. row 4
 122
 123        -
 124        -  char
 125
 126        -  ``name[32]``
 127
 128        -  Match a chip by this name, interpreted according to the ``type``
 129           field. Currently unused.
 130
 131
 132
 133 .. _v4l2-dbg-register:
 134
 135 .. flat-table:: struct v4l2_dbg_register
 136     :header-rows:  0
 137     :stub-columns: 0
 138
 139
 140     -  .. row 1
 141
 142        -  struct v4l2_dbg_match
 143
 144        -  ``match``
 145
 146        -  How to match the chip, see :ref:`v4l2-dbg-match`.
 147
 148     -  .. row 2
 149
 150        -  __u32
 151
 152        -  ``size``
 153
 154        -  The register size in bytes.
 155
 156     -  .. row 3
 157
 158        -  __u64
 159
 160        -  ``reg``
 161
 162        -  A register number.
 163
 164     -  .. row 4
 165
 166        -  __u64
 167
 168        -  ``val``
 169
 170        -  The value read from, or to be written into the register.
 171
 172
 173
 174 .. _chip-match-types:
 175
 176 .. flat-table:: Chip Match Types
 177     :header-rows:  0
 178     :stub-columns: 0
 179     :widths:       3 1 4
 180
 181
 182     -  .. row 1
 183
 184        -  ``V4L2_CHIP_MATCH_BRIDGE``
 185
 186        -  0
 187
 188        -  Match the nth chip on the card, zero for the bridge chip. Does not
 189           match sub-devices.
 190
 191     -  .. row 2
 192
 193        -  ``V4L2_CHIP_MATCH_SUBDEV``
 194
 195        -  4
 196
 197        -  Match the nth sub-device.
 198
 199
 200 Return Value
 201 ============
 202
 203 On success 0 is returned, on error -1 and the ``errno`` variable is set
 204 appropriately. The generic error codes are described at the
 205 :ref:`Generic Error Codes <gen-errors>` chapter.
 206
 207 EPERM
 208     Insufficient permissions. Root privileges are required to execute
 209     these ioctls.