1.. SPDX-License-Identifier: GPL-2.0-only 2.. Copyright (C) 2022 Red Hat, Inc. 3 4======================================================== 5BPF_MAP_TYPE_ARRAY_OF_MAPS and BPF_MAP_TYPE_HASH_OF_MAPS 6======================================================== 7 8.. note:: 9 - ``BPF_MAP_TYPE_ARRAY_OF_MAPS`` and ``BPF_MAP_TYPE_HASH_OF_MAPS`` were 10 introduced in kernel version 4.12 11 12``BPF_MAP_TYPE_ARRAY_OF_MAPS`` and ``BPF_MAP_TYPE_HASH_OF_MAPS`` provide general 13purpose support for map in map storage. One level of nesting is supported, where 14an outer map contains instances of a single type of inner map, for example 15``array_of_maps->sock_map``. 16 17When creating an outer map, an inner map instance is used to initialize the 18metadata that the outer map holds about its inner maps. This inner map has a 19separate lifetime from the outer map and can be deleted after the outer map has 20been created. 21 22The outer map supports element lookup, update and delete from user space using 23the syscall API. A BPF program is only allowed to do element lookup in the outer 24map. 25 26.. note:: 27 - Multi-level nesting is not supported. 28 - Any BPF map type can be used as an inner map, except for 29 ``BPF_MAP_TYPE_PROG_ARRAY``. 30 - A BPF program cannot update or delete outer map entries. 31 32For ``BPF_MAP_TYPE_ARRAY_OF_MAPS`` the key is an unsigned 32-bit integer index 33into the array. The array is a fixed size with ``max_entries`` elements that are 34zero initialized when created. 35 36For ``BPF_MAP_TYPE_HASH_OF_MAPS`` the key type can be chosen when defining the 37map. The kernel is responsible for allocating and freeing key/value pairs, up to 38the max_entries limit that you specify. Hash maps use pre-allocation of hash 39table elements by default. The ``BPF_F_NO_PREALLOC`` flag can be used to disable 40pre-allocation when it is too memory expensive. 41 42Usage 43===== 44 45Kernel BPF Helper 46----------------- 47 48.. c:function:: 49 void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) 50 51Inner maps can be retrieved using the ``bpf_map_lookup_elem()`` helper. This 52helper returns a pointer to the inner map, or ``NULL`` if no entry was found. 53 54Examples 55======== 56 57Kernel BPF Example 58------------------ 59 60This snippet shows how to create and initialise an array of devmaps in a BPF 61program. Note that the outer array can only be modified from user space using 62the syscall API. 63 64.. code-block:: c 65 66 struct inner_map { 67 __uint(type, BPF_MAP_TYPE_DEVMAP); 68 __uint(max_entries, 10); 69 __type(key, __u32); 70 __type(value, __u32); 71 } inner_map1 SEC(".maps"), inner_map2 SEC(".maps"); 72 73 struct { 74 __uint(type, BPF_MAP_TYPE_ARRAY_OF_MAPS); 75 __uint(max_entries, 2); 76 __type(key, __u32); 77 __array(values, struct inner_map); 78 } outer_map SEC(".maps") = { 79 .values = { &inner_map1, 80 &inner_map2 } 81 }; 82 83See ``progs/test_btf_map_in_map.c`` in ``tools/testing/selftests/bpf`` for more 84examples of declarative initialisation of outer maps. 85 86User Space 87---------- 88 89This snippet shows how to create an array based outer map: 90 91.. code-block:: c 92 93 int create_outer_array(int inner_fd) { 94 LIBBPF_OPTS(bpf_map_create_opts, opts, .inner_map_fd = inner_fd); 95 int fd; 96 97 fd = bpf_map_create(BPF_MAP_TYPE_ARRAY_OF_MAPS, 98 "example_array", /* name */ 99 sizeof(__u32), /* key size */ 100 sizeof(__u32), /* value size */ 101 256, /* max entries */ 102 &opts); /* create opts */ 103 return fd; 104 } 105 106 107This snippet shows how to add an inner map to an outer map: 108 109.. code-block:: c 110 111 int add_devmap(int outer_fd, int index, const char *name) { 112 int fd; 113 114 fd = bpf_map_create(BPF_MAP_TYPE_DEVMAP, name, 115 sizeof(__u32), sizeof(__u32), 256, NULL); 116 if (fd < 0) 117 return fd; 118 119 return bpf_map_update_elem(outer_fd, &index, &fd, BPF_ANY); 120 } 121 122References 123========== 124 125- https://lore.kernel.org/netdev/20170322170035.923581-3-kafai@fb.com/ 126- https://lore.kernel.org/netdev/20170322170035.923581-4-kafai@fb.com/ 127