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(r'((\w+ )*?(\w+|...))( (\**)(\w+))?$') 63 res = {} 64 proto_re = re.compile(r'(.+) (\**)(\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.helper_enum_pos = {} 101 self.desc_syscalls = [] 102 self.enum_syscalls = [] 103 104 def parse_element(self): 105 proto = self.parse_symbol() 106 desc = self.parse_desc(proto) 107 ret = self.parse_ret(proto) 108 return APIElement(proto=proto, desc=desc, ret=ret) 109 110 def parse_helper(self): 111 proto = self.parse_proto() 112 desc = self.parse_desc(proto) 113 ret = self.parse_ret(proto) 114 return Helper(proto=proto, desc=desc, ret=ret) 115 116 def parse_symbol(self): 117 p = re.compile(r' \* ?(BPF\w+)$') 118 capture = p.match(self.line) 119 if not capture: 120 raise NoSyscallCommandFound 121 end_re = re.compile(r' \* ?NOTES$') 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 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. 136 p = re.compile(r' \* ?((.+) \**\w+\((((const )?(struct )?(\w+|\.\.\.)( \**\w+)?)(, )?){1,5}\))$') 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 143 def parse_desc(self, proto): 144 p = re.compile(r' \* ?(?:\t| {5,8})Description$') 145 capture = p.match(self.line) 146 if not capture: 147 raise Exception("No description section found for " + proto) 148 # Description can be several lines, some of them possibly empty, and it 149 # stops when another subsection title is met. 150 desc = '' 151 desc_present = False 152 while True: 153 self.line = self.reader.readline() 154 if self.line == ' *\n': 155 desc += '\n' 156 else: 157 p = re.compile(r' \* ?(?:\t| {5,8})(?:\t| {8})(.*)') 158 capture = p.match(self.line) 159 if capture: 160 desc_present = True 161 desc += capture.group(1) + '\n' 162 else: 163 break 164 165 if not desc_present: 166 raise Exception("No description found for " + proto) 167 return desc 168 169 def parse_ret(self, proto): 170 p = re.compile(r' \* ?(?:\t| {5,8})Return$') 171 capture = p.match(self.line) 172 if not capture: 173 raise Exception("No return section found for " + proto) 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 = '' 177 ret_present = False 178 while True: 179 self.line = self.reader.readline() 180 if self.line == ' *\n': 181 ret += '\n' 182 else: 183 p = re.compile(r' \* ?(?:\t| {5,8})(?:\t| {8})(.*)') 184 capture = p.match(self.line) 185 if capture: 186 ret_present = True 187 ret += capture.group(1) + '\n' 188 else: 189 break 190 191 if not ret_present: 192 raise Exception("No return found for " + proto) 193 return ret 194 195 def seek_to(self, target, help_message, discard_lines = 1): 196 self.reader.seek(0) 197 offset = self.reader.read().find(target) 198 if offset == -1: 199 raise Exception(help_message) 200 self.reader.seek(offset) 201 self.reader.readline() 202 for _ in range(discard_lines): 203 self.reader.readline() 204 self.line = self.reader.readline() 205 206 def parse_desc_syscall(self): 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) 213 self.desc_syscalls.append(command.proto) 214 215 except NoSyscallCommandFound: 216 break 217 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 222 bpf_p = re.compile(r'\s*(BPF\w+)+') 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 227 assign_p = re.compile(r'\s*(BPF\w+)\s*=\s*(BPF\w+)') 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+ 242 self.enum_syscalls = re.findall(r'(BPF\w+)+', bpf_cmd_str) 243 244 def parse_desc_helpers(self): 245 self.seek_to(helpersDocStart, 246 'Could not find start of eBPF helper descriptions list') 247 while True: 248 try: 249 helper = self.parse_helper() 250 self.helpers.append(helper) 251 proto = helper.proto_break_down() 252 self.desc_unique_helpers.add(proto['name']) 253 except NoHelperFound: 254 break 255 256 def parse_define_helpers(self): 257 # Parse FN(...) in #define ___BPF_FUNC_MAPPER to compare later with the 258 # number of unique function names present in description and use the 259 # correct enumeration value. 260 # Note: seek_to(..) discards the first line below the target search text, 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...)', 264 'Could not find start of eBPF helper definition list') 265 # Searches for one FN(\w+) define or a backslash for newline 266 p = re.compile(r'\s*FN\((\w+), (\d+), ##ctx\)|\\\\') 267 fn_defines_str = '' 268 i = 0 269 while True: 270 capture = p.match(self.line) 271 if capture: 272 fn_defines_str += self.line 273 helper_name = capture.expand(r'bpf_\1') 274 self.helper_enum_vals[helper_name] = int(capture.group(2)) 275 self.helper_enum_pos[helper_name] = i 276 i += 1 277 else: 278 break 279 self.line = self.reader.readline() 280 # Find the number of occurences of FN(\w+) 281 self.define_unique_helpers = re.findall(r'FN\(\w+, \d+, ##ctx\)', fn_defines_str) 282 283 def validate_helpers(self): 284 last_helper = '' 285 seen_helpers = set() 286 seen_enum_vals = set() 287 i = 0 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] 293 enum_pos = self.helper_enum_pos[name] 294 except KeyError: 295 raise Exception("Helper %s is missing from enum bpf_func_id" % name) 296 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 302 # Enforce current practice of having the descriptions ordered 303 # by enum value. 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 309 seen_helpers.add(name) 310 last_helper = name 311 seen_enum_vals.add(enum_val) 312 313 helper.enum_val = enum_val 314 i += 1 315 316 def run(self): 317 self.parse_desc_syscall() 318 self.parse_enum_syscall() 319 self.parse_desc_helpers() 320 self.parse_define_helpers() 321 self.validate_helpers() 322 self.reader.close() 323 324############################################################################### 325 326class 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. 330 @parser: A HeaderParser with objects to print to standard output 331 """ 332 def __init__(self, parser): 333 self.parser = parser 334 self.elements = [] 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() 347 for elem in self.elements: 348 self.print_one(elem) 349 self.print_footer() 350 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 = ''' 361The 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 += ''' 367The description for %s is not present or formatted correctly. 368''' % (define_unique_elem[nr_desc_unique_elem]) 369 raise Exception(exception_msg) 370 371class PrinterRST(Printer): 372 """ 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 377 """ 378 def __init__(self, parser): 379 self.parser = parser 380 381 def print_license(self): 382 license = '''\ 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.. 386.. SPDX-License-Identifier: Linux-man-pages-copyleft 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 390.. (helpers description), and from scripts/bpf_doc.py in the same 391.. repository (header and footer). 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('') 409 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 424 def get_last_doc_update(self, delimiter): 425 try: 426 cmd = ['git', 'log', '-1', '--pretty=format:%cs', '--no-patch', 427 '-L', 428 '/{}/,/\\*\\//:include/uapi/linux/bpf.h'.format(delimiter)] 429 date = subprocess.run(cmd, cwd=linuxRoot, 430 capture_output=True, check=True) 431 return date.stdout.decode().rstrip() 432 except: 433 return '' 434 435class 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 444 self.elem_number_check(parser.desc_unique_helpers, parser.define_unique_helpers, 'helper', '___BPF_FUNC_MAPPER') 445 446 def print_header(self): 447 header = '''\ 448=========== 449BPF-HELPERS 450=========== 451------------------------------------------------------------------------------- 452list of eBPF helper functions 453------------------------------------------------------------------------------- 454 455:Manual section: 7 456:Version: {version} 457{date_field}{date} 458 459DESCRIPTION 460=========== 461 462The extended Berkeley Packet Filter (eBPF) subsystem consists in programs 463written in a pseudo-assembly language, then attached to one of the several 464kernel hooks and run in reaction of specific events. This framework differs 465from the older, "classic" BPF (or "cBPF") in several aspects, one of them being 466the ability to call special functions (or "helpers") from within a program. 467These functions are restricted to a white-list of helpers defined in the 468kernel. 469 470These helpers are used by eBPF programs to interact with the system, or with 471the context in which they work. For instance, they can be used to print 472debugging messages, to get the time since the system was booted, to interact 473with eBPF maps, or to manipulate network packets. Since there are several eBPF 474program types, and that they do not run in the same context, each program type 475can only call a subset of those helpers. 476 477Due to eBPF conventions, a helper can not have more than five arguments. 478 479Internally, eBPF programs call directly into the compiled helper functions 480without requiring any foreign-function interface. As a result, calling helpers 481introduces no overhead, thus offering excellent performance. 482 483This document is an attempt to list and document the helpers available to eBPF 484developers. They are sorted by chronological order (the oldest helpers in the 485kernel at the top). 486 487HELPERS 488======= 489''' 490 kernelVersion = self.get_kernel_version() 491 lastUpdate = self.get_last_doc_update(helpersDocStart) 492 493 PrinterRST.print_license(self) 494 print(header.format(version=kernelVersion, 495 date_field = ':Date: ' if lastUpdate else '', 496 date=lastUpdate)) 497 498 def print_footer(self): 499 footer = ''' 500EXAMPLES 501======== 502 503Example usage for most of the eBPF helpers listed in this manual page are 504available within the Linux kernel sources, at the following locations: 505 506* *samples/bpf/* 507* *tools/testing/selftests/bpf/* 508 509LICENSE 510======= 511 512eBPF programs can have an associated license, passed along with the bytecode 513instructions to the kernel when the programs are loaded. The format for that 514string is identical to the one in use for kernel modules (Dual licenses, such 515as "Dual BSD/GPL", may be used). Some helper functions are only accessible to 516programs that are compatible with the GNU Privacy License (GPL). 517 518In order to use such helpers, the eBPF program must be loaded with the correct 519license string passed (via **attr**) to the **bpf**\\ () system call, and this 520generally translates into the C source code of the program containing a line 521similar to the following: 522 523:: 524 525 char ____license[] __attribute__((section("license"), used)) = "GPL"; 526 527IMPLEMENTATION 528============== 529 530This manual page is an effort to document the existing eBPF helper functions. 531But as of this writing, the BPF sub-system is under heavy development. New eBPF 532program or map types are added, along with new helper functions. Some helpers 533are occasionally made available for additional program types. So in spite of 534the efforts of the community, this page might not be up-to-date. If you want to 535check by yourself what helper functions exist in your kernel, or what types of 536programs they can support, here are some files among the kernel tree that you 537may 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.). 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 553 **bpftool-feature**\\ (8) for details). Add the **unprivileged** keyword to 554 list features available to unprivileged users. 555 556Compatibility between helper functions and program types can generally be found 557in the files where helper functions are defined. Look for the **struct 558bpf_func_proto** objects and for functions returning them: these functions 559contain 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 561other functions, themselves allowing access to additional helpers. The 562requirement for GPL license is also in those **struct bpf_func_proto**. 563 564Compatibility between helper functions and map types can be found in the 565**check_map_func_compatibility**\\ () function in file *kernel/bpf/verifier.c*. 566 567Helper functions that invalidate the checks on **data** and **data_end** 568pointers for network processing are listed in function 569**bpf_helper_changes_pkt_data**\\ () in file *net/core/filter.c*. 570 571SEE ALSO 572======== 573 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)''' 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']: 601 one_arg += ' {}**\\ '.format(a['star'].replace('*', '\\*')) 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) 612 self.print_elem(helper) 613 614 615class 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 625 self.elem_number_check(parser.desc_syscalls, parser.enum_syscalls, 'syscall', 'bpf_cmd') 626 627 def print_header(self): 628 header = '''\ 629=== 630bpf 631=== 632------------------------------------------------------------------------------- 633Perform a command on an extended BPF object 634------------------------------------------------------------------------------- 635 636:Manual section: 2 637 638COMMANDS 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) 647 648 649class PrinterHelpers(Printer): 650 """ 651 A printer for dumping collected information about helpers as C header to 652 be included from BPF program. 653 @parser: A HeaderParser with Helper objects to print to standard output 654 """ 655 def __init__(self, parser): 656 self.elements = parser.helpers 657 self.elem_number_check(parser.desc_unique_helpers, parser.define_unique_helpers, 'helper', '___BPF_FUNC_MAPPER') 658 659 type_fwds = [ 660 'struct bpf_fib_lookup', 661 'struct bpf_sk_lookup', 662 'struct bpf_perf_event_data', 663 'struct bpf_perf_event_value', 664 'struct bpf_pidns_info', 665 'struct bpf_redir_neigh', 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', 675 'struct linux_binprm', 676 'struct pt_regs', 677 'struct sk_reuseport_md', 678 'struct sockaddr', 679 'struct tcphdr', 680 'struct seq_file', 681 'struct tcp6_sock', 682 'struct tcp_sock', 683 'struct tcp_timewait_sock', 684 'struct tcp_request_sock', 685 'struct udp6_sock', 686 'struct unix_sock', 687 'struct task_struct', 688 'struct cgroup', 689 690 'struct __sk_buff', 691 'struct sk_msg_md', 692 'struct xdp_md', 693 'struct path', 694 'struct btf_ptr', 695 'struct inode', 696 'struct socket', 697 'struct file', 698 'struct bpf_timer', 699 'struct mptcp_sock', 700 'struct bpf_dynptr', 701 'struct iphdr', 702 'struct ipv6hdr', 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', 721 'struct bpf_pidns_info', 722 'struct bpf_redir_neigh', 723 'struct bpf_sk_lookup', 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', 733 'struct linux_binprm', 734 'struct pt_regs', 735 'struct sk_reuseport_md', 736 'struct sockaddr', 737 'struct tcphdr', 738 'struct seq_file', 739 'struct tcp6_sock', 740 'struct tcp_sock', 741 'struct tcp_timewait_sock', 742 'struct tcp_request_sock', 743 'struct udp6_sock', 744 'struct unix_sock', 745 'struct task_struct', 746 'struct cgroup', 747 'struct path', 748 'struct btf_ptr', 749 'struct inode', 750 'struct socket', 751 'struct file', 752 'struct bpf_timer', 753 'struct mptcp_sock', 754 'struct bpf_dynptr', 755 'const struct bpf_dynptr', 756 'struct iphdr', 757 'struct ipv6hdr', 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 } 775 # Helpers overloaded for different context types. 776 overloaded_helpers = [ 777 'bpf_get_socket_cookie', 778 'bpf_sk_assign', 779 ] 780 781 def print_header(self): 782 header = '''\ 783/* This is auto-generated file. See bpf_doc.py for details. */ 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] 801 print("Unrecognized type '%s', please add it to known types!" % t, 802 file=sys.stderr) 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(' */') 830 print('static %s %s(*%s)(' % (self.map_type(proto['ret_type']), 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'] 836 if proto['name'] in self.overloaded_helpers and i == 0: 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 849 print(') = (void *) %d;' % helper.enum_val) 850 print('') 851 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. 857script = os.path.abspath(sys.argv[0]) 858linuxRoot = os.path.dirname(os.path.dirname(script)) 859bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h') 860 861printers = { 862 'helpers': PrinterHelpersRST, 863 'syscall': PrinterSyscallRST, 864} 865 866argParser = argparse.ArgumentParser(description=""" 867Parse eBPF header file and generate documentation for the eBPF API. 868The RST-formatted output produced can be turned into a manual page with the 869rst2man utility. 870""") 871argParser.add_argument('--header', action='store_true', 872 help='generate C header file') 873if (os.path.isfile(bpfh)): 874 argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h', 875 default=bpfh) 876else: 877 argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h') 878argParser.add_argument('target', nargs='?', default='helpers', 879 choices=printers.keys(), help='eBPF API target') 880args = argParser.parse_args() 881 882# Parse file. 883headerParser = HeaderParser(args.filename) 884headerParser.run() 885 886# Print formatted output to standard output. 887if args.header: 888 if args.target != 'helpers': 889 raise NotImplementedError('Only helpers header generation is supported') 890 printer = PrinterHelpers(headerParser) 891else: 892 printer = printers[args.target](headerParser) 893printer.print_all() 894