Skip to contentSkip to conversation

docs/bpf: Add documentation for BPF_MAP_TYPE_SK_STORAGE

PATCH Superseded Donald Hunter 3 participants 6 messages Dec 7, 2022 – Dec 8, 2022

Subsystems (2)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 docs/bpf: Add documentation for BPF_MAP_TYPE_SK_STORAGE

Add documentation for the BPF_MAP_TYPE_SK_STORAGE including kernel version introduced, usage and examples.

---
v2 -> v3:
- Fix void * return, reported by Yonghong Song
- Add tracing programs to API note, reported by Yonghong Song v1 -> v2:
- Fix bpf_sk_storage_* function signatures, reported by Yonghong Song
- Fix NULL return on failure, reported by Yonghong Song

 Documentation/bpf/map_sk_storage.rst | 142 +++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 Documentation/bpf/map_sk_storage.rst
Documentation/bpf/map_sk_storage.rst new file +142 -0
new file mode 100644
index 000000000000..955b287bb7de
@@ -0,0 +1,142 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+.. Copyright (C) 2022 Red Hat, Inc.
+
+=======================
+BPF_MAP_TYPE_SK_STORAGE
+=======================
+
+.. note::
+   - ``BPF_MAP_TYPE_SK_STORAGE`` was introduced in kernel version 5.2
+
+``BPF_MAP_TYPE_SK_STORAGE`` is used to provide socket-local storage for BPF programs. A map of
+type ``BPF_MAP_TYPE_SK_STORAGE`` declares the type of storage to be provided and acts as the
+handle for accessing the socket-local storage from a BPF program. The key type must be ``int``
+and ``max_entries`` must be set to ``0``.
+
+The ``BPF_F_NO_PREALLOC`` must be used when creating a map for socket-local storage. The kernel
+is responsible for allocating storage for a socket when requested and for freeing the storage
+when either the map or the socket is deleted.
+
+Usage
+=====
+
+Kernel BPF
+----------
+
+bpf_sk_storage_get()
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   void *bpf_sk_storage_get(struct bpf_map *map, void *sk, void *value, u64 flags)
+
+Socket-local storage can be retrieved using the ``bpf_sk_storage_get()`` helper. The helper gets
+the storage from ``sk`` that is identified by ``map``.  If the
+``BPF_LOCAL_STORAGE_GET_F_CREATE`` flag is used then ``bpf_sk_storage_get()`` will create the
+storage for ``sk`` if it does not already exist. ``value`` can be used together with
+``BPF_LOCAL_STORAGE_GET_F_CREATE`` to initialize the storage value, otherwise it will be zero
+initialized. Returns a pointer to the storage on success, or ``NULL`` in case of failure.
+
+.. note::
+   - ``sk`` is a kernel ``struct sock`` pointer for LSM or tracing programs.
+   - ``sk`` is a ``struct bpf_sock`` pointer for other program types.
+
+bpf_sk_storage_delete()
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   long bpf_sk_storage_delete(struct bpf_map *map, void *sk)
+
+Socket-local storage can be deleted using the ``bpf_sk_storage_delete()`` helper. The helper
+deletes the storage from ``sk`` that is identified by ``map``. Returns ``0`` on success, or negative
+error in case of failure.
+
+User space
+----------
+
+bpf_map_update_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   int bpf_map_update_elem(int map_fd, const void *key, const void *value, __u64 flags)
+
+Socket-local storage with type identified by ``map_fd`` for the socket identified by ``key`` can
+be added or updated using the ``bpf_map_update_elem()`` libbpf function. ``key`` must be a
+pointer to a valid ``fd`` in the user space program. The ``flags`` parameter can be used to
+control the update behaviour:
+
+- ``BPF_ANY`` will create storage for ``fd`` or update existing storage.
+- ``BPF_NOEXIST`` will create storage for ``fd`` only if it did not already
+  exist
+- ``BPF_EXIST`` will update existing storage for ``fd``
+
+Returns ``0`` on success, or negative error in case of failure.
+
+bpf_map_lookup_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   int bpf_map_lookup_elem(int map_fd, const void *key, void *value)
+
+Socket-local storage for the socket identified by ``key`` belonging to ``map_fd`` can be
+retrieved using the ``bpf_map_lookup_elem()`` libbpf function. ``key`` must be a pointer to a
+valid ``fd`` in the user space program. Returns ``0`` on success, or negative error in case of
+failure.
+
+bpf_map_delete_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   int bpf_map_delete_elem (int map_fd, const void *key)
+
+Socket-local storage for the socket identified by ``key`` belonging to ``map_fd`` can be deleted
+using the ``bpf_map_delete_elem()`` libbpf function. Returns ``0`` on success, or negative error
+in case of failure.
+
+Examples
+========
+
+Kernel BPF
+----------
+
+This snippet shows how to declare socket-local storage in a BPF program:
+
+.. code-block:: c
+
+    struct {
+            __uint(type, BPF_MAP_TYPE_SK_STORAGE);
+            __uint(map_flags, BPF_F_NO_PREALLOC);
+            __type(key, int);
+            __type(value, struct my_storage);
+    } socket_storage SEC(".maps");
+
+This snippet shows how to retrieve socket-local storage in a BPF program:
+
+.. code-block:: c
+
+    SEC("sockops")
+    int _sockops(struct bpf_sock_ops *ctx)
+    {
+            struct my_storage *storage;
+            struct bpf_sock *sk;
+
+            sk = ctx->sk;
+            if (!sk)
+                    return 1;
+
+            storage = bpf_sk_storage_get(&socket_storage, sk, 0,
+                                         BPF_LOCAL_STORAGE_GET_F_CREATE);
+            if (!storage)
+                    return 1;
+
+            /* Use 'storage' here */
+    }
+
+References
+==========
+
+https://lwn.net/ml/netdev/[email protected]/
Signature · 1 line
2.38.1
#2 lore raw
In reply to Donald Hunter
Quoted 30 lines · Donald Hunter

