← Documents Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst GitHub 원문 ↗

Linux 6.18.37 · Userspace API / Media / Media Controller

MEDIA_IOC_ENUM_ENTITIES

Media topology의 entity와 property를 비연속 ID 규칙에 맞춰 열거합니다.

Source pathDocumentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

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

1. 요약·해설

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

요약·해설

media-ioc-enum-entities.rst:1-146

Entity ID는 연속적이지도, device instance 사이에서 안정적이지도 않습니다. 반드시 `MEDIA_ENT_ID_FLAG_NEXT`를 사용해 순회하고 ID를 application에 hardcode하지 않아야 합니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: MC
3
4 .. _media_ioc_enum_entities:
5
6 *****************************
7 ioctl MEDIA_IOC_ENUM_ENTITIES
8 *****************************
9
10 Name
11 ====
12
13 MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
14
15 Synopsis
16 ========
17
18 .. c:macro:: MEDIA_IOC_ENUM_ENTITIES
19
20 ``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)``
21
22 Arguments
23 =========
24
25 ``fd``
26 File descriptor returned by :c:func:`open()`.
27
28 ``argp``
29 Pointer to struct :c:type:`media_entity_desc`.
30
31 Description
32 ===========
33
34 To query the attributes of an entity, applications set the id field of a
35 struct :c:type:`media_entity_desc` structure and
36 call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
37 structure. The driver fills the rest of the structure or returns an
38 EINVAL error code when the id is invalid.
39
40 .. _media-ent-id-flag-next:
41
42 Entities can be enumerated by or'ing the id with the
43 ``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information
44 about the entity with the smallest id strictly larger than the requested
45 one ('next entity'), or the ``EINVAL`` error code if there is none.
46
47 Entity IDs can be non-contiguous. Applications must *not* try to
48 enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
49 id's until they get an error.
50
51 .. c:type:: media_entity_desc
52
53 .. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{10.6cm}|
54
55 .. flat-table:: struct media_entity_desc
56 :header-rows: 0
57 :stub-columns: 0
58 :widths: 2 2 1 8
59
60 * - __u32
61 - ``id``
62 -
63 - Entity ID, set by the application. When the ID is or'ed with
64 ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns
65 the first entity with a larger ID. Do not expect that the ID will
66 always be the same for each instance of the device. In other words,
67 do not hardcode entity IDs in an application.
68
69 * - char
70 - ``name``\ [32]
71 -
72 - Entity name as an UTF-8 NULL-terminated string. This name must be unique
73 within the media topology.
74
75 * - __u32
76 - ``type``
77 -
78 - Entity type, see :ref:`media-entity-functions` for details.
79
80 * - __u32
81 - ``revision``
82 -
83 - Entity revision. Always zero (obsolete)
84
85 * - __u32
86 - ``flags``
87 -
88 - Entity flags, see :ref:`media-entity-flag` for details.
89
90 * - __u32
91 - ``group_id``
92 -
93 - Entity group ID. Always zero (obsolete)
94
95 * - __u16
96 - ``pads``
97 -
98 - Number of pads
99
100 * - __u16
101 - ``links``
102 -
103 - Total number of outbound links. Inbound links are not counted in
104 this field.
105
106 * - __u32
107 - ``reserved[4]``
108 -
109 - Reserved for future extensions. Drivers and applications must set
110 the array to zero.
111
112 * - union {
113 - (anonymous)
114
115 * - struct
116 - ``dev``
117 -
118 - Valid for (sub-)devices that create a single device node.
119
120 * -
121 - __u32
122 - ``major``
123 - Device node major number.
124
125 * -
126 - __u32
127 - ``minor``
128 - Device node minor number.
129
130 * - __u8
131 - ``raw``\ [184]
132 -
133 -
134 * - }
135 -
136
137 Return Value
138 ============
139
140 On success 0 is returned, on error -1 and the ``errno`` variable is set
141 appropriately. The generic error codes are described at the
142 :ref:`Generic Error Codes <gen-errors>` chapter.
143
144 EINVAL
145 The struct :c:type:`media_entity_desc` ``id``
146 references a non-existing entity.
147

3. 한국어 전문 번역

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

이름, 호출 형식과 arguments

1-30

`MEDIA_IOC_ENUM_ENTITIES`는 entity와 entity property를 열거합니다.

int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp);
MEDIA_IOC_ENUM_ENTITIES arguments
Argument의미
fd`open()`이 반환한 file descriptor
argp`struct media_entity_desc`를 가리키는 pointer

조회할 entity ID와 결과를 같은 structure로 전달합니다.

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

.. _media_ioc_enum_entities:

*****************************
ioctl MEDIA_IOC_ENUM_ENTITIES
*****************************

Name
====

MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties

Synopsis
========

.. c:macro:: MEDIA_IOC_ENUM_ENTITIES

``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)``

Arguments
=========

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

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

Entity 조회와 NEXT flag

31-50

