Commit | Line | Data |
---|---|---|
3cd046f1 | 1 | #!/usr/bin/env python3 |
56a092c8 QM |
2 | # SPDX-License-Identifier: GPL-2.0-only |
3 | # | |
748c7c82 | 4 | # Copyright (C) 2018-2019 Netronome Systems, Inc. |
923a932c | 5 | # Copyright (C) 2021 Isovalent, Inc. |
56a092c8 QM |
6 | |
7 | # In case user attempts to run with Python 2. | |
8 | from __future__ import print_function | |
9 | ||
10 | import argparse | |
11 | import re | |
12 | import sys, os | |
fd0a38f9 QM |
13 | import subprocess |
14 | ||
92ec1cc3 | 15 | helpersDocStart = 'Start of BPF helper function descriptions:' |
56a092c8 QM |
16 | |
17 | class NoHelperFound(BaseException): | |
18 | pass | |
19 | ||
a67882a2 JS |
20 | class NoSyscallCommandFound(BaseException): |
21 | pass | |
22 | ||
56a092c8 QM |
23 | class ParsingError(BaseException): |
24 | def __init__(self, line='<line not provided>', reader=None): | |
25 | if reader: | |
26 | BaseException.__init__(self, | |
27 | 'Error at file offset %d, parsing line: %s' % | |
28 | (reader.tell(), line)) | |
29 | else: | |
30 | BaseException.__init__(self, 'Error parsing line: %s' % line) | |
31 | ||
a67882a2 JS |
32 | |
33 | class APIElement(object): | |
56a092c8 | 34 | """ |
a67882a2 JS |
35 | An object representing the description of an aspect of the eBPF API. |
36 | @proto: prototype of the API symbol | |
37 | @desc: textual description of the symbol | |
38 | @ret: (optional) description of any associated return value | |
56a092c8 QM |
39 | """ |
40 | def __init__(self, proto='', desc='', ret=''): | |
41 | self.proto = proto | |
42 | self.desc = desc | |
43 | self.ret = ret | |
44 | ||
a67882a2 JS |
45 | |
46 | class Helper(APIElement): | |
47 | """ | |
48 | An object representing the description of an eBPF helper function. | |
49 | @proto: function prototype of the helper function | |
50 | @desc: textual description of the helper function | |
51 | @ret: description of the return value of the helper function | |
52 | """ | |
0a0d55ef EB |
53 | def __init__(self, *args, **kwargs): |
54 | super().__init__(*args, **kwargs) | |
55 | self.enum_val = None | |
56 | ||
56a092c8 QM |
57 | def proto_break_down(self): |
58 | """ | |
59 | Break down helper function protocol into smaller chunks: return type, | |
60 | name, distincts arguments. | |
61 | """ | |
121fd33b | 62 | arg_re = re.compile(r'((\w+ )*?(\w+|...))( (\**)(\w+))?$') |
56a092c8 | 63 | res = {} |
121fd33b | 64 | proto_re = re.compile(r'(.+) (\**)(\w+)\(((([^,]+)(, )?){1,5})\)$') |
56a092c8 QM |
65 | |
66 | capture = proto_re.match(self.proto) | |
67 | res['ret_type'] = capture.group(1) | |
68 | res['ret_star'] = capture.group(2) | |
69 | res['name'] = capture.group(3) | |
70 | res['args'] = [] | |
71 | ||
72 | args = capture.group(4).split(', ') | |
73 | for a in args: | |
74 | capture = arg_re.match(a) | |
75 | res['args'].append({ | |
76 | 'type' : capture.group(1), | |
748c7c82 QM |
77 | 'star' : capture.group(5), |
78 | 'name' : capture.group(6) | |
56a092c8 QM |
79 | }) |
80 | ||
81 | return res | |
82 | ||
a67882a2 | 83 | |
56a092c8 QM |
84 | class HeaderParser(object): |
85 | """ | |
86 | An object used to parse a file in order to extract the documentation of a | |
87 | list of eBPF helper functions. All the helpers that can be retrieved are | |
88 | stored as Helper object, in the self.helpers() array. | |
89 | @filename: name of file to parse, usually include/uapi/linux/bpf.h in the | |
90 | kernel tree | |
91 | """ | |
92 | def __init__(self, filename): | |
93 | self.reader = open(filename, 'r') | |
94 | self.line = '' | |
95 | self.helpers = [] | |
a67882a2 | 96 | self.commands = [] |
71a3cdf8 UA |
97 | self.desc_unique_helpers = set() |
98 | self.define_unique_helpers = [] | |
0a0d55ef | 99 | self.helper_enum_vals = {} |
ce3e44a0 | 100 | self.helper_enum_pos = {} |
0ba3929e UA |
101 | self.desc_syscalls = [] |
102 | self.enum_syscalls = [] | |
a67882a2 JS |
103 | |
104 | def parse_element(self): | |
105 | proto = self.parse_symbol() | |
f1f3f67f UA |
106 | desc = self.parse_desc(proto) |
107 | ret = self.parse_ret(proto) | |
a67882a2 | 108 | return APIElement(proto=proto, desc=desc, ret=ret) |
56a092c8 QM |
109 | |
110 | def parse_helper(self): | |
111 | proto = self.parse_proto() | |
f1f3f67f UA |
112 | desc = self.parse_desc(proto) |
113 | ret = self.parse_ret(proto) | |
56a092c8 QM |
114 | return Helper(proto=proto, desc=desc, ret=ret) |
115 | ||
a67882a2 | 116 | def parse_symbol(self): |
121fd33b | 117 | p = re.compile(r' \* ?(BPF\w+)$') |
a67882a2 JS |
118 | capture = p.match(self.line) |
119 | if not capture: | |
120 | raise NoSyscallCommandFound | |
121fd33b | 121 | end_re = re.compile(r' \* ?NOTES$') |
a67882a2 JS |
122 | end = end_re.match(self.line) |
123 | if end: | |
124 | raise NoSyscallCommandFound | |
125 | self.line = self.reader.readline() | |
126 | return capture.group(1) | |
127 | ||
56a092c8 QM |
128 | def parse_proto(self): |
129 | # Argument can be of shape: | |
130 | # - "void" | |
131 | # - "type name" | |
132 | # - "type *name" | |
133 | # - Same as above, with "const" and/or "struct" in front of type | |
134 | # - "..." (undefined number of arguments, for bpf_trace_printk()) | |
135 | # There is at least one term ("void"), and at most five arguments. | |
121fd33b | 136 | p = re.compile(r' \* ?((.+) \**\w+\((((const )?(struct )?(\w+|\.\.\.)( \**\w+)?)(, )?){1,5}\))$') |
56a092c8 QM |
137 | capture = p.match(self.line) |
138 | if not capture: | |
139 | raise NoHelperFound | |
140 | self.line = self.reader.readline() | |
141 | return capture.group(1) | |
142 | ||
f1f3f67f | 143 | def parse_desc(self, proto): |
121fd33b | 144 | p = re.compile(r' \* ?(?:\t| {5,8})Description$') |
56a092c8 QM |
145 | capture = p.match(self.line) |
146 | if not capture: | |
f1f3f67f | 147 | raise Exception("No description section found for " + proto) |
56a092c8 QM |
148 | # Description can be several lines, some of them possibly empty, and it |
149 | # stops when another subsection title is met. | |
150 | desc = '' | |
f1f3f67f | 151 | desc_present = False |
56a092c8 QM |
152 | while True: |
153 | self.line = self.reader.readline() | |
154 | if self.line == ' *\n': | |
155 | desc += '\n' | |
156 | else: | |
121fd33b | 157 | p = re.compile(r' \* ?(?:\t| {5,8})(?:\t| {8})(.*)') |
56a092c8 QM |
158 | capture = p.match(self.line) |
159 | if capture: | |
f1f3f67f | 160 | desc_present = True |
56a092c8 QM |
161 | desc += capture.group(1) + '\n' |
162 | else: | |
163 | break | |
f1f3f67f UA |
164 | |
165 | if not desc_present: | |
166 | raise Exception("No description found for " + proto) | |
56a092c8 QM |
167 | return desc |
168 | ||
f1f3f67f | 169 | def parse_ret(self, proto): |
121fd33b | 170 | p = re.compile(r' \* ?(?:\t| {5,8})Return$') |
56a092c8 QM |
171 | capture = p.match(self.line) |
172 | if not capture: | |
f1f3f67f | 173 | raise Exception("No return section found for " + proto) |
56a092c8 QM |
174 | # Return value description can be several lines, some of them possibly |
175 | # empty, and it stops when another subsection title is met. | |
176 | ret = '' | |
f1f3f67f | 177 | ret_present = False |
56a092c8 QM |
178 | while True: |
179 | self.line = self.reader.readline() | |
180 | if self.line == ' *\n': | |
181 | ret += '\n' | |
182 | else: | |
121fd33b | 183 | p = re.compile(r' \* ?(?:\t| {5,8})(?:\t| {8})(.*)') |
56a092c8 QM |
184 | capture = p.match(self.line) |
185 | if capture: | |
f1f3f67f | 186 | ret_present = True |
56a092c8 QM |
187 | ret += capture.group(1) + '\n' |
188 | else: | |
189 | break | |
f1f3f67f UA |
190 | |
191 | if not ret_present: | |
192 | raise Exception("No return found for " + proto) | |
56a092c8 QM |
193 | return ret |
194 | ||
0ba3929e | 195 | def seek_to(self, target, help_message, discard_lines = 1): |
a67882a2 JS |
196 | self.reader.seek(0) |
197 | offset = self.reader.read().find(target) | |
56a092c8 | 198 | if offset == -1: |
a67882a2 | 199 | raise Exception(help_message) |
56a092c8 QM |
200 | self.reader.seek(offset) |
201 | self.reader.readline() | |
0ba3929e UA |
202 | for _ in range(discard_lines): |
203 | self.reader.readline() | |
56a092c8 QM |
204 | self.line = self.reader.readline() |
205 | ||
0ba3929e | 206 | def parse_desc_syscall(self): |
a67882a2 JS |
207 | self.seek_to('* DOC: eBPF Syscall Commands', |
208 | 'Could not find start of eBPF syscall descriptions list') | |
209 | while True: | |
210 | try: | |
211 | command = self.parse_element() | |
212 | self.commands.append(command) | |
0ba3929e UA |
213 | self.desc_syscalls.append(command.proto) |
214 | ||
a67882a2 JS |
215 | except NoSyscallCommandFound: |
216 | break | |
217 | ||
0ba3929e UA |
218 | def parse_enum_syscall(self): |
219 | self.seek_to('enum bpf_cmd {', | |
220 | 'Could not find start of bpf_cmd enum', 0) | |
221 | # Searches for either one or more BPF\w+ enums | |
121fd33b | 222 | bpf_p = re.compile(r'\s*(BPF\w+)+') |
0ba3929e UA |
223 | # Searches for an enum entry assigned to another entry, |
224 | # for e.g. BPF_PROG_RUN = BPF_PROG_TEST_RUN, which is | |
225 | # not documented hence should be skipped in check to | |
226 | # determine if the right number of syscalls are documented | |
121fd33b | 227 | assign_p = re.compile(r'\s*(BPF\w+)\s*=\s*(BPF\w+)') |
0ba3929e UA |
228 | bpf_cmd_str = '' |
229 | while True: | |
230 | capture = assign_p.match(self.line) | |
231 | if capture: | |
232 | # Skip line if an enum entry is assigned to another entry | |
233 | self.line = self.reader.readline() | |
234 | continue | |
235 | capture = bpf_p.match(self.line) | |
236 | if capture: | |
237 | bpf_cmd_str += self.line | |
238 | else: | |
239 | break | |
240 | self.line = self.reader.readline() | |
241 | # Find the number of occurences of BPF\w+ | |
121fd33b | 242 | self.enum_syscalls = re.findall(r'(BPF\w+)+', bpf_cmd_str) |
0ba3929e | 243 | |
71a3cdf8 | 244 | def parse_desc_helpers(self): |
92ec1cc3 | 245 | self.seek_to(helpersDocStart, |
a67882a2 | 246 | 'Could not find start of eBPF helper descriptions list') |
56a092c8 QM |
247 | while True: |
248 | try: | |
249 | helper = self.parse_helper() | |
250 | self.helpers.append(helper) | |
71a3cdf8 UA |
251 | proto = helper.proto_break_down() |
252 | self.desc_unique_helpers.add(proto['name']) | |
56a092c8 QM |
253 | except NoHelperFound: |
254 | break | |
255 | ||
71a3cdf8 | 256 | def parse_define_helpers(self): |
8a76145a | 257 | # Parse FN(...) in #define ___BPF_FUNC_MAPPER to compare later with the |
0a0d55ef EB |
258 | # number of unique function names present in description and use the |
259 | # correct enumeration value. | |
71a3cdf8 | 260 | # Note: seek_to(..) discards the first line below the target search text, |
8a76145a AN |
261 | # resulting in FN(unspec, 0, ##ctx) being skipped and not added to |
262 | # self.define_unique_helpers. | |
263 | self.seek_to('#define ___BPF_FUNC_MAPPER(FN, ctx...)', | |
71a3cdf8 | 264 | 'Could not find start of eBPF helper definition list') |
0a0d55ef | 265 | # Searches for one FN(\w+) define or a backslash for newline |
121fd33b | 266 | p = re.compile(r'\s*FN\((\w+), (\d+), ##ctx\)|\\\\') |
71a3cdf8 | 267 | fn_defines_str = '' |
ce3e44a0 | 268 | i = 0 |
71a3cdf8 UA |
269 | while True: |
270 | capture = p.match(self.line) | |
271 | if capture: | |
272 | fn_defines_str += self.line | |
ce3e44a0 | 273 | helper_name = capture.expand(r'bpf_\1') |
5fbea423 | 274 | self.helper_enum_vals[helper_name] = int(capture.group(2)) |
ce3e44a0 AN |
275 | self.helper_enum_pos[helper_name] = i |
276 | i += 1 | |
71a3cdf8 UA |
277 | else: |
278 | break | |
279 | self.line = self.reader.readline() | |
280 | # Find the number of occurences of FN(\w+) | |
121fd33b | 281 | self.define_unique_helpers = re.findall(r'FN\(\w+, \d+, ##ctx\)', fn_defines_str) |
71a3cdf8 | 282 | |
ce3e44a0 AN |
283 | def validate_helpers(self): |
284 | last_helper = '' | |
0a0d55ef | 285 | seen_helpers = set() |
ce3e44a0 AN |
286 | seen_enum_vals = set() |
287 | i = 0 | |
0a0d55ef EB |
288 | for helper in self.helpers: |
289 | proto = helper.proto_break_down() | |
290 | name = proto['name'] | |
291 | try: | |
292 | enum_val = self.helper_enum_vals[name] | |
ce3e44a0 | 293 | enum_pos = self.helper_enum_pos[name] |
0a0d55ef EB |
294 | except KeyError: |
295 | raise Exception("Helper %s is missing from enum bpf_func_id" % name) | |
296 | ||
ce3e44a0 AN |
297 | if name in seen_helpers: |
298 | if last_helper != name: | |
299 | raise Exception("Helper %s has multiple descriptions which are not grouped together" % name) | |
300 | continue | |
301 | ||
0a0d55ef EB |
302 | # Enforce current practice of having the descriptions ordered |
303 | # by enum value. | |
ce3e44a0 AN |
304 | if enum_pos != i: |
305 | raise Exception("Helper %s (ID %d) comment order (#%d) must be aligned with its position (#%d) in enum bpf_func_id" % (name, enum_val, i + 1, enum_pos + 1)) | |
306 | if enum_val in seen_enum_vals: | |
307 | raise Exception("Helper %s has duplicated value %d" % (name, enum_val)) | |
308 | ||
0a0d55ef | 309 | seen_helpers.add(name) |
ce3e44a0 AN |
310 | last_helper = name |
311 | seen_enum_vals.add(enum_val) | |
0a0d55ef EB |
312 | |
313 | helper.enum_val = enum_val | |
ce3e44a0 | 314 | i += 1 |
0a0d55ef | 315 | |
a67882a2 | 316 | def run(self): |
0ba3929e UA |
317 | self.parse_desc_syscall() |
318 | self.parse_enum_syscall() | |
71a3cdf8 UA |
319 | self.parse_desc_helpers() |
320 | self.parse_define_helpers() | |
ce3e44a0 | 321 | self.validate_helpers() |
56a092c8 | 322 | self.reader.close() |
56a092c8 QM |
323 | |
324 | ############################################################################### | |
325 | ||
326 | class Printer(object): | |
327 | """ | |
328 | A generic class for printers. Printers should be created with an array of | |
329 | Helper objects, and implement a way to print them in the desired fashion. | |
923a932c | 330 | @parser: A HeaderParser with objects to print to standard output |
56a092c8 | 331 | """ |
923a932c JS |
332 | def __init__(self, parser): |
333 | self.parser = parser | |
334 | self.elements = [] | |
56a092c8 QM |
335 | |
336 | def print_header(self): | |
337 | pass | |
338 | ||
339 | def print_footer(self): | |
340 | pass | |
341 | ||
342 | def print_one(self, helper): | |
343 | pass | |
344 | ||
345 | def print_all(self): | |
346 | self.print_header() | |
923a932c JS |
347 | for elem in self.elements: |
348 | self.print_one(elem) | |
56a092c8 QM |
349 | self.print_footer() |
350 | ||
0ba3929e UA |
351 | def elem_number_check(self, desc_unique_elem, define_unique_elem, type, instance): |
352 | """ | |
353 | Checks the number of helpers/syscalls documented within the header file | |
354 | description with those defined as part of enum/macro and raise an | |
355 | Exception if they don't match. | |
356 | """ | |
357 | nr_desc_unique_elem = len(desc_unique_elem) | |
358 | nr_define_unique_elem = len(define_unique_elem) | |
359 | if nr_desc_unique_elem != nr_define_unique_elem: | |
360 | exception_msg = ''' | |
361 | The number of unique %s in description (%d) doesn\'t match the number of unique %s defined in %s (%d) | |
362 | ''' % (type, nr_desc_unique_elem, type, instance, nr_define_unique_elem) | |
363 | if nr_desc_unique_elem < nr_define_unique_elem: | |
364 | # Function description is parsed until no helper is found (which can be due to | |
365 | # misformatting). Hence, only print the first missing/misformatted helper/enum. | |
366 | exception_msg += ''' | |
367 | The description for %s is not present or formatted correctly. | |
368 | ''' % (define_unique_elem[nr_desc_unique_elem]) | |
369 | raise Exception(exception_msg) | |
923a932c | 370 | |
56a092c8 QM |
371 | class PrinterRST(Printer): |
372 | """ | |
923a932c JS |
373 | A generic class for printers that print ReStructured Text. Printers should |
374 | be created with a HeaderParser object, and implement a way to print API | |
375 | elements in the desired fashion. | |
376 | @parser: A HeaderParser with objects to print to standard output | |
56a092c8 | 377 | """ |
923a932c JS |
378 | def __init__(self, parser): |
379 | self.parser = parser | |
380 | ||
381 | def print_license(self): | |
382 | license = '''\ | |
56a092c8 QM |
383 | .. Copyright (C) All BPF authors and contributors from 2014 to present. |
384 | .. See git log include/uapi/linux/bpf.h in kernel tree for details. | |
385 | .. | |
eafa9215 | 386 | .. SPDX-License-Identifier: Linux-man-pages-copyleft |
56a092c8 QM |
387 | .. |
388 | .. Please do not edit this file. It was generated from the documentation | |
389 | .. located in file include/uapi/linux/bpf.h of the Linux kernel sources | |
923a932c | 390 | .. (helpers description), and from scripts/bpf_doc.py in the same |
56a092c8 | 391 | .. repository (header and footer). |
923a932c JS |
392 | ''' |
393 | print(license) | |
394 | ||
395 | def print_elem(self, elem): | |
396 | if (elem.desc): | |
397 | print('\tDescription') | |
398 | # Do not strip all newline characters: formatted code at the end of | |
399 | # a section must be followed by a blank line. | |
400 | for line in re.sub('\n$', '', elem.desc, count=1).split('\n'): | |
401 | print('{}{}'.format('\t\t' if line else '', line)) | |
402 | ||
403 | if (elem.ret): | |
404 | print('\tReturn') | |
405 | for line in elem.ret.rstrip().split('\n'): | |
406 | print('{}{}'.format('\t\t' if line else '', line)) | |
407 | ||
408 | print('') | |
56a092c8 | 409 | |
fd0a38f9 QM |
410 | def get_kernel_version(self): |
411 | try: | |
412 | version = subprocess.run(['git', 'describe'], cwd=linuxRoot, | |
413 | capture_output=True, check=True) | |
414 | version = version.stdout.decode().rstrip() | |
415 | except: | |
416 | try: | |
417 | version = subprocess.run(['make', 'kernelversion'], cwd=linuxRoot, | |
418 | capture_output=True, check=True) | |
419 | version = version.stdout.decode().rstrip() | |
420 | except: | |
421 | return 'Linux' | |
422 | return 'Linux {version}'.format(version=version) | |
423 | ||
92ec1cc3 QM |
424 | def get_last_doc_update(self, delimiter): |
425 | try: | |
426 | cmd = ['git', 'log', '-1', '--pretty=format:%cs', '--no-patch', | |
427 | '-L', | |
121fd33b | 428 | '/{}/,/\\*\\//:include/uapi/linux/bpf.h'.format(delimiter)] |
92ec1cc3 QM |
429 | date = subprocess.run(cmd, cwd=linuxRoot, |
430 | capture_output=True, check=True) | |
431 | return date.stdout.decode().rstrip() | |
432 | except: | |
433 | return '' | |
434 | ||
923a932c JS |
435 | class PrinterHelpersRST(PrinterRST): |
436 | """ | |
437 | A printer for dumping collected information about helpers as a ReStructured | |
438 | Text page compatible with the rst2man program, which can be used to | |
439 | generate a manual page for the helpers. | |
440 | @parser: A HeaderParser with Helper objects to print to standard output | |
441 | """ | |
442 | def __init__(self, parser): | |
443 | self.elements = parser.helpers | |
8a76145a | 444 | self.elem_number_check(parser.desc_unique_helpers, parser.define_unique_helpers, 'helper', '___BPF_FUNC_MAPPER') |
923a932c JS |
445 | |
446 | def print_header(self): | |
447 | header = '''\ | |
56a092c8 QM |
448 | =========== |
449 | BPF-HELPERS | |
450 | =========== | |
451 | ------------------------------------------------------------------------------- | |
452 | list of eBPF helper functions | |
453 | ------------------------------------------------------------------------------- | |
454 | ||
455 | :Manual section: 7 | |
fd0a38f9 | 456 | :Version: {version} |
92ec1cc3 | 457 | {date_field}{date} |
56a092c8 QM |
458 | |
459 | DESCRIPTION | |
460 | =========== | |
461 | ||
462 | The extended Berkeley Packet Filter (eBPF) subsystem consists in programs | |
463 | written in a pseudo-assembly language, then attached to one of the several | |
464 | kernel hooks and run in reaction of specific events. This framework differs | |
465 | from the older, "classic" BPF (or "cBPF") in several aspects, one of them being | |
466 | the ability to call special functions (or "helpers") from within a program. | |
467 | These functions are restricted to a white-list of helpers defined in the | |
468 | kernel. | |
469 | ||
470 | These helpers are used by eBPF programs to interact with the system, or with | |
471 | the context in which they work. For instance, they can be used to print | |
472 | debugging messages, to get the time since the system was booted, to interact | |
473 | with eBPF maps, or to manipulate network packets. Since there are several eBPF | |
474 | program types, and that they do not run in the same context, each program type | |
475 | can only call a subset of those helpers. | |
476 | ||
477 | Due to eBPF conventions, a helper can not have more than five arguments. | |
478 | ||
479 | Internally, eBPF programs call directly into the compiled helper functions | |
480 | without requiring any foreign-function interface. As a result, calling helpers | |
481 | introduces no overhead, thus offering excellent performance. | |
482 | ||
483 | This document is an attempt to list and document the helpers available to eBPF | |
484 | developers. They are sorted by chronological order (the oldest helpers in the | |
485 | kernel at the top). | |
486 | ||
487 | HELPERS | |
488 | ======= | |
489 | ''' | |
fd0a38f9 | 490 | kernelVersion = self.get_kernel_version() |
92ec1cc3 | 491 | lastUpdate = self.get_last_doc_update(helpersDocStart) |
fd0a38f9 | 492 | |
923a932c | 493 | PrinterRST.print_license(self) |
92ec1cc3 QM |
494 | print(header.format(version=kernelVersion, |
495 | date_field = ':Date: ' if lastUpdate else '', | |
496 | date=lastUpdate)) | |
56a092c8 QM |
497 | |
498 | def print_footer(self): | |
499 | footer = ''' | |
500 | EXAMPLES | |
501 | ======== | |
502 | ||
503 | Example usage for most of the eBPF helpers listed in this manual page are | |
504 | available within the Linux kernel sources, at the following locations: | |
505 | ||
506 | * *samples/bpf/* | |
507 | * *tools/testing/selftests/bpf/* | |
508 | ||
509 | LICENSE | |
510 | ======= | |
511 | ||
512 | eBPF programs can have an associated license, passed along with the bytecode | |
513 | instructions to the kernel when the programs are loaded. The format for that | |
514 | string is identical to the one in use for kernel modules (Dual licenses, such | |
515 | as "Dual BSD/GPL", may be used). Some helper functions are only accessible to | |
e37243b6 | 516 | programs that are compatible with the GNU General Public License (GNU GPL). |
56a092c8 QM |
517 | |
518 | In order to use such helpers, the eBPF program must be loaded with the correct | |
121fd33b | 519 | license string passed (via **attr**) to the **bpf**\\ () system call, and this |
56a092c8 QM |
520 | generally translates into the C source code of the program containing a line |
521 | similar to the following: | |
522 | ||
523 | :: | |
524 | ||
525 | char ____license[] __attribute__((section("license"), used)) = "GPL"; | |
526 | ||
527 | IMPLEMENTATION | |
528 | ============== | |
529 | ||
530 | This manual page is an effort to document the existing eBPF helper functions. | |
531 | But as of this writing, the BPF sub-system is under heavy development. New eBPF | |
532 | program or map types are added, along with new helper functions. Some helpers | |
533 | are occasionally made available for additional program types. So in spite of | |
534 | the efforts of the community, this page might not be up-to-date. If you want to | |
535 | check by yourself what helper functions exist in your kernel, or what types of | |
536 | programs they can support, here are some files among the kernel tree that you | |
537 | may be interested in: | |
538 | ||
539 | * *include/uapi/linux/bpf.h* is the main BPF header. It contains the full list | |
540 | of all helper functions, as well as many other BPF definitions including most | |
541 | of the flags, structs or constants used by the helpers. | |
542 | * *net/core/filter.c* contains the definition of most network-related helper | |
543 | functions, and the list of program types from which they can be used. | |
544 | * *kernel/trace/bpf_trace.c* is the equivalent for most tracing program-related | |
545 | helpers. | |
546 | * *kernel/bpf/verifier.c* contains the functions used to check that valid types | |
547 | of eBPF maps are used with a given helper function. | |
548 | * *kernel/bpf/* directory contains other files in which additional helpers are | |
549 | defined (for cgroups, sockmaps, etc.). | |
ab8d7809 QM |
550 | * The bpftool utility can be used to probe the availability of helper functions |
551 | on the system (as well as supported program and map types, and a number of | |
552 | other parameters). To do so, run **bpftool feature probe** (see | |
121fd33b | 553 | **bpftool-feature**\\ (8) for details). Add the **unprivileged** keyword to |
ab8d7809 | 554 | list features available to unprivileged users. |
56a092c8 QM |
555 | |
556 | Compatibility between helper functions and program types can generally be found | |
557 | in the files where helper functions are defined. Look for the **struct | |
558 | bpf_func_proto** objects and for functions returning them: these functions | |
559 | contain a list of helpers that a given program type can call. Note that the | |
560 | **default:** label of the **switch ... case** used to filter helpers can call | |
561 | other functions, themselves allowing access to additional helpers. The | |
562 | requirement for GPL license is also in those **struct bpf_func_proto**. | |
563 | ||
564 | Compatibility between helper functions and map types can be found in the | |
121fd33b | 565 | **check_map_func_compatibility**\\ () function in file *kernel/bpf/verifier.c*. |
56a092c8 QM |
566 | |
567 | Helper functions that invalidate the checks on **data** and **data_end** | |
568 | pointers for network processing are listed in function | |
121fd33b | 569 | **bpf_helper_changes_pkt_data**\\ () in file *net/core/filter.c*. |
56a092c8 QM |
570 | |
571 | SEE ALSO | |
572 | ======== | |
573 | ||
121fd33b VC |
574 | **bpf**\\ (2), |
575 | **bpftool**\\ (8), | |
576 | **cgroups**\\ (7), | |
577 | **ip**\\ (8), | |
578 | **perf_event_open**\\ (2), | |
579 | **sendmsg**\\ (2), | |
580 | **socket**\\ (7), | |
581 | **tc-bpf**\\ (8)''' | |
56a092c8 QM |
582 | print(footer) |
583 | ||
584 | def print_proto(self, helper): | |
585 | """ | |
586 | Format function protocol with bold and italics markers. This makes RST | |
587 | file less readable, but gives nice results in the manual page. | |
588 | """ | |
589 | proto = helper.proto_break_down() | |
590 | ||
591 | print('**%s %s%s(' % (proto['ret_type'], | |
592 | proto['ret_star'].replace('*', '\\*'), | |
593 | proto['name']), | |
594 | end='') | |
595 | ||
596 | comma = '' | |
597 | for a in proto['args']: | |
598 | one_arg = '{}{}'.format(comma, a['type']) | |
599 | if a['name']: | |
600 | if a['star']: | |
121fd33b | 601 | one_arg += ' {}**\\ '.format(a['star'].replace('*', '\\*')) |
56a092c8 QM |
602 | else: |
603 | one_arg += '** ' | |
604 | one_arg += '*{}*\\ **'.format(a['name']) | |
605 | comma = ', ' | |
606 | print(one_arg, end='') | |
607 | ||
608 | print(')**') | |
609 | ||
610 | def print_one(self, helper): | |
611 | self.print_proto(helper) | |
923a932c | 612 | self.print_elem(helper) |
56a092c8 | 613 | |
56a092c8 | 614 | |
a67882a2 JS |
615 | class PrinterSyscallRST(PrinterRST): |
616 | """ | |
617 | A printer for dumping collected information about the syscall API as a | |
618 | ReStructured Text page compatible with the rst2man program, which can be | |
619 | used to generate a manual page for the syscall. | |
620 | @parser: A HeaderParser with APIElement objects to print to standard | |
621 | output | |
622 | """ | |
623 | def __init__(self, parser): | |
624 | self.elements = parser.commands | |
0ba3929e | 625 | self.elem_number_check(parser.desc_syscalls, parser.enum_syscalls, 'syscall', 'bpf_cmd') |
a67882a2 JS |
626 | |
627 | def print_header(self): | |
628 | header = '''\ | |
629 | === | |
630 | bpf | |
631 | === | |
632 | ------------------------------------------------------------------------------- | |
633 | Perform a command on an extended BPF object | |
634 | ------------------------------------------------------------------------------- | |
635 | ||
636 | :Manual section: 2 | |
637 | ||
638 | COMMANDS | |
639 | ======== | |
640 | ''' | |
641 | PrinterRST.print_license(self) | |
642 | print(header) | |
643 | ||
644 | def print_one(self, command): | |
645 | print('**%s**' % (command.proto)) | |
646 | self.print_elem(command) | |
56a092c8 | 647 | |
56a092c8 | 648 | |
7a387bed AN |
649 | class PrinterHelpers(Printer): |
650 | """ | |
651 | A printer for dumping collected information about helpers as C header to | |
652 | be included from BPF program. | |
923a932c | 653 | @parser: A HeaderParser with Helper objects to print to standard output |
7a387bed | 654 | """ |
923a932c JS |
655 | def __init__(self, parser): |
656 | self.elements = parser.helpers | |
8a76145a | 657 | self.elem_number_check(parser.desc_unique_helpers, parser.define_unique_helpers, 'helper', '___BPF_FUNC_MAPPER') |
7a387bed AN |
658 | |
659 | type_fwds = [ | |
660 | 'struct bpf_fib_lookup', | |
e9ddbb77 | 661 | 'struct bpf_sk_lookup', |
7a387bed AN |
662 | 'struct bpf_perf_event_data', |
663 | 'struct bpf_perf_event_value', | |
5996a587 | 664 | 'struct bpf_pidns_info', |
821f5c90 | 665 | 'struct bpf_redir_neigh', |
7a387bed AN |
666 | 'struct bpf_sock', |
667 | 'struct bpf_sock_addr', | |
668 | 'struct bpf_sock_ops', | |
669 | 'struct bpf_sock_tuple', | |
670 | 'struct bpf_spin_lock', | |
671 | 'struct bpf_sysctl', | |
672 | 'struct bpf_tcp_sock', | |
673 | 'struct bpf_tunnel_key', | |
674 | 'struct bpf_xfrm_state', | |
3f6719c7 | 675 | 'struct linux_binprm', |
7a387bed AN |
676 | 'struct pt_regs', |
677 | 'struct sk_reuseport_md', | |
678 | 'struct sockaddr', | |
679 | 'struct tcphdr', | |
492e639f | 680 | 'struct seq_file', |
af7ec138 | 681 | 'struct tcp6_sock', |
478cfbdf YS |
682 | 'struct tcp_sock', |
683 | 'struct tcp_timewait_sock', | |
684 | 'struct tcp_request_sock', | |
0d4fad3e | 685 | 'struct udp6_sock', |
9eeb3aa3 | 686 | 'struct unix_sock', |
fa28dcb8 | 687 | 'struct task_struct', |
c4bcfb38 | 688 | 'struct cgroup', |
7a387bed AN |
689 | |
690 | 'struct __sk_buff', | |
691 | 'struct sk_msg_md', | |
e0b68fb1 | 692 | 'struct xdp_md', |
6e22ab9d | 693 | 'struct path', |
c4d0bfb4 | 694 | 'struct btf_ptr', |
27672f0d | 695 | 'struct inode', |
4f19cab7 FR |
696 | 'struct socket', |
697 | 'struct file', | |
b00628b1 | 698 | 'struct bpf_timer', |
3bc253c2 | 699 | 'struct mptcp_sock', |
97e03f52 | 700 | 'struct bpf_dynptr', |
33bf9885 MM |
701 | 'struct iphdr', |
702 | 'struct ipv6hdr', | |
7a387bed AN |
703 | ] |
704 | known_types = { | |
705 | '...', | |
706 | 'void', | |
707 | 'const void', | |
708 | 'char', | |
709 | 'const char', | |
710 | 'int', | |
711 | 'long', | |
712 | 'unsigned long', | |
713 | ||
714 | '__be16', | |
715 | '__be32', | |
716 | '__wsum', | |
717 | ||
718 | 'struct bpf_fib_lookup', | |
719 | 'struct bpf_perf_event_data', | |
720 | 'struct bpf_perf_event_value', | |
b4490c5c | 721 | 'struct bpf_pidns_info', |
ba452c9e | 722 | 'struct bpf_redir_neigh', |
e9ddbb77 | 723 | 'struct bpf_sk_lookup', |
7a387bed AN |
724 | 'struct bpf_sock', |
725 | 'struct bpf_sock_addr', | |
726 | 'struct bpf_sock_ops', | |
727 | 'struct bpf_sock_tuple', | |
728 | 'struct bpf_spin_lock', | |
729 | 'struct bpf_sysctl', | |
730 | 'struct bpf_tcp_sock', | |
731 | 'struct bpf_tunnel_key', | |
732 | 'struct bpf_xfrm_state', | |
3f6719c7 | 733 | 'struct linux_binprm', |
7a387bed AN |
734 | 'struct pt_regs', |
735 | 'struct sk_reuseport_md', | |
736 | 'struct sockaddr', | |
737 | 'struct tcphdr', | |
492e639f | 738 | 'struct seq_file', |
af7ec138 | 739 | 'struct tcp6_sock', |
478cfbdf YS |
740 | 'struct tcp_sock', |
741 | 'struct tcp_timewait_sock', | |
742 | 'struct tcp_request_sock', | |
0d4fad3e | 743 | 'struct udp6_sock', |
9eeb3aa3 | 744 | 'struct unix_sock', |
fa28dcb8 | 745 | 'struct task_struct', |
c4bcfb38 | 746 | 'struct cgroup', |
6e22ab9d | 747 | 'struct path', |
c4d0bfb4 | 748 | 'struct btf_ptr', |
27672f0d | 749 | 'struct inode', |
4f19cab7 FR |
750 | 'struct socket', |
751 | 'struct file', | |
b00628b1 | 752 | 'struct bpf_timer', |
3bc253c2 | 753 | 'struct mptcp_sock', |
97e03f52 | 754 | 'struct bpf_dynptr', |
27060531 | 755 | 'const struct bpf_dynptr', |
33bf9885 MM |
756 | 'struct iphdr', |
757 | 'struct ipv6hdr', | |
7a387bed AN |
758 | } |
759 | mapped_types = { | |
760 | 'u8': '__u8', | |
761 | 'u16': '__u16', | |
762 | 'u32': '__u32', | |
763 | 'u64': '__u64', | |
764 | 's8': '__s8', | |
765 | 's16': '__s16', | |
766 | 's32': '__s32', | |
767 | 's64': '__s64', | |
768 | 'size_t': 'unsigned long', | |
769 | 'struct bpf_map': 'void', | |
770 | 'struct sk_buff': 'struct __sk_buff', | |
771 | 'const struct sk_buff': 'const struct __sk_buff', | |
772 | 'struct sk_msg_buff': 'struct sk_msg_md', | |
773 | 'struct xdp_buff': 'struct xdp_md', | |
774 | } | |
e9ddbb77 JS |
775 | # Helpers overloaded for different context types. |
776 | overloaded_helpers = [ | |
777 | 'bpf_get_socket_cookie', | |
778 | 'bpf_sk_assign', | |
779 | ] | |
7a387bed AN |
780 | |
781 | def print_header(self): | |
782 | header = '''\ | |
923a932c | 783 | /* This is auto-generated file. See bpf_doc.py for details. */ |
7a387bed AN |
784 | |
785 | /* Forward declarations of BPF structs */''' | |
786 | ||
787 | print(header) | |
788 | for fwd in self.type_fwds: | |
789 | print('%s;' % fwd) | |
790 | print('') | |
791 | ||
792 | def print_footer(self): | |
793 | footer = '' | |
794 | print(footer) | |
795 | ||
796 | def map_type(self, t): | |
797 | if t in self.known_types: | |
798 | return t | |
799 | if t in self.mapped_types: | |
800 | return self.mapped_types[t] | |
ab81e203 JS |
801 | print("Unrecognized type '%s', please add it to known types!" % t, |
802 | file=sys.stderr) | |
7a387bed AN |
803 | sys.exit(1) |
804 | ||
805 | seen_helpers = set() | |
806 | ||
807 | def print_one(self, helper): | |
808 | proto = helper.proto_break_down() | |
809 | ||
810 | if proto['name'] in self.seen_helpers: | |
811 | return | |
812 | self.seen_helpers.add(proto['name']) | |
813 | ||
814 | print('/*') | |
815 | print(" * %s" % proto['name']) | |
816 | print(" *") | |
817 | if (helper.desc): | |
818 | # Do not strip all newline characters: formatted code at the end of | |
819 | # a section must be followed by a blank line. | |
820 | for line in re.sub('\n$', '', helper.desc, count=1).split('\n'): | |
821 | print(' *{}{}'.format(' \t' if line else '', line)) | |
822 | ||
823 | if (helper.ret): | |
824 | print(' *') | |
825 | print(' * Returns') | |
826 | for line in helper.ret.rstrip().split('\n'): | |
827 | print(' *{}{}'.format(' \t' if line else '', line)) | |
828 | ||
829 | print(' */') | |
ff2071a7 | 830 | print('static %s %s(* const %s)(' % (self.map_type(proto['ret_type']), |
7a387bed AN |
831 | proto['ret_star'], proto['name']), end='') |
832 | comma = '' | |
833 | for i, a in enumerate(proto['args']): | |
834 | t = a['type'] | |
835 | n = a['name'] | |
e9ddbb77 | 836 | if proto['name'] in self.overloaded_helpers and i == 0: |
7a387bed AN |
837 | t = 'void' |
838 | n = 'ctx' | |
839 | one_arg = '{}{}'.format(comma, self.map_type(t)) | |
840 | if n: | |
841 | if a['star']: | |
842 | one_arg += ' {}'.format(a['star']) | |
843 | else: | |
844 | one_arg += ' ' | |
845 | one_arg += '{}'.format(n) | |
846 | comma = ', ' | |
847 | print(one_arg, end='') | |
848 | ||
0a0d55ef | 849 | print(') = (void *) %d;' % helper.enum_val) |
7a387bed AN |
850 | print('') |
851 | ||
56a092c8 QM |
852 | ############################################################################### |
853 | ||
854 | # If script is launched from scripts/ from kernel tree and can access | |
855 | # ../include/uapi/linux/bpf.h, use it as a default name for the file to parse, | |
856 | # otherwise the --filename argument will be required from the command line. | |
857 | script = os.path.abspath(sys.argv[0]) | |
858 | linuxRoot = os.path.dirname(os.path.dirname(script)) | |
859 | bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h') | |
860 | ||
923a932c JS |
861 | printers = { |
862 | 'helpers': PrinterHelpersRST, | |
a67882a2 | 863 | 'syscall': PrinterSyscallRST, |
923a932c JS |
864 | } |
865 | ||
56a092c8 | 866 | argParser = argparse.ArgumentParser(description=""" |
923a932c | 867 | Parse eBPF header file and generate documentation for the eBPF API. |
56a092c8 QM |
868 | The RST-formatted output produced can be turned into a manual page with the |
869 | rst2man utility. | |
870 | """) | |
7a387bed AN |
871 | argParser.add_argument('--header', action='store_true', |
872 | help='generate C header file') | |
56a092c8 QM |
873 | if (os.path.isfile(bpfh)): |
874 | argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h', | |
875 | default=bpfh) | |
876 | else: | |
877 | argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h') | |
923a932c JS |
878 | argParser.add_argument('target', nargs='?', default='helpers', |
879 | choices=printers.keys(), help='eBPF API target') | |
56a092c8 QM |
880 | args = argParser.parse_args() |
881 | ||
882 | # Parse file. | |
883 | headerParser = HeaderParser(args.filename) | |
884 | headerParser.run() | |
885 | ||
886 | # Print formatted output to standard output. | |
7a387bed | 887 | if args.header: |
a67882a2 JS |
888 | if args.target != 'helpers': |
889 | raise NotImplementedError('Only helpers header generation is supported') | |
923a932c | 890 | printer = PrinterHelpers(headerParser) |
7a387bed | 891 | else: |
923a932c | 892 | printer = printers[args.target](headerParser) |
56a092c8 | 893 | printer.print_all() |