요약·해설과 원문, 전문 번역을 서로 분리했습니다. 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_QUERYBUF:
6
*********************
7
ioctl VIDIOC_QUERYBUF
8
*********************
10
Name
11
====
13
VIDIOC_QUERYBUF - Query the status of a buffer
15
Synopsis
16
========
18
.. c:macro:: VIDIOC_QUERYBUF
20
``int ioctl(int fd, VIDIOC_QUERYBUF, 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
This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
35
be used to query the status of a buffer at any time after buffers have
36
been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.
38
Applications set the ``type`` field of a struct
39
:c:type:`v4l2_buffer` to the same buffer type as was
40
previously used with struct :c:type:`v4l2_format` ``type``
41
and struct :c:type:`v4l2_requestbuffers` ``type``,
42
and the ``index`` field. Valid index numbers range from zero to the
43
number of buffers allocated with
44
:ref:`VIDIOC_REQBUFS` (struct
45
:c:type:`v4l2_requestbuffers` ``count``) minus
46
one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
47
using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
48
field must contain a userspace pointer to an array of struct
49
:c:type:`v4l2_plane` and the ``length`` field has to be set
50
to the number of elements in that array. After calling
51
:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
52
error code or fill the rest of the structure.
54
In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
55
``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
56
``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
57
set to the current I/O method. For the single-planar API, the
58
``m.offset`` contains the offset of the buffer from the start of the
59
device memory, the ``length`` field its size. For the multi-planar API,
60
fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
61
elements will be used instead and the ``length`` field of struct
62
:c:type:`v4l2_buffer` is set to the number of filled-in
63
array elements. The driver may or may not set the remaining fields and
64
flags, they are meaningless in this context.
66
The struct :c:type:`v4l2_buffer` structure is specified in
67
:ref:`buffer`.
69
Return Value
70
============
72
On success 0 is returned, on error -1 and the ``errno`` variable is set
73
appropriately. The generic error codes are described at the
74
:ref:`Generic Error Codes <gen-errors>` chapter.
76
EINVAL
77
The buffer ``type`` is not supported, or the ``index`` is out of
78
bounds.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적, 호출 형식과 인자
1-30`VIDIOC_QUERYBUF`는 streaming I/O에서 `VIDIOC_REQBUFS`로 할당한 buffer의 현재 상태와 memory 위치 정보를 조회합니다. Buffer 할당 이후 언제든 호출할 수 있습니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _VIDIOC_QUERYBUF:
*********************
ioctl VIDIOC_QUERYBUF
*********************
Name
====
VIDIOC_QUERYBUF - Query the status of a buffer
Synopsis
========
.. c:macro:: VIDIOC_QUERYBUF
``int ioctl(int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_buffer`.
조회 입력 필드
31-53필드요구사항
`type``v4l2_format.type` 및 `v4l2_requestbuffers.type`과 동일
`index`0부터 `REQBUFS count - 1`까지
`reserved`, `reserved2`0으로 초기화
`m.planes`multi-planar에서는 `v4l2_plane` 배열의 사용자 공간 포인터
`length`multi-planar에서는 plane 배열 원소 수
Buffer type과 index는 할당 시 사용한 값의 범위와 일치해야 합니다.
호출이 성공하면 드라이버가 나머지 구조체를 채우고, 입력이 잘못되면 오류를 반환합니다.
Description
===========
This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
be used to query the status of a buffer at any time after buffers have
been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.
Applications set the ``type`` field of a struct
:c:type:`v4l2_buffer` to the same buffer type as was
previously used with struct :c:type:`v4l2_format` ``type``
and struct :c:type:`v4l2_requestbuffers` ``type``,
and the ``index`` field. Valid index numbers range from zero to the
number of buffers allocated with
:ref:`VIDIOC_REQBUFS` (struct
:c:type:`v4l2_requestbuffers` ``count``) minus
one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
field must contain a userspace pointer to an array of struct
:c:type:`v4l2_plane` and the ``length`` field has to be set
to the number of elements in that array. After calling
:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
error code or fill the rest of the structure.
상태 flag와 memory 위치
54-68플래그뜻
`V4L2_BUF_FLAG_MAPPED`memory map 상태
`V4L2_BUF_FLAG_PREPARED`I/O 사전 준비 상태
`V4L2_BUF_FLAG_QUEUED`driver queue에 들어간 상태
`V4L2_BUF_FLAG_DONE`처리 완료 상태
QUERYBUF 문맥에서 의미가 보장되는 `flags` 비트입니다.
`memory`에는 현재 I/O 방식이 반환됩니다. Single-planar API는 `m.offset`에 device memory 시작점 기준 offset, `length`에 크기를 반환합니다.
Multi-planar API는 각 `m.planes` 원소의 `m.mem_offset`과 `length`를 사용하고, 상위 `v4l2_buffer.length`에는 채워진 plane 원소 수를 반환합니다. 그 밖의 필드와 flag는 드라이버가 채울 수도 있지만 이 문맥에서는 의미가 없습니다.
In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
set to the current I/O method. For the single-planar API, the
``m.offset`` contains the offset of the buffer from the start of the
device memory, the ``length`` field its size. For the multi-planar API,
fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
elements will be used instead and the ``length`` field of struct
:c:type:`v4l2_buffer` is set to the number of filled-in
array elements. The driver may or may not set the remaining fields and
flags, they are meaningless in this context.
The struct :c:type:`v4l2_buffer` structure is specified in
:ref:`buffer`.
반환값과 오류
69-78성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다.
errno조건
`EINVAL`지원하지 않는 buffer `type` 또는 범위를 벗어난 `index`
할당된 buffer 집합에 대해 type과 index를 검사합니다.
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 the ``index`` is out of
bounds.
요약·해설
vidioc-querybuf.rst:1-78QUERYBUF에서 의미가 보장되는 상태 비트와 memory 방식별 offset 위치만 사용해야 합니다.