bpf_cgroup_acquire(), bpf_cgroup_release(), bpf_cgroup_kptr_get(), and bpf_cgroup_ancestor(), are kfuncs that were recently added to kernel/bpf/helpers.c. These are "core" kfuncs in that they're available for use in any tracepoint or struct_ops BPF program. Though they have no ABI stability guarantees, we should still document them. This patch adds a struct cgroup * subsection to the Core kfuncs section which describes each of these kfuncs.
Unified · Split
| @@ -305,3 +305,118 @@ Here is an example of it being used: · 304 unmodified lines | |||
| 305 | bpf_task_release(lookup); | 305 | bpf_task_release(lookup); |
| 306 | return 0; | 306 | return 0; |
| 307 | } | 307 | } |
| 308 | |||
| 309 | 3.2 struct cgroup * kfuncs | ||
| 310 | -------------------------- | ||
| 311 | |||
| 312 | ``struct cgroup *`` objects also have acquire and release functions: | ||
| 313 | |||
| 314 | .. kernel-doc:: kernel/bpf/helpers.c | ||
| 315 | :identifiers: bpf_cgroup_acquire bpf_cgroup_release | ||
| 316 | |||
| 317 | These kfuncs are used in exactly the same manner as bpf_task_acquire() and | ||
| 318 | bpf_task_release() respectively, so we won't provide examples for them. | ||
| 319 | |||
| 320 | ---- | ||
| 321 | |||
| 322 | You may also acquire a reference to a ``struct cgroup`` kptr that's already | ||
| 323 | stored in a map using bpf_cgroup_kptr_get(): | ||
| 324 | |||
| 325 | .. kernel-doc:: kernel/bpf/helpers.c | ||
| 326 | :identifiers: bpf_cgroup_kptr_get | ||
| 327 | |||
| 328 | Here's an example of how it can be used: | ||
| 329 | |||
| 330 | .. code-block:: c | ||
| 331 | |||
| 332 | /* struct containing the struct task_struct kptr which is actually stored in the map. */ | ||
| 333 | struct __cgroups_kfunc_map_value { | ||
| 334 | struct cgroup __kptr_ref * cgroup; | ||
| 335 | }; | ||
| 336 | |||
| 337 | /* The map containing struct __cgroups_kfunc_map_value entries. */ | ||
| 338 | struct { | ||
| 339 | __uint(type, BPF_MAP_TYPE_HASH); | ||
| 340 | __type(key, int); | ||
| 341 | __type(value, struct __cgroups_kfunc_map_value); | ||
| 342 | __uint(max_entries, 1); | ||
| 343 | } __cgroups_kfunc_map SEC(".maps"); | ||
| 344 | |||
| 345 | /* ... */ | ||
| 346 | |||
| 347 | /** | ||
| 348 | * A simple example tracepoint program showing how a | ||
| 349 | * struct cgroup kptr that is stored in a map can | ||
| 350 | * be acquired using the bpf_cgroup_kptr_get() kfunc. | ||
| 351 | */ | ||
| 352 | SEC("tp_btf/cgroup_mkdir") | ||
| 353 | int BPF_PROG(cgroup_kptr_get_example, struct cgroup *cgrp, const char *path) | ||
| 354 | { | ||
| 355 | struct cgroup *kptr; | ||
| 356 | struct __cgroups_kfunc_map_value *v; | ||
| 357 | s32 id = cgrp->self.id; | ||
| 358 | |||
| 359 | /* Assume a cgroup kptr was previously stored in the map. */ | ||
| 360 | v = bpf_map_lookup_elem(&__cgroups_kfunc_map, &id); | ||
| 361 | if (!v) | ||
| 362 | return -ENOENT; | ||
| 363 | |||
| 364 | /* Acquire a reference to the cgroup kptr that's already stored in the map. */ | ||
| 365 | kptr = bpf_cgroup_kptr_get(&v->cgroup); | ||
| 366 | if (!kptr) | ||
| 367 | /* If no cgroup was present in the map, it's because | ||
| 368 | * we're racing with another CPU that removed it with | ||
| 369 | * bpf_kptr_xchg() between the bpf_map_lookup_elem() | ||
| 370 | * above, and our call to bpf_cgroup_kptr_get(). | ||
| 371 | * bpf_cgroup_kptr_get() internally safely handles this | ||
| 372 | * race, and will return NULL if the task is no longer | ||
| 373 | * present in the map by the time we invoke the kfunc. | ||
| 374 | */ | ||
| 375 | return -EBUSY; | ||
| 376 | |||
| 377 | /* Free the reference we just took above. Note that the | ||
| 378 | * original struct cgroup kptr is still in the map. It will | ||
| 379 | * be freed either at a later time if another context deletes | ||
| 380 | * it from the map, or automatically by the BPF subsystem if | ||
| 381 | * it's still present when the map is destroyed. | ||
| 382 | */ | ||
| 383 | bpf_cgroup_release(kptr); | ||
| 384 | |||
| 385 | return 0; | ||
| 386 | } | ||
| 387 | |||
| 388 | ---- | ||
| 389 | |||
| 390 | Another kfunc available for interacting with ``struct cgroup *`` objects is | ||
| 391 | bpf_cgroup_ancestor(). This allows callers to access the ancestor of a cgroup, | ||
| 392 | and return it as a cgroup kptr. | ||
| 393 | |||
| 394 | .. kernel-doc:: kernel/bpf/helpers.c | ||
| 395 | :identifiers: bpf_cgroup_ancestor | ||
| 396 | |||
| 397 | Eventually, BPF should be updated to allow this to happen with a normal memory | ||
| 398 | load in the program itself. This is currently not possible without more work in | ||
| 399 | the verifier. bpf_cgroup_ancestor() can be used as follows: | ||
| 400 | |||
| 401 | .. code-block:: c | ||
| 402 | |||
| 403 | /** | ||
| 404 | * Simple tracepoint example that illustrates how a cgroup's | ||
| 405 | * ancestor can be accessed using bpf_cgroup_ancestor(). | ||
| 406 | */ | ||
| 407 | SEC("tp_btf/cgroup_mkdir") | ||
| 408 | int BPF_PROG(cgrp_ancestor_example, struct cgroup *cgrp, const char *path) | ||
| 409 | { | ||
| 410 | struct cgroup *parent; | ||
| 411 | |||
| 412 | /* The parent cgroup resides at the level before the current cgroup's level. */ | ||
| 413 | parent = bpf_cgroup_ancestor(cgrp, cgrp->level - 1); | ||
| 414 | if (!parent) | ||
| 415 | return -ENOENT; | ||
| 416 | |||
| 417 | bpf_printk("Parent id is %d", parent->self.id); | ||
| 418 | |||
| 419 | /* Return the parent cgroup that was acquired above. */ | ||
| 420 | bpf_cgroup_release(parent); | ||
| 421 | return 0; | ||
| 422 | } | ||
| @@ -1960,7 +1960,7 @@ struct cgroup *bpf_cgroup_kptr_get(struct cgroup **cgrpp) · 1959 unmodified lines | |||
| 1960 | } | 1960 | } |
| 1961 | 1961 | ||
| 1962 | /** | 1962 | /** |
| 1963 | * bpf_cgroup_release - Release the reference acquired on a struct cgroup *. | 1963 | * bpf_cgroup_release - Release the reference acquired on a cgroup. |
| 1964 | * If this kfunc is invoked in an RCU read region, the cgroup is guaranteed to | 1964 | * If this kfunc is invoked in an RCU read region, the cgroup is guaranteed to |
| 1965 | * not be freed until the current grace period has ended, even if its refcount | 1965 | * not be freed until the current grace period has ended, even if its refcount |
| 1966 | * drops to 0. | 1966 | * drops to 0. |