1.. SPDX-License-Identifier: GPL-2.0-only 2.. Copyright (C) 2022 Meta Platforms, Inc. and affiliates. 3 4========================= 5BPF_MAP_TYPE_CGRP_STORAGE 6========================= 7 8The ``BPF_MAP_TYPE_CGRP_STORAGE`` map type represents a local fix-sized 9storage for cgroups. It is only available with ``CONFIG_CGROUPS``. 10The programs are made available by the same Kconfig. The 11data for a particular cgroup can be retrieved by looking up the map 12with that cgroup. 13 14This document describes the usage and semantics of the 15``BPF_MAP_TYPE_CGRP_STORAGE`` map type. 16 17Usage 18===== 19 20The map key must be ``sizeof(int)`` representing a cgroup fd. 21To 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 26a new local storage will be created if one does not exist. 27 28The 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 32The map is available to all program types. 33 34Examples 35======== 36 37A 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 64Userspace 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 78Difference Between BPF_MAP_TYPE_CGRP_STORAGE and BPF_MAP_TYPE_CGROUP_STORAGE 79============================================================================ 80 81The old cgroup storage map ``BPF_MAP_TYPE_CGROUP_STORAGE`` has been marked as 82deprecated (renamed to ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``). The new 83``BPF_MAP_TYPE_CGRP_STORAGE`` map should be used instead. The following 84illusates 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 107So overall, ``BPF_MAP_TYPE_CGRP_STORAGE`` supports all ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` 108functionality and beyond. It is recommended to use ``BPF_MAP_TYPE_CGRP_STORAGE`` 109instead of ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``. 110