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