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 .. c:function:: int ioctl( int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp )
  19     :name: VIDIOC_DBG_G_REGISTER
  20
  21 .. c:function:: int ioctl( int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp )
  22     :name: VIDIOC_DBG_S_REGISTER
  23
  24
  25 Arguments
  26 =========
  27
  28 ``fd``
  29     File descriptor returned by :ref:`open() <func-open>`.
  30
  31 ``argp``
  32
  33
  34 Description
  35 ===========
  36
  37 .. note::
  38
  39     This is an :ref:`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 :c:type:`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` 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`. 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 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
  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 1 2
  96
  97     * - __u32
  98       - ``type``
  99       - See :ref:`chip-match-types` for a list of possible types.
 100     * - union
 101       - (anonymous)
 102     * -
 103       - __u32
 104       - ``addr``
 105       - Match a chip by this number, interpreted according to the ``type``
 106         field.
 107     * -
 108       - char
 109       - ``name[32]``
 110       - Match a chip by this name, interpreted according to the ``type``
 111         field. Currently unused.
 112
 113
 114
 115 .. c:type:: v4l2_dbg_register
 116
 117 .. flat-table:: struct v4l2_dbg_register
 118     :header-rows:  0
 119     :stub-columns: 0
 120
 121     * - struct v4l2_dbg_match
 122       - ``match``
 123       - How to match the chip, see :c:type:`v4l2_dbg_match`.
 124     * - __u32
 125       - ``size``
 126       - The register size in bytes.
 127     * - __u64
 128       - ``reg``
 129       - A register number.
 130     * - __u64
 131       - ``val``
 132       - The value read from, or to be written into the register.
 133
 134
 135
 136 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 137
 138 .. _chip-match-types:
 139
 140 .. flat-table:: Chip Match Types
 141     :header-rows:  0
 142     :stub-columns: 0
 143     :widths:       3 1 4
 144
 145     * - ``V4L2_CHIP_MATCH_BRIDGE``
 146       - 0
 147       - Match the nth chip on the card, zero for the bridge chip. Does not
 148         match sub-devices.
 149     * - ``V4L2_CHIP_MATCH_SUBDEV``
 150       - 4
 151       - Match the nth sub-device.
 152
 153
 154 Return Value
 155 ============
 156
 157 On success 0 is returned, on error -1 and the ``errno`` variable is set
 158 appropriately. The generic error codes are described at the
 159 :ref:`Generic Error Codes <gen-errors>` chapter.
 160
 161 EPERM
 162     Insufficient permissions. Root privileges are required to execute
 163     these ioctls.