요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
2
.. c:namespace:: MC
4
.. _media_request_ioc_queue:
6
*****************************
7
ioctl MEDIA_REQUEST_IOC_QUEUE
8
*****************************
10
Name
11
====
13
MEDIA_REQUEST_IOC_QUEUE - Queue a request
15
Synopsis
16
========
18
.. c:macro:: MEDIA_REQUEST_IOC_QUEUE
20
``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``
22
Arguments
23
=========
25
``request_fd``
26
File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
28
Description
29
===========
31
If the media device supports :ref:`requests <media-request-api>`, then
32
this request ioctl can be used to queue a previously allocated request.
34
If the request was successfully queued, then the file descriptor can be
35
:ref:`polled <request-func-poll>` to wait for the request to complete.
37
If the request was already queued before, then ``EBUSY`` is returned.
38
Other errors can be returned if the contents of the request contained
39
invalid or inconsistent data, see the next section for a list of
40
common error codes. On error both the request and driver state are unchanged.
42
Once a request is queued, then the driver is required to gracefully handle
43
errors that occur when the request is applied to the hardware. The
44
exception is the ``EIO`` error which signals a fatal error that requires
45
the application to stop streaming to reset the hardware state.
47
It is not allowed to mix queuing requests with queuing buffers directly
48
(without a request). ``EBUSY`` will be returned if the first buffer was
49
queued directly and you next try to queue a request, or vice versa.
51
A request must contain at least one buffer, otherwise this ioctl will
52
return an ``ENOENT`` error.
54
Return Value
55
============
57
On success 0 is returned, on error -1 and the ``errno`` variable is set
58
appropriately. The generic error codes are described at the
59
:ref:`Generic Error Codes <gen-errors>` chapter.
61
EBUSY
62
The request was already queued or the application queued the first
63
buffer directly, but later attempted to use a request. It is not permitted
64
to mix the two APIs.
65
ENOENT
66
The request did not contain any buffers. All requests are required
67
to have at least one buffer. This can also be returned if some required
68
configuration is missing in the request.
69
ENOMEM
70
Out of memory when allocating internal data structures for this
71
request.
72
EINVAL
73
The request has invalid data.
74
EIO
75
The hardware is in a bad state. To recover, the application needs to
76
stop streaming to reset the hardware state and then try to restart
77
streaming.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름, 호출 형식과 인자
1-27`MEDIA_REQUEST_IOC_QUEUE`는 앞서 할당하고 구성한 media request를 queue하는 request fd ioctl입니다.
int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE);인자설명
request_fd`MEDIA_IOC_REQUEST_ALLOC`이 반환한 request file descriptor
Media device fd가 아니라 request fd에 호출합니다.
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_request_ioc_queue:
*****************************
ioctl MEDIA_REQUEST_IOC_QUEUE
*****************************
Name
====
MEDIA_REQUEST_IOC_QUEUE - Queue a request
Synopsis
========
.. c:macro:: MEDIA_REQUEST_IOC_QUEUE
``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``
Arguments
=========
``request_fd``
File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
Queue와 오류 시 상태
28-40Media device가 request API를 지원하면 이전에 할당한 request를 이 ioctl로 queue할 수 있습니다. 성공 후 request fd를 poll하여 완료를 기다립니다.
이미 queue된 request를 다시 queue하면 `EBUSY`입니다. Request 내용이 invalid하거나 서로 일관되지 않아도 해당 오류 조건에 맞는 errno가 반환됩니다.
Queue 호출이 오류로 끝나면 request 상태와 driver 상태는 모두 바뀌지 않습니다. Application은 실패한 제출이 일부만 적용되었다고 가정할 필요가 없습니다.
Description
===========
If the media device supports :ref:`requests <media-request-api>`, then
this request ioctl can be used to queue a previously allocated request.
If the request was successfully queued, then the file descriptor can be
:ref:`polled <request-func-poll>` to wait for the request to complete.
If the request was already queued before, then ``EBUSY`` is returned.
Other errors can be returned if the contents of the request contained
invalid or inconsistent data, see the next section for a list of
common error codes. On error both the request and driver state are unchanged.Hardware 오류와 queue 방식의 일관성
41-53Request가 성공적으로 queue된 뒤 hardware에 적용하는 과정에서 오류가 발생하면 driver는 이를 정상적으로 수습해야 합니다. 예외인 `EIO`는 hardware state를 reset해야 하는 치명적 오류를 뜻합니다.
`EIO`를 복구하려면 application이 streaming을 멈춰 hardware state를 reset한 뒤 streaming을 다시 시작해야 합니다.
Request를 통한 queue와 request 없이 buffer를 직접 queue하는 방식을 한 stream에서 섞을 수 없습니다. 어느 방식을 먼저 사용했든 나중에 다른 방식을 쓰면 `EBUSY`입니다.
모든 request에는 buffer가 하나 이상 있어야 합니다. Buffer가 없거나 필수 구성이 빠졌다면 `ENOENT`를 반환할 수 있습니다.
Request fd가 아직 queue되지 않았는지 확인→Request에 buffer와 필수 구성이 있는지 확인→현재 stream이 direct buffer queue와 request queue를 섞지 않는지 확인→MEDIA_REQUEST_IOC_QUEUE 호출→성공하면 poll로 완료 대기→EIO이면 streaming 중지, hardware reset 후 재시작
제출 전 구성과 stream의 queue 방식을 함께 검사합니다.
Once a request is queued, then the driver is required to gracefully handle
errors that occur when the request is applied to the hardware. The
exception is the ``EIO`` error which signals a fatal error that requires
the application to stop streaming to reset the hardware state.
It is not allowed to mix queuing requests with queuing buffers directly
(without a request). ``EBUSY`` will be returned if the first buffer was
queued directly and you next try to queue a request, or vice versa.
A request must contain at least one buffer, otherwise this ioctl will
return an ``ENOENT`` error.
반환값과 오류 코드
54-77성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 알맞게 설정합니다. 공통 오류는 `Generic Error Codes <gen-errors>` 장에서 설명합니다.
오류 코드는 request 상태, 필수 구성, 내부 memory, data 유효성, hardware 상태를 구분합니다.
errno조건과 대응
EBUSYRequest가 이미 queue되었거나 direct buffer queue와 request API를 혼용
ENOENTRequest에 buffer가 없거나 필요한 구성이 빠짐
ENOMEMRequest용 내부 data structure 할당 중 memory 부족
EINVALRequest data가 invalid
EIOHardware가 나쁜 상태. Streaming을 중지해 hardware state를 reset한 뒤 재시작 필요
각 errno에 필요한 application 대응이 다릅니다.
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.
EBUSY
The request was already queued or the application queued the first
buffer directly, but later attempted to use a request. It is not permitted
to mix the two APIs.
ENOENT
The request did not contain any buffers. All requests are required
to have at least one buffer. This can also be returned if some required
configuration is missing in the request.
ENOMEM
Out of memory when allocating internal data structures for this
request.
EINVAL
The request has invalid data.
EIO
The hardware is in a bad state. To recover, the application needs to
stop streaming to reset the hardware state and then try to restart
streaming.
요약·해설
media-request-ioc-queue.rst:1-77Request queue와 direct buffer queue는 혼용할 수 없고 request에는 buffer가 하나 이상 필요합니다. 제출 오류 때 request와 driver 상태는 그대로이며, `EIO`만 streaming 중지와 hardware reset이 필요한 치명적 상태입니다.