History

bpf/docs: Document struct cgroup * kfuncs

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.

David Vernet committed 3 years ago

Commit 36aa10f1 parent 25c5e922 files · +116 −1Browse files

Unified · Split

2 files
  1. Documentation/bpf/kfuncs.rst +115 −0
  2. kernel/bpf/helpers.c +1 −1
Documentation/bpf/kfuncs.rst+115−0
@@ -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
3093.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
317These kfuncs are used in exactly the same manner as bpf_task_acquire() and
318bpf_task_release() respectively, so we won't provide examples for them.
319
320----
321
322You may also acquire a reference to a ``struct cgroup`` kptr that's already
323stored in a map using bpf_cgroup_kptr_get():
324
325.. kernel-doc:: kernel/bpf/helpers.c
326 :identifiers: bpf_cgroup_kptr_get
327
328Here'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
390Another kfunc available for interacting with ``struct cgroup *`` objects is
391bpf_cgroup_ancestor(). This allows callers to access the ancestor of a cgroup,
392and return it as a cgroup kptr.
393
394.. kernel-doc:: kernel/bpf/helpers.c
395 :identifiers: bpf_cgroup_ancestor
396
397Eventually, BPF should be updated to allow this to happen with a normal memory
398load in the program itself. This is currently not possible without more work in
399the 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 }
kernel/bpf/helpers.c+1−1
@@ -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 to1964 * 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 refcount1965 * not be freed until the current grace period has ended, even if its refcount
1966 * drops to 0.1966 * drops to 0.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t