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. 161