From patchwork Tue Nov 22 10:37:37 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maryam Tahhan X-Patchwork-Id: 13052191 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id D7D08C4321E for ; Tue, 22 Nov 2022 10:44:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232854AbiKVKo2 (ORCPT ); Tue, 22 Nov 2022 05:44:28 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37632 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232540AbiKVKoB (ORCPT ); Tue, 22 Nov 2022 05:44:01 -0500 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 43DBA23BEF for ; Tue, 22 Nov 2022 02:37:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1669113467; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=s+4gJYDnQvTuS/31lYB/e4/AodAkPbxTauMPJtMr03Q=; b=ZliFbYjs+/2qB+F2KP9tLjWHtKGr8M8ejonM7UieCUlwC3vxkj7RTwvHa3nxq+E0X1/4ov +4rpcK3h5Ii8kfC8UnyBSmUAuIRNuVVtGr0/r0+DSCx+e2MJdvwlyGTeXLbey6AAyV8QxM LOp5cD1r+QOeHHOtxhjcAGi0pSHvqIs= Received: from mail-wm1-f70.google.com (mail-wm1-f70.google.com [209.85.128.70]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_128_GCM_SHA256) id us-mta-621-T108CTNjNLqA8wXXBgIIIw-1; Tue, 22 Nov 2022 05:37:45 -0500 X-MC-Unique: T108CTNjNLqA8wXXBgIIIw-1 Received: by mail-wm1-f70.google.com with SMTP id c126-20020a1c3584000000b003cfffcf7c1aso8547637wma.0 for ; Tue, 22 Nov 2022 02:37:45 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=s+4gJYDnQvTuS/31lYB/e4/AodAkPbxTauMPJtMr03Q=; b=i0ZpIbCTb4EbhO1rmKXYh6HnpGvbAvrtpoZoX7jl7/CPZppRD0LJG4Hn27r3AACVrE An3OS0tCb9C+7hs1xyrn14JwjZiRFjzbxY9jfs49jdvRzIhK+T4KpRNUWNRbgxrGNMF+ u60goY1Nq2uT9B6E2RkNMayknNZB32lqT9PelWzjejwQcYG6Dd1M9dpQeXXCnIQ9q7P0 DVZtanRO1No4kDHkiYY+Pjd0hAlEBdv3Gu/vxnauQePg9tvzyzlQGCroRNHiAHfyuB00 m0h3rh396fO4sU9KqEBH7yJVQ5smocLIIft3z8CAJe6MFV1k2Gyg/IwviaQlck+HPOQI bsqQ== X-Gm-Message-State: ANoB5pn6AlBVx8uIDPeMCHmhZDvON/CZn++9uysEeei1HatZ86MHgU2H P3eYFT3nKuHpOYpAPQDefSqcrZBs0+wTR5R3Dmpbcz7QTp9++OVZ/gfEql089CEUrfEQZRnPGX3 8v9+n3NumsRgmhRmfZCntYbnG8Ey+OV3UbaeE0FWEAUWXRo5ouF0LhtmRgVY+iw8= X-Received: by 2002:a05:600c:4f92:b0:3cf:e87a:8068 with SMTP id n18-20020a05600c4f9200b003cfe87a8068mr9603572wmq.3.1669113463720; Tue, 22 Nov 2022 02:37:43 -0800 (PST) X-Google-Smtp-Source: AA0mqf4Ab8h51KNcYx1KMRerv4pVPNWsPhdy90oxEI7wCRvozraqNMuP3TQujOLw162yul2tIKLrjQ== X-Received: by 2002:a05:600c:4f92:b0:3cf:e87a:8068 with SMTP id n18-20020a05600c4f9200b003cfe87a8068mr9603540wmq.3.1669113463345; Tue, 22 Nov 2022 02:37:43 -0800 (PST) Received: from teaching-eagle.redhat.com ([78.19.107.254]) by smtp.gmail.com with ESMTPSA id p11-20020a05600c468b00b003c65c9a36dfsm18674438wmo.48.2022.11.22.02.37.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 22 Nov 2022 02:37:42 -0800 (PST) From: mtahhan@redhat.com To: bpf@vger.kernel.org, linux-doc@vger.kernel.org Cc: jbrouer@redhat.com, thoiland@redhat.com, donhunte@redhat.com, akiyks@gmail.com, Maryam Tahhan Subject: [PATCH bpf-next v1 1/2] docs: fix sphinx warnings for cpumap Date: Tue, 22 Nov 2022 10:37:37 +0000 Message-Id: <20221122103738.65980-2-mtahhan@redhat.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221122103738.65980-1-mtahhan@redhat.com> References: <20221122103738.65980-1-mtahhan@redhat.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Maryam Tahhan Sphinx version >=3.3 warns about duplicate function delcarations in the CPUMAP documentation. This is because the function name is the same for Kernel and Userspace BPF progs but the parameters and return types they take is what differs. This patch moves from using the ``c:function::`` directive to using the ``code-block:: c`` directive. The patches also fix the indentation for the text associated with the "new" code block delcarations. Signed-off-by: Maryam Tahhan Acked-by: David Vernet --- Documentation/bpf/map_cpumap.rst | 48 ++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/Documentation/bpf/map_cpumap.rst b/Documentation/bpf/map_cpumap.rst index 61a797a86342..e8d9f7abf26a 100644 --- a/Documentation/bpf/map_cpumap.rst +++ b/Documentation/bpf/map_cpumap.rst @@ -30,15 +30,18 @@ Usage Kernel BPF ---------- -.. c:function:: +bpf_redirect_map() +^^^^^^^^^^^^^^^^^^ +.. code-block:: c + long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags) - Redirect the packet to the endpoint referenced by ``map`` at index ``key``. - For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs. +Redirect the packet to the endpoint referenced by ``map`` at index ``key``. +For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs. - The lower two bits of ``flags`` are used as the return code if the map lookup - fails. This is so that the return value can be one of the XDP program return - codes up to ``XDP_TX``, as chosen by the caller. +The lower two bits of ``flags`` are used as the return code if the map lookup +fails. This is so that the return value can be one of the XDP program return +codes up to ``XDP_TX``, as chosen by the caller. Userspace --------- @@ -47,12 +50,15 @@ Userspace from an eBPF program. Trying to call these functions from a kernel eBPF program will result in the program failing to load and a verifier warning. -.. c:function:: +bpf_map_update_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags); - CPU entries can be added or updated using the ``bpf_map_update_elem()`` - helper. This helper replaces existing elements atomically. The ``value`` parameter - can be ``struct bpf_cpumap_val``. +CPU entries can be added or updated using the ``bpf_map_update_elem()`` +helper. This helper replaces existing elements atomically. The ``value`` parameter +can be ``struct bpf_cpumap_val``. .. code-block:: c @@ -64,23 +70,29 @@ Userspace } bpf_prog; }; - The flags argument can be one of the following: +The flags argument can be one of the following: - BPF_ANY: Create a new element or update an existing element. - BPF_NOEXIST: Create a new element only if it did not exist. - BPF_EXIST: Update an existing element. -.. c:function:: +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + int bpf_map_lookup_elem(int fd, const void *key, void *value); - CPU entries can be retrieved using the ``bpf_map_lookup_elem()`` - helper. +CPU entries can be retrieved using the ``bpf_map_lookup_elem()`` +helper. + +bpf_map_delete_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c -.. c:function:: int bpf_map_delete_elem(int fd, const void *key); - CPU entries can be deleted using the ``bpf_map_delete_elem()`` - helper. This helper will return 0 on success, or negative error in case of - failure. +CPU entries can be deleted using the ``bpf_map_delete_elem()`` +helper. This helper will return 0 on success, or negative error in case of +failure. Examples ======== From patchwork Tue Nov 22 10:37:38 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maryam Tahhan X-Patchwork-Id: 13052192 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id ED829C433FE for ; Tue, 22 Nov 2022 10:44:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232553AbiKVKo3 (ORCPT ); Tue, 22 Nov 2022 05:44:29 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37830 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232378AbiKVKoB (ORCPT ); Tue, 22 Nov 2022 05:44:01 -0500 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4558727B02 for ; Tue, 22 Nov 2022 02:37:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1669113467; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=0BCDlnZyGDW7YaEJ/TivOn8mKa3/ZKeFN9Ygd4zUWM8=; b=FHEMAEz9xpfKp8wiJfWQB9n9bHoAK0lFlMyaceCKl+7TThldd3UIyegtF5Wa5e1Jtz38CN 3niv5pOCLf2wNzJmkKEm0RApCCQmSqx8WZjxuEun9+oINAunIFlyYFnfse89eKNZv8gKK7 A47bmFXvvzNpY3JXIkbhHFUWzVkHkrA= Received: from mail-wm1-f69.google.com (mail-wm1-f69.google.com [209.85.128.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_128_GCM_SHA256) id us-mta-298-YfnJtKt8MziyT3Pj6oCciA-1; Tue, 22 Nov 2022 05:37:46 -0500 X-MC-Unique: YfnJtKt8MziyT3Pj6oCciA-1 Received: by mail-wm1-f69.google.com with SMTP id q12-20020a1ce90c000000b003d00f3fe1e7so2817809wmc.4 for ; Tue, 22 Nov 2022 02:37:46 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=0BCDlnZyGDW7YaEJ/TivOn8mKa3/ZKeFN9Ygd4zUWM8=; b=JTZeiMs6trYq2AXg9d5gvCTeUUvuR1FjtBen8MZezvAokWRTBz4xPnsnWpCrNcosg2 +/cT+aXRq8ozEgdCSxf0V8g0YPivCUgtpDEbgAp56zUHQQmbVkWMhoPrJBrJmRXI2wJX /TzDLe6hIE16cLh9clQC4t3ie8W+Rm+FJRAhm0nGBEDwCP4wGovz94S0FSvEandS8WKx HxtsQaxx7QMWEtgmXJHWHC3gKhC6o6tUG4xF1MbzqhfcijLvmFlZyAgy5v6TbwSRQU8x OieIR1ulT/psIQYUq2NJoa8c8hzxX4MX4NJ2vgI0XoK7giEK6LyPPYnLVAgNsSMQtT5t ngVA== X-Gm-Message-State: ANoB5pmhNo2CPEIF80WJKoHVn8XvVjbZ7RgTKIGwFcNHXYZl4aHJg2HH tXJ47kFqMTw8/4Z/DgXEQfeYFxQH3jxeH33BhmdGz31dHNqPFBUT43HrR/Fyl0eXBlwwqfZ9CBJ 0hbWuYWZmTRaVxJpU0/bVr42iph10mY6FXGr4b7JGlnSl4aFDGio1kJsqKT/pSHw= X-Received: by 2002:adf:e50b:0:b0:240:e14:cfa8 with SMTP id j11-20020adfe50b000000b002400e14cfa8mr13539383wrm.63.1669113465212; Tue, 22 Nov 2022 02:37:45 -0800 (PST) X-Google-Smtp-Source: AA0mqf5vPa2asJ16s9GJjFoLHtjoFVYznQP3lg4nEMeCfAMG3Ej1SnUt8NrUNlUuRYYX712wqaV0ag== X-Received: by 2002:adf:e50b:0:b0:240:e14:cfa8 with SMTP id j11-20020adfe50b000000b002400e14cfa8mr13539370wrm.63.1669113464918; Tue, 22 Nov 2022 02:37:44 -0800 (PST) Received: from teaching-eagle.redhat.com ([78.19.107.254]) by smtp.gmail.com with ESMTPSA id p11-20020a05600c468b00b003c65c9a36dfsm18674438wmo.48.2022.11.22.02.37.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 22 Nov 2022 02:37:44 -0800 (PST) From: mtahhan@redhat.com To: bpf@vger.kernel.org, linux-doc@vger.kernel.org Cc: jbrouer@redhat.com, thoiland@redhat.com, donhunte@redhat.com, akiyks@gmail.com, Maryam Tahhan Subject: [PATCH bpf-next v1 2/2] docs: fix sphinx warnings for devmap Date: Tue, 22 Nov 2022 10:37:38 +0000 Message-Id: <20221122103738.65980-3-mtahhan@redhat.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221122103738.65980-1-mtahhan@redhat.com> References: <20221122103738.65980-1-mtahhan@redhat.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Maryam Tahhan Sphinx version >=3.3 warns about duplicate function delcarations in the DEVMAP documentation. This is because the function name is the same for Kernel and Userspace BPF progs but the parameters and return types they take is what differs. This patch moves from using the ``c:function::`` directive to using the ``code-block:: c`` directive. The patches also fix the indentation for the text associated with the "new" code block delcarations. Signed-off-by: Maryam Tahhan Acked-by: David Vernet --- Documentation/bpf/map_devmap.rst | 64 ++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 24 deletions(-) diff --git a/Documentation/bpf/map_devmap.rst b/Documentation/bpf/map_devmap.rst index f64da348dbfe..cdb7c484c425 100644 --- a/Documentation/bpf/map_devmap.rst +++ b/Documentation/bpf/map_devmap.rst @@ -29,8 +29,11 @@ Usage ===== Kernel BPF ---------- -.. c:function:: - long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags) +bpf_redirect_map() +^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags) Redirect the packet to the endpoint referenced by ``map`` at index ``key``. For ``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` this map contains @@ -56,7 +59,10 @@ lower bits of the ``flags`` argument if the map lookup fails. More information about redirection can be found :doc:`redirect` -.. c:function:: +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) Net device entries can be retrieved using the ``bpf_map_lookup_elem()`` @@ -69,13 +75,16 @@ Userspace from an eBPF program. Trying to call these functions from a kernel eBPF program will result in the program failing to load and a verifier warning. -.. c:function:: +bpf_map_update_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags); - Net device entries can be added or updated using the ``bpf_map_update_elem()`` - helper. This helper replaces existing elements atomically. The ``value`` parameter - can be ``struct bpf_devmap_val`` or a simple ``int ifindex`` for backwards - compatibility. +Net device entries can be added or updated using the ``bpf_map_update_elem()`` +helper. This helper replaces existing elements atomically. The ``value`` parameter +can be ``struct bpf_devmap_val`` or a simple ``int ifindex`` for backwards +compatibility. .. code-block:: c @@ -87,35 +96,42 @@ Userspace } bpf_prog; }; - The ``flags`` argument can be one of the following: - +The ``flags`` argument can be one of the following: - ``BPF_ANY``: Create a new element or update an existing element. - ``BPF_NOEXIST``: Create a new element only if it did not exist. - ``BPF_EXIST``: Update an existing element. - DEVMAPs can associate a program with a device entry by adding a ``bpf_prog.fd`` - to ``struct bpf_devmap_val``. Programs are run after ``XDP_REDIRECT`` and have - access to both Rx device and Tx device. The program associated with the ``fd`` - must have type XDP with expected attach type ``xdp_devmap``. - When a program is associated with a device index, the program is run on an - ``XDP_REDIRECT`` and before the buffer is added to the per-cpu queue. Examples - of how to attach/use xdp_devmap progs can be found in the kernel selftests: +DEVMAPs can associate a program with a device entry by adding a ``bpf_prog.fd`` +to ``struct bpf_devmap_val``. Programs are run after ``XDP_REDIRECT`` and have +access to both Rx device and Tx device. The program associated with the ``fd`` +must have type XDP with expected attach type ``xdp_devmap``. +When a program is associated with a device index, the program is run on an +``XDP_REDIRECT`` and before the buffer is added to the per-cpu queue. Examples +of how to attach/use xdp_devmap progs can be found in the kernel selftests: - - ``tools/testing/selftests/bpf/prog_tests/xdp_devmap_attach.c`` - - ``tools/testing/selftests/bpf/progs/test_xdp_with_devmap_helpers.c`` +- ``tools/testing/selftests/bpf/prog_tests/xdp_devmap_attach.c`` +- ``tools/testing/selftests/bpf/progs/test_xdp_with_devmap_helpers.c`` + +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c .. c:function:: int bpf_map_lookup_elem(int fd, const void *key, void *value); - Net device entries can be retrieved using the ``bpf_map_lookup_elem()`` - helper. +Net device entries can be retrieved using the ``bpf_map_lookup_elem()`` +helper. + +bpf_map_delete_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c .. c:function:: int bpf_map_delete_elem(int fd, const void *key); - Net device entries can be deleted using the ``bpf_map_delete_elem()`` - helper. This helper will return 0 on success, or negative error in case of - failure. +Net device entries can be deleted using the ``bpf_map_delete_elem()`` +helper. This helper will return 0 on success, or negative error in case of +failure. Examples ========