Map type BPF_MAP_TYPE_ARRAY_OF_MAPS
The array of maps map type contains references to other maps.
Usage
This map type is a map-in-map type. The map values contain references to other BPF maps. We will refer to map-in-map as the "outer map" and the maps referenced as the "inner map(s)". The key advantage of using a map-in-map is that the outer map is directly referenced by any programs that use it, but the inner maps are not.
There are a couple of use cases for this indirection. First is to implement a form of RCU on the whole map, copying the existing map to a new map, updating multiple fields, then switching out the maps in the outer map. A second use case can be for statistics/metrics accuracy. It takes time for userspace to iterate and read the full contents of a map containing statistics/metrics. If accuracy is required, the outer map can contain multiple inner maps with counters, the program switches the inner map it writes to, giving userspace time to collect the values on the other maps, resulting in very accurate measurements. Lastly, since v5.1 most inner map types can have varying max_entries values from the reference map. This allows for dynamic resizing of a map without having to reload any programs.
Warning
For inner maps of type BPF_MAP_TYPE_ARRAY the BPF_F_INNER_MAP flag must be set on the inner map to allow varying max_entries. And inner maps of type BPF_MAP_TYPE_XSKMAP must always have the same amount of max_entries as the reference map.
Warning
maps of type BPF_MAP_TYPE_PERF_EVENT_ARRAY are not allowed as inner maps.
Users should be aware of the read/write asymmetry of this map type:
- The
BPF_MAP_UPDATE_ELEMsyscall command takes file descriptor of the BPF map you wish to insert into the map. - The
BPF_MAP_LOOKUP_ELEMsyscall command returns the ID of the BPF map, which can be turned into a file descriptor with theBPF_MAP_GET_FD_BY_IDsyscall command. - The bpf_map_lookup_elem returns a pointer to the inner map or
NULL. This pointer can be used like any other in helpers that that map pointers.
Attributes
Both the value_size and the key_size must always be 4 indicating a 32-bit unsigned integer.
The inner_map_fd attribute must be set to the file descriptor of another map. This other map will serve as a template for the inner maps. After loading, during insertion of values, the kernel will verify that the spec of the inner map values you are attempting to insert match the spec of the map provided by this field. The map used to indicate the type is not linked to the map-in-map type in any way, it is just used to transfer type info. A common technique for loaders is to build a temporary map just for the purpose of providing the type info and freeing that map as soon as the outer map has been created.
Note
If inner maps use the BPF_F_INNER_MAP flag, the max_entries field of the spec is ignored for the purposes of comparing the map spec.
Syscall commands
The following syscall commands work with this map type:
Helper functions
The following helper functions work with this map type:
Flags
The following flags are supported by this map type.
BPF_F_NUMA_NODE
When set, the numa_node attribute is respected during map creation.
BPF_F_RDONLY
Setting this flag will make it so the map can only be read via the syscall interface, but not written to.
For details please check the generic description.
BPF_F_WRONLY
Setting this flag will make it so the map can only be written to via the syscall interface, but not read from.
BPF_F_RDONLY_PROG
Setting this flag will make it so the map can only be read via helper functions, but not written to.
For details please check the generic description.
BPF_F_WRONLY_PROG
Setting this flag will make it so the map can only be written to via helper functions, but not read from.
For details please check the generic description.