blob: c55878bddfddc445a8f4548e4c763991585b1844 [file] [log] [blame]
Scott Branden3cd046f2020-02-25 12:54:26 -08001#!/usr/bin/env python3
Quentin Monnet56a092c2018-04-25 18:16:52 +01002# SPDX-License-Identifier: GPL-2.0-only
3#
Quentin Monnet748c7c82019-05-10 15:51:22 +01004# Copyright (C) 2018-2019 Netronome Systems, Inc.
Joe Stringer923a9322021-03-02 09:19:41 -08005# Copyright (C) 2021 Isovalent, Inc.
Quentin Monnet56a092c2018-04-25 18:16:52 +01006
7# In case user attempts to run with Python 2.
8from __future__ import print_function
9
10import argparse
11import re
12import sys, os
Quentin Monnetfd0a38f2022-08-23 16:53:26 +010013import subprocess
14
Quentin Monnet92ec1cc2022-08-23 16:53:27 +010015helpersDocStart = 'Start of BPF helper function descriptions:'
Quentin Monnet56a092c2018-04-25 18:16:52 +010016
17class NoHelperFound(BaseException):
18 pass
19
Joe Stringera67882a2021-03-02 09:19:42 -080020class NoSyscallCommandFound(BaseException):
21 pass
22
Quentin Monnet56a092c2018-04-25 18:16:52 +010023class ParsingError(BaseException):
24 def __init__(self, line='<line not provided>', reader=None):
25 if reader:
26 BaseException.__init__(self,
27 'Error at file offset %d, parsing line: %s' %
28 (reader.tell(), line))
29 else:
30 BaseException.__init__(self, 'Error parsing line: %s' % line)
31
Joe Stringera67882a2021-03-02 09:19:42 -080032
33class APIElement(object):
Quentin Monnet56a092c2018-04-25 18:16:52 +010034 """
Joe Stringera67882a2021-03-02 09:19:42 -080035 An object representing the description of an aspect of the eBPF API.
36 @proto: prototype of the API symbol
37 @desc: textual description of the symbol
38 @ret: (optional) description of any associated return value
Quentin Monnet56a092c2018-04-25 18:16:52 +010039 """
40 def __init__(self, proto='', desc='', ret=''):
41 self.proto = proto
42 self.desc = desc
43 self.ret = ret
44
Joe Stringera67882a2021-03-02 09:19:42 -080045
46class Helper(APIElement):
47 """
48 An object representing the description of an eBPF helper function.
49 @proto: function prototype of the helper function
50 @desc: textual description of the helper function
51 @ret: description of the return value of the helper function
52 """
Eyal Birger0a0d55e2022-08-24 21:10:43 +030053 def __init__(self, *args, **kwargs):
54 super().__init__(*args, **kwargs)
55 self.enum_val = None
56
Quentin Monnet56a092c2018-04-25 18:16:52 +010057 def proto_break_down(self):
58 """
59 Break down helper function protocol into smaller chunks: return type,
60 name, distincts arguments.
61 """
Vishal Chourasia121fd332023-08-29 13:19:31 +053062 arg_re = re.compile(r'((\w+ )*?(\w+|...))( (\**)(\w+))?$')
Quentin Monnet56a092c2018-04-25 18:16:52 +010063 res = {}
Vishal Chourasia121fd332023-08-29 13:19:31 +053064 proto_re = re.compile(r'(.+) (\**)(\w+)\(((([^,]+)(, )?){1,5})\)$')
Quentin Monnet56a092c2018-04-25 18:16:52 +010065
66 capture = proto_re.match(self.proto)
67 res['ret_type'] = capture.group(1)
68 res['ret_star'] = capture.group(2)
69 res['name'] = capture.group(3)
70 res['args'] = []
71
72 args = capture.group(4).split(', ')
73 for a in args:
74 capture = arg_re.match(a)
75 res['args'].append({
76 'type' : capture.group(1),
Quentin Monnet748c7c82019-05-10 15:51:22 +010077 'star' : capture.group(5),
78 'name' : capture.group(6)
Quentin Monnet56a092c2018-04-25 18:16:52 +010079 })
80
81 return res
82
Joe Stringera67882a2021-03-02 09:19:42 -080083
Quentin Monnet56a092c2018-04-25 18:16:52 +010084class HeaderParser(object):
85 """
86 An object used to parse a file in order to extract the documentation of a
87 list of eBPF helper functions. All the helpers that can be retrieved are
88 stored as Helper object, in the self.helpers() array.
89 @filename: name of file to parse, usually include/uapi/linux/bpf.h in the
90 kernel tree
91 """
92 def __init__(self, filename):
93 self.reader = open(filename, 'r')
94 self.line = ''
95 self.helpers = []
Joe Stringera67882a2021-03-02 09:19:42 -080096 self.commands = []
Usama Arif71a3cdf2022-01-12 11:49:53 +000097 self.desc_unique_helpers = set()
98 self.define_unique_helpers = []
Eyal Birger0a0d55e2022-08-24 21:10:43 +030099 self.helper_enum_vals = {}
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700100 self.helper_enum_pos = {}
Usama Arif0ba39292022-01-19 11:44:42 +0000101 self.desc_syscalls = []
102 self.enum_syscalls = []
Joe Stringera67882a2021-03-02 09:19:42 -0800103
104 def parse_element(self):
105 proto = self.parse_symbol()
Usama Ariff1f3f672022-01-19 11:44:41 +0000106 desc = self.parse_desc(proto)
107 ret = self.parse_ret(proto)
Joe Stringera67882a2021-03-02 09:19:42 -0800108 return APIElement(proto=proto, desc=desc, ret=ret)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100109
110 def parse_helper(self):
111 proto = self.parse_proto()
Usama Ariff1f3f672022-01-19 11:44:41 +0000112 desc = self.parse_desc(proto)
113 ret = self.parse_ret(proto)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100114 return Helper(proto=proto, desc=desc, ret=ret)
115
Joe Stringera67882a2021-03-02 09:19:42 -0800116 def parse_symbol(self):
Vishal Chourasia121fd332023-08-29 13:19:31 +0530117 p = re.compile(r' \* ?(BPF\w+)$')
Joe Stringera67882a2021-03-02 09:19:42 -0800118 capture = p.match(self.line)
119 if not capture:
120 raise NoSyscallCommandFound
Vishal Chourasia121fd332023-08-29 13:19:31 +0530121 end_re = re.compile(r' \* ?NOTES$')
Joe Stringera67882a2021-03-02 09:19:42 -0800122 end = end_re.match(self.line)
123 if end:
124 raise NoSyscallCommandFound
125 self.line = self.reader.readline()
126 return capture.group(1)
127
Quentin Monnet56a092c2018-04-25 18:16:52 +0100128 def parse_proto(self):
129 # Argument can be of shape:
130 # - "void"
131 # - "type name"
132 # - "type *name"
133 # - Same as above, with "const" and/or "struct" in front of type
134 # - "..." (undefined number of arguments, for bpf_trace_printk())
135 # There is at least one term ("void"), and at most five arguments.
Vishal Chourasia121fd332023-08-29 13:19:31 +0530136 p = re.compile(r' \* ?((.+) \**\w+\((((const )?(struct )?(\w+|\.\.\.)( \**\w+)?)(, )?){1,5}\))$')
Quentin Monnet56a092c2018-04-25 18:16:52 +0100137 capture = p.match(self.line)
138 if not capture:
139 raise NoHelperFound
140 self.line = self.reader.readline()
141 return capture.group(1)
142
Usama Ariff1f3f672022-01-19 11:44:41 +0000143 def parse_desc(self, proto):
Vishal Chourasia121fd332023-08-29 13:19:31 +0530144 p = re.compile(r' \* ?(?:\t| {5,8})Description$')
Quentin Monnet56a092c2018-04-25 18:16:52 +0100145 capture = p.match(self.line)
146 if not capture:
Usama Ariff1f3f672022-01-19 11:44:41 +0000147 raise Exception("No description section found for " + proto)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100148 # Description can be several lines, some of them possibly empty, and it
149 # stops when another subsection title is met.
150 desc = ''
Usama Ariff1f3f672022-01-19 11:44:41 +0000151 desc_present = False
Quentin Monnet56a092c2018-04-25 18:16:52 +0100152 while True:
153 self.line = self.reader.readline()
154 if self.line == ' *\n':
155 desc += '\n'
156 else:
Vishal Chourasia121fd332023-08-29 13:19:31 +0530157 p = re.compile(r' \* ?(?:\t| {5,8})(?:\t| {8})(.*)')
Quentin Monnet56a092c2018-04-25 18:16:52 +0100158 capture = p.match(self.line)
159 if capture:
Usama Ariff1f3f672022-01-19 11:44:41 +0000160 desc_present = True
Quentin Monnet56a092c2018-04-25 18:16:52 +0100161 desc += capture.group(1) + '\n'
162 else:
163 break
Usama Ariff1f3f672022-01-19 11:44:41 +0000164
165 if not desc_present:
166 raise Exception("No description found for " + proto)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100167 return desc
168
Usama Ariff1f3f672022-01-19 11:44:41 +0000169 def parse_ret(self, proto):
Vishal Chourasia121fd332023-08-29 13:19:31 +0530170 p = re.compile(r' \* ?(?:\t| {5,8})Return$')
Quentin Monnet56a092c2018-04-25 18:16:52 +0100171 capture = p.match(self.line)
172 if not capture:
Usama Ariff1f3f672022-01-19 11:44:41 +0000173 raise Exception("No return section found for " + proto)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100174 # Return value description can be several lines, some of them possibly
175 # empty, and it stops when another subsection title is met.
176 ret = ''
Usama Ariff1f3f672022-01-19 11:44:41 +0000177 ret_present = False
Quentin Monnet56a092c2018-04-25 18:16:52 +0100178 while True:
179 self.line = self.reader.readline()
180 if self.line == ' *\n':
181 ret += '\n'
182 else:
Vishal Chourasia121fd332023-08-29 13:19:31 +0530183 p = re.compile(r' \* ?(?:\t| {5,8})(?:\t| {8})(.*)')
Quentin Monnet56a092c2018-04-25 18:16:52 +0100184 capture = p.match(self.line)
185 if capture:
Usama Ariff1f3f672022-01-19 11:44:41 +0000186 ret_present = True
Quentin Monnet56a092c2018-04-25 18:16:52 +0100187 ret += capture.group(1) + '\n'
188 else:
189 break
Usama Ariff1f3f672022-01-19 11:44:41 +0000190
191 if not ret_present:
192 raise Exception("No return found for " + proto)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100193 return ret
194
Usama Arif0ba39292022-01-19 11:44:42 +0000195 def seek_to(self, target, help_message, discard_lines = 1):
Joe Stringera67882a2021-03-02 09:19:42 -0800196 self.reader.seek(0)
197 offset = self.reader.read().find(target)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100198 if offset == -1:
Joe Stringera67882a2021-03-02 09:19:42 -0800199 raise Exception(help_message)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100200 self.reader.seek(offset)
201 self.reader.readline()
Usama Arif0ba39292022-01-19 11:44:42 +0000202 for _ in range(discard_lines):
203 self.reader.readline()
Quentin Monnet56a092c2018-04-25 18:16:52 +0100204 self.line = self.reader.readline()
205
Usama Arif0ba39292022-01-19 11:44:42 +0000206 def parse_desc_syscall(self):
Joe Stringera67882a2021-03-02 09:19:42 -0800207 self.seek_to('* DOC: eBPF Syscall Commands',
208 'Could not find start of eBPF syscall descriptions list')
209 while True:
210 try:
211 command = self.parse_element()
212 self.commands.append(command)
Usama Arif0ba39292022-01-19 11:44:42 +0000213 self.desc_syscalls.append(command.proto)
214
Joe Stringera67882a2021-03-02 09:19:42 -0800215 except NoSyscallCommandFound:
216 break
217
Usama Arif0ba39292022-01-19 11:44:42 +0000218 def parse_enum_syscall(self):
219 self.seek_to('enum bpf_cmd {',
220 'Could not find start of bpf_cmd enum', 0)
221 # Searches for either one or more BPF\w+ enums
Vishal Chourasia121fd332023-08-29 13:19:31 +0530222 bpf_p = re.compile(r'\s*(BPF\w+)+')
Usama Arif0ba39292022-01-19 11:44:42 +0000223 # Searches for an enum entry assigned to another entry,
224 # for e.g. BPF_PROG_RUN = BPF_PROG_TEST_RUN, which is
225 # not documented hence should be skipped in check to
226 # determine if the right number of syscalls are documented
Vishal Chourasia121fd332023-08-29 13:19:31 +0530227 assign_p = re.compile(r'\s*(BPF\w+)\s*=\s*(BPF\w+)')
Usama Arif0ba39292022-01-19 11:44:42 +0000228 bpf_cmd_str = ''
229 while True:
230 capture = assign_p.match(self.line)
231 if capture:
232 # Skip line if an enum entry is assigned to another entry
233 self.line = self.reader.readline()
234 continue
235 capture = bpf_p.match(self.line)
236 if capture:
237 bpf_cmd_str += self.line
238 else:
239 break
240 self.line = self.reader.readline()
241 # Find the number of occurences of BPF\w+
Vishal Chourasia121fd332023-08-29 13:19:31 +0530242 self.enum_syscalls = re.findall(r'(BPF\w+)+', bpf_cmd_str)
Usama Arif0ba39292022-01-19 11:44:42 +0000243
Usama Arif71a3cdf2022-01-12 11:49:53 +0000244 def parse_desc_helpers(self):
Quentin Monnet92ec1cc2022-08-23 16:53:27 +0100245 self.seek_to(helpersDocStart,
Joe Stringera67882a2021-03-02 09:19:42 -0800246 'Could not find start of eBPF helper descriptions list')
Quentin Monnet56a092c2018-04-25 18:16:52 +0100247 while True:
248 try:
249 helper = self.parse_helper()
250 self.helpers.append(helper)
Usama Arif71a3cdf2022-01-12 11:49:53 +0000251 proto = helper.proto_break_down()
252 self.desc_unique_helpers.add(proto['name'])
Quentin Monnet56a092c2018-04-25 18:16:52 +0100253 except NoHelperFound:
254 break
255
Usama Arif71a3cdf2022-01-12 11:49:53 +0000256 def parse_define_helpers(self):
Andrii Nakryiko8a761452022-10-05 21:24:51 -0700257 # Parse FN(...) in #define ___BPF_FUNC_MAPPER to compare later with the
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300258 # number of unique function names present in description and use the
259 # correct enumeration value.
Usama Arif71a3cdf2022-01-12 11:49:53 +0000260 # Note: seek_to(..) discards the first line below the target search text,
Andrii Nakryiko8a761452022-10-05 21:24:51 -0700261 # resulting in FN(unspec, 0, ##ctx) being skipped and not added to
262 # self.define_unique_helpers.
263 self.seek_to('#define ___BPF_FUNC_MAPPER(FN, ctx...)',
Usama Arif71a3cdf2022-01-12 11:49:53 +0000264 'Could not find start of eBPF helper definition list')
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300265 # Searches for one FN(\w+) define or a backslash for newline
Vishal Chourasia121fd332023-08-29 13:19:31 +0530266 p = re.compile(r'\s*FN\((\w+), (\d+), ##ctx\)|\\\\')
Usama Arif71a3cdf2022-01-12 11:49:53 +0000267 fn_defines_str = ''
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700268 i = 0
Usama Arif71a3cdf2022-01-12 11:49:53 +0000269 while True:
270 capture = p.match(self.line)
271 if capture:
272 fn_defines_str += self.line
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700273 helper_name = capture.expand(r'bpf_\1')
Michal Suchanek5fbea422023-01-09 12:34:42 +0100274 self.helper_enum_vals[helper_name] = int(capture.group(2))
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700275 self.helper_enum_pos[helper_name] = i
276 i += 1
Usama Arif71a3cdf2022-01-12 11:49:53 +0000277 else:
278 break
279 self.line = self.reader.readline()
280 # Find the number of occurences of FN(\w+)
Vishal Chourasia121fd332023-08-29 13:19:31 +0530281 self.define_unique_helpers = re.findall(r'FN\(\w+, \d+, ##ctx\)', fn_defines_str)
Usama Arif71a3cdf2022-01-12 11:49:53 +0000282
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700283 def validate_helpers(self):
284 last_helper = ''
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300285 seen_helpers = set()
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700286 seen_enum_vals = set()
287 i = 0
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300288 for helper in self.helpers:
289 proto = helper.proto_break_down()
290 name = proto['name']
291 try:
292 enum_val = self.helper_enum_vals[name]
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700293 enum_pos = self.helper_enum_pos[name]
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300294 except KeyError:
295 raise Exception("Helper %s is missing from enum bpf_func_id" % name)
296
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700297 if name in seen_helpers:
298 if last_helper != name:
299 raise Exception("Helper %s has multiple descriptions which are not grouped together" % name)
300 continue
301
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300302 # Enforce current practice of having the descriptions ordered
303 # by enum value.
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700304 if enum_pos != i:
305 raise Exception("Helper %s (ID %d) comment order (#%d) must be aligned with its position (#%d) in enum bpf_func_id" % (name, enum_val, i + 1, enum_pos + 1))
306 if enum_val in seen_enum_vals:
307 raise Exception("Helper %s has duplicated value %d" % (name, enum_val))
308
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300309 seen_helpers.add(name)
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700310 last_helper = name
311 seen_enum_vals.add(enum_val)
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300312
313 helper.enum_val = enum_val
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700314 i += 1
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300315
Joe Stringera67882a2021-03-02 09:19:42 -0800316 def run(self):
Usama Arif0ba39292022-01-19 11:44:42 +0000317 self.parse_desc_syscall()
318 self.parse_enum_syscall()
Usama Arif71a3cdf2022-01-12 11:49:53 +0000319 self.parse_desc_helpers()
320 self.parse_define_helpers()
Andrii Nakryikoce3e44a2022-10-05 21:24:52 -0700321 self.validate_helpers()
Quentin Monnet56a092c2018-04-25 18:16:52 +0100322 self.reader.close()
Quentin Monnet56a092c2018-04-25 18:16:52 +0100323
324###############################################################################
325
326class Printer(object):
327 """
328 A generic class for printers. Printers should be created with an array of
329 Helper objects, and implement a way to print them in the desired fashion.
Joe Stringer923a9322021-03-02 09:19:41 -0800330 @parser: A HeaderParser with objects to print to standard output
Quentin Monnet56a092c2018-04-25 18:16:52 +0100331 """
Joe Stringer923a9322021-03-02 09:19:41 -0800332 def __init__(self, parser):
333 self.parser = parser
334 self.elements = []
Quentin Monnet56a092c2018-04-25 18:16:52 +0100335
336 def print_header(self):
337 pass
338
339 def print_footer(self):
340 pass
341
342 def print_one(self, helper):
343 pass
344
345 def print_all(self):
346 self.print_header()
Joe Stringer923a9322021-03-02 09:19:41 -0800347 for elem in self.elements:
348 self.print_one(elem)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100349 self.print_footer()
350
Usama Arif0ba39292022-01-19 11:44:42 +0000351 def elem_number_check(self, desc_unique_elem, define_unique_elem, type, instance):
352 """
353 Checks the number of helpers/syscalls documented within the header file
354 description with those defined as part of enum/macro and raise an
355 Exception if they don't match.
356 """
357 nr_desc_unique_elem = len(desc_unique_elem)
358 nr_define_unique_elem = len(define_unique_elem)
359 if nr_desc_unique_elem != nr_define_unique_elem:
360 exception_msg = '''
361The number of unique %s in description (%d) doesn\'t match the number of unique %s defined in %s (%d)
362''' % (type, nr_desc_unique_elem, type, instance, nr_define_unique_elem)
363 if nr_desc_unique_elem < nr_define_unique_elem:
364 # Function description is parsed until no helper is found (which can be due to
365 # misformatting). Hence, only print the first missing/misformatted helper/enum.
366 exception_msg += '''
367The description for %s is not present or formatted correctly.
368''' % (define_unique_elem[nr_desc_unique_elem])
369 raise Exception(exception_msg)
Joe Stringer923a9322021-03-02 09:19:41 -0800370
Quentin Monnet56a092c2018-04-25 18:16:52 +0100371class PrinterRST(Printer):
372 """
Joe Stringer923a9322021-03-02 09:19:41 -0800373 A generic class for printers that print ReStructured Text. Printers should
374 be created with a HeaderParser object, and implement a way to print API
375 elements in the desired fashion.
376 @parser: A HeaderParser with objects to print to standard output
Quentin Monnet56a092c2018-04-25 18:16:52 +0100377 """
Joe Stringer923a9322021-03-02 09:19:41 -0800378 def __init__(self, parser):
379 self.parser = parser
380
381 def print_license(self):
382 license = '''\
Quentin Monnet56a092c2018-04-25 18:16:52 +0100383.. Copyright (C) All BPF authors and contributors from 2014 to present.
384.. See git log include/uapi/linux/bpf.h in kernel tree for details.
385..
Alejandro Colomareafa9212023-04-11 15:47:47 +0100386.. SPDX-License-Identifier: Linux-man-pages-copyleft
Quentin Monnet56a092c2018-04-25 18:16:52 +0100387..
388.. Please do not edit this file. It was generated from the documentation
389.. located in file include/uapi/linux/bpf.h of the Linux kernel sources
Joe Stringer923a9322021-03-02 09:19:41 -0800390.. (helpers description), and from scripts/bpf_doc.py in the same
Quentin Monnet56a092c2018-04-25 18:16:52 +0100391.. repository (header and footer).
Joe Stringer923a9322021-03-02 09:19:41 -0800392'''
393 print(license)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100394
Joe Stringer923a9322021-03-02 09:19:41 -0800395 def print_elem(self, elem):
396 if (elem.desc):
397 print('\tDescription')
398 # Do not strip all newline characters: formatted code at the end of
399 # a section must be followed by a blank line.
400 for line in re.sub('\n$', '', elem.desc, count=1).split('\n'):
401 print('{}{}'.format('\t\t' if line else '', line))
402
403 if (elem.ret):
404 print('\tReturn')
405 for line in elem.ret.rstrip().split('\n'):
406 print('{}{}'.format('\t\t' if line else '', line))
407
408 print('')
409
Quentin Monnetfd0a38f2022-08-23 16:53:26 +0100410 def get_kernel_version(self):
411 try:
412 version = subprocess.run(['git', 'describe'], cwd=linuxRoot,
413 capture_output=True, check=True)
414 version = version.stdout.decode().rstrip()
415 except:
416 try:
Hangbin Liu5384cc02024-03-15 10:34:43 +0800417 version = subprocess.run(['make', '-s', '--no-print-directory', 'kernelversion'],
418 cwd=linuxRoot, capture_output=True, check=True)
Quentin Monnetfd0a38f2022-08-23 16:53:26 +0100419 version = version.stdout.decode().rstrip()
420 except:
421 return 'Linux'
422 return 'Linux {version}'.format(version=version)
423
Quentin Monnet92ec1cc2022-08-23 16:53:27 +0100424 def get_last_doc_update(self, delimiter):
425 try:
426 cmd = ['git', 'log', '-1', '--pretty=format:%cs', '--no-patch',
427 '-L',
Vishal Chourasia121fd332023-08-29 13:19:31 +0530428 '/{}/,/\\*\\//:include/uapi/linux/bpf.h'.format(delimiter)]
Quentin Monnet92ec1cc2022-08-23 16:53:27 +0100429 date = subprocess.run(cmd, cwd=linuxRoot,
430 capture_output=True, check=True)
431 return date.stdout.decode().rstrip()
432 except:
433 return ''
434
Joe Stringer923a9322021-03-02 09:19:41 -0800435class PrinterHelpersRST(PrinterRST):
436 """
437 A printer for dumping collected information about helpers as a ReStructured
438 Text page compatible with the rst2man program, which can be used to
439 generate a manual page for the helpers.
440 @parser: A HeaderParser with Helper objects to print to standard output
441 """
442 def __init__(self, parser):
443 self.elements = parser.helpers
Andrii Nakryiko8a761452022-10-05 21:24:51 -0700444 self.elem_number_check(parser.desc_unique_helpers, parser.define_unique_helpers, 'helper', '___BPF_FUNC_MAPPER')
Joe Stringer923a9322021-03-02 09:19:41 -0800445
446 def print_header(self):
447 header = '''\
Quentin Monnet56a092c2018-04-25 18:16:52 +0100448===========
449BPF-HELPERS
450===========
451-------------------------------------------------------------------------------
452list of eBPF helper functions
453-------------------------------------------------------------------------------
454
455:Manual section: 7
Quentin Monnetfd0a38f2022-08-23 16:53:26 +0100456:Version: {version}
Quentin Monnet92ec1cc2022-08-23 16:53:27 +0100457{date_field}{date}
Quentin Monnet56a092c2018-04-25 18:16:52 +0100458
459DESCRIPTION
460===========
461
462The extended Berkeley Packet Filter (eBPF) subsystem consists in programs
463written in a pseudo-assembly language, then attached to one of the several
464kernel hooks and run in reaction of specific events. This framework differs
465from the older, "classic" BPF (or "cBPF") in several aspects, one of them being
466the ability to call special functions (or "helpers") from within a program.
467These functions are restricted to a white-list of helpers defined in the
468kernel.
469
470These helpers are used by eBPF programs to interact with the system, or with
471the context in which they work. For instance, they can be used to print
472debugging messages, to get the time since the system was booted, to interact
473with eBPF maps, or to manipulate network packets. Since there are several eBPF
474program types, and that they do not run in the same context, each program type
475can only call a subset of those helpers.
476
477Due to eBPF conventions, a helper can not have more than five arguments.
478
479Internally, eBPF programs call directly into the compiled helper functions
480without requiring any foreign-function interface. As a result, calling helpers
481introduces no overhead, thus offering excellent performance.
482
483This document is an attempt to list and document the helpers available to eBPF
484developers. They are sorted by chronological order (the oldest helpers in the
485kernel at the top).
486
487HELPERS
488=======
489'''
Quentin Monnetfd0a38f2022-08-23 16:53:26 +0100490 kernelVersion = self.get_kernel_version()
Quentin Monnet92ec1cc2022-08-23 16:53:27 +0100491 lastUpdate = self.get_last_doc_update(helpersDocStart)
Quentin Monnetfd0a38f2022-08-23 16:53:26 +0100492
Joe Stringer923a9322021-03-02 09:19:41 -0800493 PrinterRST.print_license(self)
Quentin Monnet92ec1cc2022-08-23 16:53:27 +0100494 print(header.format(version=kernelVersion,
495 date_field = ':Date: ' if lastUpdate else '',
496 date=lastUpdate))
Quentin Monnet56a092c2018-04-25 18:16:52 +0100497
498 def print_footer(self):
499 footer = '''
500EXAMPLES
501========
502
503Example usage for most of the eBPF helpers listed in this manual page are
504available within the Linux kernel sources, at the following locations:
505
506* *samples/bpf/*
507* *tools/testing/selftests/bpf/*
508
509LICENSE
510=======
511
512eBPF programs can have an associated license, passed along with the bytecode
513instructions to the kernel when the programs are loaded. The format for that
514string is identical to the one in use for kernel modules (Dual licenses, such
515as "Dual BSD/GPL", may be used). Some helper functions are only accessible to
Gianmarco Lusvardie37243b2024-02-13 23:05:46 +0000516programs that are compatible with the GNU General Public License (GNU GPL).
Quentin Monnet56a092c2018-04-25 18:16:52 +0100517
518In order to use such helpers, the eBPF program must be loaded with the correct
Vishal Chourasia121fd332023-08-29 13:19:31 +0530519license string passed (via **attr**) to the **bpf**\\ () system call, and this
Quentin Monnet56a092c2018-04-25 18:16:52 +0100520generally translates into the C source code of the program containing a line
521similar to the following:
522
523::
524
525 char ____license[] __attribute__((section("license"), used)) = "GPL";
526
527IMPLEMENTATION
528==============
529
530This manual page is an effort to document the existing eBPF helper functions.
531But as of this writing, the BPF sub-system is under heavy development. New eBPF
532program or map types are added, along with new helper functions. Some helpers
533are occasionally made available for additional program types. So in spite of
534the efforts of the community, this page might not be up-to-date. If you want to
535check by yourself what helper functions exist in your kernel, or what types of
536programs they can support, here are some files among the kernel tree that you
537may be interested in:
538
539* *include/uapi/linux/bpf.h* is the main BPF header. It contains the full list
540 of all helper functions, as well as many other BPF definitions including most
541 of the flags, structs or constants used by the helpers.
542* *net/core/filter.c* contains the definition of most network-related helper
543 functions, and the list of program types from which they can be used.
544* *kernel/trace/bpf_trace.c* is the equivalent for most tracing program-related
545 helpers.
546* *kernel/bpf/verifier.c* contains the functions used to check that valid types
547 of eBPF maps are used with a given helper function.
548* *kernel/bpf/* directory contains other files in which additional helpers are
549 defined (for cgroups, sockmaps, etc.).
Quentin Monnetab8d7802020-05-11 17:15:35 +0100550* The bpftool utility can be used to probe the availability of helper functions
551 on the system (as well as supported program and map types, and a number of
552 other parameters). To do so, run **bpftool feature probe** (see
Vishal Chourasia121fd332023-08-29 13:19:31 +0530553 **bpftool-feature**\\ (8) for details). Add the **unprivileged** keyword to
Quentin Monnetab8d7802020-05-11 17:15:35 +0100554 list features available to unprivileged users.
Quentin Monnet56a092c2018-04-25 18:16:52 +0100555
556Compatibility between helper functions and program types can generally be found
557in the files where helper functions are defined. Look for the **struct
558bpf_func_proto** objects and for functions returning them: these functions
559contain a list of helpers that a given program type can call. Note that the
560**default:** label of the **switch ... case** used to filter helpers can call
561other functions, themselves allowing access to additional helpers. The
562requirement for GPL license is also in those **struct bpf_func_proto**.
563
564Compatibility between helper functions and map types can be found in the
Vishal Chourasia121fd332023-08-29 13:19:31 +0530565**check_map_func_compatibility**\\ () function in file *kernel/bpf/verifier.c*.
Quentin Monnet56a092c2018-04-25 18:16:52 +0100566
567Helper functions that invalidate the checks on **data** and **data_end**
568pointers for network processing are listed in function
Vishal Chourasia121fd332023-08-29 13:19:31 +0530569**bpf_helper_changes_pkt_data**\\ () in file *net/core/filter.c*.
Quentin Monnet56a092c2018-04-25 18:16:52 +0100570
571SEE ALSO
572========
573
Vishal Chourasia121fd332023-08-29 13:19:31 +0530574**bpf**\\ (2),
575**bpftool**\\ (8),
576**cgroups**\\ (7),
577**ip**\\ (8),
578**perf_event_open**\\ (2),
579**sendmsg**\\ (2),
580**socket**\\ (7),
581**tc-bpf**\\ (8)'''
Quentin Monnet56a092c2018-04-25 18:16:52 +0100582 print(footer)
583
584 def print_proto(self, helper):
585 """
586 Format function protocol with bold and italics markers. This makes RST
587 file less readable, but gives nice results in the manual page.
588 """
589 proto = helper.proto_break_down()
590
591 print('**%s %s%s(' % (proto['ret_type'],
592 proto['ret_star'].replace('*', '\\*'),
593 proto['name']),
594 end='')
595
596 comma = ''
597 for a in proto['args']:
598 one_arg = '{}{}'.format(comma, a['type'])
599 if a['name']:
600 if a['star']:
Vishal Chourasia121fd332023-08-29 13:19:31 +0530601 one_arg += ' {}**\\ '.format(a['star'].replace('*', '\\*'))
Quentin Monnet56a092c2018-04-25 18:16:52 +0100602 else:
603 one_arg += '** '
604 one_arg += '*{}*\\ **'.format(a['name'])
605 comma = ', '
606 print(one_arg, end='')
607
608 print(')**')
609
610 def print_one(self, helper):
611 self.print_proto(helper)
Joe Stringer923a9322021-03-02 09:19:41 -0800612 self.print_elem(helper)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100613
Quentin Monnet56a092c2018-04-25 18:16:52 +0100614
Joe Stringera67882a2021-03-02 09:19:42 -0800615class PrinterSyscallRST(PrinterRST):
616 """
617 A printer for dumping collected information about the syscall API as a
618 ReStructured Text page compatible with the rst2man program, which can be
619 used to generate a manual page for the syscall.
620 @parser: A HeaderParser with APIElement objects to print to standard
621 output
622 """
623 def __init__(self, parser):
624 self.elements = parser.commands
Usama Arif0ba39292022-01-19 11:44:42 +0000625 self.elem_number_check(parser.desc_syscalls, parser.enum_syscalls, 'syscall', 'bpf_cmd')
Joe Stringera67882a2021-03-02 09:19:42 -0800626
627 def print_header(self):
628 header = '''\
629===
630bpf
631===
632-------------------------------------------------------------------------------
633Perform a command on an extended BPF object
634-------------------------------------------------------------------------------
635
636:Manual section: 2
637
638COMMANDS
639========
640'''
641 PrinterRST.print_license(self)
642 print(header)
643
644 def print_one(self, command):
645 print('**%s**' % (command.proto))
646 self.print_elem(command)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100647
Quentin Monnet56a092c2018-04-25 18:16:52 +0100648
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700649class PrinterHelpers(Printer):
650 """
651 A printer for dumping collected information about helpers as C header to
652 be included from BPF program.
Joe Stringer923a9322021-03-02 09:19:41 -0800653 @parser: A HeaderParser with Helper objects to print to standard output
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700654 """
Joe Stringer923a9322021-03-02 09:19:41 -0800655 def __init__(self, parser):
656 self.elements = parser.helpers
Andrii Nakryiko8a761452022-10-05 21:24:51 -0700657 self.elem_number_check(parser.desc_unique_helpers, parser.define_unique_helpers, 'helper', '___BPF_FUNC_MAPPER')
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700658
659 type_fwds = [
660 'struct bpf_fib_lookup',
Jakub Sitnickie9ddbb72020-07-17 12:35:23 +0200661 'struct bpf_sk_lookup',
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700662 'struct bpf_perf_event_data',
663 'struct bpf_perf_event_value',
Carlos Neira5996a582020-03-13 12:46:50 -0300664 'struct bpf_pidns_info',
Andrii Nakryiko821f5c92020-10-28 11:12:04 -0700665 'struct bpf_redir_neigh',
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700666 'struct bpf_sock',
667 'struct bpf_sock_addr',
668 'struct bpf_sock_ops',
669 'struct bpf_sock_tuple',
670 'struct bpf_spin_lock',
671 'struct bpf_sysctl',
672 'struct bpf_tcp_sock',
673 'struct bpf_tunnel_key',
674 'struct bpf_xfrm_state',
KP Singh3f6719c2020-11-17 23:29:28 +0000675 'struct linux_binprm',
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700676 'struct pt_regs',
677 'struct sk_reuseport_md',
678 'struct sockaddr',
679 'struct tcphdr',
Yonghong Song492e6392020-05-09 10:59:14 -0700680 'struct seq_file',
Yonghong Songaf7ec132020-06-23 16:08:09 -0700681 'struct tcp6_sock',
Yonghong Song478cfbd2020-06-23 16:08:11 -0700682 'struct tcp_sock',
683 'struct tcp_timewait_sock',
684 'struct tcp_request_sock',
Yonghong Song0d4fad3e52020-06-23 16:08:15 -0700685 'struct udp6_sock',
Hengqi Chen9eeb3aa2021-10-21 21:47:51 +0800686 'struct unix_sock',
Song Liufa28dcb2020-06-29 23:28:44 -0700687 'struct task_struct',
Yonghong Songc4bcfb32022-10-25 21:28:50 -0700688 'struct cgroup',
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700689
690 'struct __sk_buff',
691 'struct sk_msg_md',
Andrii Nakryikoe0b68fb2019-10-09 21:25:34 -0700692 'struct xdp_md',
Jiri Olsa6e22ab92020-08-25 21:21:20 +0200693 'struct path',
Alan Maguirec4d0bfb2020-09-28 12:31:05 +0100694 'struct btf_ptr',
KP Singh27672f02020-11-24 15:12:09 +0000695 'struct inode',
Florent Revest4f19cab2020-12-04 12:36:05 +0100696 'struct socket',
697 'struct file',
Alexei Starovoitovb00628b2021-07-14 17:54:09 -0700698 'struct bpf_timer',
Geliang Tang3bc253c2022-05-19 16:30:10 -0700699 'struct mptcp_sock',
Joanne Koong97e03f52022-05-23 14:07:07 -0700700 'struct bpf_dynptr',
Maxim Mikityanskiy33bf9882022-06-15 16:48:44 +0300701 'struct iphdr',
702 'struct ipv6hdr',
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700703 ]
704 known_types = {
705 '...',
706 'void',
707 'const void',
708 'char',
709 'const char',
710 'int',
711 'long',
712 'unsigned long',
713
714 '__be16',
715 '__be32',
716 '__wsum',
717
718 'struct bpf_fib_lookup',
719 'struct bpf_perf_event_data',
720 'struct bpf_perf_event_value',
Carlos Neirab4490c52020-03-04 17:41:56 -0300721 'struct bpf_pidns_info',
Toke Høiland-Jørgensenba452c92020-10-20 23:25:56 +0200722 'struct bpf_redir_neigh',
Jakub Sitnickie9ddbb72020-07-17 12:35:23 +0200723 'struct bpf_sk_lookup',
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700724 'struct bpf_sock',
725 'struct bpf_sock_addr',
726 'struct bpf_sock_ops',
727 'struct bpf_sock_tuple',
728 'struct bpf_spin_lock',
729 'struct bpf_sysctl',
730 'struct bpf_tcp_sock',
731 'struct bpf_tunnel_key',
732 'struct bpf_xfrm_state',
KP Singh3f6719c2020-11-17 23:29:28 +0000733 'struct linux_binprm',
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700734 'struct pt_regs',
735 'struct sk_reuseport_md',
736 'struct sockaddr',
737 'struct tcphdr',
Yonghong Song492e6392020-05-09 10:59:14 -0700738 'struct seq_file',
Yonghong Songaf7ec132020-06-23 16:08:09 -0700739 'struct tcp6_sock',
Yonghong Song478cfbd2020-06-23 16:08:11 -0700740 'struct tcp_sock',
741 'struct tcp_timewait_sock',
742 'struct tcp_request_sock',
Yonghong Song0d4fad3e52020-06-23 16:08:15 -0700743 'struct udp6_sock',
Hengqi Chen9eeb3aa2021-10-21 21:47:51 +0800744 'struct unix_sock',
Song Liufa28dcb2020-06-29 23:28:44 -0700745 'struct task_struct',
Yonghong Songc4bcfb32022-10-25 21:28:50 -0700746 'struct cgroup',
Jiri Olsa6e22ab92020-08-25 21:21:20 +0200747 'struct path',
Alan Maguirec4d0bfb2020-09-28 12:31:05 +0100748 'struct btf_ptr',
KP Singh27672f02020-11-24 15:12:09 +0000749 'struct inode',
Florent Revest4f19cab2020-12-04 12:36:05 +0100750 'struct socket',
751 'struct file',
Alexei Starovoitovb00628b2021-07-14 17:54:09 -0700752 'struct bpf_timer',
Geliang Tang3bc253c2022-05-19 16:30:10 -0700753 'struct mptcp_sock',
Joanne Koong97e03f52022-05-23 14:07:07 -0700754 'struct bpf_dynptr',
Kumar Kartikeya Dwivedi27060532022-12-08 02:11:37 +0530755 'const struct bpf_dynptr',
Maxim Mikityanskiy33bf9882022-06-15 16:48:44 +0300756 'struct iphdr',
757 'struct ipv6hdr',
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700758 }
759 mapped_types = {
760 'u8': '__u8',
761 'u16': '__u16',
762 'u32': '__u32',
763 'u64': '__u64',
764 's8': '__s8',
765 's16': '__s16',
766 's32': '__s32',
767 's64': '__s64',
768 'size_t': 'unsigned long',
769 'struct bpf_map': 'void',
770 'struct sk_buff': 'struct __sk_buff',
771 'const struct sk_buff': 'const struct __sk_buff',
772 'struct sk_msg_buff': 'struct sk_msg_md',
773 'struct xdp_buff': 'struct xdp_md',
774 }
Jakub Sitnickie9ddbb72020-07-17 12:35:23 +0200775 # Helpers overloaded for different context types.
776 overloaded_helpers = [
777 'bpf_get_socket_cookie',
778 'bpf_sk_assign',
779 ]
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700780
781 def print_header(self):
782 header = '''\
Joe Stringer923a9322021-03-02 09:19:41 -0800783/* This is auto-generated file. See bpf_doc.py for details. */
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700784
785/* Forward declarations of BPF structs */'''
786
787 print(header)
788 for fwd in self.type_fwds:
789 print('%s;' % fwd)
790 print('')
791
792 def print_footer(self):
793 footer = ''
794 print(footer)
795
796 def map_type(self, t):
797 if t in self.known_types:
798 return t
799 if t in self.mapped_types:
800 return self.mapped_types[t]
Jakub Sitnickiab81e202019-10-20 13:23:44 +0200801 print("Unrecognized type '%s', please add it to known types!" % t,
802 file=sys.stderr)
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700803 sys.exit(1)
804
805 seen_helpers = set()
806
807 def print_one(self, helper):
808 proto = helper.proto_break_down()
809
810 if proto['name'] in self.seen_helpers:
811 return
812 self.seen_helpers.add(proto['name'])
813
814 print('/*')
815 print(" * %s" % proto['name'])
816 print(" *")
817 if (helper.desc):
818 # Do not strip all newline characters: formatted code at the end of
819 # a section must be followed by a blank line.
820 for line in re.sub('\n$', '', helper.desc, count=1).split('\n'):
821 print(' *{}{}'.format(' \t' if line else '', line))
822
823 if (helper.ret):
824 print(' *')
825 print(' * Returns')
826 for line in helper.ret.rstrip().split('\n'):
827 print(' *{}{}'.format(' \t' if line else '', line))
828
829 print(' */')
Jose E. Marchesiff2071a2024-01-27 19:50:31 +0100830 print('static %s %s(* const %s)(' % (self.map_type(proto['ret_type']),
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700831 proto['ret_star'], proto['name']), end='')
832 comma = ''
833 for i, a in enumerate(proto['args']):
834 t = a['type']
835 n = a['name']
Jakub Sitnickie9ddbb72020-07-17 12:35:23 +0200836 if proto['name'] in self.overloaded_helpers and i == 0:
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700837 t = 'void'
838 n = 'ctx'
839 one_arg = '{}{}'.format(comma, self.map_type(t))
840 if n:
841 if a['star']:
842 one_arg += ' {}'.format(a['star'])
843 else:
844 one_arg += ' '
845 one_arg += '{}'.format(n)
846 comma = ', '
847 print(one_arg, end='')
848
Eyal Birger0a0d55e2022-08-24 21:10:43 +0300849 print(') = (void *) %d;' % helper.enum_val)
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700850 print('')
851
Quentin Monnet56a092c2018-04-25 18:16:52 +0100852###############################################################################
853
854# If script is launched from scripts/ from kernel tree and can access
855# ../include/uapi/linux/bpf.h, use it as a default name for the file to parse,
856# otherwise the --filename argument will be required from the command line.
857script = os.path.abspath(sys.argv[0])
858linuxRoot = os.path.dirname(os.path.dirname(script))
859bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h')
860
Joe Stringer923a9322021-03-02 09:19:41 -0800861printers = {
862 'helpers': PrinterHelpersRST,
Joe Stringera67882a2021-03-02 09:19:42 -0800863 'syscall': PrinterSyscallRST,
Joe Stringer923a9322021-03-02 09:19:41 -0800864}
865
Quentin Monnet56a092c2018-04-25 18:16:52 +0100866argParser = argparse.ArgumentParser(description="""
Joe Stringer923a9322021-03-02 09:19:41 -0800867Parse eBPF header file and generate documentation for the eBPF API.
Quentin Monnet56a092c2018-04-25 18:16:52 +0100868The RST-formatted output produced can be turned into a manual page with the
869rst2man utility.
870""")
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700871argParser.add_argument('--header', action='store_true',
872 help='generate C header file')
Quentin Monnet56a092c2018-04-25 18:16:52 +0100873if (os.path.isfile(bpfh)):
874 argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h',
875 default=bpfh)
876else:
877 argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h')
Joe Stringer923a9322021-03-02 09:19:41 -0800878argParser.add_argument('target', nargs='?', default='helpers',
879 choices=printers.keys(), help='eBPF API target')
Quentin Monnet56a092c2018-04-25 18:16:52 +0100880args = argParser.parse_args()
881
882# Parse file.
883headerParser = HeaderParser(args.filename)
884headerParser.run()
885
886# Print formatted output to standard output.
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700887if args.header:
Joe Stringera67882a2021-03-02 09:19:42 -0800888 if args.target != 'helpers':
889 raise NotImplementedError('Only helpers header generation is supported')
Joe Stringer923a9322021-03-02 09:19:41 -0800890 printer = PrinterHelpers(headerParser)
Andrii Nakryiko7a387be2019-10-06 20:07:37 -0700891else:
Joe Stringer923a9322021-03-02 09:19:41 -0800892 printer = printers[args.target](headerParser)
Quentin Monnet56a092c2018-04-25 18:16:52 +0100893printer.print_all()