0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_DBG_G_REGISTER:
0005
0006 **************************************************
0007 ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
0008 **************************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_DBG_G_REGISTER
0019
0020 ``int ioctl(int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp)``
0021
0022 .. c:macro:: VIDIOC_DBG_S_REGISTER
0023
0024 ``int ioctl(int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_dbg_register`.
0034
0035 Description
0036 ===========
0037
0038 .. note::
0039
0040 This is an :ref:`experimental` interface and may
0041 change in the future.
0042
0043 For driver debugging purposes these ioctls allow test applications to
0044 access hardware registers directly. Regular applications must not use
0045 them.
0046
0047 Since writing or even reading registers can jeopardize the system
0048 security, its stability and damage the hardware, both ioctls require
0049 superuser privileges. Additionally the Linux kernel must be compiled
0050 with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.
0051
0052 To write a register applications must initialize all fields of a struct
0053 :c:type:`v4l2_dbg_register` except for ``size`` and
0054 call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
0055 ``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
0056 on the TV card, the ``reg`` field specifies a register number and the
0057 ``val`` field the value to be written into the register.
0058
0059 To read a register applications must initialize the ``match.type``,
0060 ``match.addr`` or ``match.name`` and ``reg`` fields, and call
0061 ``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success
0062 the driver stores the register value in the ``val`` field and the size
0063 (in bytes) of the value in ``size``.
0064
0065 When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
0066 selects the nth non-sub-device chip on the TV card. The number zero
0067 always selects the host chip, e. g. the chip connected to the PCI or USB
0068 bus. You can find out which chips are present with the
0069 :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
0070
0071 When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
0072 selects the nth sub-device.
0073
0074 These ioctls are optional, not all drivers may support them. However
0075 when a driver supports these ioctls it must also support
0076 :ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely
0077 it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.
0078
0079 ``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
0080 in Linux 2.6.21, but their API was changed to the one described here in
0081 kernel 2.6.29.
0082
0083 We recommended the v4l2-dbg utility over calling these ioctls directly.
0084 It is available from the LinuxTV v4l-dvb repository; see
0085 `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
0086 instructions.
0087
0088 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}|
0089
0090 .. c:type:: v4l2_dbg_match
0091
0092 .. flat-table:: struct v4l2_dbg_match
0093 :header-rows: 0
0094 :stub-columns: 0
0095 :widths: 1 1 2
0096
0097 * - __u32
0098 - ``type``
0099 - See :ref:`chip-match-types` for a list of possible types.
0100 * - union {
0101 - (anonymous)
0102 * - __u32
0103 - ``addr``
0104 - Match a chip by this number, interpreted according to the ``type``
0105 field.
0106 * - char
0107 - ``name[32]``
0108 - Match a chip by this name, interpreted according to the ``type``
0109 field. Currently unused.
0110 * - }
0111 -
0112
0113
0114 .. c:type:: v4l2_dbg_register
0115
0116 .. flat-table:: struct v4l2_dbg_register
0117 :header-rows: 0
0118 :stub-columns: 0
0119
0120 * - struct v4l2_dbg_match
0121 - ``match``
0122 - How to match the chip, see :c:type:`v4l2_dbg_match`.
0123 * - __u32
0124 - ``size``
0125 - The register size in bytes.
0126 * - __u64
0127 - ``reg``
0128 - A register number.
0129 * - __u64
0130 - ``val``
0131 - The value read from, or to be written into the register.
0132
0133
0134 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0135
0136 .. _chip-match-types:
0137
0138 .. flat-table:: Chip Match Types
0139 :header-rows: 0
0140 :stub-columns: 0
0141 :widths: 3 1 4
0142
0143 * - ``V4L2_CHIP_MATCH_BRIDGE``
0144 - 0
0145 - Match the nth chip on the card, zero for the bridge chip. Does not
0146 match sub-devices.
0147 * - ``V4L2_CHIP_MATCH_SUBDEV``
0148 - 4
0149 - Match the nth sub-device.
0150
0151 Return Value
0152 ============
0153
0154 On success 0 is returned, on error -1 and the ``errno`` variable is set
0155 appropriately. The generic error codes are described at the
0156 :ref:`Generic Error Codes <gen-errors>` chapter.
0157
0158 EPERM
0159 Insufficient permissions. Root privileges are required to execute
0160 these ioctls.
