Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/BPF_CORE_READ.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ SEC("kprobe.multi/__netif_receive_skb_core*")
int bpf_prog1(struct pt_regs *ctx)
{
/* attaches to kprobe __netif_receive_skb_core,
* looks for packets on loobpack device and prints them
* looks for packets on loopback device and prints them
* (wildcard is used for avoiding symbol mismatch due to optimization)
*/
char devname[IFNAMSIZ];
Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/BPF_KPROBE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: "This page documents the 'BPF_KPROBE' libbpf eBPF macro, including
The `BPF_KPROBE` macro makes it easier to write [kprobe](../../../linux/program-type/BPF_PROG_TYPE_KPROBE.md) programs.

!!! note
The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefore, the variable name `ctx` should not be reused in arguments or function body.

## Definition

Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/BPF_KSYSCALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Traditionally a program author would have to use the [`PT_REGS_SYSCALL_REGS`](PT
The `BPF_KSYSCALL` macro allows you to write your program with an argument list, the macro will do the casting for you and accounts for the syscall wrapping.

!!! note
The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefore, the variable name `ctx` should not be reused in arguments or function body.

!!! warning
At the moment `BPF_KSYSCALL` does not transparently handle all the calling convention quirks for the following syscalls:
Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/BPF_PROG.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Conventionally with these program contexts, the arguments to the program are put
The `BPF_PROG` macro allows you to write your program with a normal function signature, the macro will then do the casting for you.

!!! note
The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefore, the variable name `ctx` should not be reused in arguments or function body.

!!! warning
This macro assumes a 1 to 1 conversion between a `u64` and argument. However, the Sys V calling convention allows types such as structs of up to 16 bytes to be passed over 2 registers and thus two `u64`s in the context. That breaks the assumption and may lead to hard to resolve bugs. The [`BPF_PROG2`](BPF_PROG2.md) macro is the improved version of this one which does account for this. Its recommend to use the second version when you might be dealing with arguments larger than 8 bytes.
Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/BPF_PROG2.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The `BPF_PROG2` macro allows you to write your program with a normal function si
This macro also accounts for an edge case in the <nospell>Sys V</nospell> calling convention. When a function call is made, every argument will be put in specific registers. When a variable is to large to put in a register (8 bytes) it is often put on the stack and a pointer to it is passed instead (pointers being 8 bytes). However, the <nospell>Sys V</nospell> calling convention specifies that if a variable is between 8 and 16 bytes, it may be transferred using 2 registers instead, for a `struct{u64, u64}` for example. Since the context is a translation of the arguments passed, it to can use one or two slots depending on the type. The `BPF_PROG2` handles this in the background, which is what improved over the [`BPF_PROG`](BPF_PROG.md) version of this macro.

!!! note
The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefore, the variable name `ctx` should not be reused in arguments or function body.

### Example

Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/PT_REGS_PARM.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ SEC("kprobe.multi/__netif_receive_skb_core*")
int bpf_prog1(struct pt_regs *ctx)
{
/* attaches to kprobe __netif_receive_skb_core,
* looks for packets on loobpack device and prints them
* looks for packets on loopback device and prints them
* (wildcard is used for avoiding symbol mismatch due to optimization)
*/
char devname[IFNAMSIZ];
Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/__arg_ctx.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The `__arg_ctx` macros is used to tag a function argument to tell the verifier t

## Usage

This macro can be used to tag a function argument of a [global function](../../../linux/concepts/functions.md#function-by-function-verification) if you want to write that function in such a way that it can be re-used between different program types. Global functions are verified function-by-function, so the function can be verifier before any of its callers. The verifier therefore has to use type info to determine possible values. The verifier will already implicitly associate types such as `struct __sk_buff*` and `struct xdp_md*` with the program context and assert only the actual, valid context is passed. However, a function that can work with multiple program contexts needs to use `void *` to be able to compile, which means the verifier is missing type info. When this becomes an issue you can add the `__arg_ctx` macro to the function argument to tell the verifier that the argument is a program context. The verifier will treat the argument as a program context for all intents and purposes and it will enforce a valid context is passed on the call site.
This macro can be used to tag a function argument of a [global function](../../../linux/concepts/functions.md#function-by-function-verification) if you want to write that function in such a way that it can be reused between different program types. Global functions are verified function-by-function, so the function can be verifier before any of its callers. The verifier therefore has to use type info to determine possible values. The verifier will already implicitly associate types such as `struct __sk_buff*` and `struct xdp_md*` with the program context and assert only the actual, valid context is passed. However, a function that can work with multiple program contexts needs to use `void *` to be able to compile, which means the verifier is missing type info. When this becomes an issue you can add the `__arg_ctx` macro to the function argument to tell the verifier that the argument is a program context. The verifier will treat the argument as a program context for all intents and purposes and it will enforce a valid context is passed on the call site.

### Example

Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/__kconfig.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ enum libbpf_tristate {

This enum type is also provided by the `bpf_helpers.h` file.

This capability ties into CO-RE (Compile Once - Run Everywhere). Since the value is provided at load time it allows the user to write multiple variations / code paths that are enabled or disabled based on the value of, for example, in this case a kernel configuration option. Therefor allowing the same pre-compiled eBPF program to be loaded on different systems with different kernel configurations.
This capability ties into CO-RE (Compile Once - Run Everywhere). Since the value is provided at load time it allows the user to write multiple variations / code paths that are enabled or disabled based on the value of, for example, in this case a kernel configuration option. Therefore allowing the same pre-compiled eBPF program to be loaded on different systems with different kernel configurations.

If a value for a kernel configuration option is not found, the loader (library) will error out, unless the [`__weak`](__weak.md) attribute is also used.

Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/bpf_core_read.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ struct some_value dst;
bpf_core_read(&dst, sizeof(dst), a.c.d);
```

Since `src` contains the field accesses, these fill be stored in the relocation entry so the actual offset can be adjusted. It is therefor important to not do the field access outside of the `bpf_core_read`:
Since `src` contains the field accesses, these fill be stored in the relocation entry so the actual offset can be adjusted. It is therefore important to not do the field access outside of the `bpf_core_read`:

```c
/* Incorrect */
Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libbpf/ebpf/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ The file contains definitions for the following:

## [`bpf_endian.h`](https://github.com/libbpf/libbpf/blob/master/src/bpf_endian.h)

The `bpf_endian.h` file contains macros for endianess conversion. It is useful when you need to convert data between host and network byte order.
The `bpf_endian.h` file contains macros for endianness conversion. It is useful when you need to convert data between host and network byte order.

The file contains definitions for the following:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This function allow to access a specific transmit descriptor in the **TX** ring.

### Returns

`struct xdp_desc`, informations about the packet to be transmitted.
`struct xdp_desc`, information about the packet to be transmitted.

## Usage

Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/libxdp/libxdp.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
libxdp is a light eBPF library who add 2 features for [XDP programs](../../linux/program-type/BPF_PROG_TYPE_XDP.md).

- Load multiple programs on single network device using a "dispatcher program" thanks to [`freplace`](../../linux/program-type/BPF_PROG_TYPE_EXT.md)
- Configuring [`AF_XDP`](../../linux/concepts/af_xdp.md) and functions to read and write on theses sockets
- Configuring [`AF_XDP`](../../linux/concepts/af_xdp.md) and functions to read and write on these sockets

You can check more information on the [libxdp readme](https://github.com/xdp-project/xdp-tools/blob/master/lib/libxdp/README.org).

Expand Down
2 changes: 1 addition & 1 deletion docs/ebpf-library/scx/READ_ONCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ static __always_inline void __read_once_size(const volatile void *p, void *res,

Compilers will try to optimize code in any way possible within the constraints they are aware of. They may for example:

* Keep the result of a memory read in a register and re-use it instead of re-reading the memory location. (caching)
* Keep the result of a memory read in a register and reuse it instead of re-reading the memory location. (caching)
* Reorder reads to improve cache locality (reordering)
* Re-read from memory instead of keeping the value in a register (redoing)

Expand Down
2 changes: 1 addition & 1 deletion docs/linux/concepts/af_xdp.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ In the above diagram you can see our UMEM section, the 4 ring buffers, the kerne

The ring buffers are used to communicate between the process and the kernel. If done correctly, it allows for a bi-directional data stream using the same pre-allocated memory blocks without the need for spin-locks or other synchronization techniques.

The ring buffers are single-producer, single-consumer ring buffers. The rings consists of the actual array of descriptors (`#!c struct xdp_desc`), a `producer` and a `consumer`. In our diagram we refer to the `producer` as `head` and `consumer` as `tail` since those are the more typical terms used for queues/ring buffers. The kernel updates the `producer`/`head` of the RX and COMPLETION buffers and the process updated the `producer`/`head` of the TX and FILL buffers. The consumer watches for changes in the `producer`/`head`, if updated, it is safe to read the UMEM chunks between the `tail`/`consumer` and `producer`/`head`. The consumer increments the `tail`/`consumer` to indicate to the producer that the spot on the ring can be re-used. The descriptors in the ring contain a `addr` field which is the offset into the UMEM indicating the chunk, a `len` field indicating the length of any data in the chunk and a `flags` field.
The ring buffers are single-producer, single-consumer ring buffers. The rings consists of the actual array of descriptors (`#!c struct xdp_desc`), a `producer` and a `consumer`. In our diagram we refer to the `producer` as `head` and `consumer` as `tail` since those are the more typical terms used for queues/ring buffers. The kernel updates the `producer`/`head` of the RX and COMPLETION buffers and the process updated the `producer`/`head` of the TX and FILL buffers. The consumer watches for changes in the `producer`/`head`, if updated, it is safe to read the UMEM chunks between the `tail`/`consumer` and `producer`/`head`. The consumer increments the `tail`/`consumer` to indicate to the producer that the spot on the ring can be reused. The descriptors in the ring contain a `addr` field which is the offset into the UMEM indicating the chunk, a `len` field indicating the length of any data in the chunk and a `flags` field.

When we start all chunks are owned by the process, which means it can safely read and write without fear of race conditions.

Expand Down
2 changes: 1 addition & 1 deletion docs/linux/concepts/functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Until [:octicons-tag-24: v5.6](https://github.com/torvalds/linux/commit/51c39bb1

Since [:octicons-tag-24: v5.6](https://github.com/torvalds/linux/commit/51c39bb1d5d105a02e29aa7960f0a395086e6342) a distinction is made between "static" and "global" functions. Static functions are functions marked with the `static` keyword in the C code, global functions regular non-static functions. Static functions are still verified as usual. But global functions undergo "function by function verification". This means that the verifier will verify every function once, and even out of order. So every function is verified exactly once, and not per-call site anymore. This change reduces verification times and complexity. But the verifier does impose a lot more limitations.

The verifier will assume no information about arguments, since it will not check every call site anymore. So even tough a function is only ever called with a `u32` of `123`, the verifier will assume the full `0`-`4294967295` are possible values. Therefor, functions might require more input checking to pass the verifier.
The verifier will assume no information about arguments, since it will not check every call site anymore. So even tough a function is only ever called with a `u32` of `123`, the verifier will assume the full `0`-`4294967295` are possible values. Therefore, functions might require more input checking to pass the verifier.

The verifier also limits the return type to always be scalar (a number). And the arguments to be pointer to a program context and scalars. This limitation on arguments was widen in later kernel releases, see later sections.

Expand Down
2 changes: 1 addition & 1 deletion docs/linux/concepts/kfuncs.md
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,7 @@ The verifier will guarantee that an iterator is destroyed by a function with the

The `KF_ITER_NEXT` flag is used to indicate that the KFunc is used to advance an iterator. This means that the KFunc will take a pointer to an iterator and advance it to the next object.

The verifier will enforce that a `KF_ITER_NEXT` KFunc is only called with an interator created a `KF_ITER_NEW` KFunc. Typically a `KF_ITER_NEW` KFunc will have a corresponding `KF_ITER_NEXT` KFunc, such pairs are easy to spot.
The verifier will enforce that a `KF_ITER_NEXT` KFunc is only called with an iterator created a `KF_ITER_NEW` KFunc. Typically a `KF_ITER_NEW` KFunc will have a corresponding `KF_ITER_NEXT` KFunc, such pairs are easy to spot.

### `KF_ITER_DESTROY`

Expand Down
2 changes: 1 addition & 1 deletion docs/linux/helper-function/bpf_map_lookup_elem.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Map value associated to _key_, or **NULL** if no entry was found.
The `map` argument must be a pointer to a map definition and `key` must be a pointer to the key you
wish to lookup.

The return value will be a pointer to the map value or `NULL`. The value is a direct reference to the kernel memory where this map value is stored, not a copy. Therefor any modifications made to the value are automatically persisted without the need to call any additional helpers.
The return value will be a pointer to the map value or `NULL`. The value is a direct reference to the kernel memory where this map value is stored, not a copy. Therefore any modifications made to the value are automatically persisted without the need to call any additional helpers.

!!! warning
modifying map values of non per-CPU maps is subject to race conditions, atomic instructions or spinlocks must be utilized to prevent race conditions if they are detrimental to your use case.
Expand Down
2 changes: 1 addition & 1 deletion docs/linux/map-type/BPF_MAP_TYPE_ARRAY.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The array map type is a generic map type with no restrictions on the structure o

While the [`value_size`](../syscall/BPF_MAP_CREATE.md#value_size) is essentially unrestricted, the [`key_size`](../syscall/BPF_MAP_CREATE.md#key_size) must always be `4` indicating the key is a 32-bit unsigned integer.

The value of [`value_size`](../syscall/BPF_MAP_CREATE.md#value_size) shouldn't exceed `KMALLOC_MAX_SIZE`. `KMALLOC_MAX_SIZE` is the maximum size which can be allocated by the kernel memory allocator, its exact value being dependant on a number of factors. If this edge case is hit a `-E2BIG` [error number](https://man7.org/linux/man-pages/man3/errno.3.html) is returned to the [map create syscall](../syscall/BPF_MAP_CREATE.md).
The value of [`value_size`](../syscall/BPF_MAP_CREATE.md#value_size) shouldn't exceed `KMALLOC_MAX_SIZE`. `KMALLOC_MAX_SIZE` is the maximum size which can be allocated by the kernel memory allocator, its exact value being dependent on a number of factors. If this edge case is hit a `-E2BIG` [error number](https://man7.org/linux/man-pages/man3/errno.3.html) is returned to the [map create syscall](../syscall/BPF_MAP_CREATE.md).

<!-- TODO link to generic page for attributes which are the same for every map type -->

Expand Down
2 changes: 1 addition & 1 deletion docs/linux/map-type/BPF_MAP_TYPE_HASH.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The hash map type is a generic map type with no restrictions on the structure of

## Attributes

While the size of the key and value are essentially unrestricted, both [`value_size`](../syscall/BPF_MAP_CREATE.md#value_size) and [`key_size`](../syscall/BPF_MAP_CREATE.md#key_size) must be at least zero and their combined size no larger than `KMALLOC_MAX_SIZE`. `KMALLOC_MAX_SIZE` is the maximum size which can be allocated by the kernel memory allocator, its exact value being dependant on a number of factors. If this edge case is hit a `-E2BIG` [error number](https://man7.org/linux/man-pages/man3/errno.3.html) is returned to the [map create syscall](../syscall/BPF_MAP_CREATE.md).
While the size of the key and value are essentially unrestricted, both [`value_size`](../syscall/BPF_MAP_CREATE.md#value_size) and [`key_size`](../syscall/BPF_MAP_CREATE.md#key_size) must be at least zero and their combined size no larger than `KMALLOC_MAX_SIZE`. `KMALLOC_MAX_SIZE` is the maximum size which can be allocated by the kernel memory allocator, its exact value being dependent on a number of factors. If this edge case is hit a `-E2BIG` [error number](https://man7.org/linux/man-pages/man3/errno.3.html) is returned to the [map create syscall](../syscall/BPF_MAP_CREATE.md).

<!-- TODO link to generic page for attributes which are the same for every map type -->

Expand Down
Loading