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

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