scripts/bpf_doc.py

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