요약·해설과 원문, 전문 번역을 서로 분리했습니다. 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_PREPARE_BUF:
6
************************
7
ioctl VIDIOC_PREPARE_BUF
8
************************
10
Name
11
====
13
VIDIOC_PREPARE_BUF - Prepare a buffer for I/O
15
Synopsis
16
========
18
.. c:macro:: VIDIOC_PREPARE_BUF
20
``int ioctl(int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp)``
22
Arguments
23
=========
25
``fd``
26
File descriptor returned by :c:func:`open()`.
28
``argp``
29
Pointer to struct :c:type:`v4l2_buffer`.
31
Description
32
===========
34
Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to
35
pass ownership of the buffer to the driver before actually enqueuing it,
36
using the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl, and to prepare it for future I/O. Such
37
preparations may include cache invalidation or cleaning. Performing them
38
in advance saves time during the actual I/O.
40
The struct :c:type:`v4l2_buffer` structure is specified in
41
:ref:`buffer`.
43
Return Value
44
============
46
On success 0 is returned, on error -1 and the ``errno`` variable is set
47
appropriately. The generic error codes are described at the
48
:ref:`Generic Error Codes <gen-errors>` chapter.
50
EBUSY
51
File I/O is in progress.
53
EINVAL
54
The buffer ``type`` is not supported, or the ``index`` is out of
55
bounds, or no buffers have been allocated yet, or the ``userptr`` or
56
``length`` are invalid.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적, 호출 형식과 인자
1-28`VIDIOC_PREPARE_BUF`는 `struct v4l2_buffer`로 지정한 buffer를 실제 큐잉 전에 I/O용으로 준비합니다. 호출은 선택 사항입니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _VIDIOC_PREPARE_BUF:
************************
ioctl VIDIOC_PREPARE_BUF
************************
Name
====
VIDIOC_PREPARE_BUF - Prepare a buffer for I/O
Synopsis
========
.. c:macro:: VIDIOC_PREPARE_BUF
``int ioctl(int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``사전 준비의 효과
29-40애플리케이션은 `VIDIOC_QBUF`로 enqueue하기 전에 buffer 소유권을 드라이버에 넘겨 향후 I/O를 준비시킬 수 있습니다. 준비 작업에는 cache invalidation이나 cache cleaning이 포함될 수 있습니다.
1. `v4l2_buffer` 구성→2. 선택적으로 `VIDIOC_PREPARE_BUF` 호출→3. 나중에 `VIDIOC_QBUF`로 enqueue→4. 실제 I/O 지연 감소
비용이 큰 준비를 실제 I/O 경로 밖에서 앞당깁니다.
`struct v4l2_buffer`의 필드 정의는 `buffer` 절을 따릅니다.
Pointer to struct :c:type:`v4l2_buffer`.
Description
===========
Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to
pass ownership of the buffer to the driver before actually enqueuing it,
using the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl, and to prepare it for future I/O. Such
preparations may include cache invalidation or cleaning. Performing them
in advance saves time during the actual I/O.
The struct :c:type:`v4l2_buffer` structure is specified in반환값과 오류
41-56성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다.
errno조건
`EBUSY`file I/O가 진행 중임
`EINVAL`지원하지 않는 `type`, 범위를 벗어난 `index`, 미할당 buffer, 잘못된 `userptr` 또는 `length`
현재 I/O 상태와 buffer 설명자의 유효성을 검사합니다.
:ref:`buffer`.
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
File I/O is in progress.
EINVAL
The buffer ``type`` is not supported, or the ``index`` is out of
bounds, or no buffers have been allocated yet, or the ``userptr`` or
``length`` are invalid.
요약·해설
vidioc-prepare-buf.rst:1-56사전 준비는 필수 절차가 아니라 실제 I/O 시점의 지연을 줄이는 최적화입니다.