MEDIA_IOC_DEVICE_INFO | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

media-ioc-device-info.rst:1-106

Hardware instance 식별에는 serial을 우선 사용하고, 없으면 bus_info를 사용합니다. bus_info는 unique하지만 reboot나 재연결 뒤 바뀔 수 있으므로 장기 식별자로 사용할 때 주의해야 합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

2 .. c:namespace:: MC

4 .. _media_ioc_device_info:

6 ***************************

7 ioctl MEDIA_IOC_DEVICE_INFO

8 ***************************

10 Name

11 ====

13 MEDIA_IOC_DEVICE_INFO - Query device information

15 Synopsis

16 ========

18 .. c:macro:: MEDIA_IOC_DEVICE_INFO

20 ``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)``

22 Arguments

23 =========

25 ``fd``

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

28 ``argp``

29 Pointer to struct :c:type:`media_device_info`.

31 Description

32 ===========

34 All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To

35 query device information, applications call the ioctl with a pointer to

36 a struct :c:type:`media_device_info`. The driver

37 fills the structure and returns the information to the application. The

38 ioctl never fails.

40 .. c:type:: media_device_info

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

44 .. flat-table:: struct media_device_info

45 :header-rows: 0

46 :stub-columns: 0

47 :widths: 1 1 2

49 * - char

50 - ``driver``\ [16]

51 - Name of the driver implementing the media API as a NUL-terminated

52 ASCII string. The driver version is stored in the

53 ``driver_version`` field.

55 Driver specific applications can use this information to verify

56 the driver identity. It is also useful to work around known bugs,

57 or to identify drivers in error reports.

59 * - char

60 - ``model``\ [32]

61 - Device model name as a NUL-terminated UTF-8 string. The device

62 version is stored in the ``device_version`` field and is not be

63 appended to the model name.

65 * - char

66 - ``serial``\ [40]

67 - Serial number as a NUL-terminated ASCII string.

69 * - char

70 - ``bus_info``\ [32]

71 - Location of the device in the system as a NUL-terminated ASCII

72 string. This includes the bus type name (PCI, USB, ...) and a

73 bus-specific identifier.

75 * - __u32

76 - ``media_version``

77 - Media API version, formatted with the ``KERNEL_VERSION()`` macro.

79 * - __u32

80 - ``hw_revision``

81 - Hardware device revision in a driver-specific format.

83 * - __u32

84 - ``driver_version``

85 - Media device driver version, formatted with the

86 ``KERNEL_VERSION()`` macro. Together with the ``driver`` field

87 this identifies a particular driver.

89 * - __u32

90 - ``reserved``\ [31]

91 - Reserved for future extensions. Drivers and applications must set

92 this array to zero.

94 The ``serial`` and ``bus_info`` fields can be used to distinguish

95 between multiple instances of otherwise identical hardware. The serial

96 number takes precedence when provided and can be assumed to be unique.

97 If the serial number is an empty string, the ``bus_info`` field can be

98 used instead. The ``bus_info`` field is guaranteed to be unique, but can

99 vary across reboots or device unplug/replug.

100

101 Return Value

102 ============

103

104 On success 0 is returned, on error -1 and the ``errno`` variable is set

105 appropriately. The generic error codes are described at the

106 :ref:`Generic Error Codes <gen-errors>` chapter.

107

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

이름, 호출 형식과 arguments

1-30

`MEDIA_IOC_DEVICE_INFO`는 media device 정보를 조회합니다. 모든 media device가 지원해야 하는 `MC` namespace ioctl입니다.

int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp);

MEDIA_IOC_DEVICE_INFO arguments

Argument의미

fd`open()`이 반환한 file descriptor

argp`struct media_device_info`를 가리키는 pointer

열린 media device와 결과 structure를 전달합니다.

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

.. _media_ioc_device_info:

***************************
ioctl MEDIA_IOC_DEVICE_INFO
***************************

Name
====

MEDIA_IOC_DEVICE_INFO - Query device information

Synopsis
========

.. c:macro:: MEDIA_IOC_DEVICE_INFO

``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)``

Arguments
=========

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

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

조회 동작

31-39

Application은 `struct media_device_info` pointer로 `MEDIA_IOC_DEVICE_INFO`를 호출합니다. Driver가 structure를 채워 device 정보를 application에 반환합니다.

