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