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