Commit 56a092c8 authored by Quentin Monnet's avatar Quentin Monnet Committed by Daniel Borkmann
Browse files

bpf: add script and prepare bpf.h for new helpers documentation 



Remove previous "overview" of eBPF helpers from user bpf.h header.
Replace it by a comment explaining how to process the new documentation
(to come in following patches) with a Python script to produce RST, then
man page documentation.

Also add the aforementioned Python script under scripts/. It is used to
process include/uapi/linux/bpf.h and to extract helper descriptions, to
turn it into a RST document that can further be processed with rst2man
to produce a man page. The script takes one "--filename <path/to/file>"
option. If the script is launched from scripts/ in the kernel root
directory, it should be able to find the location of the header to
parse, and "--filename <path/to/file>" is then optional. If it cannot
find the file, then the option becomes mandatory. RST-formatted
documentation is printed to standard output.

Typical workflow for producing the final man page would be:

    $ ./scripts/bpf_helpers_doc.py \
            --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst
    $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7
    $ man /tmp/bpf-helpers.7

Note that the tool kernel-doc cannot be used to document eBPF helpers,
whose signatures are not available directly in the header files
(pre-processor directives are used to produce them at the beginning of
the compilation process).

v4:
- Also remove overviews for newly added bpf_xdp_adjust_tail() and
  bpf_skb_get_xfrm_state().
- Remove vague statement about what helpers are restricted to GPL
  programs in "LICENSE" section for man page footer.
- Replace license boilerplate with SPDX tag for Python script.

v3:
- Change license for man page.
- Remove "for safety reasons" from man page header text.
- Change "packets metadata" to "packets" in man page header text.
- Move and fix comment on helpers introducing no overhead.
- Remove "NOTES" section from man page footer.
- Add "LICENSE" section to man page footer.
- Edit description of file include/uapi/linux/bpf.h in man page footer.

Signed-off-by: default avatarQuentin Monnet <quentin.monnet@netronome.com>
Signed-off-by: default avatarDaniel Borkmann <daniel@iogearbox.net>
parent 3f13de6d

include/uapi/linux/bpf.h

+16 −406
Original line number Diff line number Diff line
@@ -377,412 +377,22 @@ union bpf_attr { 
	};

} __attribute__((aligned(8)));



