Documentation/bpf/map_cgrp_storage.rst

   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``.