scripts/bpf_doc.py: implement json output format
PATCH v3 1/1 scripts/bpf_doc.py: implement json output format
bpf_doc.py parses bpf.h header to collect information about various API elements (such as BPF helpers) and then dump them in one of the supported formats: rst docs and a C header.
It's useful for external tools to be able to consume this information in an easy-to-parse format such as JSON. Implement JSON printers and add --json command line argument.
v2->v3: nit cleanupv1->v2: add json printer for syscall target
v2: https://lore.kernel.org/bpf/[email protected]/
v1: https://lore.kernel.org/bpf/[email protected]/
--- scripts/bpf_doc.py | 111 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 95 insertions(+), 16 deletions(-)
scripts/bpf_doc.py +95 -16
@@ -8,6 +8,7 @@ from __future__ import print_function import argparse +import json import re import sys, os import subprocess
@@ -43,6 +44,14 @@ class APIElement(object): self.ret = ret self.attrs = attrs + def to_dict(self): + return { + 'proto': self.proto, + 'desc': self.desc, + 'ret': self.ret, + 'attrs': self.attrs + } + class Helper(APIElement): """
@@ -81,6 +90,11 @@ class Helper(APIElement): return res + def to_dict(self): + d = super().to_dict() + d.update(self.proto_break_down()) + return d + ATTRS = { '__bpf_fastcall': 'bpf_fastcall'
@@ -675,7 +689,7 @@ COMMANDS self.print_elem(command) -class PrinterHelpers(Printer): +class PrinterHelpersHeader(Printer): """ A printer for dumping collected information about helpers as C header to be included from BPF program.
@@ -896,6 +910,43 @@ class PrinterHelpers(Printer): print(') = (void *) %d;' % helper.enum_val) print('') + +class PrinterHelpersJSON(Printer): + """ + A printer for dumping collected information about helpers as a JSON file. + @parser: A HeaderParser with Helper objects + """ + + def __init__(self, parser): + self.elements = parser.helpers + self.elem_number_check( + parser.desc_unique_helpers, + parser.define_unique_helpers, + "helper", + "___BPF_FUNC_MAPPER", + ) + + def print_all(self): + helper_dicts = [helper.to_dict() for helper in self.elements] + out_dict = {'helpers': helper_dicts} + print(json.dumps(out_dict, indent=4)) + + +class PrinterSyscallJSON(Printer): + """ + A printer for dumping collected syscall information as a JSON file. + @parser: A HeaderParser with APIElement objects + """ + + def __init__(self, parser): + self.elements = parser.commands + self.elem_number_check(parser.desc_syscalls, parser.enum_syscalls, 'syscall', 'bpf_cmd') + + def print_all(self): + syscall_dicts = [syscall.to_dict() for syscall in self.elements] + out_dict = {'syscall': syscall_dicts} + print(json.dumps(out_dict, indent=4)) + ############################################################################### # If script is launched from scripts/ from kernel tree and can access
@@ -905,9 +956,17 @@ 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') +# target -> output format -> printer printers = { - 'helpers': PrinterHelpersRST, - 'syscall': PrinterSyscallRST, + 'helpers': { + 'rst': PrinterHelpersRST, + 'json': PrinterHelpersJSON, + 'header': PrinterHelpersHeader, + }, + 'syscall': { + 'rst': PrinterSyscallRST, + 'json': PrinterSyscallJSON + }, } argParser = argparse.ArgumentParser(description="""
@@ -917,6 +976,8 @@ rst2man utility. """) argParser.add_argument('--header', action='store_true', help='generate C header file') +argParser.add_argument('--json', action='store_true', + help='generate a JSON') if (os.path.isfile(bpfh)): argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h', default=bpfh)
@@ -924,17 +985,35 @@ 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. -headerParser = HeaderParser(args.filename) -headerParser.run() - -# Print formatted output to standard output. -if args.header: - if args.target != 'helpers': - raise NotImplementedError('Only helpers header generation is supported') - printer = PrinterHelpers(headerParser) -else: - printer = printers[args.target](headerParser) -printer.print_all() +def error_die(message: str): + argParser.print_usage(file=sys.stderr) + print('Error: {}'.format(message), file=sys.stderr) + exit(1) + +def parse_and_dump(): + args = argParser.parse_args() + + # Parse file. + headerParser = HeaderParser(args.filename) + headerParser.run() + + if args.header and args.json: + error_die('Use either --header or --json, not both') + + output_format = 'rst' + if args.header: + output_format = 'header' + elif args.json: + output_format = 'json' + + try: + printer = printers[args.target][output_format](headerParser) + # Print formatted output to standard output. + printer.print_all() + except KeyError: + error_die('Unsupported target/format combination: "{}", "{}"' + .format(args.target, output_format)) + +if __name__ == "__main__": + parse_and_dump()
Signature · 1 line
2.47.1
2025-05-07 13:30 UTC-0700 ~ Ihor Solodrai <[email protected]>
Quoted 95 lines
bpf_doc.pyparsesbpf.hheader to collect information about various API elements (such as BPF helpers) and then dump them in one of the supported formats: rst docs and a C header.It's useful for external tools to be able to consume this information in an easy-to-parse format such as JSON. Implement JSON printers and add --json command line argument.
v2->v3: nit cleanupv1->v2: add json printer for syscall targetv2: https://lore.kernel.org/bpf/[email protected]/
v1: https://lore.kernel.org/bpf/[email protected]/Signed-off-by Ihor Solodrai <[email protected]>--- scripts/bpf_doc.py | 111 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 95 insertions(+), 16 deletions(-)scripts/bpf_doc.py +39
-1@@ -8,6 +8,7 @@ from __future__ import print_function import argparse +import json import re import sys, os import subprocess@@ -43,6 +44,14 @@ class APIElement(object): self.ret = ret self.attrs = attrs + def to_dict(self): + return { + 'proto': self.proto, + 'desc': self.desc, + 'ret': self.ret, + 'attrs': self.attrs + } + class Helper(APIElement): """@@ -81,6 +90,11 @@ class Helper(APIElement): return res + def to_dict(self): + d = super().to_dict() + d.update(self.proto_break_down()) + return d + ATTRS = { '__bpf_fastcall': 'bpf_fastcall'@@ -675,7 +689,7 @@ COMMANDS self.print_elem(command) -class PrinterHelpers(Printer): +class PrinterHelpersHeader(Printer): """ A printer for dumping collected information about helpers as C header to be included from BPF program.@@ -896,6 +910,43 @@ class PrinterHelpers(Printer): print(') = (void *) %d;' % helper.enum_val) print('') + +class PrinterHelpersJSON(Printer): + """ + A printer for dumping collected information about helpers as a JSON file. + @parser: A HeaderParser with Helper objects + """ + + def __init__(self, parser): + self.elements = parser.helpers + self.elem_number_check( + parser.desc_unique_helpers, + parser.define_unique_helpers, + "helper", + "___BPF_FUNC_MAPPER", + ) + + def print_all(self): + helper_dicts = [helper.to_dict() for helper in self.elements] + out_dict = {'helpers': helper_dicts} + print(json.dumps(out_dict, indent=4)) + + +class PrinterSyscallJSON(Printer): + """
scripts/bpf_doc.py class PrinterHelpers(Printer): · line 946
Quoted 10 lines
scripts/bpf_doc.py +10
-0+ A printer for dumping collected syscall information as a JSON file. + @parser: A HeaderParser with APIElement objects + """ + + def __init__(self, parser): + self.elements = parser.commands + self.elem_number_check(parser.desc_syscalls, parser.enum_syscalls, 'syscall', 'bpf_cmd') + + def print_all(self): + syscall_dicts = [syscall.to_dict() for syscall in self.elements]
Looks good and works well, thanks! I tested it and have one more nit:
for syscalls, with JSON, we print an empty "attrs" array for each syscall subcommand, because the attributes are used with helpers only. Could we avoid printing these, please? We could refactor the attribute parsing code to make it apply to helpers only, but the easiest approach is probably to just discard the attributes from JSON right here, before we print the dict:
# Attributes do not apply to syscall subcommands docs for syscall in syscall_dicts:
del syscall['attrs']
Quoted 5 lines
scripts/bpf_doc.py +3
-0+ out_dict = {'syscall': syscall_dicts} + print(json.dumps(out_dict, indent=4)) + ###############################################################################