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 | * Return | 2343 | * Return |
| 2344 | * 0 | 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 | * struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk) | 2401 | * struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk) |
| 2347 | * Description | 2402 | * Description |
| 2348 | * This helper gets a **struct bpf_sock** pointer such | 2403 | * This helper gets a **struct bpf_sock** pointer such |