Add documentation for the BPF_MAP_TYPE_SK_STORAGE including kernel version introduced, usage and examples.

---
v2 -> v3:
- Fix void * return, reported by Yonghong Song
- Add tracing programs to API note, reported by Yonghong Song v1 -> v2:
- Fix bpf_sk_storage_* function signatures, reported by Yonghong Song
- Fix NULL return on failure, reported by Yonghong Song

 Documentation/bpf/map_sk_storage.rst | 142 +++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 Documentation/bpf/map_sk_storage.rst
Documentation/bpf/map_sk_storage.rst new file +8 -0
new file mode 100644
index 000000000000..955b287bb7de
@@ -0,0 +1,142 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+.. Copyright (C) 2022 Red Hat, Inc.
+
+=======================
+BPF_MAP_TYPE_SK_STORAGE
+=======================
+
+.. note::

Documentation/bpf/map_sk_storage.rst line 18

Quoted 10 lines
Documentation/bpf/map_sk_storage.rst new file +10 -0
+   - ``BPF_MAP_TYPE_SK_STORAGE`` was introduced in kernel version 5.2
+
+``BPF_MAP_TYPE_SK_STORAGE`` is used to provide socket-local storage for BPF programs. A map of
+type ``BPF_MAP_TYPE_SK_STORAGE`` declares the type of storage to be provided and acts as the
+handle for accessing the socket-local storage from a BPF program. The key type must be ``int``
+and ``max_entries`` must be set to ``0``.
+
+The ``BPF_F_NO_PREALLOC`` must be used when creating a map for socket-local storage. The kernel
+is responsible for allocating storage for a socket when requested and for freeing the storage
+when either the map or the socket is deleted.

Hi Donald,

Thanks for writing these excellent docs.

