vidioc-dbg-g-register.rst

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