History

scripts/bpf: Abstract eBPF API target parameter

Abstract out the target parameter so that upcoming commits, more than just the existing "helpers" target can be called to generate specific portions of docs from the eBPF UAPI headers.

Joe Stringer committed 5 years ago

Commit 923a9321 parent 0cb80457 files · +69 −33Browse files

Showing the changes to scripts (1 of 7 files). Show all

Unified · Split

scripts/bpf_doc.pyrenamed from scripts/bpf_helpers_doc.py+63−28
@@ -2,6 +2,7 @@ · 1 unmodified line
22 # SPDX-License-Identifier: GPL-2.0-only
33 #
44 # Copyright (C) 2018-2019 Netronome Systems, Inc.
5+# Copyright (C) 2021 Isovalent, Inc.
56
67 # In case user attempts to run with Python 2.
78 from __future__ import print_function
@@ -165,10 +166,11 @@ class Printer(object): · 157 unmodified lines
165166 """
166167 A generic class for printers. Printers should be created with an array of
167168 Helper objects, and implement a way to print them in the desired fashion.
168− @helpers: array of Helper objects to print to standard output
169+ @parser: A HeaderParser with objects to print to standard output
169170 """
170− def __init__(self, helpers):
171− self.helpers = helpers
171+ def __init__(self, parser):
172+ self.parser = parser
173+ self.elements = []
172174
173175 def print_header(self):
174176 pass
@@ -181,19 +183,23 @@ class Printer(object): · 6 unmodified lines
181183
182184 def print_all(self):
183185 self.print_header()
184− for helper in self.helpers:
185− self.print_one(helper)
186+ for elem in self.elements:
187+ self.print_one(elem)
186188 self.print_footer()
187189
190+
188191 class PrinterRST(Printer):
189192 """
190− A printer for dumping collected information about helpers as a ReStructured
191− Text page compatible with the rst2man program, which can be used to
192− generate a manual page for the helpers.
193− @helpers: array of Helper objects to print to standard output
193+ A generic class for printers that print ReStructured Text. Printers should
194+ be created with a HeaderParser object, and implement a way to print API
195+ elements in the desired fashion.
196+ @parser: A HeaderParser with objects to print to standard output
194197 """
195− def print_header(self):
196− header = '''\
198+ def __init__(self, parser):
199+ self.parser = parser
200+
201+ def print_license(self):
202+ license = '''\
197203 .. Copyright (C) All BPF authors and contributors from 2014 to present.
198204 .. See git log include/uapi/linux/bpf.h in kernel tree for details.
199205 ..
@@ -221,9 +227,39 @@ class PrinterRST(Printer): · 21 unmodified lines
221227 ..
222228 .. Please do not edit this file. It was generated from the documentation
223229 .. located in file include/uapi/linux/bpf.h of the Linux kernel sources
224−.. (helpers description), and from scripts/bpf_helpers_doc.py in the same
230+.. (helpers description), and from scripts/bpf_doc.py in the same
225231 .. repository (header and footer).
232+'''
233+ print(license)
234+
235+ def print_elem(self, elem):
236+ if (elem.desc):
237+ print('\tDescription')
238+ # Do not strip all newline characters: formatted code at the end of
239+ # a section must be followed by a blank line.
240+ for line in re.sub('\n$', '', elem.desc, count=1).split('\n'):
241+ print('{}{}'.format('\t\t' if line else '', line))
242+
243+ if (elem.ret):
244+ print('\tReturn')
245+ for line in elem.ret.rstrip().split('\n'):
246+ print('{}{}'.format('\t\t' if line else '', line))
247+
248+ print('')
226249
250+
251+class PrinterHelpersRST(PrinterRST):
252+ """
253+ A printer for dumping collected information about helpers as a ReStructured
254+ Text page compatible with the rst2man program, which can be used to
255+ generate a manual page for the helpers.
256+ @parser: A HeaderParser with Helper objects to print to standard output
257+ """
258+ def __init__(self, parser):
259+ self.elements = parser.helpers
260+
261+ def print_header(self):
262+ header = '''\
227263 ===========
228264 BPF-HELPERS
229265 ===========
@@ -264,6 +300,7 @@ kernel at the top). · 34 unmodified lines
264300 HELPERS
265301 =======
266302 '''
303+ PrinterRST.print_license(self)
267304 print(header)
268305
269306 def print_footer(self):
@@ -380,27 +417,19 @@ SEE ALSO · 110 unmodified lines
380417
381418 def print_one(self, helper):
382419 self.print_proto(helper)
420+ self.print_elem(helper)
383421
384− if (helper.desc):
385− print('\tDescription')
386− # Do not strip all newline characters: formatted code at the end of
387− # a section must be followed by a blank line.
388− for line in re.sub('\n$', '', helper.desc, count=1).split('\n'):
389− print('{}{}'.format('\t\t' if line else '', line))
390422
391− if (helper.ret):
392− print('\tReturn')
393− for line in helper.ret.rstrip().split('\n'):
394− print('{}{}'.format('\t\t' if line else '', line))
395423
396− print('')
397424
398425 class PrinterHelpers(Printer):
399426 """
400427 A printer for dumping collected information about helpers as C header to
401428 be included from BPF program.
402− @helpers: array of Helper objects to print to standard output
429+ @parser: A HeaderParser with Helper objects to print to standard output
403430 """
431+ def __init__(self, parser):
432+ self.elements = parser.helpers
404433
405434 type_fwds = [
406435 'struct bpf_fib_lookup',
@@ -511,7 +540,7 @@ class PrinterHelpers(Printer): · 104 unmodified lines
511540
512541 def print_header(self):
513542 header = '''\
514−/* This is auto-generated file. See bpf_helpers_doc.py for details. */
543+/* This is auto-generated file. See bpf_doc.py for details. */
515544
516545 /* Forward declarations of BPF structs */'''
517546
@@ -589,8 +618,12 @@ script = os.path.abspath(sys.argv[0]) · 71 unmodified lines
589618 linuxRoot = os.path.dirname(os.path.dirname(script))
590619 bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h')
591620
621+printers = {
622+ 'helpers': PrinterHelpersRST,
623+}
624+
592625 argParser = argparse.ArgumentParser(description="""
593−Parse eBPF header file and generate documentation for eBPF helper functions.
626+Parse eBPF header file and generate documentation for the eBPF API.
594627 The RST-formatted output produced can be turned into a manual page with the
595628 rst2man utility.
596629 """)
@@ -601,6 +634,8 @@ if (os.path.isfile(bpfh)): · 4 unmodified lines
601634 default=bpfh)
602635 else:
603636 argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h')
637+argParser.add_argument('target', nargs='?', default='helpers',
638+ choices=printers.keys(), help='eBPF API target')
604639 args = argParser.parse_args()
605640
606641 # Parse file.
@@ -609,7 +644,7 @@ headerParser.run() · 2 unmodified lines
609644
610645 # Print formatted output to standard output.
611646 if args.header:
612− printer = PrinterHelpers(headerParser.helpers)
647+ printer = PrinterHelpers(headerParser)
613648 else:
614− printer = PrinterRST(headerParser.helpers)
649+ printer = printers[args.target](headerParser)
615650 printer.print_all()