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 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
  90
  91 .. _v4l2-dbg-match:
  92
  93 .. flat-table:: struct v4l2_dbg_match
  94     :header-rows:  0
  95     :stub-columns: 0
  96     :widths:       1 1 1 2
  97
  98
  99     -  .. row 1
 100
 101        -  __u32
 102
 103        -  ``type``
 104
 105        -  See :ref:`chip-match-types` for a list of possible types.
 106
 107     -  .. row 2
 108
 109        -  union
 110
 111        -  (anonymous)
 112
 113     -  .. row 3
 114
 115        -
 116        -  __u32
 117
 118        -  ``addr``
 119
 120        -  Match a chip by this number, interpreted according to the ``type``
 121           field.
 122
 123     -  .. row 4
 124
 125        -
 126        -  char
 127
 128        -  ``name[32]``
 129
 130        -  Match a chip by this name, interpreted according to the ``type``
 131           field. Currently unused.
 132
 133
 134
 135 .. _v4l2-dbg-register:
 136
 137 .. flat-table:: struct v4l2_dbg_register
 138     :header-rows:  0
 139     :stub-columns: 0
 140
 141
 142     -  .. row 1
 143
 144        -  struct v4l2_dbg_match
 145
 146        -  ``match``
 147
 148        -  How to match the chip, see :ref:`v4l2-dbg-match`.
 149
 150     -  .. row 2
 151
 152        -  __u32
 153
 154        -  ``size``
 155
 156        -  The register size in bytes.
 157
 158     -  .. row 3
 159
 160        -  __u64
 161
 162        -  ``reg``
 163
 164        -  A register number.
 165
 166     -  .. row 4
 167
 168        -  __u64
 169
 170        -  ``val``
 171
 172        -  The value read from, or to be written into the register.
 173
 174
 175
 176 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 177
 178 .. _chip-match-types:
 179
 180 .. flat-table:: Chip Match Types
 181     :header-rows:  0
 182     :stub-columns: 0
 183     :widths:       3 1 4
 184
 185
 186     -  .. row 1
 187
 188        -  ``V4L2_CHIP_MATCH_BRIDGE``
 189
 190        -  0
 191
 192        -  Match the nth chip on the card, zero for the bridge chip. Does not
 193           match sub-devices.
 194
 195     -  .. row 2
 196
 197        -  ``V4L2_CHIP_MATCH_SUBDEV``
 198
 199        -  4
 200
 201        -  Match the nth sub-device.
 202
 203
 204 Return Value
 205 ============
 206
 207 On success 0 is returned, on error -1 and the ``errno`` variable is set
 208 appropriately. The generic error codes are described at the
 209 :ref:`Generic Error Codes <gen-errors>` chapter.
 210
 211 EPERM
 212     Insufficient permissions. Root privileges are required to execute
 213     these ioctls.