Commit | Line | Data |
---|---|---|
d4319801 YS |
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``. |