1.. SPDX-License-Identifier: GPL-2.0-only 2.. Copyright (C) 2022 Red Hat, Inc. 3 4======================= 5BPF_MAP_TYPE_SK_STORAGE 6======================= 7 8.. note:: 9 - ``BPF_MAP_TYPE_SK_STORAGE`` was introduced in kernel version 5.2 10 11``BPF_MAP_TYPE_SK_STORAGE`` is used to provide socket-local storage for BPF 12programs. A map of type ``BPF_MAP_TYPE_SK_STORAGE`` declares the type of storage 13to be provided and acts as the handle for accessing the socket-local 14storage. The values for maps of type ``BPF_MAP_TYPE_SK_STORAGE`` are stored 15locally with each socket instead of with the map. The kernel is responsible for 16allocating storage for a socket when requested and for freeing the storage when 17either the map or the socket is deleted. 18 19.. note:: 20 - The key type must be ``int`` and ``max_entries`` must be set to ``0``. 21 - The ``BPF_F_NO_PREALLOC`` flag must be used when creating a map for 22 socket-local storage. 23 24Usage 25===== 26 27Kernel BPF 28---------- 29 30bpf_sk_storage_get() 31~~~~~~~~~~~~~~~~~~~~ 32 33.. code-block:: c 34 35 void *bpf_sk_storage_get(struct bpf_map *map, void *sk, void *value, u64 flags) 36 37Socket-local storage for ``map`` can be retrieved from socket ``sk`` using the 38``bpf_sk_storage_get()`` helper. If the ``BPF_LOCAL_STORAGE_GET_F_CREATE`` 39flag is used then ``bpf_sk_storage_get()`` will create the storage for ``sk`` 40if it does not already exist. ``value`` can be used together with 41``BPF_LOCAL_STORAGE_GET_F_CREATE`` to initialize the storage value, otherwise 42it will be zero initialized. Returns a pointer to the storage on success, or 43``NULL`` in case of failure. 44 45.. note:: 46 - ``sk`` is a kernel ``struct sock`` pointer for LSM or tracing programs. 47 - ``sk`` is a ``struct bpf_sock`` pointer for other program types. 48 49bpf_sk_storage_delete() 50~~~~~~~~~~~~~~~~~~~~~~~ 51 52.. code-block:: c 53 54 long bpf_sk_storage_delete(struct bpf_map *map, void *sk) 55 56Socket-local storage for ``map`` can be deleted from socket ``sk`` using the 57``bpf_sk_storage_delete()`` helper. Returns ``0`` on success, or negative 58error in case of failure. 59 60User space 61---------- 62 63bpf_map_update_elem() 64~~~~~~~~~~~~~~~~~~~~~ 65 66.. code-block:: c 67 68 int bpf_map_update_elem(int map_fd, const void *key, const void *value, __u64 flags) 69 70Socket-local storage for map ``map_fd`` can be added or updated locally to a 71socket using the ``bpf_map_update_elem()`` libbpf function. The socket is 72identified by a `socket` ``fd`` stored in the pointer ``key``. The pointer 73``value`` has the data to be added or updated to the socket ``fd``. The type 74and size of ``value`` should be the same as the value type of the map 75definition. 76 77The ``flags`` parameter can be used to control the update behaviour: 78 79- ``BPF_ANY`` will create storage for `socket` ``fd`` or update existing storage. 80- ``BPF_NOEXIST`` will create storage for `socket` ``fd`` only if it did not 81 already exist, otherwise the call will fail with ``-EEXIST``. 82- ``BPF_EXIST`` will update existing storage for `socket` ``fd`` if it already 83 exists, otherwise the call will fail with ``-ENOENT``. 84 85Returns ``0`` on success, or negative error in case of failure. 86 87bpf_map_lookup_elem() 88~~~~~~~~~~~~~~~~~~~~~ 89 90.. code-block:: c 91 92 int bpf_map_lookup_elem(int map_fd, const void *key, void *value) 93 94Socket-local storage for map ``map_fd`` can be retrieved from a socket using 95the ``bpf_map_lookup_elem()`` libbpf function. The storage is retrieved from 96the socket identified by a `socket` ``fd`` stored in the pointer 97``key``. Returns ``0`` on success, or negative error in case of failure. 98 99bpf_map_delete_elem() 100~~~~~~~~~~~~~~~~~~~~~ 101 102.. code-block:: c 103 104 int bpf_map_delete_elem(int map_fd, const void *key) 105 106Socket-local storage for map ``map_fd`` can be deleted from a socket using the 107``bpf_map_delete_elem()`` libbpf function. The storage is deleted from the 108socket identified by a `socket` ``fd`` stored in the pointer ``key``. Returns 109``0`` on success, or negative error in case of failure. 110 111Examples 112======== 113 114Kernel BPF 115---------- 116 117This snippet shows how to declare socket-local storage in a BPF program: 118 119.. code-block:: c 120 121 struct { 122 __uint(type, BPF_MAP_TYPE_SK_STORAGE); 123 __uint(map_flags, BPF_F_NO_PREALLOC); 124 __type(key, int); 125 __type(value, struct my_storage); 126 } socket_storage SEC(".maps"); 127 128This snippet shows how to retrieve socket-local storage in a BPF program: 129 130.. code-block:: c 131 132 SEC("sockops") 133 int _sockops(struct bpf_sock_ops *ctx) 134 { 135 struct my_storage *storage; 136 struct bpf_sock *sk; 137 138 sk = ctx->sk; 139 if (!sk) 140 return 1; 141 142 storage = bpf_sk_storage_get(&socket_storage, sk, 0, 143 BPF_LOCAL_STORAGE_GET_F_CREATE); 144 if (!storage) 145 return 1; 146 147 /* Use 'storage' here */ 148 149 return 1; 150 } 151 152 153Please see the ``tools/testing/selftests/bpf`` directory for functional 154examples. 155 156References 157========== 158 159https://lwn.net/ml/netdev/20190426171103.61892-1-kafai@fb.com/ 160