Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
7.8 kB · 238 lines
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239.. SPDX-License-Identifier: GPL-2.0-only.. Copyright (C) 2022 Red Hat, Inc.
=================================================BPF_MAP_TYPE_DEVMAP and BPF_MAP_TYPE_DEVMAP_HASH=================================================
.. note:: - ``BPF_MAP_TYPE_DEVMAP`` was introduced in kernel version 4.14 - ``BPF_MAP_TYPE_DEVMAP_HASH`` was introduced in kernel version 5.4
``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` are BPF maps primarilyused as backend maps for the XDP BPF helper call ``bpf_redirect_map()``.``BPF_MAP_TYPE_DEVMAP`` is backed by an array that uses the key asthe index to lookup a reference to a net device. While ``BPF_MAP_TYPE_DEVMAP_HASH``is backed by a hash table that uses a key to lookup a reference to a net device.The user provides either <``key``/ ``ifindex``> or <``key``/ ``struct bpf_devmap_val``>pairs to update the maps with new net devices.
.. note:: - The key to a hash map doesn't have to be an ``ifindex``. - While ``BPF_MAP_TYPE_DEVMAP_HASH`` allows for densely packing the net devices it comes at the cost of a hash of the key when performing a look up.
The setup and packet enqueue/send code is shared between the two types ofdevmap; only the lookup and insertion is different.
Usage=====Kernel BPF----------bpf_redirect_map()^^^^^^^^^^^^^^^^^^.. code-block:: c
long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)
Redirect the packet to the endpoint referenced by ``map`` at index ``key``.For ``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` this map containsreferences to net devices (for forwarding packets through other ports).
The lower two bits of *flags* are used as the return code if the map lookupfails. This is so that the return value can be one of the XDP program returncodes up to ``XDP_TX``, as chosen by the caller. The higher bits of ``flags``can be set to ``BPF_F_BROADCAST`` or ``BPF_F_EXCLUDE_INGRESS`` as definedbelow.
With ``BPF_F_BROADCAST`` the packet will be broadcast to all the interfacesin the map, with ``BPF_F_EXCLUDE_INGRESS`` the ingress interface will be excludedfrom the broadcast.
.. note:: - The key is ignored if BPF_F_BROADCAST is set. - The broadcast feature can also be used to implement multicast forwarding: simply create multiple DEVMAPs, each one corresponding to a single multicast group.
This helper will return ``XDP_REDIRECT`` on success, or the value of the twolower bits of the ``flags`` argument if the map lookup fails.
More information about redirection can be found :doc:`redirect`
bpf_map_lookup_elem()^^^^^^^^^^^^^^^^^^^^^.. code-block:: c
void *bpf_map_lookup_elem(struct bpf_map *map, const void *key)
Net device entries can be retrieved using the ``bpf_map_lookup_elem()``helper.
User space----------.. note:: DEVMAP entries can only be updated/deleted from user space and not from an eBPF program. Trying to call these functions from a kernel eBPF program will result in the program failing to load and a verifier warning.
bpf_map_update_elem()^^^^^^^^^^^^^^^^^^^^^.. code-block:: c
int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags);
Net device entries can be added or updated using the ``bpf_map_update_elem()``helper. This helper replaces existing elements atomically. The ``value`` parametercan be ``struct bpf_devmap_val`` or a simple ``int ifindex`` for backwardscompatibility.
.. code-block:: c
struct bpf_devmap_val { __u32 ifindex; /* device index */ union { int fd; /* prog fd on map write */ __u32 id; /* prog id on map read */ } bpf_prog; };
The ``flags`` argument can be one of the following: - ``BPF_ANY``: Create a new element or update an existing element. - ``BPF_NOEXIST``: Create a new element only if it did not exist. - ``BPF_EXIST``: Update an existing element.
DEVMAPs can associate a program with a device entry by adding a ``bpf_prog.fd``to ``struct bpf_devmap_val``. Programs are run after ``XDP_REDIRECT`` and haveaccess to both Rx device and Tx device. The program associated with the ``fd``must have type XDP with expected attach type ``xdp_devmap``.When a program is associated with a device index, the program is run on an``XDP_REDIRECT`` and before the buffer is added to the per-cpu queue. Examplesof how to attach/use xdp_devmap progs can be found in the kernel selftests:
- ``tools/testing/selftests/bpf/prog_tests/xdp_devmap_attach.c``- ``tools/testing/selftests/bpf/progs/test_xdp_with_devmap_helpers.c``
bpf_map_lookup_elem()^^^^^^^^^^^^^^^^^^^^^.. code-block:: c
.. c:function:: int bpf_map_lookup_elem(int fd, const void *key, void *value);
Net device entries can be retrieved using the ``bpf_map_lookup_elem()``helper.
bpf_map_delete_elem()^^^^^^^^^^^^^^^^^^^^^.. code-block:: c
.. c:function:: int bpf_map_delete_elem(int fd, const void *key);
Net device entries can be deleted using the ``bpf_map_delete_elem()``helper. This helper will return 0 on success, or negative error in case offailure.
Examples========
Kernel BPF----------
The following code snippet shows how to declare a ``BPF_MAP_TYPE_DEVMAP``called tx_port.
.. code-block:: c
struct { __uint(type, BPF_MAP_TYPE_DEVMAP); __type(key, __u32); __type(value, __u32); __uint(max_entries, 256); } tx_port SEC(".maps");
The following code snippet shows how to declare a ``BPF_MAP_TYPE_DEVMAP_HASH``called forward_map.
.. code-block:: c
struct { __uint(type, BPF_MAP_TYPE_DEVMAP_HASH); __type(key, __u32); __type(value, struct bpf_devmap_val); __uint(max_entries, 32); } forward_map SEC(".maps");
.. note::
The value type in the DEVMAP above is a ``struct bpf_devmap_val``
The following code snippet shows a simple xdp_redirect_map program. This programwould work with a user space program that populates the devmap ``forward_map`` basedon ingress ifindexes. The BPF program (below) is redirecting packets using theingress ``ifindex`` as the ``key``.
.. code-block:: c
SEC("xdp") int xdp_redirect_map_func(struct xdp_md *ctx) { int index = ctx->ingress_ifindex;
return bpf_redirect_map(&forward_map, index, 0); }
The following code snippet shows a BPF program that is broadcasting packets toall the interfaces in the ``tx_port`` devmap.
.. code-block:: c
SEC("xdp") int xdp_redirect_map_func(struct xdp_md *ctx) { return bpf_redirect_map(&tx_port, 0, BPF_F_BROADCAST | BPF_F_EXCLUDE_INGRESS); }
User space----------
The following code snippet shows how to update a devmap called ``tx_port``.
.. code-block:: c
int update_devmap(int ifindex, int redirect_ifindex) { int ret;
ret = bpf_map_update_elem(bpf_map__fd(tx_port), &ifindex, &redirect_ifindex, 0); if (ret < 0) { fprintf(stderr, "Failed to update devmap_ value: %s\n", strerror(errno)); }
return ret; }
The following code snippet shows how to update a hash_devmap called ``forward_map``.
.. code-block:: c
int update_devmap(int ifindex, int redirect_ifindex) { struct bpf_devmap_val devmap_val = { .ifindex = redirect_ifindex }; int ret;
ret = bpf_map_update_elem(bpf_map__fd(forward_map), &ifindex, &devmap_val, 0); if (ret < 0) { fprintf(stderr, "Failed to update devmap_ value: %s\n", strerror(errno)); } return ret; }
References===========
- https://lwn.net/Articles/728146/- https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/commit/?id=6f9d451ab1a33728adb72d7ff66a7b374d665176- https://elixir.bootlin.com/linux/latest/source/net/core/filter.c#L4106