원문은 이 ioctl이 절대로 실패하지 않는다고 명시합니다.

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

All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
query device information, applications call the ioctl with a pointer to
a struct :c:type:`media_device_info`. The driver
fills the structure and returns the information to the application. The
ioctl never fails.

struct media_device_info

40-93

struct media_device_info

Field정의

char driver[16]Media API를 구현한 driver 이름의 NUL-terminated ASCII string. Version은 driver_version에 저장

char model[32]Device model 이름의 NUL-terminated UTF-8 string. Device version은 device_version field에 두며 model 이름에 붙이지 않음

char serial[40]Serial number의 NUL-terminated ASCII string

char bus_info[32]PCI·USB 등 bus type과 bus별 identifier를 포함한 system 내 위치의 NUL-terminated ASCII string

__u32 media_versionKERNEL_VERSION() macro 형식의 Media API version

__u32 hw_revisionDriver-specific 형식의 hardware device revision

__u32 driver_versionKERNEL_VERSION() 형식의 media device driver version. driver field와 함께 특정 driver를 식별

__u32 reserved[31]향후 확장용. Driver와 application은 배열 전체를 0으로 설정

각 field의 type, 길이, encoding과 안정성 규칙을 보존합니다.

Driver 전용 application은 `driver`와 `driver_version`으로 driver identity를 확인할 수 있습니다. 알려진 bug를 우회하거나 오류 보고서에서 driver를 식별할 때도 유용합니다.

`model`에는 device version을 덧붙이지 않습니다. 원문은 device version을 `device_version` field에 저장한다고 설명합니다.

.. c:type:: media_device_info

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

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

    *  -  char
       -  ``driver``\ [16]
       -  Name of the driver implementing the media API as a NUL-terminated
	  ASCII string. The driver version is stored in the
	  ``driver_version`` field.

	  Driver specific applications can use this information to verify
	  the driver identity. It is also useful to work around known bugs,
	  or to identify drivers in error reports.

    *  -  char
       -  ``model``\ [32]
       -  Device model name as a NUL-terminated UTF-8 string. The device
	  version is stored in the ``device_version`` field and is not be
	  appended to the model name.

    *  -  char
       -  ``serial``\ [40]
       -  Serial number as a NUL-terminated ASCII string.

    *  -  char
       -  ``bus_info``\ [32]
       -  Location of the device in the system as a NUL-terminated ASCII
	  string. This includes the bus type name (PCI, USB, ...) and a
	  bus-specific identifier.

    *  -  __u32
       -  ``media_version``
       -  Media API version, formatted with the ``KERNEL_VERSION()`` macro.

    *  -  __u32
       -  ``hw_revision``
       -  Hardware device revision in a driver-specific format.

    *  -  __u32
       -  ``driver_version``
       -  Media device driver version, formatted with the
	  ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
	  this identifies a particular driver.

    *  -  __u32
       -  ``reserved``\ [31]
       -  Reserved for future extensions. Drivers and applications must set
	  this array to zero.

serial과 bus_info의 우선순위

94-100

`serial`과 `bus_info`는 그 밖의 특성이 같은 hardware instance 여러 개를 구별하는 데 사용할 수 있습니다.

제공된다면 serial number가 우선하며 unique하다고 가정할 수 있습니다. `serial`이 빈 string이면 `bus_info`를 대신 사용합니다.

`bus_info`는 unique함이 보장되지만 reboot 또는 device unplug/replug를 거치면 바뀔 수 있습니다.

Device instance 식별

serial field가 비어 있는지 확인값이 있으면 unique serial을 우선 사용빈 string이면 unique bus_info 사용bus_info는 reboot·재연결 후 변경 가능성 고려

안정적인 identifier를 선택하는 우선순위입니다.

The ``serial`` and ``bus_info`` fields can be used to distinguish
between multiple instances of otherwise identical hardware. The serial
number takes precedence when provided and can be assumed to be unique.
If the serial number is an empty string, the ``bus_info`` field can be
used instead. The ``bus_info`` field is guaranteed to be unique, but can
vary across reboots or device unplug/replug.

반환값

101-106

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 알맞게 설정하며, 공통 오류는 `Generic Error Codes <gen-errors>` 장에서 설명합니다.

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.