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