@@ -2,6 +2,7 @@
# SPDX-License-Identifier: GPL-2.0-only
#
# Copyright (C) 2018-2019 Netronome Systems, Inc.
+# Copyright (C) 2021 Isovalent, Inc.
# In case user attempts to run with Python 2.
from __future__ import print_function
@@ -165,10 +166,11 @@ class Printer(object):
"""
A generic class for printers. Printers should be created with an array of
Helper objects, and implement a way to print them in the desired fashion.
- @helpers: array of Helper objects to print to standard output
+ @parser: A HeaderParser with objects to print to standard output
"""
- def __init__(self, helpers):
- self.helpers = helpers
+ def __init__(self, parser):
+ self.parser = parser
+ self.elements = []
def print_header(self):
pass
@@ -181,19 +183,23 @@ class Printer(object):
def print_all(self):
self.print_header()
- for helper in self.helpers:
- self.print_one(helper)
+ for elem in self.elements:
+ self.print_one(elem)
self.print_footer()
+
class PrinterRST(Printer):
"""
- A printer for dumping collected information about helpers as a ReStructured
- Text page compatible with the rst2man program, which can be used to
- generate a manual page for the helpers.
- @helpers: array of Helper objects to print to standard output
+ A generic class for printers that print ReStructured Text. Printers should
+ be created with a HeaderParser object, and implement a way to print API
+ elements in the desired fashion.
+ @parser: A HeaderParser with objects to print to standard output
"""
- def print_header(self):
- header = '''\
+ def __init__(self, parser):
+ self.parser = parser
+
+ def print_license(self):
+ license = '''\
.. Copyright (C) All BPF authors and contributors from 2014 to present.
.. See git log include/uapi/linux/bpf.h in kernel tree for details.
..
@@ -223,7 +229,37 @@ class PrinterRST(Printer):
.. located in file include/uapi/linux/bpf.h of the Linux kernel sources
.. (helpers description), and from scripts/bpf_doc.py in the same
.. repository (header and footer).
+'''
+ print(license)
+
+ def print_elem(self, elem):
+ if (elem.desc):
+ print('\tDescription')
+ # Do not strip all newline characters: formatted code at the end of
+ # a section must be followed by a blank line.
+ for line in re.sub('\n$', '', elem.desc, count=1).split('\n'):
+ print('{}{}'.format('\t\t' if line else '', line))
+
+ if (elem.ret):
+ print('\tReturn')
+ for line in elem.ret.rstrip().split('\n'):
+ print('{}{}'.format('\t\t' if line else '', line))
+
+ print('')
+
+class PrinterHelpersRST(PrinterRST):
+ """
+ A printer for dumping collected information about helpers as a ReStructured
+ Text page compatible with the rst2man program, which can be used to
+ generate a manual page for the helpers.
+ @parser: A HeaderParser with Helper objects to print to standard output
+ """
+ def __init__(self, parser):
+ self.elements = parser.helpers
+
+ def print_header(self):
+ header = '''\
===========
BPF-HELPERS
===========
@@ -264,6 +300,7 @@ kernel at the top).
HELPERS
=======
'''
+ PrinterRST.print_license(self)
print(header)
def print_footer(self):
@@ -380,27 +417,19 @@ SEE ALSO
def print_one(self, helper):
self.print_proto(helper)
+ self.print_elem(helper)
- if (helper.desc):
- print('\tDescription')
- # Do not strip all newline characters: formatted code at the end of
- # a section must be followed by a blank line.
- for line in re.sub('\n$', '', helper.desc, count=1).split('\n'):
- print('{}{}'.format('\t\t' if line else '', line))
- if (helper.ret):
- print('\tReturn')
- for line in helper.ret.rstrip().split('\n'):
- print('{}{}'.format('\t\t' if line else '', line))
- print('')
class PrinterHelpers(Printer):
"""
A printer for dumping collected information about helpers as C header to
be included from BPF program.
- @helpers: array of Helper objects to print to standard output
+ @parser: A HeaderParser with Helper objects to print to standard output
"""
+ def __init__(self, parser):
+ self.elements = parser.helpers
type_fwds = [
'struct bpf_fib_lookup',
@@ -589,8 +618,12 @@ script = os.path.abspath(sys.argv[0])
linuxRoot = os.path.dirname(os.path.dirname(script))
bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h')
+printers = {
+ 'helpers': PrinterHelpersRST,
+}
+
argParser = argparse.ArgumentParser(description="""
-Parse eBPF header file and generate documentation for eBPF helper functions.
+Parse eBPF header file and generate documentation for the eBPF API.
The RST-formatted output produced can be turned into a manual page with the
rst2man utility.
""")
@@ -601,6 +634,8 @@ if (os.path.isfile(bpfh)):
default=bpfh)
else:
argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h')
+argParser.add_argument('target', nargs='?', default='helpers',
+ choices=printers.keys(), help='eBPF API target')
args = argParser.parse_args()
# Parse file.
@@ -609,7 +644,7 @@ headerParser.run()
# Print formatted output to standard output.
if args.header:
- printer = PrinterHelpers(headerParser.helpers)
+ printer = PrinterHelpers(headerParser)
else:
- printer = PrinterRST(headerParser.helpers)
+ printer = printers[args.target](headerParser)
printer.print_all()