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.
Showing the changes to include/uapi/linux (1 of 1 file). Show all
Unified · Split
| @@ -2343,6 +2343,61 @@ union bpf_attr { · 2342 unmodified lines | ||
| 2343 | 2343 | * Return |
| 2344 | 2344 | * 0 |
| 2345 | 2345 | * |
| 2346 | + * int bpf_spin_lock(struct bpf_spin_lock *lock) | |
| 2347 | + * Description | |
| 2348 | + * Acquire a spinlock represented by the pointer *lock*, which is | |
| 2349 | + * stored as part of a value of a map. Taking the lock allows to | |
| 2350 | + * safely update the rest of the fields in that value. The | |
| 2351 | + * spinlock can (and must) later be released with a call to | |
| 2352 | + * **bpf_spin_unlock**\ (\ *lock*\ ). | |
| 2353 | + * | |
| 2354 | + * Spinlocks in BPF programs come with a number of restrictions | |
| 2355 | + * and constraints: | |
| 2356 | + * | |
| 2357 | + * * **bpf_spin_lock** objects are only allowed inside maps of | |
| 2358 | + * types **BPF_MAP_TYPE_HASH** and **BPF_MAP_TYPE_ARRAY** (this | |
| 2359 | + * list could be extended in the future). | |
| 2360 | + * * BTF description of the map is mandatory. | |
| 2361 | + * * The BPF program can take ONE lock at a time, since taking two | |
| 2362 | + * or more could cause dead locks. | |
| 2363 | + * * Only one **struct bpf_spin_lock** is allowed per map element. | |
| 2364 | + * * When the lock is taken, calls (either BPF to BPF or helpers) | |
| 2365 | + * are not allowed. | |
| 2366 | + * * The **BPF_LD_ABS** and **BPF_LD_IND** instructions are not | |
| 2367 | + * allowed inside a spinlock-ed region. | |
| 2368 | + * * The BPF program MUST call **bpf_spin_unlock**\ () to release | |
| 2369 | + * the lock, on all execution paths, before it returns. | |
| 2370 | + * * The BPF program can access **struct bpf_spin_lock** only via | |
| 2371 | + * the **bpf_spin_lock**\ () and **bpf_spin_unlock**\ () | |
| 2372 | + * helpers. Loading or storing data into the **struct | |
| 2373 | + * bpf_spin_lock** *lock*\ **;** field of a map is not allowed. | |
| 2374 | + * * To use the **bpf_spin_lock**\ () helper, the BTF description | |
| 2375 | + * of the map value must be a struct and have **struct | |
| 2376 | + * bpf_spin_lock** *anyname*\ **;** field at the top level. | |
| 2377 | + * Nested lock inside another struct is not allowed. | |
| 2378 | + * * The **struct bpf_spin_lock** *lock* field in a map value must | |
| 2379 | + * be aligned on a multiple of 4 bytes in that value. | |
| 2380 | + * * Syscall with command **BPF_MAP_LOOKUP_ELEM** does not copy | |
| 2381 | + * the **bpf_spin_lock** field to user space. | |
| 2382 | + * * Syscall with command **BPF_MAP_UPDATE_ELEM**, or update from | |
| 2383 | + * a BPF program, do not update the **bpf_spin_lock** field. | |
| 2384 | + * * **bpf_spin_lock** cannot be on the stack or inside a | |
| 2385 | + * networking packet (it can only be inside of a map values). | |
| 2386 | + * * **bpf_spin_lock** is available to root only. | |
| 2387 | + * * Tracing programs and socket filter programs cannot use | |
| 2388 | + * **bpf_spin_lock**\ () due to insufficient preemption checks | |
| 2389 | + * (but this may change in the future). | |
| 2390 | + * * **bpf_spin_lock** is not allowed in inner maps of map-in-map. | |
| 2391 | + * Return | |
| 2392 | + * 0 | |
| 2393 | + * | |
| 2394 | + * int bpf_spin_unlock(struct bpf_spin_lock *lock) | |
| 2395 | + * Description | |
| 2396 | + * Release the *lock* previously locked by a call to | |
| 2397 | + * **bpf_spin_lock**\ (\ *lock*\ ). | |
| 2398 | + * Return | |
| 2399 | + * 0 | |
| 2400 | + * | |
| 2346 | 2401 | * struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk) |
| 2347 | 2402 | * Description |
| 2348 | 2403 | * This helper gets a **struct bpf_sock** pointer such |