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