Would you mind please wrapping your text to 80 columns (throughout the document)? It's not a hard and fast rule, but it would be ideal to keep text that can wrap without formatting issues to 80 columns. For documentation where you're e.g. showing a function signature (such as bpf_sk_storage_get() below), it's fine to exceed it.

Quoted 37 lines
Documentation/bpf/map_sk_storage.rst new file +37 -0
+
+Usage
+=====
+
+Kernel BPF
+----------
+
+bpf_sk_storage_get()
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   void *bpf_sk_storage_get(struct bpf_map *map, void *sk, void *value, u64 flags)
+
+Socket-local storage can be retrieved using the ``bpf_sk_storage_get()`` helper. The helper gets
+the storage from ``sk`` that is identified by ``map``.  If the
+``BPF_LOCAL_STORAGE_GET_F_CREATE`` flag is used then ``bpf_sk_storage_get()`` will create the
+storage for ``sk`` if it does not already exist. ``value`` can be used together with
+``BPF_LOCAL_STORAGE_GET_F_CREATE`` to initialize the storage value, otherwise it will be zero
+initialized. Returns a pointer to the storage on success, or ``NULL`` in case of failure.
+
+.. note::
+   - ``sk`` is a kernel ``struct sock`` pointer for LSM or tracing programs.
+   - ``sk`` is a ``struct bpf_sock`` pointer for other program types.
+
+bpf_sk_storage_delete()
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   long bpf_sk_storage_delete(struct bpf_map *map, void *sk)
+
+Socket-local storage can be deleted using the ``bpf_sk_storage_delete()`` helper. The helper
+deletes the storage from ``sk`` that is identified by ``map``. Returns ``0`` on success, or negative
+error in case of failure.
+
+User space

Documentation/bpf/map_sk_storage.rst line 65

Quoted 10 lines
Documentation/bpf/map_sk_storage.rst new file +10 -0
+----------
+
+bpf_map_update_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   int bpf_map_update_elem(int map_fd, const void *key, const void *value, __u64 flags)
+
+Socket-local storage with type identified by ``map_fd`` for the socket identified by ``key`` can

Could you please clarify what you mean by "with type identified by"? ``map_fd`` just corresponds to the fd of the map, correct? Not following what's meant by "type".

Documentation/bpf/map_sk_storage.rst line 72

Quoted 7 lines
Documentation/bpf/map_sk_storage.rst new file +7 -0
+be added or updated using the ``bpf_map_update_elem()`` libbpf function. ``key`` must be a
+pointer to a valid ``fd`` in the user space program. The ``flags`` parameter can be used to
+control the update behaviour:
+
+- ``BPF_ANY`` will create storage for ``fd`` or update existing storage.
+- ``BPF_NOEXIST`` will create storage for ``fd`` only if it did not already
+  exist

I believe that if BPF_NOEXIST is specified, if storage already exists then in addition to storage not being created, the call will fail with -EEXIST.

Documentation/bpf/map_sk_storage.rst line 73

Quoted 1 line
Documentation/bpf/map_sk_storage.rst new file +1 -0
+- ``BPF_EXIST`` will update existing storage for ``fd``

Can we also mention that if BPF_EXIST is specified, and no element is present with the specified ``key``, that the call will fail with -ENOENT?

Quoted 11 lines
Documentation/bpf/map_sk_storage.rst new file +11 -0
+
+Returns ``0`` on success, or negative error in case of failure.
+
+bpf_map_lookup_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   int bpf_map_lookup_elem(int map_fd, const void *key, void *value)
+
+Socket-local storage for the socket identified by ``key`` belonging to ``map_fd`` can be

Documentation/bpf/map_sk_storage.rst line 94

Quoted 10 lines
Documentation/bpf/map_sk_storage.rst new file +10 -0
+retrieved using the ``bpf_map_lookup_elem()`` libbpf function. ``key`` must be a pointer to a
+valid ``fd`` in the user space program. Returns ``0`` on success, or negative error in case of
+failure.
+
+bpf_map_delete_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   int bpf_map_delete_elem (int map_fd, const void *key)

