요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
.. c:namespace:: V4L
4
.. _VIDIOC_SUBSCRIBE_EVENT:
5
.. _VIDIOC_UNSUBSCRIBE_EVENT:
7
******************************************************
8
ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
9
******************************************************
11
Name
12
====
14
VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
16
Synopsis
17
========
19
.. c:macro:: VIDIOC_SUBSCRIBE_EVENT
21
``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
23
.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT
25
``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
27
Arguments
28
=========
30
``fd``
31
File descriptor returned by :c:func:`open()`.
33
``argp``
34
Pointer to struct :c:type:`v4l2_event_subscription`.
36
Description
37
===========
39
Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
40
using the :ref:`VIDIOC_DQEVENT` ioctl.
42
.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}|
44
.. c:type:: v4l2_event_subscription
46
.. flat-table:: struct v4l2_event_subscription
47
:header-rows: 0
48
:stub-columns: 0
49
:widths: 1 1 2
51
* - __u32
52
- ``type``
53
- Type of the event, see :ref:`event-type`.
55
.. note::
57
``V4L2_EVENT_ALL`` can be used with
58
:ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for
59
unsubscribing all events at once.
60
* - __u32
61
- ``id``
62
- ID of the event source. If there is no ID associated with the
63
event source, then set this to 0. Whether or not an event needs an
64
ID depends on the event type.
65
* - __u32
66
- ``flags``
67
- Event flags, see :ref:`event-flags`.
68
* - __u32
69
- ``reserved``\ [5]
70
- Reserved for future extensions. Drivers and applications must set
71
the array to zero.
74
.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}|
76
.. _event-flags:
78
.. flat-table:: Event Flags
79
:header-rows: 0
80
:stub-columns: 0
81
:widths: 3 1 4
83
* - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
84
- 0x0001
85
- When this event is subscribed an initial event will be sent
86
containing the current status. This only makes sense for events
87
that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
88
Other events will ignore this flag.
89
* - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
90
- 0x0002
91
- If set, then events directly caused by an ioctl will also be sent
92
to the filehandle that called that ioctl. For example, changing a
93
control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
94
a V4L2_EVENT_CTRL to be sent back to that same filehandle.
95
Normally such events are suppressed to prevent feedback loops
96
where an application changes a control to a one value and then
97
another, and then receives an event telling it that that control
98
has changed to the first value.
100
Since it can't tell whether that event was caused by another
101
application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
102
call it is hard to decide whether to set the control to the value
103
in the event, or ignore it.
105
Think carefully when you set this flag so you won't get into
106
situations like that.
108
Return Value
109
============
111
On success 0 is returned, on error -1 and the ``errno`` variable is set
112
appropriately. The generic error codes are described at the
113
:ref:`Generic Error Codes <gen-errors>` chapter.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적, 호출 형식과 인자
1-35`VIDIOC_SUBSCRIBE_EVENT`와 `VIDIOC_UNSUBSCRIBE_EVENT`는 V4L2 이벤트를 구독하거나 구독 해제합니다. 구독한 이벤트는 `VIDIOC_DQEVENT`로 큐에서 꺼내며, `argp`는 `struct v4l2_event_subscription`을 가리킵니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _VIDIOC_SUBSCRIBE_EVENT:
.. _VIDIOC_UNSUBSCRIBE_EVENT:
******************************************************
ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
******************************************************
Name
====
VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
Synopsis
========
.. c:macro:: VIDIOC_SUBSCRIBE_EVENT
``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT
``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_event_subscription`.
struct v4l2_event_subscription
36-73이벤트 구독은 이벤트 종류와 필요한 경우 이벤트 source ID를 함께 지정합니다. 이벤트 source에 ID가 없으면 `id = 0`으로 설정하며, ID 사용 여부는 이벤트 종류가 결정합니다.
형식필드의미
`__u32``type`구독하거나 해제할 이벤트 종류
`__u32``id`이벤트 source ID. 해당 source에 ID가 없으면 0
`__u32``flags`초기 상태 전송과 피드백 허용 같은 이벤트 flags
`__u32[5]``reserved[5]`향후 확장용이며 드라이버와 응용 프로그램이 모두 0으로 설정
구독 대상과 전달 방식을 지정합니다.
`V4L2_EVENT_ALL`은 UNSUBSCRIBE_EVENT에서만 모든 이벤트를 한 번에 구독 해제하는 값으로 사용할 수 있습니다.
type, id, flags를 설정해 SUBSCRIBE_EVENT 호출→이벤트 발생을 poll 또는 대기 방식으로 감지→VIDIOC_DQEVENT로 이벤트 dequeue→필요한 상태 처리→개별 type 또는 V4L2_EVENT_ALL로 구독 해제
구독부터 큐 처리와 해제까지의 기본 순서입니다.
Description
===========
Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
using the :ref:`VIDIOC_DQEVENT` ioctl.
.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}|
.. c:type:: v4l2_event_subscription
.. flat-table:: struct v4l2_event_subscription
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u32
- ``type``
- Type of the event, see :ref:`event-type`.
.. note::
``V4L2_EVENT_ALL`` can be used with
:ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for
unsubscribing all events at once.
* - __u32
- ``id``
- ID of the event source. If there is no ID associated with the
event source, then set this to 0. Whether or not an event needs an
ID depends on the event type.
* - __u32
- ``flags``
- Event flags, see :ref:`event-flags`.
* - __u32
- ``reserved``\ [5]
- Reserved for future extensions. Drivers and applications must set
the array to zero.
이벤트 구독 flags
74-107flag값동작
`V4L2_EVENT_SUB_FL_SEND_INITIAL``0x0001`구독 시 현재 상태를 담은 초기 이벤트 전송. `V4L2_EVENT_CTRL` 같은 상태 변화 이벤트에만 의미가 있고 다른 이벤트는 무시
`V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``0x0002`ioctl로 직접 발생한 이벤트도 그 ioctl을 호출한 파일 핸들에 전송
초기 상태 전달과 호출자 자신에게 보내는 피드백을 제어합니다.
기본 동작은 응용 프로그램 자신의 `VIDIOC_S_CTRL` 호출이 일으킨 `V4L2_EVENT_CTRL`을 같은 파일 핸들에 돌려보내지 않습니다. 이는 응용 프로그램이 과거 값의 이벤트를 다시 적용해 피드백 루프를 만드는 상황을 막습니다.
ALLOW_FEEDBACK을 설정하면 이벤트가 다른 응용 프로그램에서 왔는지 자신의 ioctl에서 왔는지 구분하기 어려울 수 있습니다. 이벤트의 값을 다시 control에 적용하는 로직은 루프와 순서 역전을 피하도록 신중히 설계해야 합니다.
.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}|
.. _event-flags:
.. flat-table:: Event Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
- 0x0001
- When this event is subscribed an initial event will be sent
containing the current status. This only makes sense for events
that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
Other events will ignore this flag.
* - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
- 0x0002
- If set, then events directly caused by an ioctl will also be sent
to the filehandle that called that ioctl. For example, changing a
control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
a V4L2_EVENT_CTRL to be sent back to that same filehandle.
Normally such events are suppressed to prevent feedback loops
where an application changes a control to a one value and then
another, and then receives an event telling it that that control
has changed to the first value.
Since it can't tell whether that event was caused by another
application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
call it is hard to decide whether to set the control to the value
in the event, or ignore it.
Think carefully when you set this flag so you won't get into
situations like that.
반환값
108-113성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다. 개별 오류는 공통 V4L2 오류 규칙을 따릅니다.
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.
요약·해설
vidioc-subscribe-event.rst:1-113ALLOW_FEEDBACK은 자기 ioctl이 만든 이벤트까지 되돌려 주므로 응용 프로그램이 이벤트 값을 다시 적용할 때 순서 역전과 제어 루프를 명시적으로 막아야 합니다.