182 lines
5.3 KiB
ReStructuredText
182 lines
5.3 KiB
ReStructuredText
|
.. SPDX-License-Identifier: GPL-2.0-only
|
||
|
.. Copyright (C) 2022 Red Hat, Inc.
|
||
|
|
||
|
=====================
|
||
|
BPF_MAP_TYPE_LPM_TRIE
|
||
|
=====================
|
||
|
|
||
|
.. note::
|
||
|
- ``BPF_MAP_TYPE_LPM_TRIE`` was introduced in kernel version 4.11
|
||
|
|
||
|
``BPF_MAP_TYPE_LPM_TRIE`` provides a longest prefix match algorithm that
|
||
|
can be used to match IP addresses to a stored set of prefixes.
|
||
|
Internally, data is stored in an unbalanced trie of nodes that uses
|
||
|
``prefixlen,data`` pairs as its keys. The ``data`` is interpreted in
|
||
|
network byte order, i.e. big endian, so ``data[0]`` stores the most
|
||
|
significant byte.
|
||
|
|
||
|
LPM tries may be created with a maximum prefix length that is a multiple
|
||
|
of 8, in the range from 8 to 2048. The key used for lookup and update
|
||
|
operations is a ``struct bpf_lpm_trie_key``, extended by
|
||
|
``max_prefixlen/8`` bytes.
|
||
|
|
||
|
- For IPv4 addresses the data length is 4 bytes
|
||
|
- For IPv6 addresses the data length is 16 bytes
|
||
|
|
||
|
The value type stored in the LPM trie can be any user defined type.
|
||
|
|
||
|
.. note::
|
||
|
When creating a map of type ``BPF_MAP_TYPE_LPM_TRIE`` you must set the
|
||
|
``BPF_F_NO_PREALLOC`` flag.
|
||
|
|
||
|
Usage
|
||
|
=====
|
||
|
|
||
|
Kernel BPF
|
||
|
----------
|
||
|
|
||
|
.. c:function::
|
||
|
void *bpf_map_lookup_elem(struct bpf_map *map, const void *key)
|
||
|
|
||
|
The longest prefix entry for a given data value can be found using the
|
||
|
``bpf_map_lookup_elem()`` helper. This helper returns a pointer to the
|
||
|
value associated with the longest matching ``key``, or ``NULL`` if no
|
||
|
entry was found.
|
||
|
|
||
|
The ``key`` should have ``prefixlen`` set to ``max_prefixlen`` when
|
||
|
performing longest prefix lookups. For example, when searching for the
|
||
|
longest prefix match for an IPv4 address, ``prefixlen`` should be set to
|
||
|
``32``.
|
||
|
|
||
|
.. c:function::
|
||
|
long bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags)
|
||
|
|
||
|
Prefix entries can be added or updated using the ``bpf_map_update_elem()``
|
||
|
helper. This helper replaces existing elements atomically.
|
||
|
|
||
|
``bpf_map_update_elem()`` returns ``0`` on success, or negative error in
|
||
|
case of failure.
|
||
|
|
||
|
.. note::
|
||
|
The flags parameter must be one of BPF_ANY, BPF_NOEXIST or BPF_EXIST,
|
||
|
but the value is ignored, giving BPF_ANY semantics.
|
||
|
|
||
|
.. c:function::
|
||
|
long bpf_map_delete_elem(struct bpf_map *map, const void *key)
|
||
|
|
||
|
Prefix entries can be deleted using the ``bpf_map_delete_elem()``
|
||
|
helper. This helper will return 0 on success, or negative error in case
|
||
|
of failure.
|
||
|
|
||
|
Userspace
|
||
|
---------
|
||
|
|
||
|
Access from userspace uses libbpf APIs with the same names as above, with
|
||
|
the map identified by ``fd``.
|
||
|
|
||
|
.. c:function::
|
||
|
int bpf_map_get_next_key (int fd, const void *cur_key, void *next_key)
|
||
|
|
||
|
A userspace program can iterate through the entries in an LPM trie using
|
||
|
libbpf's ``bpf_map_get_next_key()`` function. The first key can be
|
||
|
fetched by calling ``bpf_map_get_next_key()`` with ``cur_key`` set to
|
||
|
``NULL``. Subsequent calls will fetch the next key that follows the
|
||
|
current key. ``bpf_map_get_next_key()`` returns ``0`` on success,
|
||
|
``-ENOENT`` if ``cur_key`` is the last key in the trie, or negative
|
||
|
error in case of failure.
|
||
|
|
||
|
``bpf_map_get_next_key()`` will iterate through the LPM trie elements
|
||
|
from leftmost leaf first. This means that iteration will return more
|
||
|
specific keys before less specific ones.
|
||
|
|
||
|
Examples
|
||
|
========
|
||
|
|
||
|
Please see ``tools/testing/selftests/bpf/test_lpm_map.c`` for examples
|
||
|
of LPM trie usage from userspace. The code snippets below demonstrate
|
||
|
API usage.
|
||
|
|
||
|
Kernel BPF
|
||
|
----------
|
||
|
|
||
|
The following BPF code snippet shows how to declare a new LPM trie for IPv4
|
||
|
address prefixes:
|
||
|
|
||
|
.. code-block:: c
|
||
|
|
||
|
#include <linux/bpf.h>
|
||
|
#include <bpf/bpf_helpers.h>
|
||
|
|
||
|
struct ipv4_lpm_key {
|
||
|
__u32 prefixlen;
|
||
|
__u32 data;
|
||
|
};
|
||
|
|
||
|
struct {
|
||
|
__uint(type, BPF_MAP_TYPE_LPM_TRIE);
|
||
|
__type(key, struct ipv4_lpm_key);
|
||
|
__type(value, __u32);
|
||
|
__uint(map_flags, BPF_F_NO_PREALLOC);
|
||
|
__uint(max_entries, 255);
|
||
|
} ipv4_lpm_map SEC(".maps");
|
||
|
|
||
|
The following BPF code snippet shows how to lookup by IPv4 address:
|
||
|
|
||
|
.. code-block:: c
|
||
|
|
||
|
void *lookup(__u32 ipaddr)
|
||
|
{
|
||
|
struct ipv4_lpm_key key = {
|
||
|
.prefixlen = 32,
|
||
|
.data = ipaddr
|
||
|
};
|
||
|
|
||
|
return bpf_map_lookup_elem(&ipv4_lpm_map, &key);
|
||
|
}
|
||
|
|
||
|
Userspace
|
||
|
---------
|
||
|
|
||
|
The following snippet shows how to insert an IPv4 prefix entry into an
|
||
|
LPM trie:
|
||
|
|
||
|
.. code-block:: c
|
||
|
|
||
|
int add_prefix_entry(int lpm_fd, __u32 addr, __u32 prefixlen, struct value *value)
|
||
|
{
|
||
|
struct ipv4_lpm_key ipv4_key = {
|
||
|
.prefixlen = prefixlen,
|
||
|
.data = addr
|
||
|
};
|
||
|
return bpf_map_update_elem(lpm_fd, &ipv4_key, value, BPF_ANY);
|
||
|
}
|
||
|
|
||
|
The following snippet shows a userspace program walking through the entries
|
||
|
of an LPM trie:
|
||
|
|
||
|
|
||
|
.. code-block:: c
|
||
|
|
||
|
#include <bpf/libbpf.h>
|
||
|
#include <bpf/bpf.h>
|
||
|
|
||
|
void iterate_lpm_trie(int map_fd)
|
||
|
{
|
||
|
struct ipv4_lpm_key *cur_key = NULL;
|
||
|
struct ipv4_lpm_key next_key;
|
||
|
struct value value;
|
||
|
int err;
|
||
|
|
||
|
for (;;) {
|
||
|
err = bpf_map_get_next_key(map_fd, cur_key, &next_key);
|
||
|
if (err)
|
||
|
break;
|
||
|
|
||
|
bpf_map_lookup_elem(map_fd, &next_key, &value);
|
||
|
|
||
|
/* Use key and value here */
|
||
|
|
||
|
cur_key = &next_key;
|
||
|
}
|
||
|
}
|