Extra space between _elem and (.

Quoted 25 lines
Documentation/bpf/map_sk_storage.rst new file +25 -0
+
+Socket-local storage for the socket identified by ``key`` belonging to ``map_fd`` can be deleted
+using the ``bpf_map_delete_elem()`` libbpf function. Returns ``0`` on success, or negative error
+in case of failure.
+
+Examples
+========
+
+Kernel BPF
+----------
+
+This snippet shows how to declare socket-local storage in a BPF program:
+
+.. code-block:: c
+
+    struct {
+            __uint(type, BPF_MAP_TYPE_SK_STORAGE);
+            __uint(map_flags, BPF_F_NO_PREALLOC);
+            __type(key, int);
+            __type(value, struct my_storage);
+    } socket_storage SEC(".maps");
+
+This snippet shows how to retrieve socket-local storage in a BPF program:
+
+.. code-block:: c

Documentation/bpf/map_sk_storage.rst line 129

Quoted 10 lines
Documentation/bpf/map_sk_storage.rst new file +10 -0
+
+    SEC("sockops")
+    int _sockops(struct bpf_sock_ops *ctx)
+    {
+            struct my_storage *storage;
+            struct bpf_sock *sk;
+
+            sk = ctx->sk;
+            if (!sk)
+                    return 1;

Don't feel strongly about this one, but IMO it's nice for examples to illustrate code that's as close to real and pristine as possible. To that point, should this example perhaps be updated to return -ENOENT here, and -ENOMEM below?

Documentation/bpf/map_sk_storage.rst line 136

Quoted 7 lines
Documentation/bpf/map_sk_storage.rst new file +7 -0
+
+            storage = bpf_sk_storage_get(&socket_storage, sk, 0,
+                                         BPF_LOCAL_STORAGE_GET_F_CREATE);
+            if (!storage)
+                    return 1;
+
+            /* Use 'storage' here */

Let's return 0 at the end to make the example program technically correct.

Documentation/bpf/map_sk_storage.rst line 137

Quoted 1 line
Documentation/bpf/map_sk_storage.rst new file +1 -0
+    }

Thanks,
David

#3 lore raw
Quoted 44 lines · David Vernet
Quoted 30 lines · Donald Hunter

Add documentation for the BPF_MAP_TYPE_SK_STORAGE including kernel version introduced, usage and examples.

---
v2 -> v3:
- Fix void * return, reported by Yonghong Song
- Add tracing programs to API note, reported by Yonghong Song v1 -> v2:
- Fix bpf_sk_storage_* function signatures, reported by Yonghong Song
- Fix NULL return on failure, reported by Yonghong Song

 Documentation/bpf/map_sk_storage.rst | 142 +++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 Documentation/bpf/map_sk_storage.rst
Documentation/bpf/map_sk_storage.rst new file +8 -0
new file mode 100644
index 000000000000..955b287bb7de
@@ -0,0 +1,142 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+.. Copyright (C) 2022 Red Hat, Inc.
+
+=======================
+BPF_MAP_TYPE_SK_STORAGE
+=======================
+
+.. note::

Documentation/bpf/map_sk_storage.rst line 18

Quoted 10 lines
Documentation/bpf/map_sk_storage.rst new file +10 -0
+   - ``BPF_MAP_TYPE_SK_STORAGE`` was introduced in kernel version 5.2
+
+``BPF_MAP_TYPE_SK_STORAGE`` is used to provide socket-local storage for BPF programs. A map of
+type ``BPF_MAP_TYPE_SK_STORAGE`` declares the type of storage to be provided and acts as the
+handle for accessing the socket-local storage from a BPF program. The key type must be ``int``
+and ``max_entries`` must be set to ``0``.
+
+The ``BPF_F_NO_PREALLOC`` must be used when creating a map for socket-local storage. The kernel
+is responsible for allocating storage for a socket when requested and for freeing the storage
+when either the map or the socket is deleted.

Hi Donald,

Quoted 7 lines

Thanks for writing these excellent docs.

Would you mind please wrapping your text to 80 columns (throughout the document)? It's not a hard and fast rule, but it would be ideal to keep text that can wrap without formatting issues to 80 columns. For documentation where you're e.g. showing a function signature (such as bpf_sk_storage_get() below), it's fine to exceed it.

Yes, of course. That was an oversight on my part.

Quoted 43 lines
Quoted 43 lines
Documentation/bpf/map_sk_storage.rst new file +43 -0
+
+Usage
+=====
+
+Kernel BPF
+----------
+
+bpf_sk_storage_get()
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   void *bpf_sk_storage_get(struct bpf_map *map, void *sk, void *value, u64 flags)
+
+Socket-local storage can be retrieved using the ``bpf_sk_storage_get()`` helper. The helper gets
+the storage from ``sk`` that is identified by ``map``.  If the
+``BPF_LOCAL_STORAGE_GET_F_CREATE`` flag is used then ``bpf_sk_storage_get()`` will create the
+storage for ``sk`` if it does not already exist. ``value`` can be used together with
+``BPF_LOCAL_STORAGE_GET_F_CREATE`` to initialize the storage value, otherwise it will be zero
+initialized. Returns a pointer to the storage on success, or ``NULL`` in case of failure.
+
+.. note::
+   - ``sk`` is a kernel ``struct sock`` pointer for LSM or tracing programs.
+   - ``sk`` is a ``struct bpf_sock`` pointer for other program types.
+
+bpf_sk_storage_delete()
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   long bpf_sk_storage_delete(struct bpf_map *map, void *sk)
+
+Socket-local storage can be deleted using the ``bpf_sk_storage_delete()`` helper. The helper
+deletes the storage from ``sk`` that is identified by ``map``. Returns ``0`` on success, or negative
+error in case of failure.
+
+User space
+----------
+
+bpf_map_update_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
Quoted 8 lines

Documentation/bpf/map_sk_storage.rst line 65

Quoted 4 lines
Documentation/bpf/map_sk_storage.rst new file +4 -0
+
+   int bpf_map_update_elem(int map_fd, const void *key, const void *value, __u64 flags)
+
+Socket-local storage with type identified by ``map_fd`` for the socket identified by ``key`` can

Could you please clarify what you mean by "with type identified by"? ``map_fd`` just corresponds to the fd of the map, correct? Not following what's meant by "type".

A clumsy attempt to say that the map definition declares the type of the storage that gets added to the socket, as opposed to behaving like a traditional map. I'll rework this to be more clear.

Quoted 11 lines

Documentation/bpf/map_sk_storage.rst line 72

Quoted 7 lines
Documentation/bpf/map_sk_storage.rst new file +7 -0
+be added or updated using the ``bpf_map_update_elem()`` libbpf function. ``key`` must be a
+pointer to a valid ``fd`` in the user space program. The ``flags`` parameter can be used to
+control the update behaviour:
+
+- ``BPF_ANY`` will create storage for ``fd`` or update existing storage.
+- ``BPF_NOEXIST`` will create storage for ``fd`` only if it did not already
+  exist

I believe that if BPF_NOEXIST is specified, if storage already exists then in addition to storage not being created, the call will fail with -EEXIST.

Good point, I'll add this.

Quoted 5 lines

Documentation/bpf/map_sk_storage.rst line 73

Quoted 1 line
Documentation/bpf/map_sk_storage.rst new file +1 -0
+- ``BPF_EXIST`` will update existing storage for ``fd``

Can we also mention that if BPF_EXIST is specified, and no element is present with the specified ``key``, that the call will fail with -ENOENT?

I'll add this too.

Quoted 15 lines
Quoted 15 lines
Documentation/bpf/map_sk_storage.rst new file +15 -0
+
+Returns ``0`` on success, or negative error in case of failure.
+
+bpf_map_lookup_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   int bpf_map_lookup_elem(int map_fd, const void *key, void *value)
+
+Socket-local storage for the socket identified by ``key`` belonging to ``map_fd`` can be
+retrieved using the ``bpf_map_lookup_elem()`` libbpf function. ``key`` must be a pointer to a
+valid ``fd`` in the user space program. Returns ``0`` on success, or negative error in case of
+failure.
+
Quoted 8 lines

Documentation/bpf/map_sk_storage.rst line 94

Quoted 6 lines
Documentation/bpf/map_sk_storage.rst new file +6 -0
+bpf_map_delete_elem()
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+   int bpf_map_delete_elem (int map_fd, const void *key)

Extra space between _elem and (.

Good catch, thx.

Quoted 32 lines
Quoted 32 lines
Documentation/bpf/map_sk_storage.rst new file +32 -0
+
+Socket-local storage for the socket identified by ``key`` belonging to ``map_fd`` can be deleted
+using the ``bpf_map_delete_elem()`` libbpf function. Returns ``0`` on success, or negative error
+in case of failure.
+
+Examples
+========
+
+Kernel BPF
+----------
+
+This snippet shows how to declare socket-local storage in a BPF program:
+
+.. code-block:: c
+
+    struct {
+            __uint(type, BPF_MAP_TYPE_SK_STORAGE);
+            __uint(map_flags, BPF_F_NO_PREALLOC);
+            __type(key, int);
+            __type(value, struct my_storage);
+    } socket_storage SEC(".maps");
+
+This snippet shows how to retrieve socket-local storage in a BPF program:
+
+.. code-block:: c
+
+    SEC("sockops")
+    int _sockops(struct bpf_sock_ops *ctx)
+    {
+            struct my_storage *storage;
+            struct bpf_sock *sk;
+
Quoted 8 lines

Documentation/bpf/map_sk_storage.rst line 129

Quoted 3 lines
Documentation/bpf/map_sk_storage.rst new file +3 -0
+            sk = ctx->sk;
+            if (!sk)
+                    return 1;

Don't feel strongly about this one, but IMO it's nice for examples to illustrate code that's as close to real and pristine as possible. To that point, should this example perhaps be updated to return -ENOENT here, and -ENOMEM below?

Will do.

Quoted 10 lines

Documentation/bpf/map_sk_storage.rst line 136

Quoted 7 lines
Documentation/bpf/map_sk_storage.rst new file +7 -0
+
+            storage = bpf_sk_storage_get(&socket_storage, sk, 0,
+                                         BPF_LOCAL_STORAGE_GET_F_CREATE);
+            if (!storage)
+                    return 1;
+
+            /* Use 'storage' here */

Let's return 0 at the end to make the example program technically correct.

Will do.

Quoted 4 lines

Documentation/bpf/map_sk_storage.rst line 137

Quoted 1 line
Documentation/bpf/map_sk_storage.rst new file +1 -0
+    }

Thanks,
David

#4 lore raw
Quoted 23 lines · Donald Hunter
Quoted 12 lines · David Vernet
Quoted 11 lines · Donald Hunter
Documentation/bpf/map_sk_storage.rst new file +11 -0
+
+This snippet shows how to retrieve socket-local storage in a BPF program:
+
+.. code-block:: c
+
+    SEC("sockops")
+    int _sockops(struct bpf_sock_ops *ctx)
+    {
+            struct my_storage *storage;
+            struct bpf_sock *sk;
+
Quoted 8 lines

Documentation/bpf/map_sk_storage.rst line 129

Quoted 3 lines
Documentation/bpf/map_sk_storage.rst new file +3 -0
+            sk = ctx->sk;
+            if (!sk)
+                    return 1;

Don't feel strongly about this one, but IMO it's nice for examples to illustrate code that's as close to real and pristine as possible. To that point, should this example perhaps be updated to return -ENOENT here, and -ENOMEM below?

Quoted 2 lines

Will do.

After digging into this a bit more I notice that the sockops programs in tools/testing/selftests/bpf/progs mostly return 1 in all cases.

I'm assuming that sockops programs should return valid values for some op types such as BPF_SOCK_OPS_TIMEOUT_INIT. Other than that I can't find a definitive list. Do you know if valid return values are enumerated anywhere, or do I need to dig some more?

Quoted 17 lines
Quoted 10 lines

Documentation/bpf/map_sk_storage.rst line 136

Quoted 7 lines
Documentation/bpf/map_sk_storage.rst new file +7 -0
+
+            storage = bpf_sk_storage_get(&socket_storage, sk, 0,
+                                         BPF_LOCAL_STORAGE_GET_F_CREATE);
+            if (!storage)
+                    return 1;
+
+            /* Use 'storage' here */

Let's return 0 at the end to make the example program technically correct.

Will do.

Quoted 4 lines
Quoted 1 line

+ }

Thanks,
David

#5 lore raw
Quoted 28 lines · Donald Hunter
Quoted 23 lines · Donald Hunter
Quoted 12 lines · David Vernet
Quoted 11 lines · Donald Hunter
Documentation/bpf/map_sk_storage.rst new file +11 -0
+
+This snippet shows how to retrieve socket-local storage in a BPF program:
+
+.. code-block:: c
+
+    SEC("sockops")
+    int _sockops(struct bpf_sock_ops *ctx)
+    {
+            struct my_storage *storage;
+            struct bpf_sock *sk;
+
Quoted 8 lines

Documentation/bpf/map_sk_storage.rst line 129

Quoted 3 lines
Documentation/bpf/map_sk_storage.rst new file +3 -0
+            sk = ctx->sk;
+            if (!sk)
+                    return 1;

Don't feel strongly about this one, but IMO it's nice for examples to illustrate code that's as close to real and pristine as possible. To that point, should this example perhaps be updated to return -ENOENT here, and -ENOMEM below?

Quoted 2 lines

Will do.

Quoted 7 lines

After digging into this a bit more I notice that the sockops programs in tools/testing/selftests/bpf/progs mostly return 1 in all cases.

I'm assuming that sockops programs should return valid values for some op types such as BPF_SOCK_OPS_TIMEOUT_INIT. Other than that I can't find a definitive list. Do you know if valid return values are enumerated anywhere, or do I need to dig some more?

It can return any integer.

static inline u32 tcp_timeout_init(struct sock *sk)

{
        int timeout;

        timeout = tcp_call_bpf(sk, BPF_SOCK_OPS_TIMEOUT_INIT, 0, NULL);

        if (timeout <= 0)
                timeout = TCP_TIMEOUT_INIT;
        return min_t(int, timeout, TCP_RTO_MAX);
}

In uapi bpf.h,

BPF_SOCK_OPS_TIMEOUT_INIT, /* Should return SYN-RTO value
to use or
* -1 if default value should
be used

                                         */

I think the above code is from selftests tcp_rtt.c. You can add a reference to provide more context. If people are really interested, they can go to selftest to find more.

Quoted 12 lines
Quoted 12 lines
Quoted 11 lines

Documentation/bpf/map_sk_storage.rst line 136

Quoted 8 lines
Documentation/bpf/map_sk_storage.rst new file +7 -0
+
+            storage = bpf_sk_storage_get(&socket_storage, sk, 0,
+                                         BPF_LOCAL_STORAGE_GET_F_CREATE);
+            if (!storage)
+                    return 1;
+
+            /* Use 'storage' here */

Let's return 0 at the end to make the example program technically correct.

Quoted 1 line
Quoted 1 line

Will do.

In this case, 'return 0' probably not correct. I suggest keep the code as is to sync with selftests. Add a reference to selftest for more reference.

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 2 lines

+ }

Thanks,
David