| @@ -2,6 +2,7 @@ · 1 unmodified line |
| 2 | 2 | # SPDX-License-Identifier: GPL-2.0-only |
| 3 | 3 | # |
| 4 | 4 | # Copyright (C) 2018-2019 Netronome Systems, Inc. |
| 5 | +# Copyright (C) 2021 Isovalent, Inc. |
| 5 | 6 | |
| 6 | 7 | # In case user attempts to run with Python 2. |
| 7 | 8 | from __future__ import print_function |
| @@ -165,10 +166,11 @@ class Printer(object): · 157 unmodified lines |
| 165 | 166 | """ |
| 166 | 167 | A generic class for printers. Printers should be created with an array of |
| 167 | 168 | 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 |
| 169 | 170 | """ |
| 170 | | − def __init__(self, helpers): |
| 171 | | − self.helpers = helpers |
| 171 | + def __init__(self, parser): |
| 172 | + self.parser = parser |
| 173 | + self.elements = [] |
| 172 | 174 | |
| 173 | 175 | def print_header(self): |
| 174 | 176 | pass |
| @@ -181,19 +183,23 @@ class Printer(object): · 6 unmodified lines |
| 181 | 183 | |
| 182 | 184 | def print_all(self): |
| 183 | 185 | 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) |
| 186 | 188 | self.print_footer() |
| 187 | 189 | |
| 190 | + |
| 188 | 191 | class PrinterRST(Printer): |
| 189 | 192 | """ |
| 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 |
| 194 | 197 | """ |
| 195 | | − def print_header(self): |
| 196 | | − header = '''\ |
| 198 | + def __init__(self, parser): |
| 199 | + self.parser = parser |
| 200 | + |
| 201 | + def print_license(self): |
| 202 | + license = '''\ |
| 197 | 203 | .. Copyright (C) All BPF authors and contributors from 2014 to present. |
| 198 | 204 | .. See git log include/uapi/linux/bpf.h in kernel tree for details. |
| 199 | 205 | .. |
| @@ -221,9 +227,39 @@ class PrinterRST(Printer): · 21 unmodified lines |
| 221 | 227 | .. |
| 222 | 228 | .. Please do not edit this file. It was generated from the documentation |
| 223 | 229 | .. 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 |
| 225 | 231 | .. 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('') |
| 226 | 249 | |
| 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 = '''\ |
| 227 | 263 | =========== |
| 228 | 264 | BPF-HELPERS |
| 229 | 265 | =========== |
| @@ -264,6 +300,7 @@ kernel at the top). · 34 unmodified lines |
| 264 | 300 | HELPERS |
| 265 | 301 | ======= |
| 266 | 302 | ''' |
| 303 | + PrinterRST.print_license(self) |
| 267 | 304 | print(header) |
| 268 | 305 | |
| 269 | 306 | def print_footer(self): |
| @@ -380,27 +417,19 @@ SEE ALSO · 110 unmodified lines |
| 380 | 417 | |
| 381 | 418 | def print_one(self, helper): |
| 382 | 419 | self.print_proto(helper) |
| 420 | + self.print_elem(helper) |
| 383 | 421 | |
| 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)) |
| 390 | 422 | |
| 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)) |
| 395 | 423 | |
| 396 | | − print('') |
| 397 | 424 | |
| 398 | 425 | class PrinterHelpers(Printer): |
| 399 | 426 | """ |
| 400 | 427 | A printer for dumping collected information about helpers as C header to |
| 401 | 428 | 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 |
| 403 | 430 | """ |
| 431 | + def __init__(self, parser): |
| 432 | + self.elements = parser.helpers |
| 404 | 433 | |
| 405 | 434 | type_fwds = [ |
| 406 | 435 | 'struct bpf_fib_lookup', |
| @@ -511,7 +540,7 @@ class PrinterHelpers(Printer): · 104 unmodified lines |
| 511 | 540 | |
| 512 | 541 | def print_header(self): |
| 513 | 542 | 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. */ |
| 515 | 544 | |
| 516 | 545 | /* Forward declarations of BPF structs */''' |
| 517 | 546 | |
| @@ -589,8 +618,12 @@ script = os.path.abspath(sys.argv[0]) · 71 unmodified lines |
| 589 | 618 | linuxRoot = os.path.dirname(os.path.dirname(script)) |
| 590 | 619 | bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h') |
| 591 | 620 | |
| 621 | +printers = { |
| 622 | + 'helpers': PrinterHelpersRST, |
| 623 | +} |
| 624 | + |
| 592 | 625 | 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. |
| 594 | 627 | The RST-formatted output produced can be turned into a manual page with the |
| 595 | 628 | rst2man utility. |
| 596 | 629 | """) |
| @@ -601,6 +634,8 @@ if (os.path.isfile(bpfh)): · 4 unmodified lines |
| 601 | 634 | default=bpfh) |
| 602 | 635 | else: |
| 603 | 636 | 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') |
| 604 | 639 | args = argParser.parse_args() |
| 605 | 640 | |
| 606 | 641 | # Parse file. |
| @@ -609,7 +644,7 @@ headerParser.run() · 2 unmodified lines |
| 609 | 644 | |
| 610 | 645 | # Print formatted output to standard output. |
| 611 | 646 | if args.header: |
| 612 | | − printer = PrinterHelpers(headerParser.helpers) |
| 647 | + printer = PrinterHelpers(headerParser) |
| 613 | 648 | else: |
| 614 | | − printer = PrinterRST(headerParser.helpers) |
| 649 | + printer = printers[args.target](headerParser) |
| 615 | 650 | printer.print_all() |