요약·해설과 원문, 전문 번역을 서로 분리했습니다. 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_STREAMON:
6
***************************************
7
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
8
***************************************
10
Name
11
====
13
VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
15
Synopsis
16
========
18
.. c:macro:: VIDIOC_STREAMON
20
``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``
22
.. c:macro:: VIDIOC_STREAMOFF
24
``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``
26
Arguments
27
=========
29
``fd``
30
File descriptor returned by :c:func:`open()`.
32
``argp``
33
Pointer to an integer.
35
Description
36
===========
38
The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
39
the capture or output process during streaming
40
(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
41
:ref:`DMABUF <dmabuf>`) I/O.
43
Capture hardware is disabled and no input buffers are filled (if there
44
are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
45
has been called. Output hardware is disabled and no video signal is
46
produced until ``VIDIOC_STREAMON`` has been called.
48
Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
49
been called for both the capture and output stream types.
51
If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
52
queued.
54
The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
55
in progress, unlocks any user pointer buffers locked in physical memory,
56
and it removes all buffers from the incoming and outgoing queues. That
57
means all images captured but not dequeued yet will be lost, likewise
58
all images enqueued for output but not transmitted yet. I/O returns to
59
the same state as after calling
60
:ref:`VIDIOC_REQBUFS` and can be restarted
61
accordingly.
63
If buffers have been queued with :ref:`VIDIOC_QBUF` and
64
``VIDIOC_STREAMOFF`` is called without ever having called
65
``VIDIOC_STREAMON``, then those queued buffers will also be removed from
66
the incoming queue and all are returned to the same state as after
67
calling :ref:`VIDIOC_REQBUFS` and can be restarted
68
accordingly.
70
Both ioctls take a pointer to an integer, the desired buffer or stream
71
type. This is the same as struct
72
:c:type:`v4l2_requestbuffers` ``type``.
74
If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
75
or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
76
then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
77
but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
78
state as mentioned above.
80
.. note::
82
Applications can be preempted for unknown periods right before
83
or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
84
no notion of starting or stopping "now". Buffer timestamps can be used
85
to synchronize with other events.
87
Return Value
88
============
90
On success 0 is returned, on error -1 and the ``errno`` variable is set
91
appropriately. The generic error codes are described at the
92
:ref:`Generic Error Codes <gen-errors>` chapter.
94
EINVAL
95
The buffer ``type`` is not supported, or no buffers have been
96
allocated (memory mapping) or enqueued (output) yet.
98
EPIPE
99
The driver implements
100
:ref:`pad-level format configuration <pad-level-formats>` and the
101
pipeline configuration is invalid.
103
ENOLINK
104
The driver implements Media Controller interface and the pipeline
105
link configuration is invalid.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적, 호출 형식과 인자
1-34`VIDIOC_STREAMON`과 `VIDIOC_STREAMOFF`는 MMAP, USERPTR 또는 DMABUF 방식의 스트리밍 I/O에서 캡처나 출력 처리를 시작하고 중지합니다. 두 ioctl 모두 `v4l2_requestbuffers.type`과 같은 버퍼 또는 스트림 형식을 가리키는 정수 포인터를 받습니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _VIDIOC_STREAMON:
***************************************
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
***************************************
Name
====
VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
Synopsis
========
.. c:macro:: VIDIOC_STREAMON
``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``
.. c:macro:: VIDIOC_STREAMOFF
``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an integer.
스트리밍 시작
35-52캡처 장치는 `VIDIOC_STREAMON`을 호출하기 전까지 입력 큐의 빈 버퍼를 채우지 않습니다. 출력 장치도 호출 전까지 비디오 신호를 내보내지 않습니다.
메모리 대 메모리 장치는 캡처 형식과 출력 형식 양쪽에 대해 `VIDIOC_STREAMON`이 호출되어야 실제 처리를 시작합니다. 한쪽만 시작한 상태에서는 파이프라인이 동작하지 않습니다.
`VIDIOC_STREAMON`이 실패해도 이미 큐에 넣은 버퍼는 큐에 남습니다. 응용 프로그램은 오류를 처리한 뒤 구성을 바로잡아 다시 시작하거나 명시적으로 스트림을 정리할 수 있습니다.
버퍼를 할당하고 QBUF로 큐에 등록→캡처 또는 출력 형식에 STREAMON 호출→일반 장치는 해당 방향 처리 시작→메모리 대 메모리 장치는 양쪽 형식이 모두 시작된 뒤 처리 시작
장치 유형별로 실제 데이터 처리가 시작되는 지점을 구분합니다.
Description
===========
The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
the capture or output process during streaming
(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
:ref:`DMABUF <dmabuf>`) I/O.
Capture hardware is disabled and no input buffers are filled (if there
are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
has been called. Output hardware is disabled and no video signal is
produced until ``VIDIOC_STREAMON`` has been called.
Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
been called for both the capture and output stream types.
If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
queued.스트리밍 중지와 큐 초기화
53-78`VIDIOC_STREAMOFF`는 진행 중인 DMA를 중단하거나 마무리하고, 물리 메모리에 고정한 USERPTR 버퍼를 해제하며, 입력 큐와 출력 큐의 모든 버퍼를 제거합니다.
아직 dequeue하지 않은 캡처 영상과 아직 전송하지 않은 출력 영상은 모두 소실됩니다. I/O 상태는 `VIDIOC_REQBUFS` 직후로 돌아가며, 버퍼를 다시 큐에 넣은 뒤 스트리밍을 재시작할 수 있습니다.
`VIDIOC_STREAMON`을 한 번도 호출하지 않았더라도 QBUF로 등록한 버퍼가 있다면 STREAMOFF가 이를 큐에서 제거하고 초기 상태로 되돌립니다.
이미 실행 중일 때 STREAMON을 다시 호출하거나 이미 중지된 상태에서 STREAMOFF를 호출해도 0을 반환합니다. 전자는 아무 일도 하지 않지만 후자는 남아 있는 큐 버퍼를 초기 상태로 되돌리는 정리 작업을 수행합니다.
호출현재 상태결과
`VIDIOC_STREAMON`중지됨요건을 만족하면 스트리밍 시작
`VIDIOC_STREAMON`이미 실행 중0 반환, 상태 변화 없음
`VIDIOC_STREAMOFF`실행 중DMA 정리, USERPTR 잠금 해제, 모든 큐 버퍼 초기화
`VIDIOC_STREAMOFF`이미 중지됨0 반환, 큐에 남은 버퍼는 초기 상태로 복원
중복 호출도 성공하지만 큐에 미치는 효과는 서로 다릅니다.
The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
in progress, unlocks any user pointer buffers locked in physical memory,
and it removes all buffers from the incoming and outgoing queues. That
means all images captured but not dequeued yet will be lost, likewise
all images enqueued for output but not transmitted yet. I/O returns to
the same state as after calling
:ref:`VIDIOC_REQBUFS` and can be restarted
accordingly.
If buffers have been queued with :ref:`VIDIOC_QBUF` and
``VIDIOC_STREAMOFF`` is called without ever having called
``VIDIOC_STREAMON``, then those queued buffers will also be removed from
the incoming queue and all are returned to the same state as after
calling :ref:`VIDIOC_REQBUFS` and can be restarted
accordingly.
Both ioctls take a pointer to an integer, the desired buffer or stream
type. This is the same as struct
:c:type:`v4l2_requestbuffers` ``type``.
If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
state as mentioned above.호출 시점과 오류
79-105응용 프로그램은 호출 직전이나 직후에 예측할 수 없는 시간 동안 선점될 수 있으므로 스트리밍이 바로 '지금' 시작되거나 중지된다는 보장은 없습니다. 다른 사건과 맞추려면 버퍼 타임스탬프를 사용해야 합니다.
성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다.
errno조건
`EINVAL`버퍼 `type`이 지원되지 않거나 MMAP 버퍼가 할당되지 않았거나 출력 버퍼가 아직 큐에 없음
`EPIPE`드라이버가 pad-level 형식 구성을 구현하며 파이프라인 형식 구성이 잘못됨
`ENOLINK`드라이버가 Media Controller 인터페이스를 구현하며 파이프라인 링크 구성이 잘못됨
버퍼 준비 상태와 미디어 파이프라인 구성을 검사합니다.
.. note::
Applications can be preempted for unknown periods right before
or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
no notion of starting or stopping "now". Buffer timestamps can be used
to synchronize with other events.
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 buffer ``type`` is not supported, or no buffers have been
allocated (memory mapping) or enqueued (output) yet.
EPIPE
The driver implements
:ref:`pad-level format configuration <pad-level-formats>` and the
pipeline configuration is invalid.
ENOLINK
The driver implements Media Controller interface and the pipeline
link configuration is invalid.
요약·해설
vidioc-streamon.rst:1-105STREAMOFF는 단순한 정지 신호가 아니라 DMA와 버퍼 큐를 `VIDIOC_REQBUFS` 직후 상태로 되돌리는 경계이므로, 아직 소비하지 않은 데이터의 손실을 전제로 호출해야 합니다.