요약·해설과 원문, 전문 번역을 서로 분리했습니다. 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
.. _func-mmap:
6
***********
7
V4L2 mmap()
8
***********
10
Name
11
====
13
v4l2-mmap - Map device memory into application address space
15
Synopsis
16
========
18
.. code-block:: c
20
#include <unistd.h>
21
#include <sys/mman.h>
23
.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
25
Arguments
26
=========
28
``start``
29
Map the buffer to this address in the application's address space.
30
When the ``MAP_FIXED`` flag is specified, ``start`` must be a
31
multiple of the pagesize and mmap will fail when the specified
32
address cannot be used. Use of this option is discouraged;
33
applications should just specify a ``NULL`` pointer here.
35
``length``
36
Length of the memory area to map. This must be the same value as
37
returned by the driver in the struct
38
:c:type:`v4l2_buffer` ``length`` field for the
39
single-planar API, and the same value as returned by the driver in
40
the struct :c:type:`v4l2_plane` ``length`` field for
41
the multi-planar API.
43
``prot``
44
The ``prot`` argument describes the desired memory protection.
45
Regardless of the device type and the direction of data exchange it
46
should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
47
and write access to image buffers. Drivers should support at least
48
this combination of flags.
50
.. note::
52
#. The Linux ``videobuf`` kernel module, which is used by some
53
drivers supports only ``PROT_READ`` | ``PROT_WRITE``. When the
54
driver does not support the desired protection, the
55
:c:func:`mmap()` function fails.
57
#. Device memory accesses (e. g. the memory on a graphics card
58
with video capturing hardware) may incur a performance penalty
59
compared to main memory accesses, or reads may be significantly
60
slower than writes or vice versa. Other I/O methods may be more
61
efficient in such case.
63
``flags``
64
The ``flags`` parameter specifies the type of the mapped object,
65
mapping options and whether modifications made to the mapped copy of
66
the page are private to the process or are to be shared with other
67
references.
69
``MAP_FIXED`` requests that the driver selects no other address than
70
the one specified. If the specified address cannot be used,
71
:c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified,
72
``start`` must be a multiple of the pagesize. Use of this option is
73
discouraged.
75
One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
76
``MAP_SHARED`` allows applications to share the mapped memory with
77
other (e. g. child-) processes.
79
.. note::
81
The Linux ``videobuf`` module which is used by some
82
drivers supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests
83
copy-on-write semantics. V4L2 applications should not set the
84
``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON``
85
flags.
87
``fd``
88
File descriptor returned by :c:func:`open()`.
90
``offset``
91
Offset of the buffer in device memory. This must be the same value
92
as returned by the driver in the struct
93
:c:type:`v4l2_buffer` ``m`` union ``offset`` field for
94
the single-planar API, and the same value as returned by the driver
95
in the struct :c:type:`v4l2_plane` ``m`` union
96
``mem_offset`` field for the multi-planar API.
98
Description
99
===========
101
The :c:func:`mmap()` function asks to map ``length`` bytes starting at
102
``offset`` in the memory of the device specified by ``fd`` into the
103
application address space, preferably at address ``start``. This latter
104
address is a hint only, and is usually specified as 0.
106
Suitable length and offset parameters are queried with the
107
:ref:`VIDIOC_QUERYBUF` ioctl. Buffers must be
108
allocated with the :ref:`VIDIOC_REQBUFS` ioctl
109
before they can be queried.
111
To unmap buffers the :c:func:`munmap()` function is used.
113
Return Value
114
============
116
On success :c:func:`mmap()` returns a pointer to the mapped buffer. On
117
error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
118
appropriately. Possible error codes are:
120
EBADF
121
``fd`` is not a valid file descriptor.
123
EACCES
124
``fd`` is not open for reading and writing.
126
EINVAL
127
The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
128
they are too large, or not aligned on a ``PAGESIZE`` boundary.)
130
The ``flags`` or ``prot`` value is not supported.
132
No buffers have been allocated with the
133
:ref:`VIDIOC_REQBUFS` ioctl.
135
ENOMEM
136
Not enough physical or virtual memory was available to complete the
137
request.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
장치 메모리 매핑 선언
1-24`v4l2-mmap`은 장치 메모리를 application address space에 매핑합니다. `<unistd.h>`와 `<sys/mman.h>`를 포함하고 `void *mmap(void *start, size_t length, int prot, int flags, int fd, off_t offset)`을 호출합니다.
`VIDIOC_REQBUFS`로 buffer 할당→`VIDIOC_QUERYBUF`로 length와 offset 조회→Plane별 `mmap()` 호출→반환 pointer로 image buffer 접근→사용 후 `munmap()` 호출
드라이버가 할당하고 보고한 값을 그대로 매핑 인자로 사용합니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _func-mmap:
***********
V4L2 mmap()
***********
Name
====
v4l2-mmap - Map device memory into application address space
Synopsis
========
.. code-block:: c
#include <unistd.h>
#include <sys/mman.h>
.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
주소, 길이, 보호와 sharing 인자
25-97`start`는 매핑을 원하는 application 주소입니다. `MAP_FIXED`를 쓰면 page size의 배수여야 하고 정확히 그 주소를 사용할 수 없을 때 실패합니다. 이 옵션은 권장되지 않으므로 application은 보통 `NULL`을 전달해 kernel이 주소를 고르게 해야 합니다.
`length`는 매핑할 영역 크기입니다. Single-planar API에서는 driver가 반환한 `v4l2_buffer.length`, multi-planar API에서는 해당 `v4l2_plane.length`와 정확히 같아야 합니다.
`prot`는 장치 종류나 data 방향과 관계없이 image buffer의 read/write 접근을 허용하는 `PROT_READ | PROT_WRITE`로 설정해야 하며 driver는 적어도 이 조합을 지원해야 합니다. 일부 driver가 쓰는 Linux `videobuf` module은 이 조합만 지원합니다. 장치 메모리는 main memory보다 느리거나 read와 write 성능이 비대칭일 수 있으므로 다른 I/O 방식이 더 효율적일 수도 있습니다.
`flags`는 mapped object type, mapping option과 변경 내용을 다른 reference와 공유할지 정합니다. `MAP_SHARED` 또는 `MAP_PRIVATE` 중 하나는 반드시 있어야 하지만 V4L2 application은 공유 매핑을 위해 `MAP_SHARED`를 사용해야 합니다. `MAP_PRIVATE`의 copy-on-write 의미는 V4L2 buffer에 적합하지 않으며 `MAP_DENYWRITE`, `MAP_EXECUTABLE`, `MAP_ANON`도 설정하지 않아야 합니다. 일부 `videobuf` driver는 `MAP_SHARED`만 지원합니다.
항목설명
`start`보통 `NULL`; `MAP_FIXED` 사용 시 page-aligned exact address
`length` single-planar`v4l2_buffer.length`
`length` multi-planar`v4l2_plane.length`
`prot``PROT_READ | PROT_WRITE`
`flags``MAP_SHARED`; V4L2에서는 private·anonymous·executable mapping을 피함
`fd``open()`이 반환한 file descriptor
`offset` single-planar`v4l2_buffer.m.offset`
`offset` multi-planar`v4l2_plane.m.mem_offset`
Single-planar와 multi-planar에서 driver가 보고한 필드를 정확히 대응시킵니다.
`offset`은 device memory 안의 buffer 위치이며 single-planar에서는 `v4l2_buffer.m.offset`, multi-planar에서는 `v4l2_plane.m.mem_offset`이 반환한 값을 그대로 사용합니다.
Arguments
=========
``start``
Map the buffer to this address in the application's address space.
When the ``MAP_FIXED`` flag is specified, ``start`` must be a
multiple of the pagesize and mmap will fail when the specified
address cannot be used. Use of this option is discouraged;
applications should just specify a ``NULL`` pointer here.
``length``
Length of the memory area to map. This must be the same value as
returned by the driver in the struct
:c:type:`v4l2_buffer` ``length`` field for the
single-planar API, and the same value as returned by the driver in
the struct :c:type:`v4l2_plane` ``length`` field for
the multi-planar API.
``prot``
The ``prot`` argument describes the desired memory protection.
Regardless of the device type and the direction of data exchange it
should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
and write access to image buffers. Drivers should support at least
this combination of flags.
.. note::
#. The Linux ``videobuf`` kernel module, which is used by some
drivers supports only ``PROT_READ`` | ``PROT_WRITE``. When the
driver does not support the desired protection, the
:c:func:`mmap()` function fails.
#. Device memory accesses (e. g. the memory on a graphics card
with video capturing hardware) may incur a performance penalty
compared to main memory accesses, or reads may be significantly
slower than writes or vice versa. Other I/O methods may be more
efficient in such case.
``flags``
The ``flags`` parameter specifies the type of the mapped object,
mapping options and whether modifications made to the mapped copy of
the page are private to the process or are to be shared with other
references.
``MAP_FIXED`` requests that the driver selects no other address than
the one specified. If the specified address cannot be used,
:c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified,
``start`` must be a multiple of the pagesize. Use of this option is
discouraged.
One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
``MAP_SHARED`` allows applications to share the mapped memory with
other (e. g. child-) processes.
.. note::
The Linux ``videobuf`` module which is used by some
drivers supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests
copy-on-write semantics. V4L2 applications should not set the
``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON``
flags.
``fd``
File descriptor returned by :c:func:`open()`.
``offset``
Offset of the buffer in device memory. This must be the same value
as returned by the driver in the struct
:c:type:`v4l2_buffer` ``m`` union ``offset`` field for
the single-planar API, and the same value as returned by the driver
in the struct :c:type:`v4l2_plane` ``m`` union
``mem_offset`` field for the multi-planar API.
매핑 동작, 반환값과 오류
98-137`mmap()`은 `fd` 장치 메모리의 `offset`부터 `length` byte를 application address space에 매핑합니다. `start`는 `MAP_FIXED`가 아니면 hint일 뿐이며 보통 0입니다. 적합한 length와 offset은 `VIDIOC_REQBUFS`로 buffer를 할당한 뒤 `VIDIOC_QUERYBUF`로 조회합니다.
성공하면 mapped buffer pointer를 반환합니다. 실패하면 `MAP_FAILED`(-1)를 반환하고 `errno`를 설정합니다.
항목설명
`EBADF``fd`가 유효한 file descriptor가 아닙니다.
`EACCES``fd`가 read와 write 양쪽으로 열리지 않았습니다.
`EINVAL``start`, `length`, `offset`이 너무 크거나 PAGESIZE에 정렬되지 않았습니다.
`EINVAL``flags` 또는 `prot` 조합을 지원하지 않습니다.
`EINVAL``VIDIOC_REQBUFS`로 buffer를 할당하지 않았습니다.
`ENOMEM`요청을 완료할 physical 또는 virtual memory가 부족합니다.
Descriptor, 접근 mode, alignment, buffer 할당과 memory 부족을 구분합니다.
Description
===========
The :c:func:`mmap()` function asks to map ``length`` bytes starting at
``offset`` in the memory of the device specified by ``fd`` into the
application address space, preferably at address ``start``. This latter
address is a hint only, and is usually specified as 0.
Suitable length and offset parameters are queried with the
:ref:`VIDIOC_QUERYBUF` ioctl. Buffers must be
allocated with the :ref:`VIDIOC_REQBUFS` ioctl
before they can be queried.
To unmap buffers the :c:func:`munmap()` function is used.
Return Value
============
On success :c:func:`mmap()` returns a pointer to the mapped buffer. On
error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
appropriately. Possible error codes are:
EBADF
``fd`` is not a valid file descriptor.
EACCES
``fd`` is not open for reading and writing.
EINVAL
The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
they are too large, or not aligned on a ``PAGESIZE`` boundary.)
The ``flags`` or ``prot`` value is not supported.
No buffers have been allocated with the
:ref:`VIDIOC_REQBUFS` ioctl.
ENOMEM
Not enough physical or virtual memory was available to complete the
request.
요약·해설
func-mmap.rst:1-137V4L2 MMAP은 REQBUFS와 QUERYBUF가 반환한 plane별 length·offset을 그대로 사용하고 read/write shared mapping으로 장치 buffer를 application에 연결합니다.