178 lines · plain
1.. SPDX-License-Identifier: GPL-2.0-only2.. Copyright (C) 2022 Red Hat, Inc.3 4===================5BPF_MAP_TYPE_CPUMAP6===================7 8.. note::9 - ``BPF_MAP_TYPE_CPUMAP`` was introduced in kernel version 4.1510 11.. kernel-doc:: kernel/bpf/cpumap.c12 :doc: cpu map13 14An example use-case for this map type is software based Receive Side Scaling (RSS).15 16The CPUMAP represents the CPUs in the system indexed as the map-key, and the17map-value is the config setting (per CPUMAP entry). Each CPUMAP entry has a dedicated18kernel thread bound to the given CPU to represent the remote CPU execution unit.19 20Starting from Linux kernel version 5.9 the CPUMAP can run a second XDP program21on the remote CPU. This allows an XDP program to split its processing across22multiple CPUs. For example, a scenario where the initial CPU (that sees/receives23the packets) needs to do minimal packet processing and the remote CPU (to which24the packet is directed) can afford to spend more cycles processing the frame. The25initial CPU is where the XDP redirect program is executed. The remote CPU26receives raw ``xdp_frame`` objects.27 28Usage29=====30 31Kernel BPF32----------33bpf_redirect_map()34^^^^^^^^^^^^^^^^^^35.. code-block:: c36 37 long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)38 39Redirect the packet to the endpoint referenced by ``map`` at index ``key``.40For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs.41 42The lower two bits of ``flags`` are used as the return code if the map lookup43fails. This is so that the return value can be one of the XDP program return44codes up to ``XDP_TX``, as chosen by the caller.45 46User space47----------48.. note::49 CPUMAP entries can only be updated/looked up/deleted from user space and not50 from an eBPF program. Trying to call these functions from a kernel eBPF51 program will result in the program failing to load and a verifier warning.52 53bpf_map_update_elem()54^^^^^^^^^^^^^^^^^^^^^55.. code-block:: c56 57 int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags);58 59CPU entries can be added or updated using the ``bpf_map_update_elem()``60helper. This helper replaces existing elements atomically. The ``value`` parameter61can be ``struct bpf_cpumap_val``.62 63 .. code-block:: c64 65 struct bpf_cpumap_val {66 __u32 qsize; /* queue size to remote target CPU */67 union {68 int fd; /* prog fd on map write */69 __u32 id; /* prog id on map read */70 } bpf_prog;71 };72 73The flags argument can be one of the following:74 - BPF_ANY: Create a new element or update an existing element.75 - BPF_NOEXIST: Create a new element only if it did not exist.76 - BPF_EXIST: Update an existing element.77 78bpf_map_lookup_elem()79^^^^^^^^^^^^^^^^^^^^^80.. code-block:: c81 82 int bpf_map_lookup_elem(int fd, const void *key, void *value);83 84CPU entries can be retrieved using the ``bpf_map_lookup_elem()``85helper.86 87bpf_map_delete_elem()88^^^^^^^^^^^^^^^^^^^^^89.. code-block:: c90 91 int bpf_map_delete_elem(int fd, const void *key);92 93CPU entries can be deleted using the ``bpf_map_delete_elem()``94helper. This helper will return 0 on success, or negative error in case of95failure.96 97Examples98========99Kernel100------101 102The following code snippet shows how to declare a ``BPF_MAP_TYPE_CPUMAP`` called103``cpu_map`` and how to redirect packets to a remote CPU using a round robin scheme.104 105.. code-block:: c106 107 struct {108 __uint(type, BPF_MAP_TYPE_CPUMAP);109 __type(key, __u32);110 __type(value, struct bpf_cpumap_val);111 __uint(max_entries, 12);112 } cpu_map SEC(".maps");113 114 struct {115 __uint(type, BPF_MAP_TYPE_ARRAY);116 __type(key, __u32);117 __type(value, __u32);118 __uint(max_entries, 12);119 } cpus_available SEC(".maps");120 121 struct {122 __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);123 __type(key, __u32);124 __type(value, __u32);125 __uint(max_entries, 1);126 } cpus_iterator SEC(".maps");127 128 SEC("xdp")129 int xdp_redir_cpu_round_robin(struct xdp_md *ctx)130 {131 __u32 key = 0;132 __u32 cpu_dest = 0;133 __u32 *cpu_selected, *cpu_iterator;134 __u32 cpu_idx;135 136 cpu_iterator = bpf_map_lookup_elem(&cpus_iterator, &key);137 if (!cpu_iterator)138 return XDP_ABORTED;139 cpu_idx = *cpu_iterator;140 141 *cpu_iterator += 1;142 if (*cpu_iterator == bpf_num_possible_cpus())143 *cpu_iterator = 0;144 145 cpu_selected = bpf_map_lookup_elem(&cpus_available, &cpu_idx);146 if (!cpu_selected)147 return XDP_ABORTED;148 cpu_dest = *cpu_selected;149 150 if (cpu_dest >= bpf_num_possible_cpus())151 return XDP_ABORTED;152 153 return bpf_redirect_map(&cpu_map, cpu_dest, 0);154 }155 156User space157----------158 159The following code snippet shows how to dynamically set the max_entries for a160CPUMAP to the max number of cpus available on the system.161 162.. code-block:: c163 164 int set_max_cpu_entries(struct bpf_map *cpu_map)165 {166 if (bpf_map__set_max_entries(cpu_map, libbpf_num_possible_cpus()) < 0) {167 fprintf(stderr, "Failed to set max entries for cpu_map map: %s",168 strerror(errno));169 return -1;170 }171 return 0;172 }173 174References175===========176 177- https://developers.redhat.com/blog/2021/05/13/receive-side-scaling-rss-with-ebpf-and-cpumap#redirecting_into_a_cpumap178