Documentation/linux_tv/media/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 *man VIDIOC_DBG_G_REGISTER(2)*
  10
  11 VIDIOC_DBG_S_REGISTER
  12 Read or write hardware registers
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, int request, struct v4l2_dbg_register *argp )
  19
  20 .. c:function:: int ioctl( int fd, int request, const struct v4l2_dbg_register *argp )
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :ref:`open() <func-open>`.
  27
  28 ``request``
  29     VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
  30
  31 ``argp``
  32
  33
  34 Description
  35 ===========
  36
  37     **Note**
  38
  39     This is an :ref:`experimental <experimental>` interface and may
  40     change in the future.
  41
  42 For driver debugging purposes these ioctls allow test applications to
  43 access hardware registers directly. Regular applications must not use
  44 them.
  45
  46 Since writing or even reading registers can jeopardize the system
  47 security, its stability and damage the hardware, both ioctls require
  48 superuser privileges. Additionally the Linux kernel must be compiled
  49 with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.
  50
  51 To write a register applications must initialize all fields of a struct
  52 :ref:`v4l2_dbg_register <v4l2-dbg-register>` except for ``size`` and
  53 call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
  54 ``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
  55 on the TV card, the ``reg`` field specifies a register number and the
  56 ``val`` field the value to be written into the register.
  57
  58 To read a register applications must initialize the ``match.type``,
  59 ``match.addr`` or ``match.name`` and ``reg`` fields, and call
  60 ``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success
  61 the driver stores the register value in the ``val`` field and the size
  62 (in bytes) of the value in ``size``.
  63
  64 When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
  65 selects the nth non-sub-device chip on the TV card. The number zero
  66 always selects the host chip, e. g. the chip connected to the PCI or USB
  67 bus. You can find out which chips are present with the
  68 :ref:`VIDIOC_DBG_G_CHIP_INFO <vidioc-dbg-g-chip-info>` ioctl.
  69
  70 When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
  71 selects the nth sub-device.
  72
  73 These ioctls are optional, not all drivers may support them. However
  74 when a driver supports these ioctls it must also support
  75 :ref:`VIDIOC_DBG_G_CHIP_INFO <vidioc-dbg-g-chip-info>`. Conversely
  76 it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.
  77
  78 ``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
  79 in Linux 2.6.21, but their API was changed to the one described here in
  80 kernel 2.6.29.
  81
  82 We recommended the v4l2-dbg utility over calling these ioctls directly.
  83 It is available from the LinuxTV v4l-dvb repository; see
  84 `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
  85 instructions.
  86
  87
  88 .. _v4l2-dbg-match:
  89
  90 .. flat-table:: struct v4l2_dbg_match
  91     :header-rows:  0
  92     :stub-columns: 0
  93     :widths:       1 1 1 2
  94
  95
  96     -  .. row 1
  97
  98        -  __u32
  99
 100        -  ``type``
 101
 102        -  See :ref:`chip-match-types` for a list of possible types.
 103
 104     -  .. row 2
 105
 106        -  union
 107
 108        -  (anonymous)
 109
 110     -  .. row 3
 111
 112        -
 113        -  __u32
 114
 115        -  ``addr``
 116
 117        -  Match a chip by this number, interpreted according to the ``type``
 118           field.
 119
 120     -  .. row 4
 121
 122        -
 123        -  char
 124
 125        -  ``name[32]``
 126
 127        -  Match a chip by this name, interpreted according to the ``type``
 128           field. Currently unused.
 129
 130
 131
 132 .. _v4l2-dbg-register:
 133
 134 .. flat-table:: struct v4l2_dbg_register
 135     :header-rows:  0
 136     :stub-columns: 0
 137
 138
 139     -  .. row 1
 140
 141        -  struct v4l2_dbg_match
 142
 143        -  ``match``
 144
 145        -  How to match the chip, see :ref:`v4l2-dbg-match`.
 146
 147     -  .. row 2
 148
 149        -  __u32
 150
 151        -  ``size``
 152
 153        -  The register size in bytes.
 154
 155     -  .. row 3
 156
 157        -  __u64
 158
 159        -  ``reg``
 160
 161        -  A register number.
 162
 163     -  .. row 4
 164
 165        -  __u64
 166
 167        -  ``val``
 168
 169        -  The value read from, or to be written into the register.
 170
 171
 172
 173 .. _chip-match-types:
 174
 175 .. flat-table:: Chip Match Types
 176     :header-rows:  0
 177     :stub-columns: 0
 178     :widths:       3 1 4
 179
 180
 181     -  .. row 1
 182
 183        -  ``V4L2_CHIP_MATCH_BRIDGE``
 184
 185        -  0
 186
 187        -  Match the nth chip on the card, zero for the bridge chip. Does not
 188           match sub-devices.
 189
 190     -  .. row 2
 191
 192        -  ``V4L2_CHIP_MATCH_SUBDEV``
 193
 194        -  4
 195
 196        -  Match the nth sub-device.
 197
 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.
 210
 211
 212 .. ------------------------------------------------------------------------------
 213 .. This file was automatically converted from DocBook-XML with the dbxml
 214 .. library (https://github.com/return42/sphkerneldoc). The origin XML comes
 215 .. from the linux kernel, refer to:
 216 ..
 217 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
 218 .. ------------------------------------------------------------------------------