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() 873