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
305305 bpf_task_release(lookup);
306306 return 0;
307307 }
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+ }
kernel/bpf/helpers.c+1−1
@@ -1960,7 +1960,7 @@ struct cgroup *bpf_cgroup_kptr_get(struct cgroup **cgrpp) · 1959 unmodified lines
19601960 }
19611961
19621962 /**
1963− * bpf_cgroup_release - Release the reference acquired on a struct cgroup *.
1963+ * bpf_cgroup_release - Release the reference acquired on a cgroup.
19641964 * If this kfunc is invoked in an RCU read region, the cgroup is guaranteed to
19651965 * not be freed until the current grace period has ended, even if its refcount
19661966 * 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