1 .. SPDX-License-Identifier: GPL-2.0-only
2 .. Copyright (C) 2022 Meta Platforms, Inc. and affiliates.
3
4 =========================
5 BPF_MAP_TYPE_CGRP_STORAGE
6 =========================
7
8 The ``BPF_MAP_TYPE_CGRP_STORAGE`` map type represents a local fix-sized
9 storage for cgroups. It is only available with ``CONFIG_CGROUPS``.
10 The programs are made available by the same Kconfig. The
11 data for a particular cgroup can be retrieved by looking up the map
12 with that cgroup.
13
14 This document describes the usage and semantics of the
15 ``BPF_MAP_TYPE_CGRP_STORAGE`` map type.
16
17 Usage
18 =====
19
20 The map key must be ``sizeof(int)`` representing a cgroup fd.
21 To access the storage in a program, use ``bpf_cgrp_storage_get``::
22
23 void *bpf_cgrp_storage_get(struct bpf_map *map, struct cgroup *cgroup, void *value, u64 flags)
24
25 ``flags`` could be 0 or ``BPF_LOCAL_STORAGE_GET_F_CREATE`` which indicates that
26 a new local storage will be created if one does not exist.
27
28 The local storage can be removed with ``bpf_cgrp_storage_delete``::
29
30 long bpf_cgrp_storage_delete(struct bpf_map *map, struct cgroup *cgroup)
31
32 The map is available to all program types.
33
34 Examples
35 ========
36
37 A BPF program example with BPF_MAP_TYPE_CGRP_STORAGE::
38
39 #include <vmlinux.h>
40 #include <bpf/bpf_helpers.h>
41 #include <bpf/bpf_tracing.h>
42
43 struct {
44 __uint(type, BPF_MAP_TYPE_CGRP_STORAGE);
45 __uint(map_flags, BPF_F_NO_PREALLOC);
46 __type(key, int);
47 __type(value, long);
48 } cgrp_storage SEC(".maps");
49
50 SEC("tp_btf/sys_enter")
51 int BPF_PROG(on_enter, struct pt_regs *regs, long id)
52 {
53 struct task_struct *task = bpf_get_current_task_btf();
54 long *ptr;
55
56 ptr = bpf_cgrp_storage_get(&cgrp_storage, task->cgroups->dfl_cgrp, 0,
57 BPF_LOCAL_STORAGE_GET_F_CREATE);
58 if (ptr)
59 __sync_fetch_and_add(ptr, 1);
60
61 return 0;
62 }
63
64 Userspace accessing map declared above::
65
66 #include <linux/bpf.h>
67 #include <linux/libbpf.h>
68
69 __u32 map_lookup(struct bpf_map *map, int cgrp_fd)
70 {
71 __u32 *value;
72 value = bpf_map_lookup_elem(bpf_map__fd(map), &cgrp_fd);
73 if (value)
74 return *value;
75 return 0;
76 }
77
78 Difference Between BPF_MAP_TYPE_CGRP_STORAGE and BPF_MAP_TYPE_CGROUP_STORAGE
79 ============================================================================
80
81 The old cgroup storage map ``BPF_MAP_TYPE_CGROUP_STORAGE`` has been marked as
82 deprecated (renamed to ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``). The new
83 ``BPF_MAP_TYPE_CGRP_STORAGE`` map should be used instead. The following
84 illusates the main difference between ``BPF_MAP_TYPE_CGRP_STORAGE`` and
85 ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``.
86
87 (1). ``BPF_MAP_TYPE_CGRP_STORAGE`` can be used by all program types while
88 ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` is available only to cgroup program types
89 like BPF_CGROUP_INET_INGRESS or BPF_CGROUP_SOCK_OPS, etc.
90
91 (2). ``BPF_MAP_TYPE_CGRP_STORAGE`` supports local storage for more than one
92 cgroup while ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` only supports one cgroup
93 which is attached by a BPF program.
94
95 (3). ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` allocates local storage at attach time so
96 ``bpf_get_local_storage()`` always returns non-NULL local storage.
97 ``BPF_MAP_TYPE_CGRP_STORAGE`` allocates local storage at runtime so
98 it is possible that ``bpf_cgrp_storage_get()`` may return null local storage.
99 To avoid such null local storage issue, user space can do
100 ``bpf_map_update_elem()`` to pre-allocate local storage before a BPF program
101 is attached.
102
103 (4). ``BPF_MAP_TYPE_CGRP_STORAGE`` supports deleting local storage by a BPF program
104 while ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` only deletes storage during
105 prog detach time.
106
107 So overall, ``BPF_MAP_TYPE_CGRP_STORAGE`` supports all ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``
108 functionality and beyond. It is recommended to use ``BPF_MAP_TYPE_CGRP_STORAGE``
109 instead of ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.