/* BPF helper function descriptions:

 *

 * void *bpf_map_lookup_elem(&map, &key)

 *     Return: Map value or NULL

 *

 * int bpf_map_update_elem(&map, &key, &value, flags)

 *     Return: 0 on success or negative error

 *

 * int bpf_map_delete_elem(&map, &key)

 *     Return: 0 on success or negative error

 *

 * int bpf_probe_read(void *dst, int size, void *src)

 *     Return: 0 on success or negative error

 *

 * u64 bpf_ktime_get_ns(void)

 *     Return: current ktime

 *

 * int bpf_trace_printk(const char *fmt, int fmt_size, ...)

 *     Return: length of buffer written or negative error

 *

 * u32 bpf_prandom_u32(void)

 *     Return: random value

 *

 * u32 bpf_raw_smp_processor_id(void)

 *     Return: SMP processor ID

 *

 * int bpf_skb_store_bytes(skb, offset, from, len, flags)

 *     store bytes into packet

 *     @skb: pointer to skb

 *     @offset: offset within packet from skb->mac_header

 *     @from: pointer where to copy bytes from

 *     @len: number of bytes to store into packet

 *     @flags: bit 0 - if true, recompute skb->csum

 *             other bits - reserved

 *     Return: 0 on success or negative error

 *

 * int bpf_l3_csum_replace(skb, offset, from, to, flags)

 *     recompute IP checksum

 *     @skb: pointer to skb

 *     @offset: offset within packet where IP checksum is located

 *     @from: old value of header field

 *     @to: new value of header field

 *     @flags: bits 0-3 - size of header field

 *             other bits - reserved

 *     Return: 0 on success or negative error

 *

 * int bpf_l4_csum_replace(skb, offset, from, to, flags)

 *     recompute TCP/UDP checksum

 *     @skb: pointer to skb

 *     @offset: offset within packet where TCP/UDP checksum is located

 *     @from: old value of header field

 *     @to: new value of header field

 *     @flags: bits 0-3 - size of header field

 *             bit 4 - is pseudo header

 *             other bits - reserved

 *     Return: 0 on success or negative error

 *

 * int bpf_tail_call(ctx, prog_array_map, index)

 *     jump into another BPF program

 *     @ctx: context pointer passed to next program

 *     @prog_array_map: pointer to map which type is BPF_MAP_TYPE_PROG_ARRAY

 *     @index: 32-bit index inside array that selects specific program to run

 *     Return: 0 on success or negative error

 *

 * int bpf_clone_redirect(skb, ifindex, flags)

 *     redirect to another netdev

 *     @skb: pointer to skb

 *     @ifindex: ifindex of the net device

 *     @flags: bit 0 - if set, redirect to ingress instead of egress

 *             other bits - reserved

 *     Return: 0 on success or negative error

 *

 * u64 bpf_get_current_pid_tgid(void)

 *     Return: current->tgid << 32 | current->pid

 *

 * u64 bpf_get_current_uid_gid(void)

 *     Return: current_gid << 32 | current_uid

 *

 * int bpf_get_current_comm(char *buf, int size_of_buf)

 *     stores current->comm into buf

 *     Return: 0 on success or negative error

 *

 * u32 bpf_get_cgroup_classid(skb)

 *     retrieve a proc's classid

 *     @skb: pointer to skb

 *     Return: classid if != 0

 *

 * int bpf_skb_vlan_push(skb, vlan_proto, vlan_tci)

 *     Return: 0 on success or negative error

 *

 * int bpf_skb_vlan_pop(skb)

 *     Return: 0 on success or negative error

 *

 * int bpf_skb_get_tunnel_key(skb, key, size, flags)

 * int bpf_skb_set_tunnel_key(skb, key, size, flags)

 *     retrieve or populate tunnel metadata

 *     @skb: pointer to skb

 *     @key: pointer to 'struct bpf_tunnel_key'

 *     @size: size of 'struct bpf_tunnel_key'

 *     @flags: room for future extensions

 *     Return: 0 on success or negative error

 *

 * u64 bpf_perf_event_read(map, flags)

 *     read perf event counter value

 *     @map: pointer to perf_event_array map

 *     @flags: index of event in the map or bitmask flags

 *     Return: value of perf event counter read or error code

 *

 * int bpf_redirect(ifindex, flags)

 *     redirect to another netdev

 *     @ifindex: ifindex of the net device

 *     @flags:

 *	  cls_bpf:

 *          bit 0 - if set, redirect to ingress instead of egress

 *          other bits - reserved

 *	  xdp_bpf:

 *	    all bits - reserved

 *     Return: cls_bpf: TC_ACT_REDIRECT on success or TC_ACT_SHOT on error

 *	       xdp_bfp: XDP_REDIRECT on success or XDP_ABORT on error

 * int bpf_redirect_map(map, key, flags)

 *     redirect to endpoint in map

 *     @map: pointer to dev map

 *     @key: index in map to lookup

 *     @flags: --

 *     Return: XDP_REDIRECT on success or XDP_ABORT on error

 *

 * u32 bpf_get_route_realm(skb)

 *     retrieve a dst's tclassid

 *     @skb: pointer to skb

 *     Return: realm if != 0

 *

 * int bpf_perf_event_output(ctx, map, flags, data, size)

 *     output perf raw sample

 *     @ctx: struct pt_regs*

 *     @map: pointer to perf_event_array map

 *     @flags: index of event in the map or bitmask flags

 *     @data: data on stack to be output as raw data

 *     @size: size of data

 *     Return: 0 on success or negative error

 *

 * int bpf_get_stackid(ctx, map, flags)

 *     walk user or kernel stack and return id

 *     @ctx: struct pt_regs*

 *     @map: pointer to stack_trace map

 *     @flags: bits 0-7 - numer of stack frames to skip

 *             bit 8 - collect user stack instead of kernel

 *             bit 9 - compare stacks by hash only

 *             bit 10 - if two different stacks hash into the same stackid

 *                      discard old

 *             other bits - reserved

 *     Return: >= 0 stackid on success or negative error

 *

 * s64 bpf_csum_diff(from, from_size, to, to_size, seed)

 *     calculate csum diff

 *     @from: raw from buffer

 *     @from_size: length of from buffer

 *     @to: raw to buffer

 *     @to_size: length of to buffer

 *     @seed: optional seed

 *     Return: csum result or negative error code

 *

 * int bpf_skb_get_tunnel_opt(skb, opt, size)

 *     retrieve tunnel options metadata

 *     @skb: pointer to skb

 *     @opt: pointer to raw tunnel option data

 *     @size: size of @opt

 *     Return: option size

 *

 * int bpf_skb_set_tunnel_opt(skb, opt, size)

 *     populate tunnel options metadata

 *     @skb: pointer to skb

 *     @opt: pointer to raw tunnel option data

 *     @size: size of @opt

 *     Return: 0 on success or negative error

 *

 * int bpf_skb_change_proto(skb, proto, flags)

 *     Change protocol of the skb. Currently supported is v4 -> v6,

 *     v6 -> v4 transitions. The helper will also resize the skb. eBPF

 *     program is expected to fill the new headers via skb_store_bytes

 *     and lX_csum_replace.

 *     @skb: pointer to skb

 *     @proto: new skb->protocol type

 *     @flags: reserved

 *     Return: 0 on success or negative error

 *

 * int bpf_skb_change_type(skb, type)

 *     Change packet type of skb.

 *     @skb: pointer to skb

 *     @type: new skb->pkt_type type

 *     Return: 0 on success or negative error

 *

 * int bpf_skb_under_cgroup(skb, map, index)

 *     Check cgroup2 membership of skb

 *     @skb: pointer to skb

 *     @map: pointer to bpf_map in BPF_MAP_TYPE_CGROUP_ARRAY type

 *     @index: index of the cgroup in the bpf_map

 *     Return:

 *       == 0 skb failed the cgroup2 descendant test

 *       == 1 skb succeeded the cgroup2 descendant test

 *        < 0 error

 *

 * u32 bpf_get_hash_recalc(skb)

 *     Retrieve and possibly recalculate skb->hash.

 *     @skb: pointer to skb

 *     Return: hash

 *

 * u64 bpf_get_current_task(void)

 *     Returns current task_struct

 *     Return: current

 *

 * int bpf_probe_write_user(void *dst, void *src, int len)

 *     safely attempt to write to a location

 *     @dst: destination address in userspace

 *     @src: source address on stack

 *     @len: number of bytes to copy

 *     Return: 0 on success or negative error

 *

 * int bpf_current_task_under_cgroup(map, index)

 *     Check cgroup2 membership of current task

 *     @map: pointer to bpf_map in BPF_MAP_TYPE_CGROUP_ARRAY type

 *     @index: index of the cgroup in the bpf_map

 *     Return:

 *       == 0 current failed the cgroup2 descendant test

 *       == 1 current succeeded the cgroup2 descendant test

 *        < 0 error

 *

 * int bpf_skb_change_tail(skb, len, flags)

 *     The helper will resize the skb to the given new size, to be used f.e.

 *     with control messages.

 *     @skb: pointer to skb

 *     @len: new skb length

 *     @flags: reserved

 *     Return: 0 on success or negative error

 *

 * int bpf_skb_pull_data(skb, len)

 *     The helper will pull in non-linear data in case the skb is non-linear

 *     and not all of len are part of the linear section. Only needed for

 *     read/write with direct packet access.

 *     @skb: pointer to skb

 *     @len: len to make read/writeable

 *     Return: 0 on success or negative error

 *

 * s64 bpf_csum_update(skb, csum)

 *     Adds csum into skb->csum in case of CHECKSUM_COMPLETE.

 *     @skb: pointer to skb

 *     @csum: csum to add

 *     Return: csum on success or negative error

 *

 * void bpf_set_hash_invalid(skb)

 *     Invalidate current skb->hash.

 *     @skb: pointer to skb

 *

 * int bpf_get_numa_node_id()

 *     Return: Id of current NUMA node.

 *

 * int bpf_skb_change_head()

 *     Grows headroom of skb and adjusts MAC header offset accordingly.

 *     Will extends/reallocae as required automatically.

 *     May change skb data pointer and will thus invalidate any check

 *     performed for direct packet access.

 *     @skb: pointer to skb

 *     @len: length of header to be pushed in front

 *     @flags: Flags (unused for now)

 *     Return: 0 on success or negative error

 *

 * int bpf_xdp_adjust_head(xdp_md, delta)

 *     Adjust the xdp_md.data by delta

 *     @xdp_md: pointer to xdp_md

 *     @delta: An positive/negative integer to be added to xdp_md.data

 *     Return: 0 on success or negative on error

 *

 * int bpf_probe_read_str(void *dst, int size, const void *unsafe_ptr)

 *     Copy a NUL terminated string from unsafe address. In case the string

 *     length is smaller than size, the target is not padded with further NUL

 *     bytes. In case the string length is larger than size, just count-1

 *     bytes are copied and the last byte is set to NUL.

 *     @dst: destination address

 *     @size: maximum number of bytes to copy, including the trailing NUL

 *     @unsafe_ptr: unsafe address

 *     Return:

 *       > 0 length of the string including the trailing NUL on success

 *       < 0 error

 *

 * u64 bpf_get_socket_cookie(skb)

 *     Get the cookie for the socket stored inside sk_buff.

 *     @skb: pointer to skb

 *     Return: 8 Bytes non-decreasing number on success or 0 if the socket

 *     field is missing inside sk_buff

 *

 * u32 bpf_get_socket_uid(skb)

 *     Get the owner uid of the socket stored inside sk_buff.

 *     @skb: pointer to skb

 *     Return: uid of the socket owner on success or overflowuid if failed.

 *

 * u32 bpf_set_hash(skb, hash)

 *     Set full skb->hash.

 *     @skb: pointer to skb

 *     @hash: hash to set

 *

 * int bpf_setsockopt(bpf_socket, level, optname, optval, optlen)

 *     Calls setsockopt. Not all opts are available, only those with

 *     integer optvals plus TCP_CONGESTION.

 *     Supported levels: SOL_SOCKET and IPPROTO_TCP

 *     @bpf_socket: pointer to bpf_socket

 *     @level: SOL_SOCKET or IPPROTO_TCP

 *     @optname: option name

 *     @optval: pointer to option value

 *     @optlen: length of optval in bytes

 *     Return: 0 or negative error

 *

 * int bpf_getsockopt(bpf_socket, level, optname, optval, optlen)

 *     Calls getsockopt. Not all opts are available.

 *     Supported levels: IPPROTO_TCP

 *     @bpf_socket: pointer to bpf_socket

 *     @level: IPPROTO_TCP

 *     @optname: option name

 *     @optval: pointer to option value

 *     @optlen: length of optval in bytes

 *     Return: 0 or negative error

 *

 * int bpf_sock_ops_cb_flags_set(bpf_sock_ops, flags)

 *     Set callback flags for sock_ops

 *     @bpf_sock_ops: pointer to bpf_sock_ops_kern struct

 *     @flags: flags value

 *     Return: 0 for no error

 *             -EINVAL if there is no full tcp socket

 *             bits in flags that are not supported by current kernel

 *

 * int bpf_skb_adjust_room(skb, len_diff, mode, flags)

 *     Grow or shrink room in sk_buff.

 *     @skb: pointer to skb

 *     @len_diff: (signed) amount of room to grow/shrink

 *     @mode: operation mode (enum bpf_adj_room_mode)

 *     @flags: reserved for future use

 *     Return: 0 on success or negative error code

 *

 * int bpf_sk_redirect_map(map, key, flags)

 *     Redirect skb to a sock in map using key as a lookup key for the

 *     sock in map.

 *     @map: pointer to sockmap

 *     @key: key to lookup sock in map

 *     @flags: reserved for future use

 *     Return: SK_PASS

 *

 * int bpf_sock_map_update(skops, map, key, flags)

 *	@skops: pointer to bpf_sock_ops

 *	@map: pointer to sockmap to update

 *	@key: key to insert/update sock in map

 *	@flags: same flags as map update elem

 *

 * int bpf_xdp_adjust_meta(xdp_md, delta)

 *     Adjust the xdp_md.data_meta by delta

 *     @xdp_md: pointer to xdp_md

 *     @delta: An positive/negative integer to be added to xdp_md.data_meta

 *     Return: 0 on success or negative on error

 *

 * int bpf_perf_event_read_value(map, flags, buf, buf_size)

 *     read perf event counter value and perf event enabled/running time

 *     @map: pointer to perf_event_array map

 *     @flags: index of event in the map or bitmask flags

 *     @buf: buf to fill

 *     @buf_size: size of the buf

 *     Return: 0 on success or negative error code

 *

 * int bpf_perf_prog_read_value(ctx, buf, buf_size)

 *     read perf prog attached perf event counter and enabled/running time

 *     @ctx: pointer to ctx

 *     @buf: buf to fill

 *     @buf_size: size of the buf

 *     Return : 0 on success or negative error code

 *

 * int bpf_override_return(pt_regs, rc)

 *	@pt_regs: pointer to struct pt_regs

 *	@rc: the return value to set

 *

 * int bpf_msg_redirect_map(map, key, flags)

 *     Redirect msg to a sock in map using key as a lookup key for the

 *     sock in map.

 *     @map: pointer to sockmap

 *     @key: key to lookup sock in map

 *     @flags: reserved for future use

 *     Return: SK_PASS

 *

 * int bpf_bind(ctx, addr, addr_len)

 *     Bind socket to address. Only binding to IP is supported, no port can be

 *     set in addr.

 *     @ctx: pointer to context of type bpf_sock_addr

 *     @addr: pointer to struct sockaddr to bind socket to

 *     @addr_len: length of sockaddr structure

 *     Return: 0 on success or negative error code

 *

 * int bpf_xdp_adjust_tail(xdp_md, delta)

 *     Adjust the xdp_md.data_end by delta. Only shrinking of packet's

 *     size is supported.

 *     @xdp_md: pointer to xdp_md

 *     @delta: A negative integer to be added to xdp_md.data_end

 *     Return: 0 on success or negative on error

 *

 * int bpf_skb_get_xfrm_state(skb, index, xfrm_state, size, flags)

 *     retrieve XFRM state

 *     @skb: pointer to skb

 *     @index: index of the xfrm state in the secpath

 *     @key: pointer to 'struct bpf_xfrm_state'

 *     @size: size of 'struct bpf_xfrm_state'

 *     @flags: room for future extensions

 *     Return: 0 on success or negative error

/* The description below is an attempt at providing documentation to eBPF

 * developers about the multiple available eBPF helper functions. It can be

 * parsed and used to produce a manual page. The workflow is the following,

 * and requires the rst2man utility:

 *

 *     $ ./scripts/bpf_helpers_doc.py \

 *             --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst

 *     $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7

 *     $ man /tmp/bpf-helpers.7

 *

 * Note that in order to produce this external documentation, some RST

 * formatting is used in the descriptions to get "bold" and "italics" in

 * manual pages. Also note that the few trailing white spaces are

 * intentional, removing them would break paragraphs for rst2man.

 *

 * Start of BPF helper function descriptions:

 */

#define __BPF_FUNC_MAPPER(FN)		\

	FN(unspec),			\

scripts/bpf_helpers_doc.py

0 → 100755
+421 −0

File added.

Preview size limit exceeded, changes collapsed.

CRA Git | Maintained and supported by SUSTech CRA and CCSE