API naming convention

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

libbpf_naming_convention.rst:1-193

Libbpf는 symbol 역할에 따라 `bpf_`, `btf_`, `libbpf_`, `ring_buffer_` 같은 prefix를 사용합니다. Object method는 `bpf_object__open`처럼 object name과 purpose를 double underscore로 구분합니다.

ABI symbol은 기본 hidden이고 `LIBBPF_API`로만 export합니다. `libbpf.map`의 `LIBBPF_x.y.z` version node로 extension을 관리하며, 새 node는 이전 version에 의존하도록 작성합니다.

Header API comment는 `/\**`, `@brief`, API name, 각 `@param`, 필요한 `@return` 순서를 지킵니다. Stand-alone mirror가 있어도 code change는 mainline kernel tree를 통해 upstream해야 합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)

3 API naming convention

4 =====================

6 libbpf API provides access to a few logically separated groups of

7 functions and types. Every group has its own naming convention

8 described here. It's recommended to follow these conventions whenever a

9 new function or type is added to keep libbpf API clean and consistent.

11 All types and functions provided by libbpf API should have one of the

12 following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``btf_dump_``,

13 ``ring_buffer_``, ``perf_buffer_``.

15 System call wrappers

16 --------------------

18 System call wrappers are simple wrappers for commands supported by

19 sys_bpf system call. These wrappers should go to ``bpf.h`` header file

20 and map one to one to corresponding commands.

22 For example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM``

23 command of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc.

25 Objects

26 -------

28 Another class of types and functions provided by libbpf API is "objects"

29 and functions to work with them. Objects are high-level abstractions

30 such as BPF program or BPF map. They're represented by corresponding

31 structures such as ``struct bpf_object``, ``struct bpf_program``,

32 ``struct bpf_map``, etc.

34 Structures are forward declared and access to their fields should be

35 provided via corresponding getters and setters rather than directly.

37 These objects are associated with corresponding parts of ELF object that

38 contains compiled BPF programs.

40 For example ``struct bpf_object`` represents ELF object itself created

41 from an ELF file or from a buffer, ``struct bpf_program`` represents a

42 program in ELF object and ``struct bpf_map`` is a map.

44 Functions that work with an object have names built from object name,

45 double underscore and part that describes function purpose.

47 For example ``bpf_object__open`` consists of the name of corresponding

48 object, ``bpf_object``, double underscore and ``open`` that defines the

49 purpose of the function to open ELF file and create ``bpf_object`` from

50 it.

52 All objects and corresponding functions other than BTF related should go

53 to ``libbpf.h``. BTF types and functions should go to ``btf.h``.

55 Auxiliary functions

56 -------------------

58 Auxiliary functions and types that don't fit well in any of categories

59 described above should have ``libbpf_`` prefix, e.g.

60 ``libbpf_get_error`` or ``libbpf_prog_type_by_name``.

62 ABI

63 ---

65 libbpf can be both linked statically or used as DSO. To avoid possible

66 conflicts with other libraries an application is linked with, all

67 non-static libbpf symbols should have one of the prefixes mentioned in

68 API documentation above. See API naming convention to choose the right

69 name for a new symbol.

71 Symbol visibility

72 -----------------

74 libbpf follow the model when all global symbols have visibility "hidden"

75 by default and to make a symbol visible it has to be explicitly

76 attributed with ``LIBBPF_API`` macro. For example:

78 .. code-block:: c

80 LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);

82 This prevents from accidentally exporting a symbol, that is not supposed

83 to be a part of ABI what, in turn, improves both libbpf developer- and

84 user-experiences.

86 ABI versioning

87 --------------

89 To make future ABI extensions possible libbpf ABI is versioned.

90 Versioning is implemented by ``libbpf.map`` version script that is

91 passed to linker.

93 Version name is ``LIBBPF_`` prefix + three-component numeric version,

94 starting from ``0.0.1``.

96 Every time ABI is being changed, e.g. because a new symbol is added or

97 semantic of existing symbol is changed, ABI version should be bumped.

98 This bump in ABI version is at most once per kernel development cycle.

100 For example, if current state of ``libbpf.map`` is:

101

102 .. code-block:: none

103

104 LIBBPF_0.0.1 {

105 global:

106 bpf_func_a;

107 bpf_func_b;

108 local:

109 \*;

110 };

111

112 , and a new symbol ``bpf_func_c`` is being introduced, then

113 ``libbpf.map`` should be changed like this:

114

115 .. code-block:: none

116

117 LIBBPF_0.0.1 {

118 global:

119 bpf_func_a;

120 bpf_func_b;

121 local:

122 \*;

123 };

124 LIBBPF_0.0.2 {

125 global:

126 bpf_func_c;

127 } LIBBPF_0.0.1;

128

129 , where new version ``LIBBPF_0.0.2`` depends on the previous

