BPF_MAP_TYPE_CGROUP_STORAGE

Cgroup local storage 개요

`BPF_MAP_TYPE_CGROUP_STORAGE` 문서는 `GPL-2.0-only` license와 `Copyright (C) 2020 Google LLC.`를 명시합니다.

`BPF_MAP_TYPE_CGROUP_STORAGE` map type은 local fixed-size storage를 나타냅니다. `CONFIG_CGROUP_BPF`가 enable된 경우와 같은 Kconfig가 제공하는 cgroup attach program에서만 사용할 수 있으며, storage는 program이 attach된 cgroup으로 식별합니다.

이 map은 BPF program이 attach된 cgroup에 local storage를 제공합니다. Hash lookup을 수행하고 live cgroup을 user가 직접 추적해야 하는 general-purpose hash table보다 빠르고 단순하게 접근할 수 있습니다.

문서는 `BPF_MAP_TYPE_CGROUP_STORAGE`의 usage와 semantics를 설명하며 Linux 5.9에서 변경된 behavior를 이전 version과 비교합니다.

Key type, local storage helper와 synchronization

Map key는 `linux/bpf.h`에 선언된 `__u64 cgroup_inode_id` 또는 `struct bpf_cgroup_storage_key` type을 사용합니다.

struct bpf_cgroup_storage_key {
        __u64 cgroup_inode_id;
        __u32 attach_type;
};

`cgroup_inode_id`는 cgroup directory의 inode ID이고 `attach_type`은 program attach type입니다.

Linux 5.9부터 `__u64 cgroup_inode_id`를 key type으로 사용할 수 있습니다. 이 type이면 특정 cgroup과 map의 모든 attach type이 같은 storage를 공유합니다. `struct bpf_cgroup_storage_key`를 사용하면 attach type이 다른 program은 서로 격리된 storage를 봅니다.

Program에서 storage에 접근하는 helper prototype은 다음과 같습니다.

void *bpf_get_local_storage(void *map, u64 flags)

`bpf_get_local_storage()`의 `flags`는 future use를 위해 reserve되어 있으며 반드시 0이어야 합니다.

Implicit synchronization은 없습니다. 여러 CPU의 여러 program이 `BPF_MAP_TYPE_CGROUP_STORAGE`에 접근할 수 있으므로 user가 직접 synchronize해야 합니다. BPF infrastructure는 `struct bpf_spin_lock`을 제공하며 example은 `tools/testing/selftests/bpf/progs/test_spin_lock.c`에 있습니다.

Structured key 사용 예제

첫 kernel example은 key를 `struct bpf_cgroup_storage_key`, value를 `__u32`로 선언합니다. Program은 `bpf_get_local_storage()`로 current attachment의 storage를 얻고 `__sync_fetch_and_add()`로 값을 증가시킵니다.

#include <bpf/bpf.h>

struct {
        __uint(type, BPF_MAP_TYPE_CGROUP_STORAGE);
        __type(key, struct bpf_cgroup_storage_key);
        __type(value, __u32);
} cgroup_storage SEC(".maps");

int program(struct __sk_buff *skb)
{
        __u32 *ptr = bpf_get_local_storage(&cgroup_storage, 0);
        __sync_fetch_and_add(ptr, 1);

        return 0;
}

Userspace example은 cgroup inode ID와 `enum bpf_attach_type`을 `struct bpf_cgroup_storage_key`에 넣고 `bpf_map__fd()` 및 `bpf_map_lookup_elem()`으로 해당 attachment storage value를 읽습니다.

#include <linux/bpf.h>
#include <linux/libbpf.h>

__u32 map_lookup(struct bpf_map *map, __u64 cgrp, enum bpf_attach_type type)
{
        struct bpf_cgroup_storage_key = {
                .cgroup_inode_id = cgrp,
                .attach_type = type,
        };
        __u32 value;
        bpf_map_lookup_elem(bpf_map__fd(map), &key, &value);
        // error checking omitted
        return value;
}

Cgroup inode ID key 사용 예제

대안은 key type으로 `__u64 cgroup_inode_id`만 사용하는 것입니다. Kernel program의 storage access 방식은 structured key example과 같습니다.

#include <bpf/bpf.h>

struct {
        __uint(type, BPF_MAP_TYPE_CGROUP_STORAGE);
        __type(key, __u64);
        __type(value, __u32);
} cgroup_storage SEC(".maps");

int program(struct __sk_buff *skb)
{
        __u32 *ptr = bpf_get_local_storage(&cgroup_storage, 0);
        __sync_fetch_and_add(ptr, 1);

        return 0;
}

Userspace에서는 cgroup inode ID `cgrp` 자체를 key pointer로 전달합니다. Attach type parameter는 function signature에 남아 있지만 shared storage lookup에는 사용하지 않습니다.

#include <linux/bpf.h>
#include <linux/libbpf.h>

__u32 map_lookup(struct bpf_map *map, __u64 cgrp, enum bpf_attach_type type)
{
        __u32 value;
        bpf_map_lookup_elem(bpf_map__fd(map), &cgrp, &value);
        // error checking omitted
        return value;
}

Linux 5.9 이전 semantics

`BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE`는 이 map의 per-CPU variant입니다. 각 storage에 CPU별로 다른 memory region을 두며 non-per-CPU variant는 각 storage에서 같은 region을 공유합니다.

Linux 5.9 이전에는 storage lifetime이 정확히 attachment 단위였습니다. 하나의 `CGROUP_STORAGE` map은 이를 사용하는 program을 최대 하나만 load할 수 있었습니다. Program이 여러 cgroup 또는 attach type에 attach되면 각 attach가 새 zeroed storage를 만들고 detach 시 storage를 free했습니다.

Load verification 시 각 map type의 map과 BPF program 사이에 one-to-one association이 있었습니다. 따라서 각 map은 한 BPF program만, 각 program은 type별 storage map 하나만 사용할 수 있었고 다른 BPF program과 cgroup storage를 공유할 수 없었습니다.

Linux 5.9 이후 sharing과 lifetime

Linux 5.9부터 storage를 여러 program이 공유할 수 있습니다. Program을 cgroup에 attach할 때 map에 같은 cgroup·attach type pair entry가 없을 때만 새 storage를 만들고, 이미 있으면 기존 storage를 새 attachment가 재사용합니다. Attach-type-shared map에서는 비교할 때 attach type을 무시합니다.

Storage는 map 또는 attached cgroup이 free될 때만 free됩니다. Detach가 storage를 직접 free하지는 않지만 map reference count를 0으로 만들면 map의 모든 storage가 간접적으로 free될 수 있습니다.

Map은 특정 BPF program과 연결되지 않으므로 sharing이 가능합니다. 하지만 BPF program 하나는 여전히 per-CPU와 non-per-CPU 각 type당 map 하나만 연결할 수 있습니다. 즉 `BPF_MAP_TYPE_CGROUP_STORAGE`나 `BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE`를 각각 둘 이상 사용할 수 없습니다.

모든 version에서 userspace는 `struct bpf_cgroup_storage_key`의 cgroup·attach type pair를 BPF map API key로 사용해 특정 attachment storage를 read하거나 update할 수 있습니다. Linux 5.9 attach-type-shared storage는 비교할 때 struct의 첫 value인 cgroup inode ID만 사용하므로 userspace가 `__u64`를 직접 지정할 수 있습니다.

Storage binding은 attach time에 결정됩니다. Program을 parent에 attach하고 child에서 trigger해도 storage는 parent에 속합니다.

Userspace는 map에 새 entry를 만들거나 기존 entry를 delete할 수 없습니다. Program test run은 항상 temporary storage를 사용합니다.