Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 0eb09785 authored by Quentin Monnet's avatar Quentin Monnet Committed by Alexei Starovoitov
Browse files

bpf: add documentation for helpers bpf_spin_lock(), bpf_spin_unlock() 



Add documentation for the BPF spinlock-related helpers to the doc in
bpf.h. I added the constraints and restrictions coming with the use of
spinlocks for BPF: not all of it is directly related to the use of the
helper, but I thought it would be nice for users to find them in the man
page.

This list of restrictions is nearly a verbatim copy of the list in
Alexei's commit log for those helpers.

Signed-off-by: default avatarQuentin Monnet <quentin.monnet@netronome.com>
Reviewed-by: default avatarJakub Kicinski <jakub.kicinski@netronome.com>
Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parent 62369db2

include/uapi/linux/bpf.h

+55 −0
Original line number Diff line number Diff line
@@ -2343,6 +2343,61 @@ union bpf_attr { 
 *	Return

 *		0

 *

 * int bpf_spin_lock(struct bpf_spin_lock *lock)

 *	Description

 *		Acquire a spinlock represented by the pointer *lock*, which is

 *		stored as part of a value of a map. Taking the lock allows to

 *		safely update the rest of the fields in that value. The

 *		spinlock can (and must) later be released with a call to

 *		**bpf_spin_unlock**\ (\ *lock*\ ).

 *

 *		Spinlocks in BPF programs come with a number of restrictions

 *		and constraints:

 *

 *		* **bpf_spin_lock** objects are only allowed inside maps of

 *		  types **BPF_MAP_TYPE_HASH** and **BPF_MAP_TYPE_ARRAY** (this

 *		  list could be extended in the future).

 *		* BTF description of the map is mandatory.

 *		* The BPF program can take ONE lock at a time, since taking two

 *		  or more could cause dead locks.

 *		* Only one **struct bpf_spin_lock** is allowed per map element.

 *		* When the lock is taken, calls (either BPF to BPF or helpers)

 *		  are not allowed.

 *		* The **BPF_LD_ABS** and **BPF_LD_IND** instructions are not

 *		  allowed inside a spinlock-ed region.

 *		* The BPF program MUST call **bpf_spin_unlock**\ () to release

 *		  the lock, on all execution paths, before it returns.

 *		* The BPF program can access **struct bpf_spin_lock** only via

 *		  the **bpf_spin_lock**\ () and **bpf_spin_unlock**\ ()

 *		  helpers. Loading or storing data into the **struct

 *		  bpf_spin_lock** *lock*\ **;** field of a map is not allowed.

 *		* To use the **bpf_spin_lock**\ () helper, the BTF description

 *		  of the map value must be a struct and have **struct

 *		  bpf_spin_lock** *anyname*\ **;** field at the top level.

 *		  Nested lock inside another struct is not allowed.

 *		* The **struct bpf_spin_lock** *lock* field in a map value must

 *		  be aligned on a multiple of 4 bytes in that value.

 *		* Syscall with command **BPF_MAP_LOOKUP_ELEM** does not copy

 *		  the **bpf_spin_lock** field to user space.

 *		* Syscall with command **BPF_MAP_UPDATE_ELEM**, or update from

 *		  a BPF program, do not update the **bpf_spin_lock** field.

 *		* **bpf_spin_lock** cannot be on the stack or inside a

 *		  networking packet (it can only be inside of a map values).

 *		* **bpf_spin_lock** is available to root only.

 *		* Tracing programs and socket filter programs cannot use

 *		  **bpf_spin_lock**\ () due to insufficient preemption checks

 *		  (but this may change in the future).

 *		* **bpf_spin_lock** is not allowed in inner maps of map-in-map.

 *	Return

 *		0

 *

 * int bpf_spin_unlock(struct bpf_spin_lock *lock)

 *	Description

 *		Release the *lock* previously locked by a call to

 *		**bpf_spin_lock**\ (\ *lock*\ ).

 *	Return

 *		0

 *

 * struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk)

 *	Description

 *		This helper gets a **struct bpf_sock** pointer such