VIDIOC_DBG_G_REGISTER와 VIDIOC_DBG_S_REGISTER ioctl

읽기·쓰기 호출 형식과 인자

`VIDIOC_DBG_G_REGISTER`와 `VIDIOC_DBG_S_REGISTER`는 하드웨어 레지스터를 직접 읽거나 씁니다. 읽기는 변경 가능한 `struct v4l2_dbg_register *argp`를 받고, 쓰기는 `const struct v4l2_dbg_register *argp`를 받습니다.

두 호출 모두 `open()`이 반환한 `fd`와 `struct v4l2_dbg_register` 포인터를 사용합니다. 읽기 결과는 같은 구조체의 `val`과 `size`로 돌아옵니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_DBG_G_REGISTER:

**************************************************
ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
**************************************************

Name
====

VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers

Synopsis
========

.. c:macro:: VIDIOC_DBG_G_REGISTER

``int ioctl(int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp)``

.. c:macro:: VIDIOC_DBG_S_REGISTER

``int ioctl(int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_dbg_register`.

권한, 위험과 레지스터 접근 절차

이 인터페이스도 실험적이며 드라이버 디버깅용 테스트 프로그램만 사용해야 합니다. 레지스터 읽기나 쓰기는 시스템 보안과 안정성을 해치거나 하드웨어를 손상시킬 수 있으므로 두 ioctl 모두 superuser 권한이 필요합니다. 커널도 `CONFIG_VIDEO_ADV_DEBUG`를 켜서 빌드해야 합니다.

레지스터를 쓰려면 `size`를 제외한 모든 필드를 초기화합니다. `match.type`과 `match.addr` 또는 `match.name`으로 TV 카드의 칩을 고르고, `reg`에 레지스터 번호, `val`에 쓸 값을 넣은 뒤 `VIDIOC_DBG_S_REGISTER`를 호출합니다.

레지스터를 읽으려면 일치 조건과 `reg`를 초기화한 뒤 `VIDIOC_DBG_G_REGISTER`를 호출합니다. 성공하면 드라이버가 `val`에 읽은 값, `size`에 값의 바이트 크기를 저장합니다.

bridge 일치에서 주소 0은 PCI나 USB 버스에 연결된 host 칩이고, 그 밖의 번호는 n번째 비-sub-device 칩을 뜻합니다. 존재하는 칩은 `VIDIOC_DBG_G_CHIP_INFO`로 확인합니다. sub-device 일치에서는 주소가 n번째 sub-device를 선택합니다.

레지스터 ioctl은 선택 기능입니다. 이를 지원하는 드라이버는 반드시 `VIDIOC_DBG_G_CHIP_INFO`도 지원해야 하지만, 칩 정보 조회만 지원하고 레지스터 접근은 제공하지 않을 수 있습니다. ioctl은 Linux 2.6.21에 도입됐고 현재 API 형태는 2.6.29에서 바뀌었습니다. 직접 호출보다 `v4l2-dbg` 도구가 권장됩니다.

Description
===========

.. note::

    This is an :ref:`experimental` interface and may
    change in the future.

For driver debugging purposes these ioctls allow test applications to
access hardware registers directly. Regular applications must not use
them.

Since writing or even reading registers can jeopardize the system
security, its stability and damage the hardware, both ioctls require
superuser privileges. Additionally the Linux kernel must be compiled
with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.

To write a register applications must initialize all fields of a struct
:c:type:`v4l2_dbg_register` except for ``size`` and
call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
on the TV card, the ``reg`` field specifies a register number and the
``val`` field the value to be written into the register.

To read a register applications must initialize the ``match.type``,
``match.addr`` or ``match.name`` and ``reg`` fields, and call
``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success
the driver stores the register value in the ``val`` field and the size
(in bytes) of the value in ``size``.

When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
selects the nth non-sub-device chip on the TV card. The number zero
always selects the host chip, e. g. the chip connected to the PCI or USB
bus. You can find out which chips are present with the
:ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.

When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
selects the nth sub-device.

These ioctls are optional, not all drivers may support them. However
when a driver supports these ioctls it must also support
:ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely
it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.

``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
in Linux 2.6.21, but their API was changed to the one described here in
kernel 2.6.29.

We recommended the v4l2-dbg utility over calling these ioctls directly.
It is available from the LinuxTV v4l-dvb repository; see
`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
instructions.

v4l2_dbg_match 구조체

.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}|

.. c:type:: v4l2_dbg_match

.. flat-table:: struct v4l2_dbg_match
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``type``
      - See :ref:`chip-match-types` for a list of possible types.
    * - union {
      - (anonymous)
    * - __u32
      - ``addr``
      - Match a chip by this number, interpreted according to the ``type``
	field.
    * - char
      - ``name[32]``
      - Match a chip by this name, interpreted according to the ``type``
	field. Currently unused.
    * - }
      -

v4l2_dbg_register 구조체

`reg`와 `val`은 64비트이므로 폭이 다른 하드웨어 레지스터를 담을 수 있습니다. 읽기에서 실제 유효 바이트 수는 드라이버가 반환하는 `size`로 판단해야 합니다.

.. c:type:: v4l2_dbg_register

.. flat-table:: struct v4l2_dbg_register
    :header-rows:  0
    :stub-columns: 0

    * - struct v4l2_dbg_match
      - ``match``
      - How to match the chip, see :c:type:`v4l2_dbg_match`.
    * - __u32
      - ``size``
      - The register size in bytes.
    * - __u64
      - ``reg``
      - A register number.
    * - __u64
      - ``val``
      - The value read from, or to be written into the register.

칩 일치 유형

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _chip-match-types:

.. flat-table:: Chip Match Types
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_CHIP_MATCH_BRIDGE``
      - 0
      - Match the nth chip on the card, zero for the bridge chip. Does not
	match sub-devices.
    * - ``V4L2_CHIP_MATCH_SUBDEV``
      - 4
      - Match the nth sub-device.

반환값과 권한 오류

성공하면 0을 반환하고 실패하면 -1과 `errno`를 반환합니다. `EPERM`은 권한이 부족하다는 뜻이며 이 ioctl을 실행하려면 root 권한이 필요합니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EPERM
    Insufficient permissions. Root privileges are required to execute
    these ioctls.