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