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 | 305 | bpf_task_release(lookup); |
| 306 | 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 | 1964 | * If this kfunc is invoked in an RCU read region, the cgroup is guaranteed to |
| 1965 | 1965 | * not be freed until the current grace period has ended, even if its refcount |
| 1966 | 1966 | * drops to 0. |