Entity attribute를 조회하려면 application이 `struct media_entity_desc`의 `id` field를 설정하고 structure pointer로 `MEDIA_IOC_ENUM_ENTITIES`를 호출합니다. Driver는 나머지 field를 채우며, ID가 유효하지 않으면 `EINVAL`을 반환합니다.

Entity를 열거할 때는 `id`에 `MEDIA_ENT_ID_FLAG_NEXT`를 OR합니다. Driver는 flag를 지우고 요청한 값보다 엄격히 큰 ID 가운데 가장 작은 ID를 가진 다음 entity 정보를 반환합니다. 다음 entity가 없으면 `EINVAL`입니다.

Entity ID는 연속적이지 않을 수 있습니다. ID를 1씩 늘려 오류가 날 때까지 호출하는 방식으로 entity를 열거하면 안 됩니다.

Entity 열거
시작 id에 MEDIA_ENT_ID_FLAG_NEXT ORMEDIA_IOC_ENUM_ENTITIES 호출Driver가 flag 제거 후 더 큰 최소 id 반환반환된 id에 NEXT flag를 다시 OR하여 반복EINVAL이면 다음 entity 없음

비연속 ID를 올바르게 순회하는 절차입니다.

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

To query the attributes of an entity, applications set the id field of a
struct :c:type:`media_entity_desc` structure and
call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
structure. The driver fills the rest of the structure or returns an
EINVAL error code when the id is invalid.

.. _media-ent-id-flag-next:

Entities can be enumerated by or'ing the id with the
``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information
about the entity with the smallest id strictly larger than the requested
one ('next entity'), or the ``EINVAL`` error code if there is none.

Entity IDs can be non-contiguous. Applications must *not* try to
enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
id's until they get an error.

media_entity_desc 기본 field

51-110
struct media_entity_desc 기본 field
Field정의
__u32 idApplication이 설정하는 Entity ID. NEXT flag 사용 시 driver가 더 큰 첫 ID를 반환. Device instance마다 같다고 기대하거나 hardcode하면 안 됨
char name[32]Media topology 안에서 unique한 UTF-8 NULL-terminated entity 이름
__u32 typeEntity type. media-entity-functions 참조
__u32 revisionEntity revision. 항상 0이며 obsolete
__u32 flagsEntity flag. media-entity-flag 참조
__u32 group_idEntity group ID. 항상 0이며 obsolete
__u16 padsPad 수
__u16 linksOutbound link의 전체 수. Inbound link는 세지 않음
__u32 reserved[4]향후 확장용. Driver와 application은 배열을 0으로 설정

ID, 이름, type, pad와 outbound link 수를 담습니다.

`name`은 topology 범위에서 unique해야 하지만 `id`는 device instance마다 안정적이라는 보장이 없습니다.

`links`는 source 쪽 outbound link만 세며 inbound link는 포함하지 않습니다.

.. c:type:: media_entity_desc

.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{10.6cm}|

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

    *  -  __u32
       -  ``id``
       -
       -  Entity ID, set by the application. When the ID is or'ed with
	  ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns
	  the first entity with a larger ID. Do not expect that the ID will
	  always be the same for each instance of the device. In other words,
	  do not hardcode entity IDs in an application.

    *  -  char
       -  ``name``\ [32]
       -
       -  Entity name as an UTF-8 NULL-terminated string. This name must be unique
          within the media topology.

    *  -  __u32
       -  ``type``
       -
       -  Entity type, see :ref:`media-entity-functions` for details.

    *  -  __u32
       -  ``revision``
       -
       -  Entity revision. Always zero (obsolete)

    *  -  __u32
       -  ``flags``
       -
       -  Entity flags, see :ref:`media-entity-flag` for details.

    *  -  __u32
       -  ``group_id``
       -
       -  Entity group ID. Always zero (obsolete)

    *  -  __u16
       -  ``pads``
       -
       -  Number of pads

    *  -  __u16
       -  ``links``
       -
       -  Total number of outbound links. Inbound links are not counted in
	  this field.

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

Device node union

111-136

Anonymous union 안의 `struct dev`는 device node 하나를 만드는 device 또는 sub-device에 유효합니다.

media_entity_desc device union
Member정의
struct devDevice node 하나를 생성하는 (sub-)device용 structure
__u32 majorDevice node major number
__u32 minorDevice node minor number
__u8 raw[184]Union의 raw storage

Device node 번호와 raw storage를 정의합니다.


    *  -  union {
       -  (anonymous)

    *  -  struct
       -  ``dev``
       -
       -  Valid for (sub-)devices that create a single device node.

    *  -
       -  __u32
       -  ``major``
       -  Device node major number.

    *  -
       -  __u32
       -  ``minor``
       -  Device node minor number.

    *  -  __u8
       -  ``raw``\ [184]
       -
       -
    *  - }
       -

반환값과 EINVAL

137-146

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

`EINVAL`은 `struct media_entity_desc`의 `id`가 존재하지 않는 entity를 참조한다는 뜻입니다. NEXT 방식에서는 다음 entity가 없을 때도 이 결과를 사용합니다.

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 struct :c:type:`media_entity_desc` ``id``
    references a non-existing entity.