130 ``LIBBPF_0.0.1``.

131

132 Format of version script and ways to handle ABI changes, including

133 incompatible ones, described in details in [1].

134

135 Stand-alone build

136 -------------------

137

138 Under https://github.com/libbpf/libbpf there is a (semi-)automated

139 mirror of the mainline's version of libbpf for a stand-alone build.

140

141 However, all changes to libbpf's code base must be upstreamed through

142 the mainline kernel tree.

143

144

145 API documentation convention

146 ============================

147

148 The libbpf API is documented via comments above definitions in

149 header files. These comments can be rendered by doxygen and sphinx

150 for well organized html output. This section describes the

151 convention in which these comments should be formatted.

152

153 Here is an example from btf.h:

154

155 .. code-block:: c

156

157 /**

158 * @brief **btf__new()** creates a new instance of a BTF object from the raw

159 * bytes of an ELF's BTF section

160 * @param data raw bytes

161 * @param size number of bytes passed in `data`

162 * @return new BTF object instance which has to be eventually freed with

163 * **btf__free()**

164 *

165 * On error, error-code-encoded-as-pointer is returned, not a NULL. To extract

166 * error code from such a pointer `libbpf_get_error()` should be used. If

167 * `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is enabled, NULL is

168 * returned on error instead. In both cases thread-local `errno` variable is

169 * always set to error code as well.

170 */

171

172 The comment must start with a block comment of the form '/\*\*'.

173

174 The documentation always starts with a @brief directive. This line is a short

175 description about this API. It starts with the name of the API, denoted in bold

176 like so: **api_name**. Please include an open and close parenthesis if this is a

177 function. Follow with the short description of the API. A longer form description

178 can be added below the last directive, at the bottom of the comment.

179

180 Parameters are denoted with the @param directive, there should be one for each

181 parameter. If this is a function with a non-void return, use the @return directive

182 to document it.

183

184 License

185 -------------------

186

187 libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.

188

189 Links

190 -------------------

191

192 [1] https://www.akkadia.org/drepper/dsohowto.pdf

193 (Chapter 3. Maintaining APIs and ABIs).

194

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

1-14

이 문서는 `(LGPL-2.1 OR BSD-2-Clause)` license를 따르며 libbpf API naming convention을 설명합니다.

Libbpf API는 논리적으로 분리된 여러 function·type group에 접근할 수 있게 하며, 각 group에는 이 문서에서 설명하는 고유한 naming convention이 있습니다. API를 깔끔하고 일관되게 유지하려면 새 function이나 type을 추가할 때 이 convention을 따르는 것이 좋습니다.

Libbpf API가 제공하는 모든 type과 function은 다음 prefix 중 하나를 가져야 합니다.

`bpf_`
`btf_`
`libbpf_`
`btf_dump_`
`ring_buffer_`
`perf_buffer_`

System call wrapper naming

15-24

System call wrapper는 `sys_bpf` system call이 지원하는 command의 단순 wrapper입니다. 이 wrapper는 `bpf.h` header에 두고 대응하는 command와 일대일로 mapping해야 합니다.

예를 들어 `bpf_map_lookup_elem`은 `sys_bpf`의 `BPF_MAP_LOOKUP_ELEM` command를 감싸고, `bpf_prog_attach`는 `BPF_PROG_ATTACH`를 감쌉니다.

Object type과 function naming

25-54

Libbpf API가 제공하는 또 다른 type·function class는 "object"와 이를 다루는 function입니다. Object는 BPF program이나 BPF map 같은 high-level abstraction이며 `struct bpf_object`, `struct bpf_program`, `struct bpf_map` 같은 structure로 나타냅니다.

Structure는 forward declaration하고, field에는 직접 접근하지 않고 대응하는 getter와 setter로 접근해야 합니다.

이 object들은 compiled BPF program이 들어 있는 ELF object의 대응 부분과 연결됩니다. `struct bpf_object`는 ELF file이나 buffer에서 만든 ELF object 자체를, `struct bpf_program`은 ELF object 안의 program을, `struct bpf_map`은 map을 나타냅니다.

Object를 다루는 function name은 object name, double underscore, function purpose를 설명하는 부분으로 구성합니다.

예를 들어 `bpf_object__open`은 object name `bpf_object`, double underscore, ELF file을 열고 `bpf_object`를 만드는 목적을 나타내는 `open`으로 이루어집니다.

BTF 관련 항목을 제외한 모든 object와 대응 function은 `libbpf.h`에 두고, BTF type과 function은 `btf.h`에 둡니다.

Auxiliary function naming

55-61

앞의 category에 잘 맞지 않는 auxiliary function과 type은 `libbpf_` prefix를 사용해야 합니다. 예로 `libbpf_get_error`와 `libbpf_prog_type_by_name`이 있습니다.

