VIDIOC_DBG_G_CHIP_INFO ioctl

이름, 호출 형식과 인자

`VIDIOC_DBG_G_CHIP_INFO`는 TV 카드에 존재하는 칩을 식별하는 디버그 ioctl입니다. 호출 형식은 `int ioctl(int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp)`입니다.

`fd`는 `open()`이 반환한 파일 디스크립터이며 `argp`는 선택 조건과 결과를 담는 `struct v4l2_dbg_chip_info`를 가리킵니다.

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

.. _VIDIOC_DBG_G_CHIP_INFO:

****************************
ioctl VIDIOC_DBG_G_CHIP_INFO
****************************

Name
====

VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card

Synopsis
========

.. c:macro:: VIDIOC_DBG_G_CHIP_INFO

``int ioctl(int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp)``

Arguments
=========

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

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

실험적 인터페이스와 칩 열거

이 인터페이스는 실험적이며 앞으로 바뀔 수 있습니다. 드라이버 디버깅용 테스트 프로그램이 TV 카드의 칩 구성을 조회할 때만 사용해야 하며 일반 응용 프로그램은 사용하면 안 됩니다. 칩별 결함을 찾았다면 linux-media 메일링 리스트에 알려 드라이버에서 수정되도록 해야 합니다.

커널은 `CONFIG_VIDEO_ADV_DEBUG` 옵션을 켜서 빌드해야 이 ioctl을 제공합니다. 응용 프로그램은 `match.type`과 `match.addr` 또는 `match.name`을 초기화합니다. 성공하면 드라이버가 선택된 칩의 이름을 `name`에, 레지스터 접근 능력을 `flags`에 저장합니다.

`V4L2_CHIP_MATCH_BRIDGE`에서는 `match.addr`가 TV 카드의 n번째 bridge 칩을 선택합니다. 0부터 하나씩 증가시키며 호출하다 `EINVAL`이 나오면 열거가 끝납니다. 0은 PCI나 USB 버스에 직접 연결된 bridge 칩 자체이고, 0보다 큰 값은 AC97 레지스터 블록 같은 bridge 내부의 특정 부분을 가리킬 수 있습니다.

`V4L2_CHIP_MATCH_SUBDEV`에서는 `match.addr`가 n번째 sub-device를 선택하므로 같은 방식으로 모든 sub-device를 열거할 수 있습니다. 성공 시 `V4L2_CHIP_FL_READABLE`은 레지스터 읽기 지원, `V4L2_CHIP_FL_WRITABLE`은 쓰기 지원을 뜻합니다.

ioctl을 직접 호출하기보다 LinuxTV v4l-dvb 저장소의 `v4l2-dbg` 도구를 사용하는 것이 권장됩니다.

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

.. note::

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

For driver debugging purposes this ioctl allows test applications to
query the driver about the chips present on the TV card. Regular
applications must not use it. When you found a chip specific bug, please
contact the linux-media mailing list
(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
so it can be fixed.

Additionally the Linux kernel must be compiled with the
``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl.

To query the driver applications must initialize the ``match.type`` and
``match.addr`` or ``match.name`` fields of a struct
:c:type:`v4l2_dbg_chip_info` and call
:ref:`VIDIOC_DBG_G_CHIP_INFO` with a pointer to this structure. On success
the driver stores information about the selected chip in the ``name``
and ``flags`` fields.

When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
selects the nth bridge 'chip' on the TV card. You can enumerate all
chips by starting at zero and incrementing ``match.addr`` by one until
:ref:`VIDIOC_DBG_G_CHIP_INFO` fails with an ``EINVAL`` error code. The number
zero always selects the bridge chip itself, e. g. the chip connected to
the PCI or USB bus. Non-zero numbers identify specific parts of the
bridge chip such as an AC97 register block.

When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
selects the nth sub-device. This allows you to enumerate over all
sub-devices.

On success, the ``name`` field will contain a chip name and the
``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver
supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE``
if the driver supports writing registers to the device.

We recommended the v4l2-dbg utility over calling this ioctl 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 구조체

현재 이름 기반 일치는 사용되지 않으므로 실제 열거에서는 `type`과 `addr` 조합을 사용합니다. 같은 구조체가 칩 정보 조회와 레지스터 접근 ioctl에 공통으로 쓰입니다.

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

.. _name-v4l2-dbg-match:

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

    * - __u32
      - ``type``
      - See :ref:`name-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.
    * - }
      -


.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

v4l2_dbg_chip_info 구조체

.. c:type:: v4l2_dbg_chip_info

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

    * - struct v4l2_dbg_match
      - ``match``
      - How to match the chip, see :ref:`name-v4l2-dbg-match`.
    * - char
      - ``name[32]``
      - The name of the chip.
    * - __u32
      - ``flags``
      - Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the
	driver supports reading registers from the device. If
	``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing
	registers.
    * - __u32
      - ``reserved[8]``
      - Reserved fields, both application and driver must set these to 0.

칩 일치 유형

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

.. _name-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`를 반환합니다. `EINVAL`은 `match_type`이 유효하지 않거나 조건에 맞는 장치가 없다는 뜻이며, 순차 열거에서는 목록의 끝을 나타내기도 합니다.

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.

EINVAL
    The ``match_type`` is invalid or no device could be matched.