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