3cd046f182aab scripts/bpf_helpers_doc.py (Scott Branden 2020-02-25 12:54:26 -0800 1) #!/usr/bin/env python3
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 2) # SPDX-License-Identifier: GPL-2.0-only
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 3) #
748c7c821aca5 scripts/bpf_helpers_doc.py (Quentin Monnet 2019-05-10 15:51:22 +0100 4) # Copyright (C) 2018-2019 Netronome Systems, Inc.
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 5) # Copyright (C) 2021 Isovalent, Inc.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 6)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 7) # In case user attempts to run with Python 2.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 8) from __future__ import print_function
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 9)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 10) import argparse
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 11) import re
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 12) import sys, os
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 13)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 14) class NoHelperFound(BaseException):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 15) pass
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 16)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 17) class NoSyscallCommandFound(BaseException):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 18) pass
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 19)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 20) class ParsingError(BaseException):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 21) def __init__(self, line='<line not provided>', reader=None):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 22) if reader:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 23) BaseException.__init__(self,
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 24) 'Error at file offset %d, parsing line: %s' %
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 25) (reader.tell(), line))
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 26) else:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 27) BaseException.__init__(self, 'Error parsing line: %s' % line)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 28)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 29)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 30) class APIElement(object):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 31) """
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 32) An object representing the description of an aspect of the eBPF API.
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 33) @proto: prototype of the API symbol
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 34) @desc: textual description of the symbol
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 35) @ret: (optional) description of any associated return value
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 36) """
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 37) def __init__(self, proto='', desc='', ret=''):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 38) self.proto = proto
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 39) self.desc = desc
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 40) self.ret = ret
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 41)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 42)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 43) class Helper(APIElement):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 44) """
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 45) An object representing the description of an eBPF helper function.
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 46) @proto: function prototype of the helper function
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 47) @desc: textual description of the helper function
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 48) @ret: description of the return value of the helper function
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 49) """
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 50) def proto_break_down(self):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 51) """
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 52) Break down helper function protocol into smaller chunks: return type,
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 53) name, distincts arguments.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 54) """
748c7c821aca5 scripts/bpf_helpers_doc.py (Quentin Monnet 2019-05-10 15:51:22 +0100 55) arg_re = re.compile('((\w+ )*?(\w+|...))( (\**)(\w+))?$')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 56) res = {}
6f96674dbd8ca scripts/bpf_helpers_doc.py (Quentin Monnet 2018-05-02 14:20:24 +0100 57) proto_re = re.compile('(.+) (\**)(\w+)\(((([^,]+)(, )?){1,5})\)$')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 58)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 59) capture = proto_re.match(self.proto)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 60) res['ret_type'] = capture.group(1)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 61) res['ret_star'] = capture.group(2)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 62) res['name'] = capture.group(3)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 63) res['args'] = []
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 64)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 65) args = capture.group(4).split(', ')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 66) for a in args:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 67) capture = arg_re.match(a)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 68) res['args'].append({
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 69) 'type' : capture.group(1),
748c7c821aca5 scripts/bpf_helpers_doc.py (Quentin Monnet 2019-05-10 15:51:22 +0100 70) 'star' : capture.group(5),
748c7c821aca5 scripts/bpf_helpers_doc.py (Quentin Monnet 2019-05-10 15:51:22 +0100 71) 'name' : capture.group(6)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 72) })
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 73)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 74) return res
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 75)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 76)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 77) class HeaderParser(object):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 78) """
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 79) An object used to parse a file in order to extract the documentation of a
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 80) list of eBPF helper functions. All the helpers that can be retrieved are
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 81) stored as Helper object, in the self.helpers() array.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 82) @filename: name of file to parse, usually include/uapi/linux/bpf.h in the
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 83) kernel tree
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 84) """
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 85) def __init__(self, filename):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 86) self.reader = open(filename, 'r')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 87) self.line = ''
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 88) self.helpers = []
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 89) self.commands = []
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 90)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 91) def parse_element(self):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 92) proto = self.parse_symbol()
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 93) desc = self.parse_desc()
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 94) ret = self.parse_ret()
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 95) return APIElement(proto=proto, desc=desc, ret=ret)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 96)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 97) def parse_helper(self):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 98) proto = self.parse_proto()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 99) desc = self.parse_desc()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 100) ret = self.parse_ret()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 101) return Helper(proto=proto, desc=desc, ret=ret)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 102)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 103) def parse_symbol(self):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 104) p = re.compile(' \* ?(.+)$')
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 105) capture = p.match(self.line)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 106) if not capture:
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 107) raise NoSyscallCommandFound
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 108) end_re = re.compile(' \* ?NOTES$')
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 109) end = end_re.match(self.line)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 110) if end:
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 111) raise NoSyscallCommandFound
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 112) self.line = self.reader.readline()
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 113) return capture.group(1)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 114)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 115) def parse_proto(self):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 116) # Argument can be of shape:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 117) # - "void"
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 118) # - "type name"
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 119) # - "type *name"
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 120) # - Same as above, with "const" and/or "struct" in front of type
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 121) # - "..." (undefined number of arguments, for bpf_trace_printk())
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 122) # There is at least one term ("void"), and at most five arguments.
6f96674dbd8ca scripts/bpf_helpers_doc.py (Quentin Monnet 2018-05-02 14:20:24 +0100 123) p = re.compile(' \* ?((.+) \**\w+\((((const )?(struct )?(\w+|\.\.\.)( \**\w+)?)(, )?){1,5}\))$')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 124) capture = p.match(self.line)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 125) if not capture:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 126) raise NoHelperFound
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 127) self.line = self.reader.readline()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 128) return capture.group(1)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 129)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 130) def parse_desc(self):
eeacb7166df6e scripts/bpf_helpers_doc.py (Quentin Monnet 2018-05-17 13:43:56 +0100 131) p = re.compile(' \* ?(?:\t| {5,8})Description$')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 132) capture = p.match(self.line)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 133) if not capture:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 134) # Helper can have empty description and we might be parsing another
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 135) # attribute: return but do not consume.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 136) return ''
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 137) # Description can be several lines, some of them possibly empty, and it
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 138) # stops when another subsection title is met.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 139) desc = ''
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 140) while True:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 141) self.line = self.reader.readline()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 142) if self.line == ' *\n':
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 143) desc += '\n'
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 144) else:
eeacb7166df6e scripts/bpf_helpers_doc.py (Quentin Monnet 2018-05-17 13:43:56 +0100 145) p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 146) capture = p.match(self.line)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 147) if capture:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 148) desc += capture.group(1) + '\n'
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 149) else:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 150) break
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 151) return desc
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 152)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 153) def parse_ret(self):
eeacb7166df6e scripts/bpf_helpers_doc.py (Quentin Monnet 2018-05-17 13:43:56 +0100 154) p = re.compile(' \* ?(?:\t| {5,8})Return$')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 155) capture = p.match(self.line)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 156) if not capture:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 157) # Helper can have empty retval and we might be parsing another
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 158) # attribute: return but do not consume.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 159) return ''
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 160) # Return value description can be several lines, some of them possibly
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 161) # empty, and it stops when another subsection title is met.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 162) ret = ''
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 163) while True:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 164) self.line = self.reader.readline()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 165) if self.line == ' *\n':
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 166) ret += '\n'
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 167) else:
eeacb7166df6e scripts/bpf_helpers_doc.py (Quentin Monnet 2018-05-17 13:43:56 +0100 168) p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 169) capture = p.match(self.line)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 170) if capture:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 171) ret += capture.group(1) + '\n'
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 172) else:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 173) break
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 174) return ret
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 175)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 176) def seek_to(self, target, help_message):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 177) self.reader.seek(0)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 178) offset = self.reader.read().find(target)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 179) if offset == -1:
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 180) raise Exception(help_message)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 181) self.reader.seek(offset)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 182) self.reader.readline()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 183) self.reader.readline()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 184) self.line = self.reader.readline()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 185)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 186) def parse_syscall(self):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 187) self.seek_to('* DOC: eBPF Syscall Commands',
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 188) 'Could not find start of eBPF syscall descriptions list')
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 189) while True:
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 190) try:
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 191) command = self.parse_element()
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 192) self.commands.append(command)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 193) except NoSyscallCommandFound:
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 194) break
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 195)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 196) def parse_helpers(self):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 197) self.seek_to('* Start of BPF helper function descriptions:',
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 198) 'Could not find start of eBPF helper descriptions list')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 199) while True:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 200) try:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 201) helper = self.parse_helper()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 202) self.helpers.append(helper)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 203) except NoHelperFound:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 204) break
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 205)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 206) def run(self):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 207) self.parse_syscall()
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 208) self.parse_helpers()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 209) self.reader.close()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 210)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 211) ###############################################################################
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 212)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 213) class Printer(object):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 214) """
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 215) A generic class for printers. Printers should be created with an array of
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 216) Helper objects, and implement a way to print them in the desired fashion.
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 217) @parser: A HeaderParser with objects to print to standard output
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 218) """
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 219) def __init__(self, parser):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 220) self.parser = parser
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 221) self.elements = []
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 222)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 223) def print_header(self):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 224) pass
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 225)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 226) def print_footer(self):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 227) pass
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 228)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 229) def print_one(self, helper):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 230) pass
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 231)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 232) def print_all(self):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 233) self.print_header()
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 234) for elem in self.elements:
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 235) self.print_one(elem)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 236) self.print_footer()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 237)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 238)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 239) class PrinterRST(Printer):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 240) """
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 241) A generic class for printers that print ReStructured Text. Printers should
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 242) be created with a HeaderParser object, and implement a way to print API
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 243) elements in the desired fashion.
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 244) @parser: A HeaderParser with objects to print to standard output
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 245) """
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 246) def __init__(self, parser):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 247) self.parser = parser
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 248)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 249) def print_license(self):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 250) license = '''\
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 251) .. Copyright (C) All BPF authors and contributors from 2014 to present.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 252) .. See git log include/uapi/linux/bpf.h in kernel tree for details.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 253) ..
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 254) .. %%%LICENSE_START(VERBATIM)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 255) .. Permission is granted to make and distribute verbatim copies of this
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 256) .. manual provided the copyright notice and this permission notice are
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 257) .. preserved on all copies.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 258) ..
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 259) .. Permission is granted to copy and distribute modified versions of this
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 260) .. manual under the conditions for verbatim copying, provided that the
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 261) .. entire resulting derived work is distributed under the terms of a
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 262) .. permission notice identical to this one.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 263) ..
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 264) .. Since the Linux kernel and libraries are constantly changing, this
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 265) .. manual page may be incorrect or out-of-date. The author(s) assume no
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 266) .. responsibility for errors or omissions, or for damages resulting from
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 267) .. the use of the information contained herein. The author(s) may not
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 268) .. have taken the same level of care in the production of this manual,
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 269) .. which is licensed free of charge, as they might when working
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 270) .. professionally.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 271) ..
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 272) .. Formatted or processed versions of this manual, if unaccompanied by
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 273) .. the source, must acknowledge the copyright and authors of this work.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 274) .. %%%LICENSE_END
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 275) ..
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 276) .. Please do not edit this file. It was generated from the documentation
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 277) .. located in file include/uapi/linux/bpf.h of the Linux kernel sources
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 278) .. (helpers description), and from scripts/bpf_doc.py in the same
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 279) .. repository (header and footer).
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 280) '''
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 281) print(license)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 282)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 283) def print_elem(self, elem):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 284) if (elem.desc):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 285) print('\tDescription')
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 286) # Do not strip all newline characters: formatted code at the end of
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 287) # a section must be followed by a blank line.
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 288) for line in re.sub('\n$', '', elem.desc, count=1).split('\n'):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 289) print('{}{}'.format('\t\t' if line else '', line))
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 290)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 291) if (elem.ret):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 292) print('\tReturn')
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 293) for line in elem.ret.rstrip().split('\n'):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 294) print('{}{}'.format('\t\t' if line else '', line))
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 295)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 296) print('')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 297)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 298)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 299) class PrinterHelpersRST(PrinterRST):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 300) """
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 301) A printer for dumping collected information about helpers as a ReStructured
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 302) Text page compatible with the rst2man program, which can be used to
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 303) generate a manual page for the helpers.
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 304) @parser: A HeaderParser with Helper objects to print to standard output
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 305) """
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 306) def __init__(self, parser):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 307) self.elements = parser.helpers
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 308)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 309) def print_header(self):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 310) header = '''\
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 311) ===========
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 312) BPF-HELPERS
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 313) ===========
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 314) -------------------------------------------------------------------------------
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 315) list of eBPF helper functions
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 316) -------------------------------------------------------------------------------
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 317)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 318) :Manual section: 7
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 319)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 320) DESCRIPTION
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 321) ===========
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 322)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 323) The extended Berkeley Packet Filter (eBPF) subsystem consists in programs
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 324) written in a pseudo-assembly language, then attached to one of the several
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 325) kernel hooks and run in reaction of specific events. This framework differs
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 326) from the older, "classic" BPF (or "cBPF") in several aspects, one of them being
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 327) the ability to call special functions (or "helpers") from within a program.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 328) These functions are restricted to a white-list of helpers defined in the
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 329) kernel.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 330)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 331) These helpers are used by eBPF programs to interact with the system, or with
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 332) the context in which they work. For instance, they can be used to print
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 333) debugging messages, to get the time since the system was booted, to interact
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 334) with eBPF maps, or to manipulate network packets. Since there are several eBPF
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 335) program types, and that they do not run in the same context, each program type
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 336) can only call a subset of those helpers.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 337)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 338) Due to eBPF conventions, a helper can not have more than five arguments.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 339)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 340) Internally, eBPF programs call directly into the compiled helper functions
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 341) without requiring any foreign-function interface. As a result, calling helpers
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 342) introduces no overhead, thus offering excellent performance.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 343)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 344) This document is an attempt to list and document the helpers available to eBPF
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 345) developers. They are sorted by chronological order (the oldest helpers in the
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 346) kernel at the top).
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 347)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 348) HELPERS
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 349) =======
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 350) '''
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 351) PrinterRST.print_license(self)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 352) print(header)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 353)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 354) def print_footer(self):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 355) footer = '''
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 356) EXAMPLES
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 357) ========
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 358)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 359) Example usage for most of the eBPF helpers listed in this manual page are
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 360) available within the Linux kernel sources, at the following locations:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 361)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 362) * *samples/bpf/*
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 363) * *tools/testing/selftests/bpf/*
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 364)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 365) LICENSE
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 366) =======
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 367)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 368) eBPF programs can have an associated license, passed along with the bytecode
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 369) instructions to the kernel when the programs are loaded. The format for that
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 370) string is identical to the one in use for kernel modules (Dual licenses, such
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 371) as "Dual BSD/GPL", may be used). Some helper functions are only accessible to
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 372) programs that are compatible with the GNU Privacy License (GPL).
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 373)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 374) In order to use such helpers, the eBPF program must be loaded with the correct
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 375) license string passed (via **attr**) to the **bpf**\ () system call, and this
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 376) generally translates into the C source code of the program containing a line
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 377) similar to the following:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 378)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 379) ::
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 380)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 381) char ____license[] __attribute__((section("license"), used)) = "GPL";
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 382)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 383) IMPLEMENTATION
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 384) ==============
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 385)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 386) This manual page is an effort to document the existing eBPF helper functions.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 387) But as of this writing, the BPF sub-system is under heavy development. New eBPF
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 388) program or map types are added, along with new helper functions. Some helpers
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 389) are occasionally made available for additional program types. So in spite of
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 390) the efforts of the community, this page might not be up-to-date. If you want to
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 391) check by yourself what helper functions exist in your kernel, or what types of
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 392) programs they can support, here are some files among the kernel tree that you
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 393) may be interested in:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 394)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 395) * *include/uapi/linux/bpf.h* is the main BPF header. It contains the full list
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 396) of all helper functions, as well as many other BPF definitions including most
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 397) of the flags, structs or constants used by the helpers.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 398) * *net/core/filter.c* contains the definition of most network-related helper
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 399) functions, and the list of program types from which they can be used.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 400) * *kernel/trace/bpf_trace.c* is the equivalent for most tracing program-related
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 401) helpers.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 402) * *kernel/bpf/verifier.c* contains the functions used to check that valid types
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 403) of eBPF maps are used with a given helper function.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 404) * *kernel/bpf/* directory contains other files in which additional helpers are
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 405) defined (for cgroups, sockmaps, etc.).
ab8d78093dfa2 scripts/bpf_helpers_doc.py (Quentin Monnet 2020-05-11 17:15:35 +0100 406) * The bpftool utility can be used to probe the availability of helper functions
ab8d78093dfa2 scripts/bpf_helpers_doc.py (Quentin Monnet 2020-05-11 17:15:35 +0100 407) on the system (as well as supported program and map types, and a number of
ab8d78093dfa2 scripts/bpf_helpers_doc.py (Quentin Monnet 2020-05-11 17:15:35 +0100 408) other parameters). To do so, run **bpftool feature probe** (see
ab8d78093dfa2 scripts/bpf_helpers_doc.py (Quentin Monnet 2020-05-11 17:15:35 +0100 409) **bpftool-feature**\ (8) for details). Add the **unprivileged** keyword to
ab8d78093dfa2 scripts/bpf_helpers_doc.py (Quentin Monnet 2020-05-11 17:15:35 +0100 410) list features available to unprivileged users.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 411)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 412) Compatibility between helper functions and program types can generally be found
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 413) in the files where helper functions are defined. Look for the **struct
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 414) bpf_func_proto** objects and for functions returning them: these functions
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 415) contain a list of helpers that a given program type can call. Note that the
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 416) **default:** label of the **switch ... case** used to filter helpers can call
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 417) other functions, themselves allowing access to additional helpers. The
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 418) requirement for GPL license is also in those **struct bpf_func_proto**.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 419)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 420) Compatibility between helper functions and map types can be found in the
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 421) **check_map_func_compatibility**\ () function in file *kernel/bpf/verifier.c*.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 422)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 423) Helper functions that invalidate the checks on **data** and **data_end**
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 424) pointers for network processing are listed in function
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 425) **bpf_helper_changes_pkt_data**\ () in file *net/core/filter.c*.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 426)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 427) SEE ALSO
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 428) ========
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 429)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 430) **bpf**\ (2),
ab8d78093dfa2 scripts/bpf_helpers_doc.py (Quentin Monnet 2020-05-11 17:15:35 +0100 431) **bpftool**\ (8),
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 432) **cgroups**\ (7),
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 433) **ip**\ (8),
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 434) **perf_event_open**\ (2),
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 435) **sendmsg**\ (2),
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 436) **socket**\ (7),
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 437) **tc-bpf**\ (8)'''
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 438) print(footer)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 439)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 440) def print_proto(self, helper):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 441) """
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 442) Format function protocol with bold and italics markers. This makes RST
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 443) file less readable, but gives nice results in the manual page.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 444) """
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 445) proto = helper.proto_break_down()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 446)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 447) print('**%s %s%s(' % (proto['ret_type'],
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 448) proto['ret_star'].replace('*', '\\*'),
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 449) proto['name']),
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 450) end='')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 451)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 452) comma = ''
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 453) for a in proto['args']:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 454) one_arg = '{}{}'.format(comma, a['type'])
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 455) if a['name']:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 456) if a['star']:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 457) one_arg += ' {}**\ '.format(a['star'].replace('*', '\\*'))
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 458) else:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 459) one_arg += '** '
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 460) one_arg += '*{}*\\ **'.format(a['name'])
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 461) comma = ', '
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 462) print(one_arg, end='')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 463)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 464) print(')**')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 465)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 466) def print_one(self, helper):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 467) self.print_proto(helper)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 468) self.print_elem(helper)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 469)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 470)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 471) class PrinterSyscallRST(PrinterRST):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 472) """
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 473) A printer for dumping collected information about the syscall API as a
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 474) ReStructured Text page compatible with the rst2man program, which can be
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 475) used to generate a manual page for the syscall.
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 476) @parser: A HeaderParser with APIElement objects to print to standard
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 477) output
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 478) """
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 479) def __init__(self, parser):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 480) self.elements = parser.commands
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 481)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 482) def print_header(self):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 483) header = '''\
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 484) ===
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 485) bpf
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 486) ===
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 487) -------------------------------------------------------------------------------
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 488) Perform a command on an extended BPF object
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 489) -------------------------------------------------------------------------------
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 490)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 491) :Manual section: 2
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 492)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 493) COMMANDS
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 494) ========
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 495) '''
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 496) PrinterRST.print_license(self)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 497) print(header)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 498)
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 499) def print_one(self, command):
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 500) print('**%s**' % (command.proto))
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 501) self.print_elem(command)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 502)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 503)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 504) class PrinterHelpers(Printer):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 505) """
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 506) A printer for dumping collected information about helpers as C header to
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 507) be included from BPF program.
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 508) @parser: A HeaderParser with Helper objects to print to standard output
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 509) """
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 510) def __init__(self, parser):
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 511) self.elements = parser.helpers
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 512)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 513) type_fwds = [
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 514) 'struct bpf_fib_lookup',
e9ddbb7707ff5 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2020-07-17 12:35:23 +0200 515) 'struct bpf_sk_lookup',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 516) 'struct bpf_perf_event_data',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 517) 'struct bpf_perf_event_value',
5996a587a466f scripts/bpf_helpers_doc.py (Carlos Neira 2020-03-13 12:46:50 -0300 518) 'struct bpf_pidns_info',
821f5c90130d1 scripts/bpf_helpers_doc.py (Andrii Nakryiko 2020-10-28 11:12:04 -0700 519) 'struct bpf_redir_neigh',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 520) 'struct bpf_sock',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 521) 'struct bpf_sock_addr',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 522) 'struct bpf_sock_ops',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 523) 'struct bpf_sock_tuple',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 524) 'struct bpf_spin_lock',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 525) 'struct bpf_sysctl',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 526) 'struct bpf_tcp_sock',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 527) 'struct bpf_tunnel_key',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 528) 'struct bpf_xfrm_state',
3f6719c7b62f0 scripts/bpf_helpers_doc.py (KP Singh 2020-11-17 23:29:28 +0000 529) 'struct linux_binprm',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 530) 'struct pt_regs',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 531) 'struct sk_reuseport_md',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 532) 'struct sockaddr',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 533) 'struct tcphdr',
492e639f0c222 scripts/bpf_helpers_doc.py (Yonghong Song 2020-05-09 10:59:14 -0700 534) 'struct seq_file',
af7ec13833619 scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:09 -0700 535) 'struct tcp6_sock',
478cfbdf5f13d scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:11 -0700 536) 'struct tcp_sock',
478cfbdf5f13d scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:11 -0700 537) 'struct tcp_timewait_sock',
478cfbdf5f13d scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:11 -0700 538) 'struct tcp_request_sock',
0d4fad3e57df2 scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:15 -0700 539) 'struct udp6_sock',
fa28dcb82a38f scripts/bpf_helpers_doc.py (Song Liu 2020-06-29 23:28:44 -0700 540) 'struct task_struct',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 541)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 542) 'struct __sk_buff',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 543) 'struct sk_msg_md',
e0b68fb186b25 scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-09 21:25:34 -0700 544) 'struct xdp_md',
6e22ab9da7934 scripts/bpf_helpers_doc.py (Jiri Olsa 2020-08-25 21:21:20 +0200 545) 'struct path',
c4d0bfb45068d scripts/bpf_helpers_doc.py (Alan Maguire 2020-09-28 12:31:05 +0100 546) 'struct btf_ptr',
27672f0d280a3 scripts/bpf_helpers_doc.py (KP Singh 2020-11-24 15:12:09 +0000 547) 'struct inode',
4f19cab76136e scripts/bpf_helpers_doc.py (Florent Revest 2020-12-04 12:36:05 +0100 548) 'struct socket',
4f19cab76136e scripts/bpf_helpers_doc.py (Florent Revest 2020-12-04 12:36:05 +0100 549) 'struct file',
b00628b1c7d59 scripts/bpf_doc.py (Alexei Starovoitov 2021-07-14 17:54:09 -0700 550) 'struct bpf_timer',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 551) ]
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 552) known_types = {
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 553) '...',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 554) 'void',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 555) 'const void',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 556) 'char',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 557) 'const char',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 558) 'int',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 559) 'long',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 560) 'unsigned long',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 561)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 562) '__be16',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 563) '__be32',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 564) '__wsum',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 565)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 566) 'struct bpf_fib_lookup',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 567) 'struct bpf_perf_event_data',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 568) 'struct bpf_perf_event_value',
b4490c5c4e023 scripts/bpf_helpers_doc.py (Carlos Neira 2020-03-04 17:41:56 -0300 569) 'struct bpf_pidns_info',
ba452c9e996d8 scripts/bpf_helpers_doc.py (Toke Høiland-Jørgensen 2020-10-20 23:25:56 +0200 570) 'struct bpf_redir_neigh',
e9ddbb7707ff5 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2020-07-17 12:35:23 +0200 571) 'struct bpf_sk_lookup',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 572) 'struct bpf_sock',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 573) 'struct bpf_sock_addr',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 574) 'struct bpf_sock_ops',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 575) 'struct bpf_sock_tuple',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 576) 'struct bpf_spin_lock',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 577) 'struct bpf_sysctl',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 578) 'struct bpf_tcp_sock',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 579) 'struct bpf_tunnel_key',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 580) 'struct bpf_xfrm_state',
3f6719c7b62f0 scripts/bpf_helpers_doc.py (KP Singh 2020-11-17 23:29:28 +0000 581) 'struct linux_binprm',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 582) 'struct pt_regs',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 583) 'struct sk_reuseport_md',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 584) 'struct sockaddr',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 585) 'struct tcphdr',
492e639f0c222 scripts/bpf_helpers_doc.py (Yonghong Song 2020-05-09 10:59:14 -0700 586) 'struct seq_file',
af7ec13833619 scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:09 -0700 587) 'struct tcp6_sock',
478cfbdf5f13d scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:11 -0700 588) 'struct tcp_sock',
478cfbdf5f13d scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:11 -0700 589) 'struct tcp_timewait_sock',
478cfbdf5f13d scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:11 -0700 590) 'struct tcp_request_sock',
0d4fad3e57df2 scripts/bpf_helpers_doc.py (Yonghong Song 2020-06-23 16:08:15 -0700 591) 'struct udp6_sock',
fa28dcb82a38f scripts/bpf_helpers_doc.py (Song Liu 2020-06-29 23:28:44 -0700 592) 'struct task_struct',
6e22ab9da7934 scripts/bpf_helpers_doc.py (Jiri Olsa 2020-08-25 21:21:20 +0200 593) 'struct path',
c4d0bfb45068d scripts/bpf_helpers_doc.py (Alan Maguire 2020-09-28 12:31:05 +0100 594) 'struct btf_ptr',
27672f0d280a3 scripts/bpf_helpers_doc.py (KP Singh 2020-11-24 15:12:09 +0000 595) 'struct inode',
4f19cab76136e scripts/bpf_helpers_doc.py (Florent Revest 2020-12-04 12:36:05 +0100 596) 'struct socket',
4f19cab76136e scripts/bpf_helpers_doc.py (Florent Revest 2020-12-04 12:36:05 +0100 597) 'struct file',
b00628b1c7d59 scripts/bpf_doc.py (Alexei Starovoitov 2021-07-14 17:54:09 -0700 598) 'struct bpf_timer',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 599) }
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 600) mapped_types = {
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 601) 'u8': '__u8',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 602) 'u16': '__u16',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 603) 'u32': '__u32',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 604) 'u64': '__u64',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 605) 's8': '__s8',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 606) 's16': '__s16',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 607) 's32': '__s32',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 608) 's64': '__s64',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 609) 'size_t': 'unsigned long',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 610) 'struct bpf_map': 'void',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 611) 'struct sk_buff': 'struct __sk_buff',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 612) 'const struct sk_buff': 'const struct __sk_buff',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 613) 'struct sk_msg_buff': 'struct sk_msg_md',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 614) 'struct xdp_buff': 'struct xdp_md',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 615) }
e9ddbb7707ff5 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2020-07-17 12:35:23 +0200 616) # Helpers overloaded for different context types.
e9ddbb7707ff5 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2020-07-17 12:35:23 +0200 617) overloaded_helpers = [
e9ddbb7707ff5 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2020-07-17 12:35:23 +0200 618) 'bpf_get_socket_cookie',
e9ddbb7707ff5 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2020-07-17 12:35:23 +0200 619) 'bpf_sk_assign',
e9ddbb7707ff5 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2020-07-17 12:35:23 +0200 620) ]
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 621)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 622) def print_header(self):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 623) header = '''\
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 624) /* This is auto-generated file. See bpf_doc.py for details. */
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 625)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 626) /* Forward declarations of BPF structs */'''
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 627)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 628) print(header)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 629) for fwd in self.type_fwds:
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 630) print('%s;' % fwd)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 631) print('')
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 632)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 633) def print_footer(self):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 634) footer = ''
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 635) print(footer)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 636)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 637) def map_type(self, t):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 638) if t in self.known_types:
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 639) return t
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 640) if t in self.mapped_types:
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 641) return self.mapped_types[t]
ab81e203bc0d4 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2019-10-20 13:23:44 +0200 642) print("Unrecognized type '%s', please add it to known types!" % t,
ab81e203bc0d4 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2019-10-20 13:23:44 +0200 643) file=sys.stderr)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 644) sys.exit(1)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 645)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 646) seen_helpers = set()
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 647)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 648) def print_one(self, helper):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 649) proto = helper.proto_break_down()
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 650)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 651) if proto['name'] in self.seen_helpers:
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 652) return
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 653) self.seen_helpers.add(proto['name'])
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 654)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 655) print('/*')
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 656) print(" * %s" % proto['name'])
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 657) print(" *")
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 658) if (helper.desc):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 659) # Do not strip all newline characters: formatted code at the end of
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 660) # a section must be followed by a blank line.
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 661) for line in re.sub('\n$', '', helper.desc, count=1).split('\n'):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 662) print(' *{}{}'.format(' \t' if line else '', line))
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 663)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 664) if (helper.ret):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 665) print(' *')
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 666) print(' * Returns')
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 667) for line in helper.ret.rstrip().split('\n'):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 668) print(' *{}{}'.format(' \t' if line else '', line))
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 669)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 670) print(' */')
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 671) print('static %s %s(*%s)(' % (self.map_type(proto['ret_type']),
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 672) proto['ret_star'], proto['name']), end='')
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 673) comma = ''
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 674) for i, a in enumerate(proto['args']):
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 675) t = a['type']
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 676) n = a['name']
e9ddbb7707ff5 scripts/bpf_helpers_doc.py (Jakub Sitnicki 2020-07-17 12:35:23 +0200 677) if proto['name'] in self.overloaded_helpers and i == 0:
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 678) t = 'void'
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 679) n = 'ctx'
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 680) one_arg = '{}{}'.format(comma, self.map_type(t))
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 681) if n:
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 682) if a['star']:
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 683) one_arg += ' {}'.format(a['star'])
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 684) else:
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 685) one_arg += ' '
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 686) one_arg += '{}'.format(n)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 687) comma = ', '
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 688) print(one_arg, end='')
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 689)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 690) print(') = (void *) %d;' % len(self.seen_helpers))
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 691) print('')
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 692)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 693) ###############################################################################
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 694)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 695) # If script is launched from scripts/ from kernel tree and can access
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 696) # ../include/uapi/linux/bpf.h, use it as a default name for the file to parse,
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 697) # otherwise the --filename argument will be required from the command line.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 698) script = os.path.abspath(sys.argv[0])
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 699) linuxRoot = os.path.dirname(os.path.dirname(script))
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 700) bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 701)
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 702) printers = {
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 703) 'helpers': PrinterHelpersRST,
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 704) 'syscall': PrinterSyscallRST,
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 705) }
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 706)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 707) argParser = argparse.ArgumentParser(description="""
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 708) Parse eBPF header file and generate documentation for the eBPF API.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 709) The RST-formatted output produced can be turned into a manual page with the
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 710) rst2man utility.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 711) """)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 712) argParser.add_argument('--header', action='store_true',
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 713) help='generate C header file')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 714) if (os.path.isfile(bpfh)):
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 715) argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h',
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 716) default=bpfh)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 717) else:
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 718) argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h')
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 719) argParser.add_argument('target', nargs='?', default='helpers',
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 720) choices=printers.keys(), help='eBPF API target')
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 721) args = argParser.parse_args()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 722)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 723) # Parse file.
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 724) headerParser = HeaderParser(args.filename)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 725) headerParser.run()
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 726)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 727) # Print formatted output to standard output.
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 728) if args.header:
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 729) if args.target != 'helpers':
a67882a221e34 scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:42 -0800 730) raise NotImplementedError('Only helpers header generation is supported')
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 731) printer = PrinterHelpers(headerParser)
7a387bed47f7e scripts/bpf_helpers_doc.py (Andrii Nakryiko 2019-10-06 20:07:37 -0700 732) else:
923a932c982fd scripts/bpf_doc.py (Joe Stringer 2021-03-02 09:19:41 -0800 733) printer = printers[args.target](headerParser)
56a092c895054 scripts/bpf_helpers_doc.py (Quentin Monnet 2018-04-25 18:16:52 +0100 734) printer.print_all()
VisionFive2 Linux kernel
StarFive Tech Linux Kernel for VisionFive (JH7110) boards (mirror)
More than 9999 Commits
33 Branches
55 Tags