ABI symbol prefix

62-70

Libbpf는 static link하거나 DSO로 사용할 수 있습니다. Application이 함께 link하는 다른 library와 충돌할 가능성을 피하려면 모든 non-static libbpf symbol이 위 API documentation에서 언급한 prefix 중 하나를 가져야 합니다.

새 symbol의 올바른 name은 API naming convention에 따라 선택합니다.

Symbol visibility

71-85

Libbpf는 모든 global symbol의 visibility를 기본적으로 `hidden`으로 두고, symbol을 visible하게 만들 때 `LIBBPF_API` macro를 명시적으로 붙이는 model을 따릅니다.

LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);

이 방식은 ABI의 일부가 아니어야 할 symbol을 실수로 export하는 일을 막아 libbpf developer와 user 양쪽의 경험을 개선합니다.

ABI version naming과 갱신

86-99

향후 ABI extension을 가능하게 하기 위해 libbpf ABI는 versioning합니다. Linker에 전달하는 `libbpf.map` version script로 이를 구현합니다.

Version name은 `LIBBPF_` prefix와 세 component numeric version을 결합하며 `0.0.1`에서 시작합니다.

새 symbol 추가나 기존 symbol semantics 변경 등으로 ABI가 바뀔 때마다 ABI version을 올려야 합니다. ABI version bump는 kernel development cycle마다 최대 한 번 수행합니다.

Version script 확장 예제

100-134

현재 `libbpf.map` 상태가 다음과 같다고 가정합니다.

LIBBPF_0.0.1 {
        global:
                bpf_func_a;
                bpf_func_b;
        local:
                \*;
};

새 symbol `bpf_func_c`를 도입하면 `libbpf.map`을 다음과 같이 변경합니다.

LIBBPF_0.0.1 {
        global:
                bpf_func_a;
                bpf_func_b;
        local:
                \*;
};
LIBBPF_0.0.2 {
        global:
                bpf_func_c;
} LIBBPF_0.0.1;

새 version `LIBBPF_0.0.2`는 이전 `LIBBPF_0.0.1`에 의존합니다.

Version script format과 incompatible change를 포함한 ABI change 처리 방법은 [Maintaining APIs and ABIs, Chapter 3](https://www.akkadia.org/drepper/dsohowto.pdf)에 자세히 설명되어 있습니다.

Stand-alone build mirror

135-144

[libbpf/libbpf repository](https://github.com/libbpf/libbpf)에는 mainline libbpf version을 stand-alone build용으로 제공하는 semi-automated mirror가 있습니다.

그러나 libbpf code base의 모든 변경은 mainline kernel tree를 통해 upstream해야 합니다.

API documentation comment 예제

145-171

Libbpf API는 header file의 definition 위에 있는 comment로 문서화합니다. 이 comment는 doxygen과 Sphinx가 정돈된 HTML output으로 render할 수 있습니다. 이 절은 comment format convention을 설명합니다.

다음은 `btf.h`의 예제입니다.

/**
 * @brief **btf__new()** creates a new instance of a BTF object from the raw
 * bytes of an ELF's BTF section
 * @param data raw bytes
 * @param size number of bytes passed in `data`
 * @return new BTF object instance which has to be eventually freed with
 * **btf__free()**
 *
 * On error, error-code-encoded-as-pointer is returned, not a NULL. To extract
 * error code from such a pointer `libbpf_get_error()` should be used. If
 * `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is enabled, NULL is
 * returned on error instead. In both cases thread-local `errno` variable is
 * always set to error code as well.
 */

예제는 `btf__new()`의 brief, `data`와 `size` parameter, `btf__free()`가 필요한 return object, error-code-encoded pointer와 `libbpf_get_error()`, strict mode의 NULL return, thread-local `errno` 규칙을 한 comment에 기록합니다.

API documentation comment 규칙

172-183

Comment는 `/\**` 형태의 block comment로 시작해야 합니다.

Documentation은 항상 `@brief` directive로 시작합니다. 이 line은 API의 짧은 설명이며 bold로 표시한 `api_name`으로 시작합니다. Function이면 여는 parenthesis와 닫는 parenthesis도 포함하고, 이어서 API의 짧은 설명을 씁니다.

더 긴 설명은 마지막 directive 아래 comment 끝부분에 추가할 수 있습니다.

Parameter는 각각 `@param` directive 하나로 문서화합니다. Non-void return을 가진 function이면 `@return` directive로 반환값을 문서화합니다.

License

184-188

Libbpf는 LGPL 2.1과 BSD 2-Clause로 dual-license됩니다.

ABI reference link

189-193

[Maintaining APIs and ABIs](https://www.akkadia.org/drepper/dsohowto.pdf)의 Chapter 3이 version script와 ABI 유지 관리의 외부 reference입니다.