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