161 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_DBG_G_REGISTER:5 6**************************************************7ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER8**************************************************9 10Name11====12 13VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers14 15Synopsis16========17 18.. c:macro:: VIDIOC_DBG_G_REGISTER19 20``int ioctl(int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp)``21 22.. c:macro:: VIDIOC_DBG_S_REGISTER23 24``int ioctl(int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp)``25 26Arguments27=========28 29``fd``30 File descriptor returned by :c:func:`open()`.31 32``argp``33 Pointer to struct :c:type:`v4l2_dbg_register`.34 35Description36===========37 38.. note::39 40 This is an :ref:`experimental` interface and may41 change in the future.42 43For driver debugging purposes these ioctls allow test applications to44access hardware registers directly. Regular applications must not use45them.46 47Since writing or even reading registers can jeopardize the system48security, its stability and damage the hardware, both ioctls require49superuser privileges. Additionally the Linux kernel must be compiled50with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.51 52To write a register applications must initialize all fields of a struct53:c:type:`v4l2_dbg_register` except for ``size`` and54call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The55``match.type`` and ``match.addr`` or ``match.name`` fields select a chip56on the TV card, the ``reg`` field specifies a register number and the57``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 call61``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success62the driver stores the register value in the ``val`` field and the size63(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 zero67always selects the host chip, e. g. the chip connected to the PCI or USB68bus. You can find out which chips are present with the69: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. However75when a driver supports these ioctls it must also support76:ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely77it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.78 79``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced80in Linux 2.6.21, but their API was changed to the one described here in81kernel 2.6.29.82 83We recommended the v4l2-dbg utility over calling these ioctls directly.84It is available from the LinuxTV v4l-dvb repository; see85`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access86instructions.87 88.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}|89 90.. c:type:: v4l2_dbg_match91 92.. flat-table:: struct v4l2_dbg_match93 :header-rows: 094 :stub-columns: 095 :widths: 1 1 296 97 * - __u3298 - ``type``99 - See :ref:`chip-match-types` for a list of possible types.100 * - union {101 - (anonymous)102 * - __u32103 - ``addr``104 - Match a chip by this number, interpreted according to the ``type``105 field.106 * - char107 - ``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_register115 116.. flat-table:: struct v4l2_dbg_register117 :header-rows: 0118 :stub-columns: 0119 120 * - struct v4l2_dbg_match121 - ``match``122 - How to match the chip, see :c:type:`v4l2_dbg_match`.123 * - __u32124 - ``size``125 - The register size in bytes.126 * - __u64127 - ``reg``128 - A register number.129 * - __u64130 - ``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 Types139 :header-rows: 0140 :stub-columns: 0141 :widths: 3 1 4142 143 * - ``V4L2_CHIP_MATCH_BRIDGE``144 - 0145 - Match the nth chip on the card, zero for the bridge chip. Does not146 match sub-devices.147 * - ``V4L2_CHIP_MATCH_SUBDEV``148 - 4149 - Match the nth sub-device.150 151Return Value152============153 154On success 0 is returned, on error -1 and the ``errno`` variable is set155appropriately. The generic error codes are described at the156:ref:`Generic Error Codes <gen-errors>` chapter.157 158EPERM159 Insufficient permissions. Root privileges are required to execute160 these ioctls.161