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

Unified · Split

7 files

MAINTAINERS +1 −0
include/uapi/linux/bpf.h +1 −1
scripts/bpf_doc.py +63 −28
tools/bpf/Makefile.helpers +1 −1
tools/include/uapi/linux/bpf.h +1 −1
tools/lib/bpf/Makefile +1 −1
tools/perf/MANIFEST +1 −1

MAINTAINERS+1−0

@@ -3223,6 +3223,7 @@ F: net/core/filter.c · 3222 unmodified lines
3223	F: net/sched/act_bpf.c	3223	F: net/sched/act_bpf.c
3224	F: net/sched/cls_bpf.c	3224	F: net/sched/cls_bpf.c
3225	F: samples/bpf/	3225	F: samples/bpf/
		3226	F: scripts/bpf_doc.py
3226	F: tools/bpf/	3227	F: tools/bpf/
3227	F: tools/lib/bpf/	3228	F: tools/lib/bpf/
3228	F: tools/testing/selftests/bpf/	3229	F: tools/testing/selftests/bpf/

include/uapi/linux/bpf.h+1−1

@@ -1439,7 +1439,7 @@ union bpf_attr { · 1438 unmodified lines
1439	* parsed and used to produce a manual page. The workflow is the following,	1439	* parsed and used to produce a manual page. The workflow is the following,
1440	* and requires the rst2man utility:	1440	* and requires the rst2man utility:
1441	*	1441	*
1442	* $ ./scripts/bpf_helpers_doc.py \	1442	* $ ./scripts/bpf_doc.py \
1443	* --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst	1443	* --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst
1444	* $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7	1444	* $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7
1445	* $ man /tmp/bpf-helpers.7	1445	* $ man /tmp/bpf-helpers.7

scripts/bpf_doc.pyrenamed from scripts/bpf_helpers_doc.py+63−28

 # 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
     """
     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):
+    def __init__(self, parser):
-        self.helpers = helpers
+        self.parser = parser
+        self.elements = []
     def print_header(self):
         pass
     def print_all(self):
         self.print_header()
-        for helper in self.helpers:
+        for elem in self.elements:
-            self.print_one(helper)
+            self.print_one(elem)
         self.print_footer()
 class PrinterRST(Printer):
     """
-    A printer for dumping collected information about helpers as a ReStructured
+    A generic class for printers that print ReStructured Text. Printers should
-    Text page compatible with the rst2man program, which can be used to
+    be created with a HeaderParser object, and implement a way to print API
-    generate a manual page for the helpers.
+    elements 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 print_header(self):
+    def __init__(self, parser):
-        header = '''\
+        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.
 ..
 ..
 .. Please do not edit this file. It was generated from the documentation
 .. located in file include/uapi/linux/bpf.h of the Linux kernel sources
-.. (helpers description), and from scripts/bpf_helpers_doc.py in the same
+.. (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
 ===========
 HELPERS
 =======
 '''
+        PrinterRST.print_license(self)
         print(header)
     def print_footer(self):
     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',
     def print_header(self):
         header = '''\
-/* This is auto-generated file. See bpf_helpers_doc.py for details. */
+/* This is auto-generated file. See bpf_doc.py for details. */
 /* Forward declarations of BPF structs */'''
 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.
 """)
                            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.
 # 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()

tools/bpf/Makefile.helpers+1−1

@@ -35,7 +35,7 @@ man7: $(DOC_MAN7) · 34 unmodified lines
35	RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null)	35	RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null)
36		36
37	$(OUTPUT)$(HELPERS_RST): $(UP2DIR)../../include/uapi/linux/bpf.h	37	$(OUTPUT)$(HELPERS_RST): $(UP2DIR)../../include/uapi/linux/bpf.h
38	$(QUIET_GEN)$(UP2DIR)../../scripts/bpf_helpers_doc.py --filename $< > $@	38	$(QUIET_GEN)$(UP2DIR)../../scripts/bpf_doc.py --filename $< > $@
39		39
40	$(OUTPUT)%.7: $(OUTPUT)%.rst	40	$(OUTPUT)%.7: $(OUTPUT)%.rst
41	ifndef RST2MAN_DEP	41	ifndef RST2MAN_DEP

tools/include/uapi/linux/bpf.h+1−1

@@ -729,7 +729,7 @@ union bpf_attr { · 728 unmodified lines
729	* parsed and used to produce a manual page. The workflow is the following,	729	* parsed and used to produce a manual page. The workflow is the following,
730	* and requires the rst2man utility:	730	* and requires the rst2man utility:
731	*	731	*
732	* $ ./scripts/bpf_helpers_doc.py \	732	* $ ./scripts/bpf_doc.py \
733	* --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst	733	* --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst
734	* $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7	734	* $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7
735	* $ man /tmp/bpf-helpers.7	735	* $ man /tmp/bpf-helpers.7

tools/lib/bpf/Makefile+1−1

@@ -158,7 +158,7 @@ $(BPF_IN_STATIC): force $(BPF_HELPER_DEFS) · 157 unmodified lines
158	$(Q)$(MAKE) $(build)=libbpf OUTPUT=$(STATIC_OBJDIR)	158	$(Q)$(MAKE) $(build)=libbpf OUTPUT=$(STATIC_OBJDIR)
159		159
160	$(BPF_HELPER_DEFS): $(srctree)/tools/include/uapi/linux/bpf.h	160	$(BPF_HELPER_DEFS): $(srctree)/tools/include/uapi/linux/bpf.h
161	$(QUIET_GEN)$(srctree)/scripts/bpf_helpers_doc.py --header \	161	$(QUIET_GEN)$(srctree)/scripts/bpf_doc.py --header \
162	--file $(srctree)/tools/include/uapi/linux/bpf.h > $(BPF_HELPER_DEFS)	162	--file $(srctree)/tools/include/uapi/linux/bpf.h > $(BPF_HELPER_DEFS)
163		163
164	$(OUTPUT)libbpf.so: $(OUTPUT)libbpf.so.$(LIBBPF_VERSION)	164	$(OUTPUT)libbpf.so: $(OUTPUT)libbpf.so.$(LIBBPF_VERSION)

tools/perf/MANIFEST+1−1

@@ -20,4 +20,4 @@ tools/lib/bitmap.c · 19 unmodified lines
20	tools/lib/str_error_r.c	20	tools/lib/str_error_r.c
21	tools/lib/vsprintf.c	21	tools/lib/vsprintf.c
22	tools/lib/zalloc.c	22	tools/lib/zalloc.c
23	scripts/bpf_helpers_doc.py	23	scripts/bpf_doc.py

scripts/bpf: Abstract eBPF API target parameter

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code