| Message ID | 20210302171947.2268128-9-joe@cilium.io (mailing list archive) |
|---|---|
| State | Accepted |
| Delegated to: | BPF |
| Headers | show |
| Series | Improve BPF syscall command documentation | expand |
| Context | Check | Description |
|---|---|---|
| netdev/cover_letter | success | Link |
| netdev/fixes_present | success | Link |
| netdev/patch_count | success | Link |
| netdev/tree_selection | success | Clearly marked for bpf-next |
| netdev/subject_prefix | success | Link |
| netdev/cc_maintainers | warning | 6 maintainers not CCed: netdev@vger.kernel.org john.fastabend@gmail.com kpsingh@kernel.org songliubraving@fb.com kafai@fb.com andrii@kernel.org |
| netdev/source_inline | success | Was 0 now: 0 |
| netdev/verify_signedoff | success | Link |
| netdev/module_param | success | Was 0 now: 0 |
| netdev/build_32bit | success | Errors and warnings before: 11835 this patch: 11835 |
| netdev/kdoc | success | Errors and warnings before: 0 this patch: 0 |
| netdev/verify_fixes | success | Link |
| netdev/checkpatch | success | total: 0 errors, 0 warnings, 0 checks, 139 lines checked |
| netdev/build_allmodconfig_warn | success | Errors and warnings before: 12482 this patch: 12482 |
| netdev/header_inline | success | Link |
| netdev/stable | success | Stable not CCed |
Hi Joe, thanks for documenting this. Your description of the functions usage looks good to me. Acked-by: Brian Vazquez <brianvv@google.com> On Tue, Mar 2, 2021 at 9:20 AM Joe Stringer <joe@cilium.io> wrote: > > Based roughly on the following commits: > * Commit cb4d03ab499d ("bpf: Add generic support for lookup batch op") > * Commit 057996380a42 ("bpf: Add batch ops to all htab bpf map") > * Commit aa2e93b8e58e ("bpf: Add generic support for update and delete > batch ops") > > Acked-by: Toke Høiland-Jørgensen <toke@redhat.com> > Reviewed-by: Quentin Monnet <quentin@isovalent.com> > Signed-off-by: Joe Stringer <joe@cilium.io> > --- > CC: Brian Vazquez <brianvv@google.com> > CC: Yonghong Song <yhs@fb.com> > --- > include/uapi/linux/bpf.h | 114 +++++++++++++++++++++++++++++++++++++-- > 1 file changed, 111 insertions(+), 3 deletions(-) > > diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h > index 0cf92ef011f1..c8b9d19fce22 100644 > --- a/include/uapi/linux/bpf.h > +++ b/include/uapi/linux/bpf.h > @@ -553,13 +553,55 @@ union bpf_iter_link_info { > * Description > * Iterate and fetch multiple elements in a map. > * > + * Two opaque values are used to manage batch operations, > + * *in_batch* and *out_batch*. Initially, *in_batch* must be set > + * to NULL to begin the batched operation. After each subsequent > + * **BPF_MAP_LOOKUP_BATCH**, the caller should pass the resultant > + * *out_batch* as the *in_batch* for the next operation to > + * continue iteration from the current point. > + * > + * The *keys* and *values* are output parameters which must point > + * to memory large enough to hold *count* items based on the key > + * and value size of the map *map_fd*. The *keys* buffer must be > + * of *key_size* * *count*. The *values* buffer must be of > + * *value_size* * *count*. > + * > + * The *elem_flags* argument may be specified as one of the > + * following: > + * > + * **BPF_F_LOCK** > + * Look up the value of a spin-locked map without > + * returning the lock. This must be specified if the > + * elements contain a spinlock. > + * > + * On success, *count* elements from the map are copied into the > + * user buffer, with the keys copied into *keys* and the values > + * copied into the corresponding indices in *values*. > + * > + * If an error is returned and *errno* is not **EFAULT**, *count* > + * is set to the number of successfully processed elements. > + * > * Return > * Returns zero on success. On error, -1 is returned and *errno* > * is set appropriately. > * > + * May set *errno* to **ENOSPC** to indicate that *keys* or > + * *values* is too small to dump an entire bucket during > + * iteration of a hash-based map type. > + * > * BPF_MAP_LOOKUP_AND_DELETE_BATCH > * Description > - * Iterate and delete multiple elements in a map. > + * Iterate and delete all elements in a map. > + * > + * This operation has the same behavior as > + * **BPF_MAP_LOOKUP_BATCH** with two exceptions: > + * > + * * Every element that is successfully returned is also deleted > + * from the map. This is at least *count* elements. Note that > + * *count* is both an input and an output parameter. > + * * Upon returning with *errno* set to **EFAULT**, up to > + * *count* elements may be deleted without returning the keys > + * and values of the deleted elements. > * > * Return > * Returns zero on success. On error, -1 is returned and *errno* > @@ -567,15 +609,81 @@ union bpf_iter_link_info { > * > * BPF_MAP_UPDATE_BATCH > * Description > - * Iterate and update multiple elements in a map. > + * Update multiple elements in a map by *key*. > + * > + * The *keys* and *values* are input parameters which must point > + * to memory large enough to hold *count* items based on the key > + * and value size of the map *map_fd*. The *keys* buffer must be > + * of *key_size* * *count*. The *values* buffer must be of > + * *value_size* * *count*. > + * > + * Each element specified in *keys* is sequentially updated to the > + * value in the corresponding index in *values*. The *in_batch* > + * and *out_batch* parameters are ignored and should be zeroed. > + * > + * The *elem_flags* argument should be specified as one of the > + * following: > + * > + * **BPF_ANY** > + * Create new elements or update a existing elements. > + * **BPF_NOEXIST** > + * Create new elements only if they do not exist. > + * **BPF_EXIST** > + * Update existing elements. > + * **BPF_F_LOCK** > + * Update spin_lock-ed map elements. This must be > + * specified if the map value contains a spinlock. > + * > + * On success, *count* elements from the map are updated. > + * > + * If an error is returned and *errno* is not **EFAULT**, *count* > + * is set to the number of successfully processed elements. > * > * Return > * Returns zero on success. On error, -1 is returned and *errno* > * is set appropriately. > * > + * May set *errno* to **EINVAL**, **EPERM**, **ENOMEM**, or > + * **E2BIG**. **E2BIG** indicates that the number of elements in > + * the map reached the *max_entries* limit specified at map > + * creation time. > + * > + * May set *errno* to one of the following error codes under > + * specific circumstances: > + * > + * **EEXIST** > + * If *flags* specifies **BPF_NOEXIST** and the element > + * with *key* already exists in the map. > + * **ENOENT** > + * If *flags* specifies **BPF_EXIST** and the element with > + * *key* does not exist in the map. > + * > * BPF_MAP_DELETE_BATCH > * Description > - * Iterate and delete multiple elements in a map. > + * Delete multiple elements in a map by *key*. > + * > + * The *keys* parameter is an input parameter which must point > + * to memory large enough to hold *count* items based on the key > + * size of the map *map_fd*, that is, *key_size* * *count*. > + * > + * Each element specified in *keys* is sequentially deleted. The > + * *in_batch*, *out_batch*, and *values* parameters are ignored > + * and should be zeroed. > + * > + * The *elem_flags* argument may be specified as one of the > + * following: > + * > + * **BPF_F_LOCK** > + * Look up the value of a spin-locked map without > + * returning the lock. This must be specified if the > + * elements contain a spinlock. > + * > + * On success, *count* elements from the map are updated. > + * > + * If an error is returned and *errno* is not **EFAULT**, *count* > + * is set to the number of successfully processed elements. If > + * *errno* is **EFAULT**, up to *count* elements may be been > + * deleted. > * > * Return > * Returns zero on success. On error, -1 is returned and *errno* > -- > 2.27.0 >
On 3/2/21 9:19 AM, Joe Stringer wrote: > Based roughly on the following commits: > * Commit cb4d03ab499d ("bpf: Add generic support for lookup batch op") > * Commit 057996380a42 ("bpf: Add batch ops to all htab bpf map") > * Commit aa2e93b8e58e ("bpf: Add generic support for update and delete > batch ops") > > Acked-by: Toke Høiland-Jørgensen <toke@redhat.com> > Reviewed-by: Quentin Monnet <quentin@isovalent.com> > Signed-off-by: Joe Stringer <joe@cilium.io> > --- > CC: Brian Vazquez <brianvv@google.com> > CC: Yonghong Song <yhs@fb.com> > --- Acked-by: Yonghong Song <yhs@fb.com>
diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 0cf92ef011f1..c8b9d19fce22 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -553,13 +553,55 @@ union bpf_iter_link_info { * Description * Iterate and fetch multiple elements in a map. * + * Two opaque values are used to manage batch operations, + * *in_batch* and *out_batch*. Initially, *in_batch* must be set + * to NULL to begin the batched operation. After each subsequent + * **BPF_MAP_LOOKUP_BATCH**, the caller should pass the resultant + * *out_batch* as the *in_batch* for the next operation to + * continue iteration from the current point. + * + * The *keys* and *values* are output parameters which must point + * to memory large enough to hold *count* items based on the key + * and value size of the map *map_fd*. The *keys* buffer must be + * of *key_size* * *count*. The *values* buffer must be of + * *value_size* * *count*. + * + * The *elem_flags* argument may be specified as one of the + * following: + * + * **BPF_F_LOCK** + * Look up the value of a spin-locked map without + * returning the lock. This must be specified if the + * elements contain a spinlock. + * + * On success, *count* elements from the map are copied into the + * user buffer, with the keys copied into *keys* and the values + * copied into the corresponding indices in *values*. + * + * If an error is returned and *errno* is not **EFAULT**, *count* + * is set to the number of successfully processed elements. + * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. * + * May set *errno* to **ENOSPC** to indicate that *keys* or + * *values* is too small to dump an entire bucket during + * iteration of a hash-based map type. + * * BPF_MAP_LOOKUP_AND_DELETE_BATCH * Description - * Iterate and delete multiple elements in a map. + * Iterate and delete all elements in a map. + * + * This operation has the same behavior as + * **BPF_MAP_LOOKUP_BATCH** with two exceptions: + * + * * Every element that is successfully returned is also deleted + * from the map. This is at least *count* elements. Note that + * *count* is both an input and an output parameter. + * * Upon returning with *errno* set to **EFAULT**, up to + * *count* elements may be deleted without returning the keys + * and values of the deleted elements. * * Return * Returns zero on success. On error, -1 is returned and *errno* @@ -567,15 +609,81 @@ union bpf_iter_link_info { * * BPF_MAP_UPDATE_BATCH * Description - * Iterate and update multiple elements in a map. + * Update multiple elements in a map by *key*. + * + * The *keys* and *values* are input parameters which must point + * to memory large enough to hold *count* items based on the key + * and value size of the map *map_fd*. The *keys* buffer must be + * of *key_size* * *count*. The *values* buffer must be of + * *value_size* * *count*. + * + * Each element specified in *keys* is sequentially updated to the + * value in the corresponding index in *values*. The *in_batch* + * and *out_batch* parameters are ignored and should be zeroed. + * + * The *elem_flags* argument should be specified as one of the + * following: + * + * **BPF_ANY** + * Create new elements or update a existing elements. + * **BPF_NOEXIST** + * Create new elements only if they do not exist. + * **BPF_EXIST** + * Update existing elements. + * **BPF_F_LOCK** + * Update spin_lock-ed map elements. This must be + * specified if the map value contains a spinlock. + * + * On success, *count* elements from the map are updated. + * + * If an error is returned and *errno* is not **EFAULT**, *count* + * is set to the number of successfully processed elements. * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. * + * May set *errno* to **EINVAL**, **EPERM**, **ENOMEM**, or + * **E2BIG**. **E2BIG** indicates that the number of elements in + * the map reached the *max_entries* limit specified at map + * creation time. + * + * May set *errno* to one of the following error codes under + * specific circumstances: + * + * **EEXIST** + * If *flags* specifies **BPF_NOEXIST** and the element + * with *key* already exists in the map. + * **ENOENT** + * If *flags* specifies **BPF_EXIST** and the element with + * *key* does not exist in the map. + * * BPF_MAP_DELETE_BATCH * Description - * Iterate and delete multiple elements in a map. + * Delete multiple elements in a map by *key*. + * + * The *keys* parameter is an input parameter which must point + * to memory large enough to hold *count* items based on the key + * size of the map *map_fd*, that is, *key_size* * *count*. + * + * Each element specified in *keys* is sequentially deleted. The + * *in_batch*, *out_batch*, and *values* parameters are ignored + * and should be zeroed. + * + * The *elem_flags* argument may be specified as one of the + * following: + * + * **BPF_F_LOCK** + * Look up the value of a spin-locked map without + * returning the lock. This must be specified if the + * elements contain a spinlock. + * + * On success, *count* elements from the map are updated. + * + * If an error is returned and *errno* is not **EFAULT**, *count* + * is set to the number of successfully processed elements. If + * *errno* is **EFAULT**, up to *count* elements may be been + * deleted. * * Return * Returns zero on success. On error, -1 is returned and *errno*
Based roughly on the following commits: * Commit cb4d03ab499d ("bpf: Add generic support for lookup batch op") * Commit 057996380a42 ("bpf: Add batch ops to all htab bpf map") * Commit aa2e93b8e58e ("bpf: Add generic support for update and delete batch ops") Acked-by: Toke Høiland-Jørgensen <toke@redhat.com> Reviewed-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Joe Stringer <joe@cilium.io> --- CC: Brian Vazquez <brianvv@google.com> CC: Yonghong Song <yhs@fb.com> --- include/uapi/linux/bpf.h | 114 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 111 insertions(+), 3 deletions(-)