1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _VIDIOC_DBG_G_REGISTER:
4
5**************************************************
6ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
7**************************************************
8
9Name
10====
11
12VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
13
14
15Synopsis
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
25Arguments
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
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
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 2
97
98    * - __u32
99      - ``type``
100      - See :ref:`chip-match-types` for a list of possible types.
101    * - union {
102      - (anonymous)
103    * - __u32
104      - ``addr``
105      - Match a chip by this number, interpreted according to the ``type``
106	field.
107    * - char
108      - ``name[32]``
109      - Match a chip by this name, interpreted according to the ``type``
110	field. Currently unused.
111    * - }
112      -
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
155Return Value
156============
157
158On success 0 is returned, on error -1 and the ``errno`` variable is set
159appropriately. The generic error codes are described at the
160:ref:`Generic Error Codes <gen-errors>` chapter.
161
162EPERM
163    Insufficient permissions. Root privileges are required to execute
164    these ioctls.
165