요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_ioc_request_alloc:
*****************************
ioctl MEDIA_IOC_REQUEST_ALLOC
*****************************
Name
====
MEDIA_IOC_REQUEST_ALLOC - Allocate a request
Synopsis
========
.. c:macro:: MEDIA_IOC_REQUEST_ALLOC
``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an integer.
Description
===========
If the media device supports :ref:`requests <media-request-api>`, then
this ioctl can be used to allocate a request. If it is not supported, then
``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor
that is returned in ``*argp``.
If the request was successfully allocated, then the request file descriptor
can be passed to the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls.
In addition, the request can be queued by calling
:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling
:ref:`MEDIA_REQUEST_IOC_REINIT`.
Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
for the request to complete.
The request will remain allocated until all the file descriptors associated
with it are closed by :c:func:`close()` and the driver no
longer uses the request internally. See also
:ref:`here <media-request-life-time>` for more information.
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.
ENOTTY
The driver has no support for requests.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름, 호출 형식과 인자
1-30`MEDIA_IOC_REQUEST_ALLOC`은 media request를 할당하는 `MC` namespace ioctl입니다. 성공하면 새 request를 나타내는 file descriptor가 `*argp`에 기록됩니다.
int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp);Media device와 request fd 결과 위치를 전달합니다.
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_ioc_request_alloc:
*****************************
ioctl MEDIA_IOC_REQUEST_ALLOC
*****************************
Name
====
MEDIA_IOC_REQUEST_ALLOC - Allocate a request
Synopsis
========
.. c:macro:: MEDIA_IOC_REQUEST_ALLOC
``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an integer.
Request 사용과 수명
31-55Media device가 request API를 지원할 때 이 ioctl로 request를 할당할 수 있습니다. 지원하지 않으면 `errno`가 `ENOTTY`로 설정됩니다.
성공한 request fd는 `VIDIOC_QBUF`, `VIDIOC_G_EXT_CTRLS`, `VIDIOC_S_EXT_CTRLS`, `VIDIOC_TRY_EXT_CTRLS`에 전달해 buffer와 control을 하나의 request에 묶는 데 사용합니다.
준비된 request는 `MEDIA_REQUEST_IOC_QUEUE`로 queue하고, 완료 후 `MEDIA_REQUEST_IOC_REINIT`으로 비워 재사용할 수 있습니다. Request fd를 poll하면 완료를 기다릴 수 있습니다.
Request는 연관된 모든 file descriptor가 `close()`되고 driver도 내부 사용을 끝낼 때까지 할당된 상태로 남습니다. Application이 한 fd를 닫았다는 사실만으로 즉시 소멸한다고 가정하면 안 됩니다.
할당된 request fd를 통해 구성, 제출, 완료 대기와 재사용을 수행합니다.
Description
===========
If the media device supports :ref:`requests <media-request-api>`, then
this ioctl can be used to allocate a request. If it is not supported, then
``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor
that is returned in ``*argp``.
If the request was successfully allocated, then the request file descriptor
can be passed to the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls.
In addition, the request can be queued by calling
:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling
:ref:`MEDIA_REQUEST_IOC_REINIT`.
Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
for the request to complete.
The request will remain allocated until all the file descriptors associated
with it are closed by :c:func:`close()` and the driver no
longer uses the request internally. See also
:ref:`here <media-request-life-time>` for more information.반환값과 ENOTTY
56-65성공하면 0을 반환하고 `*argp`에 request fd를 씁니다. 오류가 발생하면 -1을 반환하고 `errno`를 알맞게 설정합니다. 공통 오류는 `Generic Error Codes <gen-errors>` 장에서 설명합니다.
`ENOTTY`는 driver가 request API를 지원하지 않는다는 뜻입니다. 이 경우 유효한 request fd가 만들어지지 않습니다.
Request 지원 여부를 직접 나타냅니다.
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.
ENOTTY
The driver has no support for requests.
요약·해설
media-ioc-request-alloc.rst:1-65성공 시 `*argp`로 받은 request fd에 buffer와 control을 구성하고 queue, poll, reinit을 수행합니다. 모든 fd 참조와 driver 내부 사용이 끝날 때까지 request의 수명이 유지됩니다.