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