요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
========
BPF maps
========
BPF 'maps' provide generic storage of different types for sharing data between
kernel and user space. There are several storage types available, including
hash, array, bloom filter and radix-tree. Several of the map types exist to
support specific BPF helpers that perform actions based on the map contents. The
maps are accessed from BPF programs via BPF helpers which are documented in the
`man-pages`_ for `bpf-helpers(7)`_.
BPF maps are accessed from user space via the ``bpf`` syscall, which provides
commands to create maps, lookup elements, update elements and delete elements.
More details of the BPF syscall are available in `ebpf-syscall`_ and in the
`man-pages`_ for `bpf(2)`_.
Map Types
=========
.. toctree::
:maxdepth: 1
:glob:
map_*
Usage Notes
===========
.. c:function::
int bpf(int command, union bpf_attr *attr, u32 size)
Use the ``bpf()`` system call to perform the operation specified by
``command``. The operation takes parameters provided in ``attr``. The ``size``
argument is the size of the ``union bpf_attr`` in ``attr``.
**BPF_MAP_CREATE**
Create a map with the desired type and attributes in ``attr``:
.. code-block:: c
int fd;
union bpf_attr attr = {
.map_type = BPF_MAP_TYPE_ARRAY; /* mandatory */
.key_size = sizeof(__u32); /* mandatory */
.value_size = sizeof(__u32); /* mandatory */
.max_entries = 256; /* mandatory */
.map_flags = BPF_F_MMAPABLE;
.map_name = "example_array";
};
fd = bpf(BPF_MAP_CREATE, &attr, sizeof(attr));
Returns a process-local file descriptor on success, or negative error in case of
failure. The map can be deleted by calling ``close(fd)``. Maps held by open
file descriptors will be deleted automatically when a process exits.
.. note:: Valid characters for ``map_name`` are ``A-Z``, ``a-z``, ``0-9``,
``'_'`` and ``'.'``.
**BPF_MAP_LOOKUP_ELEM**
Lookup key in a given map using ``attr->map_fd``, ``attr->key``,
``attr->value``. Returns zero and stores found elem into ``attr->value`` on
success, or negative error on failure.
**BPF_MAP_UPDATE_ELEM**
Create or update key/value pair in a given map using ``attr->map_fd``, ``attr->key``,
``attr->value``. Returns zero on success or negative error on failure.
**BPF_MAP_DELETE_ELEM**
Find and delete element by key in a given map using ``attr->map_fd``,
``attr->key``. Returns zero on success or negative error on failure.
.. Links:
.. _man-pages: https://www.kernel.org/doc/man-pages/
.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html
.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
.. _ebpf-syscall: https://docs.kernel.org/userspace-api/ebpf/syscall.html
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Kernel과 user space가 공유하는 BPF storage
1-17BPF `maps`는 kernel과 user space 사이에서 data를 공유하기 위한 여러 type의 범용 storage를 제공합니다. 사용할 수 있는 storage type에는 hash, array, bloom filter, radix-tree 등이 있습니다.
일부 map type은 map content에 따라 action을 수행하는 특정 BPF helper를 지원하기 위해 존재합니다. BPF program은 BPF helper를 통해 map에 접근하며, helper는 `bpf-helpers(7)` man-pages에 문서화되어 있습니다.
User space는 `bpf` syscall을 통해 BPF map에 접근합니다. 이 syscall은 map 생성, element 조회, element 갱신, element 삭제 command를 제공합니다. 자세한 내용은 `ebpf-syscall` 문서와 `bpf(2)` man-pages에 있습니다.
Map type 문서 색인
18-26Map Types toctree는 depth 1과 glob을 사용해 다음 pattern의 개별 map 문서를 포함합니다.
- `map_*`
bpf() syscall과 BPF_MAP_CREATE
27-61`bpf()` system call은 `command`가 지정한 operation을 수행합니다. Operation parameter는 `attr`에 제공하며, `size` argument는 `attr`이 가리키는 `union bpf_attr`의 크기입니다.
int bpf(int command, union bpf_attr *attr, u32 size)`BPF_MAP_CREATE`는 `attr`에 지정한 type과 attribute로 map을 생성합니다.
int fd;
union bpf_attr attr = {
.map_type = BPF_MAP_TYPE_ARRAY; /* mandatory */
.key_size = sizeof(__u32); /* mandatory */
.value_size = sizeof(__u32); /* mandatory */
.max_entries = 256; /* mandatory */
.map_flags = BPF_F_MMAPABLE;
.map_name = "example_array";
};
fd = bpf(BPF_MAP_CREATE, &attr, sizeof(attr));예제는 필수 field인 `map_type`, `key_size`, `value_size`, `max_entries`를 채우고, `map_flags`에 `BPF_F_MMAPABLE`, `map_name`에 `example_array`를 지정한 뒤 `bpf(BPF_MAP_CREATE, &attr, sizeof(attr))`를 호출합니다.
성공하면 process-local file descriptor를 반환하고, 실패하면 negative error를 반환합니다. `close(fd)`를 호출하면 map을 삭제할 수 있습니다. 열린 file descriptor가 보유한 map은 process가 종료될 때 자동으로 삭제됩니다.
`map_name`에 허용되는 문자는 `A-Z`, `a-z`, `0-9`, `'_'`, `'.'`입니다.
Element lookup, update, delete
62-82`BPF_MAP_LOOKUP_ELEM`은 `attr->map_fd`, `attr->key`, `attr->value`를 사용해 주어진 map의 key를 조회합니다. 성공하면 0을 반환하고 찾은 element를 `attr->value`에 저장하며, 실패하면 negative error를 반환합니다.
`BPF_MAP_UPDATE_ELEM`은 `attr->map_fd`, `attr->key`, `attr->value`를 사용해 주어진 map의 key/value pair를 생성하거나 갱신합니다. 성공하면 0, 실패하면 negative error를 반환합니다.
`BPF_MAP_DELETE_ELEM`은 `attr->map_fd`와 `attr->key`를 사용해 key로 element를 찾아 삭제합니다. 성공하면 0, 실패하면 negative error를 반환합니다.
원문이 연결하는 syscall, helper, man-page 자료는 다음과 같습니다.
- [https://www.kernel.org/doc/man-pages/](https://www.kernel.org/doc/man-pages/)
- [https://man7.org/linux/man-pages/man2/bpf.2.html](https://man7.org/linux/man-pages/man2/bpf.2.html)
- [https://man7.org/linux/man-pages/man7/bpf-helpers.7.html](https://man7.org/linux/man-pages/man7/bpf-helpers.7.html)
- [https://docs.kernel.org/userspace-api/ebpf/syscall.html](https://docs.kernel.org/userspace-api/ebpf/syscall.html)
요약과 해설
maps.rst:1-82BPF map은 BPF program과 user space가 data를 공유하는 핵심 storage abstraction입니다. Map type에 따라 저장 구조나 helper 연동 방식이 달라집니다.
User space에서는 `bpf()` syscall의 `BPF_MAP_CREATE`, `BPF_MAP_LOOKUP_ELEM`, `BPF_MAP_UPDATE_ELEM`, `BPF_MAP_DELETE_ELEM` command로 map의 수명과 element를 관리합니다.
Map은 file descriptor로 참조됩니다. `close(fd)` 또는 마지막 열린 descriptor를 가진 process의 종료가 map 수명에 직접 영향을 준다는 점이 resource 관리에서 중요합니다.