239 lines · plain
1.. SPDX-License-Identifier: GPL-2.0-only2.. Copyright (C) 2022 Red Hat, Inc.3 4=================================================5BPF_MAP_TYPE_DEVMAP and BPF_MAP_TYPE_DEVMAP_HASH6=================================================7 8.. note::9 - ``BPF_MAP_TYPE_DEVMAP`` was introduced in kernel version 4.1410 - ``BPF_MAP_TYPE_DEVMAP_HASH`` was introduced in kernel version 5.411 12``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` are BPF maps primarily13used as backend maps for the XDP BPF helper call ``bpf_redirect_map()``.14``BPF_MAP_TYPE_DEVMAP`` is backed by an array that uses the key as15the index to lookup a reference to a net device. While ``BPF_MAP_TYPE_DEVMAP_HASH``16is backed by a hash table that uses a key to lookup a reference to a net device.17The user provides either <``key``/ ``ifindex``> or <``key``/ ``struct bpf_devmap_val``>18pairs to update the maps with new net devices.19 20.. note::21 - The key to a hash map doesn't have to be an ``ifindex``.22 - While ``BPF_MAP_TYPE_DEVMAP_HASH`` allows for densely packing the net devices23 it comes at the cost of a hash of the key when performing a look up.24 25The setup and packet enqueue/send code is shared between the two types of26devmap; only the lookup and insertion is different.27 28Usage29=====30Kernel BPF31----------32bpf_redirect_map()33^^^^^^^^^^^^^^^^^^34.. code-block:: c35 36 long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)37 38Redirect the packet to the endpoint referenced by ``map`` at index ``key``.39For ``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` this map contains40references to net devices (for forwarding packets through other ports).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. The higher bits of ``flags``45can be set to ``BPF_F_BROADCAST`` or ``BPF_F_EXCLUDE_INGRESS`` as defined46below.47 48With ``BPF_F_BROADCAST`` the packet will be broadcast to all the interfaces49in the map, with ``BPF_F_EXCLUDE_INGRESS`` the ingress interface will be excluded50from the broadcast.51 52.. note::53 - The key is ignored if BPF_F_BROADCAST is set.54 - The broadcast feature can also be used to implement multicast forwarding:55 simply create multiple DEVMAPs, each one corresponding to a single multicast group.56 57This helper will return ``XDP_REDIRECT`` on success, or the value of the two58lower bits of the ``flags`` argument if the map lookup fails.59 60More information about redirection can be found :doc:`redirect`61 62bpf_map_lookup_elem()63^^^^^^^^^^^^^^^^^^^^^64.. code-block:: c65 66 void *bpf_map_lookup_elem(struct bpf_map *map, const void *key)67 68Net device entries can be retrieved using the ``bpf_map_lookup_elem()``69helper.70 71User space72----------73.. note::74 DEVMAP entries can only be updated/deleted from user space and not75 from an eBPF program. Trying to call these functions from a kernel eBPF76 program will result in the program failing to load and a verifier warning.77 78bpf_map_update_elem()79^^^^^^^^^^^^^^^^^^^^^80.. code-block:: c81 82 int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags);83 84Net device entries can be added or updated using the ``bpf_map_update_elem()``85helper. This helper replaces existing elements atomically. The ``value`` parameter86can be ``struct bpf_devmap_val`` or a simple ``int ifindex`` for backwards87compatibility.88 89 .. code-block:: c90 91 struct bpf_devmap_val {92 __u32 ifindex; /* device index */93 union {94 int fd; /* prog fd on map write */95 __u32 id; /* prog id on map read */96 } bpf_prog;97 };98 99The ``flags`` argument can be one of the following:100 - ``BPF_ANY``: Create a new element or update an existing element.101 - ``BPF_NOEXIST``: Create a new element only if it did not exist.102 - ``BPF_EXIST``: Update an existing element.103 104DEVMAPs can associate a program with a device entry by adding a ``bpf_prog.fd``105to ``struct bpf_devmap_val``. Programs are run after ``XDP_REDIRECT`` and have106access to both Rx device and Tx device. The program associated with the ``fd``107must have type XDP with expected attach type ``xdp_devmap``.108When a program is associated with a device index, the program is run on an109``XDP_REDIRECT`` and before the buffer is added to the per-cpu queue. Examples110of how to attach/use xdp_devmap progs can be found in the kernel selftests:111 112- ``tools/testing/selftests/bpf/prog_tests/xdp_devmap_attach.c``113- ``tools/testing/selftests/bpf/progs/test_xdp_with_devmap_helpers.c``114 115bpf_map_lookup_elem()116^^^^^^^^^^^^^^^^^^^^^117.. code-block:: c118 119.. c:function::120 int bpf_map_lookup_elem(int fd, const void *key, void *value);121 122Net device entries can be retrieved using the ``bpf_map_lookup_elem()``123helper.124 125bpf_map_delete_elem()126^^^^^^^^^^^^^^^^^^^^^127.. code-block:: c128 129.. c:function::130 int bpf_map_delete_elem(int fd, const void *key);131 132Net device entries can be deleted using the ``bpf_map_delete_elem()``133helper. This helper will return 0 on success, or negative error in case of134failure.135 136Examples137========138 139Kernel BPF140----------141 142The following code snippet shows how to declare a ``BPF_MAP_TYPE_DEVMAP``143called tx_port.144 145.. code-block:: c146 147 struct {148 __uint(type, BPF_MAP_TYPE_DEVMAP);149 __type(key, __u32);150 __type(value, __u32);151 __uint(max_entries, 256);152 } tx_port SEC(".maps");153 154The following code snippet shows how to declare a ``BPF_MAP_TYPE_DEVMAP_HASH``155called forward_map.156 157.. code-block:: c158 159 struct {160 __uint(type, BPF_MAP_TYPE_DEVMAP_HASH);161 __type(key, __u32);162 __type(value, struct bpf_devmap_val);163 __uint(max_entries, 32);164 } forward_map SEC(".maps");165 166.. note::167 168 The value type in the DEVMAP above is a ``struct bpf_devmap_val``169 170The following code snippet shows a simple xdp_redirect_map program. This program171would work with a user space program that populates the devmap ``forward_map`` based172on ingress ifindexes. The BPF program (below) is redirecting packets using the173ingress ``ifindex`` as the ``key``.174 175.. code-block:: c176 177 SEC("xdp")178 int xdp_redirect_map_func(struct xdp_md *ctx)179 {180 int index = ctx->ingress_ifindex;181 182 return bpf_redirect_map(&forward_map, index, 0);183 }184 185The following code snippet shows a BPF program that is broadcasting packets to186all the interfaces in the ``tx_port`` devmap.187 188.. code-block:: c189 190 SEC("xdp")191 int xdp_redirect_map_func(struct xdp_md *ctx)192 {193 return bpf_redirect_map(&tx_port, 0, BPF_F_BROADCAST | BPF_F_EXCLUDE_INGRESS);194 }195 196User space197----------198 199The following code snippet shows how to update a devmap called ``tx_port``.200 201.. code-block:: c202 203 int update_devmap(int ifindex, int redirect_ifindex)204 {205 int ret;206 207 ret = bpf_map_update_elem(bpf_map__fd(tx_port), &ifindex, &redirect_ifindex, 0);208 if (ret < 0) {209 fprintf(stderr, "Failed to update devmap_ value: %s\n",210 strerror(errno));211 }212 213 return ret;214 }215 216The following code snippet shows how to update a hash_devmap called ``forward_map``.217 218.. code-block:: c219 220 int update_devmap(int ifindex, int redirect_ifindex)221 {222 struct bpf_devmap_val devmap_val = { .ifindex = redirect_ifindex };223 int ret;224 225 ret = bpf_map_update_elem(bpf_map__fd(forward_map), &ifindex, &devmap_val, 0);226 if (ret < 0) {227 fprintf(stderr, "Failed to update devmap_ value: %s\n",228 strerror(errno));229 }230 return ret;231 }232 233References234===========235 236- https://lwn.net/Articles/728146/237- https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/commit/?id=6f9d451ab1a33728adb72d7ff66a7b374d665176238- https://elixir.bootlin.com/linux/latest/source/net/core/filter.c#L4106239