xref: /linux/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst (revision f77d26a9fc525286bcef3d4f98b52e17482cf49c) 
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**************************************************
13ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
14**************************************************
15
16Name
17====
18
19VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
20
21
22Synopsis
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
32Arguments
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
42Description
43===========
44
45.. note::
46
47    This is an :ref:`experimental` interface and may
48    change in the future.
49
50For driver debugging purposes these ioctls allow test applications to
51access hardware registers directly. Regular applications must not use
52them.
53
54Since writing or even reading registers can jeopardize the system
55security, its stability and damage the hardware, both ioctls require
56superuser privileges. Additionally the Linux kernel must be compiled
57with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.
58
59To write a register applications must initialize all fields of a struct
60:c:type:`v4l2_dbg_register` except for ``size`` and
61call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
62``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
63on the TV card, the ``reg`` field specifies a register number and the
64``val`` field the value to be written into the register.
65
66To 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
69the driver stores the register value in the ``val`` field and the size
70(in bytes) of the value in ``size``.
71
72When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
73selects the nth non-sub-device chip on the TV card. The number zero
74always selects the host chip, e. g. the chip connected to the PCI or USB
75bus. You can find out which chips are present with the
76:ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
77
78When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
79selects the nth sub-device.
80
81These ioctls are optional, not all drivers may support them. However
82when a driver supports these ioctls it must also support
83:ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely
84it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.
85
86``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
87in Linux 2.6.21, but their API was changed to the one described here in
88kernel 2.6.29.
89
90We recommended the v4l2-dbg utility over calling these ioctls directly.
91It is available from the LinuxTV v4l-dvb repository; see
92`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
93instructions.
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
162Return Value
163============
164
165On success 0 is returned, on error -1 and the ``errno`` variable is set
166appropriately. The generic error codes are described at the
167:ref:`Generic Error Codes <gen-errors>` chapter.
168
169EPERM
170    Insufficient permissions. Root privileges are required to execute
171    these ioctls.
172