From patchwork Wed Feb 17 01:08:05 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384277 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 27D02C43381 for ; Wed, 17 Feb 2021 01:09:26 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id F1B4C64EB4 for ; Wed, 17 Feb 2021 01:09:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231393AbhBQBJN (ORCPT ); Tue, 16 Feb 2021 20:09:13 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47430 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230292AbhBQBJK (ORCPT ); Tue, 16 Feb 2021 20:09:10 -0500 Received: from mail-pl1-x630.google.com (mail-pl1-x630.google.com [IPv6:2607:f8b0:4864:20::630]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 364DAC061574; Tue, 16 Feb 2021 17:08:30 -0800 (PST) Received: by mail-pl1-x630.google.com with SMTP id z7so6498834plk.7; Tue, 16 Feb 2021 17:08:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=vA7yf0zk+T/kB8pnBChx/NJnOYZDQH1veo7XbeOKZhg=; b=SYS1iA85ZA6CTQnNjd1kT0S7tKOPvrWT5jfcqRekx8PY7g0esCw/OGukvmYuOZcYlA 98VnNk79O3XfWIzcyXz4aYqL6siGdPzgAH6lu7bKKRosbbA3u4HWuMlpw8DvfMZ8MdvY zc4Z879xdDgaEqGlWJvT8ytlLKyV4El5ZSE9fgf4JE//9N6jtf8w2/67o+avlFI6Um3y WHi0vd+XXfuUau7DYX8kuz2IvpwnTRLZ+f+hit2yrtG7PTNJM9Zl6UNhXYyaPuqYBPGM Ebvzg5nCQ14R5Wxt4ebdZvpJB1WM9soacfHh1ul/fjbciTSCst+8uJx5b7YVFUYFkNDy Wx3w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=vA7yf0zk+T/kB8pnBChx/NJnOYZDQH1veo7XbeOKZhg=; b=muSrxyTEjt+FM48zeKhDn+eQ9qz+HZAh7DNR6C38rj7y3RUnFPvd2CCXyLGBfgnPRu xsmRayZ2ig1uDPy02gtgAOsHjhVHutnYbyDCRMZweV404JfBztDiPCUKkfV7QjaS9Mfg NrwDWMXuQHX+2GmpaGyS9ksjrZRtqdHDYnCL1rOX1bNIhGvsUkvTWkw0Djs8YIB2uxYK a4mF3/Gjf7/sGbrezQCkVgpYGP3Ow2gmNjN4vLCfqWwDfz74r2k6NTrbnIvhcOa4GpVF 2qdXAVlGo5IB3eZxMbqwdBWujCP21kKD1A81nZ4WByFMkDBh1aCcM+mGVNETNKy5uRB2 9ozQ== X-Gm-Message-State: AOAM533ZEgrENX4h0tu4397iNSVJxkUx1Kw81eILuVN1HnH5n3Fw9FrR fLaziePdoBlEmt/HiHpgmw1RSKrJnsq0fA== X-Google-Smtp-Source: ABdhPJxP/4NPeq90Q/Bm7YXAygVT/vf/FljHYezElmVReu02o328iYnecKlVaROM/6rfOi8qZfMzTg== X-Received: by 2002:a17:902:8349:b029:df:d13d:bf83 with SMTP id z9-20020a1709028349b02900dfd13dbf83mr180546pln.69.1613524109369; Tue, 16 Feb 2021 17:08:29 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:28 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet Subject: [PATCH bpf-next 01/17] bpf: Import syscall arg documentation Date: Tue, 16 Feb 2021 17:08:05 -0800 Message-Id: <20210217010821.1810741-2-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer These descriptions are present in the man-pages project from the original submissions around 2015-2016. Import them so that they can be kept up to date as developers extend the bpf syscall commands. These descriptions follow the pattern used by scripts/bpf_helpers_doc.py so that we can take advantage of the parser to generate more up-to-date man page writing based upon these headers. Some minor wording adjustments were made to make the descriptions more consistent for the description / return format. Reviewed-by: Quentin Monnet Co-authored-by: Alexei Starovoitov Co-authored-by: Michael Kerrisk Signed-off-by: Joe Stringer --- include/uapi/linux/bpf.h | 119 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 118 insertions(+), 1 deletion(-) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 4c24daa43bac..56d7db0f3daf 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -93,7 +93,124 @@ union bpf_iter_link_info { } map; }; -/* BPF syscall commands, see bpf(2) man-page for details. */ +/* BPF syscall commands, see bpf(2) man-page for more details. + * + * The operation to be performed by the **bpf**\ () system call is determined + * by the *cmd* argument. Each operation takes an accompanying argument, + * provided via *attr*, which is a pointer to a union of type *bpf_attr* (see + * below). The size argument is the size of the union pointed to by *attr*. + * + * Start of BPF syscall commands: + * + * BPF_MAP_CREATE + * Description + * Create a map and return a file descriptor that refers to the + * map. The close-on-exec file descriptor flag (see **fcntl**\ (2)) + * is automatically enabled for the new file descriptor. + * + * Applying **close**\ (2) to the file descriptor returned by + * **BPF_MAP_CREATE** will delete the map (but see NOTES). + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_MAP_LOOKUP_ELEM + * Description + * Look up an element with a given *key* in the map referred to + * by the file descriptor *map_fd*. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_MAP_UPDATE_ELEM + * Description + * Create or update an element (key/value pair) in a specified map. + * + * The *flags* argument should be specified as 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. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * May set *errno* to **EINVAL**, **EPERM**, **ENOMEM**, + * **E2BIG**, **EEXIST**, or **ENOENT**. + * + * **E2BIG** + * The number of elements in the map reached the + * *max_entries* limit specified at map creation time. + * **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_ELEM + * Description + * Look up and delete an element by key in a specified map. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_MAP_GET_NEXT_KEY + * Description + * Look up an element by key in a specified map and return the key + * of the next element. Can be used to iterate over all elements + * in the map. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * The following cases can be used to iterate over all elements of + * the map: + * + * * If *key* is not found, the operation returns zero and sets + * the *next_key* pointer to the key of the first element. + * * If *key* is found, the operation returns zero and sets the + * *next_key* pointer to the key of the next element. + * * If *key* is the last element, returns -1 and *errno* is set + * to **ENOENT**. + * + * May set *errno* to **ENOMEM**, **EFAULT**, **EPERM**, or + * **EINVAL** on error. + * + * BPF_PROG_LOAD + * Description + * Verify and load an eBPF program, returning a new file + * descriptor associated with the program. + * + * Applying **close**\ (2) to the file descriptor returned by + * **BPF_PROG_LOAD** will unload the eBPF program (but see NOTES). + * + * The close-on-exec file descriptor flag (see **fcntl**\ (2)) is + * automatically enabled for the new file descriptor. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * NOTES + * eBPF objects (maps and programs) can be shared between processes. + * For example, after **fork**\ (2), the child inherits file descriptors + * referring to the same eBPF objects. In addition, file descriptors + * referring to eBPF objects can be transferred over UNIX domain sockets. + * File descriptors referring to eBPF objects can be duplicated in the + * usual way, using **dup**\ (2) and similar calls. An eBPF object is + * deallocated only after all file descriptors referring to the object + * have been closed. + */ enum bpf_cmd { BPF_MAP_CREATE, BPF_MAP_LOOKUP_ELEM, From patchwork Wed Feb 17 01:08:06 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384276 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI, SPF_HELO_NONE, SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9F52DC433E6 for ; Wed, 17 Feb 2021 01:09:32 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 5CC2564E57 for ; Wed, 17 Feb 2021 01:09:32 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231425AbhBQBJb (ORCPT ); Tue, 16 Feb 2021 20:09:31 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47440 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231180AbhBQBJM (ORCPT ); Tue, 16 Feb 2021 20:09:12 -0500 Received: from mail-pg1-x536.google.com (mail-pg1-x536.google.com [IPv6:2607:f8b0:4864:20::536]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 118C7C061786; Tue, 16 Feb 2021 17:08:32 -0800 (PST) Received: by mail-pg1-x536.google.com with SMTP id 75so4051045pgf.13; Tue, 16 Feb 2021 17:08:32 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=5fKzG8JmJ15nM649fVhyJSDnrHFPPSgaEHYMjgBGmTI=; b=FvWDuAxZR7NA+CN8uodzBws6VelrdsQyqJ1DofMXvevdtrH7GZSA+6soTdIj9yrYKf 65Gs9o/sdz/oDnojWu3CcV87Qk23Ek2DEmAnkQP4baNuf/l1BlGTcQpE/yGnguIZuGKr 7D0x49tmFKduz6hZDAZ4fvxkB6ELvS7OzKh4dlLhqE8/KvRrDqFMatdcFryxjk2Kh5mP e34gmjtX7G6fqKRJz4e4OdbIKH+i4JBwC46EoJ0pLGQrVhpOFb9XXvzI+Q2j1qVv1/V1 LOII5Oy8YW8rUgKdXJPL89QX4ij2AGEMfAvMVFK7sge3Ps2dVmqwd8owNOueMkVkqK0q GCWA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=5fKzG8JmJ15nM649fVhyJSDnrHFPPSgaEHYMjgBGmTI=; b=mW0pdW1UPuYkt5Vew6S8rgAHlVktDgd+ohteJFMv5ESaXFcbM7XYiG2yUQGBheDXOa P2RmdFco6mHcN+vTWYS62Jy8Khu3Gpa9Q5/j95T6hUsNL5br+fvAy0TkH+08LjRaxpXs jE8YyMyUoAFmv8qR7TDiFvmp/FZq4p2w9awY+qRLcAbzMmbMRUGqFgp4AX+8gi+aO8HX 21jIuQ+Ru8Nbbp3RDvENs3SaXkVQkt64gdDPBlQE8NwdGBaWvZh8qdTRhnU52ID2SJDE KBOnGprOdxMIKkntJodz+gca/6Q0MR+zU80s4t+PkJCtzjluJ5Ns4yEjSknZd0CqvL3J hWCw== X-Gm-Message-State: AOAM531KPIT14ILnu+Nef0hh5/kEwAsa8aO/YzzKF7NLMQYrpg0FObSu RMl2PC2sA1nWuRb0TeZR5BrozMD9dW5pEg== X-Google-Smtp-Source: ABdhPJw7ClzaNqmsKaSmbumtOCfNPy4mbMLKHNuV8MhWfNJX2iIzHcfcz5xxQqEurOaadBoxN+QKig== X-Received: by 2002:aa7:9ec5:0:b029:1e7:a1c:8f8a with SMTP id r5-20020aa79ec50000b02901e70a1c8f8amr22740274pfq.41.1613524110859; Tue, 16 Feb 2021 17:08:30 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:30 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet Subject: [PATCH bpf-next 02/17] bpf: Add minimal bpf() command documentation Date: Tue, 16 Feb 2021 17:08:06 -0800 Message-Id: <20210217010821.1810741-3-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer Introduce high-level descriptions of the intent and return codes of the bpf() syscall commands. Subsequent patches may further flesh out the content to provide a more useful programming reference. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- include/uapi/linux/bpf.h | 368 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 368 insertions(+) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 56d7db0f3daf..ac6880d7b01b 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -201,6 +201,374 @@ union bpf_iter_link_info { * A new file descriptor (a nonnegative integer), or -1 if an * error occurred (in which case, *errno* is set appropriately). * + * BPF_OBJ_PIN + * Description + * Pin an eBPF program or map referred by the specified *bpf_fd* + * to the provided *pathname* on the filesystem. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_OBJ_GET + * Description + * Open a file descriptor for the eBPF object pinned to the + * specified *pathname*. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_PROG_ATTACH + * Description + * Attach an eBPF program to a *target_fd* at the specified + * *attach_type* hook. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_PROG_DETACH + * Description + * Detach the eBPF program associated with the *target_fd* at the + * hook specified by *attach_type*. The program must have been + * previously attached using **BPF_PROG_ATTACH**. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_PROG_TEST_RUN + * Description + * Run an eBPF program a number of times against a provided + * program context and return the modified program context and + * duration of the test run. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_PROG_GET_NEXT_ID + * Description + * Fetch the next eBPF program currently loaded into the kernel. + * + * Looks for the eBPF program with an id greater than *start_id* + * and updates *next_id* on success. If no other eBPF programs + * remain with ids higher than *start_id*, returns -1 and sets + * *errno* to **ENOENT**. + * + * Return + * Returns zero on success. On error, or when no id remains, -1 + * is returned and *errno* is set appropriately. + * + * BPF_MAP_GET_NEXT_ID + * Description + * Fetch the next eBPF map currently loaded into the kernel. + * + * Looks for the eBPF map with an id greater than *start_id* + * and updates *next_id* on success. If no other eBPF maps + * remain with ids higher than *start_id*, returns -1 and sets + * *errno* to **ENOENT**. + * + * Return + * Returns zero on success. On error, or when no id remains, -1 + * is returned and *errno* is set appropriately. + * + * BPF_PROG_GET_FD_BY_ID + * Description + * Open a file descriptor for the eBPF program corresponding to + * *prog_id*. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_MAP_GET_FD_BY_ID + * Description + * Open a file descriptor for the eBPF map corresponding to + * *map_id*. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_OBJ_GET_INFO_BY_FD + * Description + * Obtain information about the eBPF object corresponding to + * *bpf_fd*. + * + * Populates up to *info_len* bytes of *info*, which will be in + * one of the following formats depending on the eBPF object type + * of *bpf_fd*: + * + * * **struct bpf_prog_info** + * * **struct bpf_map_info** + * * **struct bpf_btf_info** + * * **struct bpf_link_info** + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_PROG_QUERY + * Description + * Obtain information about eBPF programs associated with the + * specified *attach_type* hook. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_RAW_TRACEPOINT_OPEN + * Description + * Attach an eBPF program to a tracepoint *name* to access kernel + * internal arguments of the tracepoint in their raw form. + * + * The *prog_fd* must be a valid file descriptor associated with + * a loaded eBPF program of type **BPF_PROG_TYPE_RAW_TRACEPOINT**. + * + * No ABI guarantees are made about the content of tracepoint + * arguments exposed to the corresponding eBPF program. + * + * Applying **close**\ (2) to the file descriptor returned by + * **BPF_RAW_TRACEPOINT_OPEN** will delete the map (but see NOTES). + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_BTF_LOAD + * Description + * Verify and load BPF Type Format (BTF) metadata into the kernel, + * returning a new file descriptor associated with the metadata. + * BTF is described in more detail at + * https://www.kernel.org/doc/html/latest/bpf/btf.html. + * + * The *btf* parameter must point to valid memory providing + * *btf_size* bytes of BTF binary metadata. + * + * The returned file descriptor can be passed to other **bpf**\ () + * subcommands such as **BPF_PROG_LOAD** or **BPF_MAP_CREATE** to + * associate the BTF with those objects. + * + * Similar to **BPF_PROG_LOAD**, **BPF_BTF_LOAD** has optional + * parameters to specify a *btf_log_buf*, *btf_log_size* and + * *btf_log_level* which allow the kernel to return freeform log + * output regarding the BTF verification process. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_BTF_GET_FD_BY_ID + * Description + * Open a file descriptor for the BPF Type Format (BTF) + * corresponding to *btf_id*. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_TASK_FD_QUERY + * Description + * Obtain information about eBPF programs associated with the + * target process identified by *pid* and *fd*. + * + * If the *pid* and *fd* are associated with a tracepoint, kprobe + * or uprobe perf event, then the *prog_id* and *fd_type* will + * be populated with the eBPF program id and file descriptor type + * of type **bpf_task_fd_type**. If associated with a kprobe or + * uprobe, the *probe_offset* and *probe_addr* will also be + * populated. Optionally, if *buf* is provided, then up to + * *buf_len* bytes of *buf* will be populated with the name of + * the tracepoint, kprobe or uprobe. + * + * The resulting *prog_id* may be introspected in deeper detail + * using **BPF_PROG_GET_FD_BY_ID** and **BPF_OBJ_GET_INFO_BY_FD**. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_MAP_LOOKUP_AND_DELETE_ELEM + * Description + * Look up an element with the given *key* in the map referred to + * by the file descriptor *fd*, and if found, delete the element. + * + * The **BPF_MAP_TYPE_QUEUE** and **BPF_MAP_TYPE_STACK** map types + * implement this command as a "pop" operation, deleting the top + * element rather than one corresponding to *key*. + * The *key* and *key_len* parameters should be zeroed when + * issuing this operation for these map types. + * + * This command is only valid for the following map types: + * * **BPF_MAP_TYPE_QUEUE** + * * **BPF_MAP_TYPE_STACK** + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_MAP_FREEZE + * Description + * Freeze the permissions of the specified map. + * + * Write permissions may be frozen by passing zero *flags*. + * Upon success, no future syscall invocations may alter the + * map state of *map_fd*. Write operations from eBPF programs + * are still possible for a frozen map. + * + * Not supported for maps of type **BPF_MAP_TYPE_STRUCT_OPS**. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_BTF_GET_NEXT_ID + * Description + * Fetch the next BPF Type Format (BTF) object currently loaded + * into the kernel. + * + * Looks for the BTF object with an id greater than *start_id* + * and updates *next_id* on success. If no other BTF objects + * remain with ids higher than *start_id*, returns -1 and sets + * *errno* to **ENOENT**. + * + * Return + * Returns zero on success. On error, or when no id remains, -1 + * is returned and *errno* is set appropriately. + * + * BPF_MAP_LOOKUP_BATCH + * Description + * Iterate and fetch multiple elements in a map. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_MAP_LOOKUP_AND_DELETE_BATCH + * Description + * Iterate and delete multiple elements in a map. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_MAP_UPDATE_BATCH + * Description + * Iterate and update multiple elements in a map. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_MAP_DELETE_BATCH + * Description + * Iterate and delete multiple elements in a map. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_LINK_CREATE + * Description + * Attach an eBPF program to a *target_fd* at the specified + * *attach_type* hook and return a file descriptor handle for + * managing the link. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_LINK_UPDATE + * Description + * Update the eBPF program in the specified *link_fd* to + * *new_prog_fd*. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_LINK_GET_FD_BY_ID + * Description + * Open a file descriptor for the eBPF Link corresponding to + * *link_id*. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_LINK_GET_NEXT_ID + * Description + * Fetch the next eBPF link currently loaded into the kernel. + * + * Looks for the eBPF link with an id greater than *start_id* + * and updates *next_id* on success. If no other eBPF links + * remain with ids higher than *start_id*, returns -1 and sets + * *errno* to **ENOENT**. + * + * Return + * Returns zero on success. On error, or when no id remains, -1 + * is returned and *errno* is set appropriately. + * + * BPF_ENABLE_STATS + * Description + * Enable eBPF runtime statistics gathering. + * + * Runtime statistics gathering for the eBPF runtime is disabled + * by default to minimize the corresponding performance overhead. + * This command enables statistics globally. + * + * Multiple programs may independently enable statistics. + * After gathering the desired statistics, eBPF runtime statistics + * may be disabled again by calling **close**\ (2) for the file + * descriptor returned by this function. Statistics will only be + * disabled system-wide when all outstanding file descriptors + * returned by prior calls for this subcommand are closed. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_ITER_CREATE + * Description + * Create an iterator on top of the specified *link_fd* (as + * previously created using **BPF_LINK_CREATE**) and return a + * file descriptor that can be used to trigger the iteration. + * + * If the resulting file descriptor is pinned to the filesystem + * using **BPF_OBJ_PIN**, then subsequent **read**\ (2) syscalls + * for that path will trigger the iterator to read kernel state + * using the eBPF program attached to *link_fd*. + * + * Return + * A new file descriptor (a nonnegative integer), or -1 if an + * error occurred (in which case, *errno* is set appropriately). + * + * BPF_LINK_DETACH + * Description + * Forcefully detach the specified *link_fd* from its + * corresponding attachment point. + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * + * BPF_PROG_BIND_MAP + * Description + * Bind a map to the lifetime of an eBPF program. + * + * The map identified by *map_fd* is bound to the program + * identified by *prog_fd* and only released when *prog_fd* is + * released. This may be used in cases where metadata should be + * associated with a program which otherwise does not contain any + * references to the map (for example, embedded in the eBPF + * program instructions). + * + * Return + * Returns zero on success. On error, -1 is returned and *errno* + * is set appropriately. + * * NOTES * eBPF objects (maps and programs) can be shared between processes. * For example, after **fork**\ (2), the child inherits file descriptors From patchwork Wed Feb 17 01:08:08 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384275 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 32277C433DB for ; Wed, 17 Feb 2021 01:10:01 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 07FBD64E57 for ; Wed, 17 Feb 2021 01:10:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231451AbhBQBJo (ORCPT ); Tue, 16 Feb 2021 20:09:44 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47458 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231395AbhBQBJQ (ORCPT ); Tue, 16 Feb 2021 20:09:16 -0500 Received: from mail-pf1-x432.google.com (mail-pf1-x432.google.com [IPv6:2607:f8b0:4864:20::432]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A09DAC06178A; Tue, 16 Feb 2021 17:08:34 -0800 (PST) Received: by mail-pf1-x432.google.com with SMTP id m6so7363057pfk.1; Tue, 16 Feb 2021 17:08:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=3KAnAbTTe8mmyGdTip1CGM5L9IEVFc3mWnvSe2CSkws=; b=KVi3gtAUMTmsDOl1WRMk7ZiqqtxipOJaAW2Ez2R2O3geu6HCBcT0pyjyFxvburERWG AFBfcnsj+AkMfoK15FPUBHV+X0S3gkvCvtdtXxQCd4xxCS1qzhhGs5Cc75QgcsKovpSN nplAmXLe567CYPEgRcYG0bP/tycAzuO+HRjTKCCAuFTdJF6ZB+rfAsTLO7ro3kaKyyZ0 Frcyl3klg0WmHgh4zIlwwCGHIDkhgFPiVYlp2DkTI5IHe9nqBzB3FGv4IB+ToL/9UL3J RbTxtRquGbRUlusiT5uVFURmAbqF0DYbhbNPl/slA4DANmohaMQsD8sGWspwCyRYQF0u bLQw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=3KAnAbTTe8mmyGdTip1CGM5L9IEVFc3mWnvSe2CSkws=; b=UxN6chU6vGhGDIiSp3OdzFnGvMEcCiaBfoDv1wLePUCkeNrgeqkH2mmhbO86JYACeG OW/9aDOW8iBPSW4agj7cfj+FZNRkhsTzs3/WnZkB+raQAY36NOZ13X2hpipDiQNdaVWB exf2wgRxEiH7egYeGU/wbtPk1C/Lxbjmvb4MNVbEeuHiO0soL8s+X+cfsCmCIHIy+s+k iie/PmEcmX5e9vxM6UQWyt5WJBoyysvGS5/o3PBENu+7U1uTXSFdBSbSh30h9gJxZbUX TncG6cxJDSO+j+iinWTzO0NcV319jrqTXLVAdhC8Yeofr0NvCeExyZzNd34wjtGQNzBW ofRg== X-Gm-Message-State: AOAM532o8iJegWJghIXB+8gFwhw8QQBr56slPwGW0xq3fTDxJAqyPyOz tsUReCplvzOM3qpylYSPo8kdunvZO9w8AA== X-Google-Smtp-Source: ABdhPJyxeCM/3c/TdtluttSnoPdGFMwn79SU5ygjwDajObQTF6wvEMc3fBBbCZiVA/r8GtmqM4rxsw== X-Received: by 2002:aa7:80ca:0:b029:1c1:b636:ecc2 with SMTP id a10-20020aa780ca0000b02901c1b636ecc2mr22076437pfn.20.1613524113856; Tue, 16 Feb 2021 17:08:33 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:33 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet Subject: [PATCH bpf-next 04/17] bpf: Document BPF_PROG_PIN syscall command Date: Tue, 16 Feb 2021 17:08:08 -0800 Message-Id: <20210217010821.1810741-5-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer Commit b2197755b263 ("bpf: add support for persistent maps/progs") contains the original implementation and git logs, used as reference for this documentation. Also pull in the filename restriction as documented in commit 6d8cb045cde6 ("bpf: comment why dots in filenames under BPF virtual FS are not allowed") Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- CC: Daniel Borkmann --- include/uapi/linux/bpf.h | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index d02259458fd6..8301a19c97de 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -216,6 +216,22 @@ union bpf_iter_link_info { * Pin an eBPF program or map referred by the specified *bpf_fd* * to the provided *pathname* on the filesystem. * + * The *pathname* argument must not contain a dot ("."). + * + * On success, *pathname* retains a reference to the eBPF object, + * preventing deallocation of the object when the original + * *bpf_fd* is closed. This allow the eBPF object to live beyond + * **close**\ (\ *bpf_fd*\ ), and hence the lifetime of the parent + * process. + * + * Applying **unlink**\ (2) or similar calls to the *pathname* + * unpins the object from the filesystem, removing the reference. + * If no other file descriptors or filesystem nodes refer to the + * same object, it will be deallocated (see NOTES). + * + * The filesystem type for the parent directory of *pathname* must + * be **BPF_FS_MAGIC**. + * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. @@ -581,13 +597,17 @@ union bpf_iter_link_info { * * NOTES * eBPF objects (maps and programs) can be shared between processes. - * For example, after **fork**\ (2), the child inherits file descriptors - * referring to the same eBPF objects. In addition, file descriptors - * referring to eBPF objects can be transferred over UNIX domain sockets. - * File descriptors referring to eBPF objects can be duplicated in the - * usual way, using **dup**\ (2) and similar calls. An eBPF object is - * deallocated only after all file descriptors referring to the object - * have been closed. + * * After **fork**\ (2), the child inherits file descriptors + * referring to the same eBPF objects. + * * File descriptors referring to eBPF objects can be transferred over + * **unix**\ (7) domain sockets. + * * File descriptors referring to eBPF objects can be duplicated in the + * usual way, using **dup**\ (2) and similar calls. + * * File descriptors referring to eBPF objects can be pinned to the + * filesystem using the **BPF_OBJ_PIN** command of **bpf**\ (2). + * An eBPF object is deallocated only after all file descriptors referring + * to the object have been closed and no references remain pinned to the + * filesystem or attached (for example, bound to a program or device). */ enum bpf_cmd { BPF_MAP_CREATE, From patchwork Wed Feb 17 01:08:10 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384274 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0DB8AC433E0 for ; Wed, 17 Feb 2021 01:10:27 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id CAC2964E79 for ; Wed, 17 Feb 2021 01:10:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231521AbhBQBKX (ORCPT ); Tue, 16 Feb 2021 20:10:23 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47468 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231403AbhBQBJS (ORCPT ); Tue, 16 Feb 2021 20:09:18 -0500 Received: from mail-pl1-x634.google.com (mail-pl1-x634.google.com [IPv6:2607:f8b0:4864:20::634]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E66F2C061756; Tue, 16 Feb 2021 17:08:37 -0800 (PST) Received: by mail-pl1-x634.google.com with SMTP id z7so6499040plk.7; Tue, 16 Feb 2021 17:08:37 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=6/SzyQ0ReKPIhC/d4qfT0iwh1ZBZem+Ch9avlwoAplk=; b=gVnZvIlKzpHKIv/8B++qGAch2hWjjuAY1tyLdFMDnzQfrhLdF5U8XbT83gLbcI/dUd fqxX6Xq/fSQJZjgEiqCoqL5IUF3WXD4c/nrrVdKMT+bwJoS3ufwu6aaB7BouMg5dpWAn dCtcA/Q5OC250smc2vFahPGHDCQGt7HO8c4KexdFYTOzNPezGxq/sQMxsTRCuWocobtT XqcQkPkYg9w9TjFpsQkXbSl9fSpkxE7gNMfA7GYDB/zx21SAOcgASlu6uW16Q3jxbNIi YoWKCUEnFb/3iEGGiMi08btgfMW9nnKE/pWd5SVh9bkE1t6yscWy85dku8ot1q1ybWjv lyzQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=6/SzyQ0ReKPIhC/d4qfT0iwh1ZBZem+Ch9avlwoAplk=; b=VU/oSesLVM2Iievs6jeVQeqkpAkU66GzVpA1BXZCYj6l0N8lnJs19DWS38ofZ5PQjO hAp9E5M/RHTogRD07cFJckPKt3kuHnncZjlajsdIrvU5UuE7PGBk7s9WcgmTzOAEclKy GAjS/ffbxKM+aOQZrWtoXHuOcqNYXvI74ggMKwVbUi9Ya6k+INu+e/DzkbL/c7ooM/c3 isYzlTfkt2UjBTH6sdNv2koxQ2JoApmNLuYG9ZQD+rGGkhNury4+ko9ZnUdt0dVwyxBx l5wcsh84rCNbNNcChG+9dF8jQZPYpb/GS7VtHoVCGAjFbBco/TiGZUD4ifwTAv7foTju 7HCA== X-Gm-Message-State: AOAM532lSgbJyfcHB2A1IfbYw9r8Ux62YDZ4ZA3aw8a/kkDdh5gURORb JpKBmgKzoGeZ2thRpJtAe26u9kpTC5xwXA== X-Google-Smtp-Source: ABdhPJyE0N+JiSpIVEpOkxXqEYEalGq51I4TjyvRLTNjKOHAYiwjIcyuuX2nLBaznQsTcVxsetj4Yg== X-Received: by 2002:a17:90a:7025:: with SMTP id f34mr6640089pjk.116.1613524117225; Tue, 16 Feb 2021 17:08:37 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:36 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet Subject: [PATCH bpf-next 06/17] bpf: Document BPF_PROG_TEST_RUN syscall command Date: Tue, 16 Feb 2021 17:08:10 -0800 Message-Id: <20210217010821.1810741-7-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer Based on a brief read of the corresponding source code. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- include/uapi/linux/bpf.h | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 603605c5ca03..86fe0445c395 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -303,14 +303,22 @@ union bpf_iter_link_info { * * BPF_PROG_TEST_RUN * Description - * Run an eBPF program a number of times against a provided - * program context and return the modified program context and - * duration of the test run. + * Run the eBPF program associated with the *prog_fd* a *repeat* + * number of times against a provided program context *ctx_in* and + * data *data_in*, and return the modified program context + * *ctx_out*, *data_out* (for example, packet data), result of the + * execution *retval*, and *duration* of the test run. * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. * + * **ENOSPC** + * Either *data_size_out* or *ctx_size_out* is too small. + * **ENOTSUPP** + * This command is not supported by the program type of + * the program referred to by *prog_fd*. + * * BPF_PROG_GET_NEXT_ID * Description * Fetch the next eBPF program currently loaded into the kernel. From patchwork Wed Feb 17 01:08:12 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384271 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7A258C433DB for ; Wed, 17 Feb 2021 01:12:08 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4740D64E6B for ; Wed, 17 Feb 2021 01:12:08 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230305AbhBQBMD (ORCPT ); Tue, 16 Feb 2021 20:12:03 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47578 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231458AbhBQBJs (ORCPT ); Tue, 16 Feb 2021 20:09:48 -0500 Received: from mail-pf1-x42e.google.com (mail-pf1-x42e.google.com [IPv6:2607:f8b0:4864:20::42e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1A09FC06178C; Tue, 16 Feb 2021 17:08:41 -0800 (PST) Received: by mail-pf1-x42e.google.com with SMTP id y25so4064976pfp.5; Tue, 16 Feb 2021 17:08:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=8woX65qt/qStfvzx9YUb2TtgE8YzDYd/O7zmfhWhqxM=; b=hng6jOIfb+MwTjYrFJ1EmYdly9YDMgRt+ebBbmz00ZTM+LBn9sXtvr2Co9Qdgk4o+f cFsTZy/5P9XViQrHvG7aevHM6vUIAnvNTh1Rqf4p1/dETWaC60sVd97OoKcichxLq3DC FrcNv4q5IosMPI7I18gFi87LVglVeRZQSm5F8XRszYft6k50TGT8bsc8g/Kb+eTdjq77 IdW8hzeXqmFR0vG+fjAorFPTjFteS0gahYH8X6PCM0CbEwq5DanZzde5oL05OMrBA/1v DXnrKlMIZa8CS7c3iw1pdeIzRLBydzJjDWg2OhYOiSE/wHwfk8DCYNmY5mh/gw8mIDfz rqqw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=8woX65qt/qStfvzx9YUb2TtgE8YzDYd/O7zmfhWhqxM=; b=li3QeH5/tkUkwHYnXRItYM6UUGkP31BjEttYt9AWoEePqIfn0+e9rrno+xG6KWMwMD KVGNCFN/24W3N5a/h0cCAQLa5chDr+P4ia9R+HRAbY5vJsa/pCElEAmGtkTfSQfPWULO SkcMYcrUATV1lo+z82lLKdM0twmUck5Wpf8pzNy7gCpvDyOdxjaFPl09lUB/DgUoXQWx ugkIgFua2ulhGWFwr3DQlX1x577ZuJUZpgMb7N8YaEWgelMEKHeY7yzgAk1xeUQ0Em1v RU3ptVhHf5tyTQJgZR73Ke8C4Rl6UKz/lePeh7+9l1loltWW5HvUEmGo8wSKvkk3vqdl pwiw== X-Gm-Message-State: AOAM533uUfmCTa80j5RI68QyiG1uv/bfD4J6L4eqMqXLtQ5Xg0BsszXI X4r/q0H0gA++i9BoH7/RTmTaLbfWy1oVuw== X-Google-Smtp-Source: ABdhPJxkiO/5qP/ws/49azU5oHCJl39GjUlKXbqu4BQ8szhhVumUXXWyCsWtiJQU/UqLQl44jVM9GQ== X-Received: by 2002:a63:1c1d:: with SMTP id c29mr22255658pgc.94.1613524120277; Tue, 16 Feb 2021 17:08:40 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:39 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet , Brian Vazquez , Yonghong Song Subject: [PATCH bpf-next 08/17] bpf: Document BPF_MAP_*_BATCH syscall commands Date: Tue, 16 Feb 2021 17:08:12 -0800 Message-Id: <20210217010821.1810741-9-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer 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") Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- CC: Brian Vazquez CC: Yonghong Song @Yonghong, would you mind double-checking whether the text is accurate for the case where BPF_MAP_LOOKUP_AND_DELETE_BATCH returns -EFAULT? --- 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 a07cecfd2148..893803f69a64 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -550,13 +550,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* @@ -564,15 +606,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* From patchwork Wed Feb 17 01:08:14 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384273 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id A7443C433E0 for ; Wed, 17 Feb 2021 01:11:06 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6AFFE64E57 for ; Wed, 17 Feb 2021 01:11:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231527AbhBQBLD (ORCPT ); Tue, 16 Feb 2021 20:11:03 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47430 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231411AbhBQBJ0 (ORCPT ); Tue, 16 Feb 2021 20:09:26 -0500 Received: from mail-pf1-x433.google.com (mail-pf1-x433.google.com [IPv6:2607:f8b0:4864:20::433]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C31C6C061794; Tue, 16 Feb 2021 17:08:52 -0800 (PST) Received: by mail-pf1-x433.google.com with SMTP id b145so7355790pfb.4; Tue, 16 Feb 2021 17:08:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=dv8MkLcOtY2EeZNXcDWE1hLwVEjep3x1oeuEfehCxV8=; b=QJk/AXrEZD0nnTG+SBuG0PXQqRRTtcvl/el5ihhrL+Vp+k27B1cYx+izpy/t6TxRrY /0UftaLwyjUqsf0yNOG0GKzewUroeBxE7G4SezmXsCwNTqCdX9HMjdQaEtLTUyCsZKQT FAgLsujgCMbu+7Y8KEefMzpiskvsixQKbsuk9JDgy4o2Uk5AUeGcBlJl+IWiqrdq9dZi wCgWOj9u4Jk1tsEsrOceJBp0KIGRI7Wl+i3uTkZ86XwlhalyMRxzTtilL2hWCYg3/ixF atbN84cmfiYM3kvy1/GOqNQethwhRFrxs89gAh87B3zOc3IBxZApnw+ddvU1fKyts09Z x9lA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=dv8MkLcOtY2EeZNXcDWE1hLwVEjep3x1oeuEfehCxV8=; b=lttzFdTDvUTmiYC1/vssI280TQwNHZUNSLU5jB/AxMWGgVUNNUZU3ArUCMpRGmpy4g ++bN6Jdnmh9/zwFM9NacBaXxR6sU9A/aflqtRrOnW/UQ0eYui8HULd7pvKip1/DRT/vE JzJKcL5JD0CuHmtQGaE6l1W2FsoBrykjxW5Nu5npfcPSDThhuyg6hDtRVUuFpCfCAWHg ZhdzC7C3YedW0SwuIRWUBAoY3b3xUWtm+BMNPhobxoyiu3GhSBr/KM/VZVfaWhLRtRto 6Zs/c8usIv0nq1AEXPo34rpq0jJauouOAMCs4iDFZXCU+YTzj77sdf/oowty5W8v3NlL EFvQ== X-Gm-Message-State: AOAM530ULATPpZKj2MO43KBYKxYrRSZZ7B1Q5bouZbhGlnvLyxw8MdRv RlJggX+lkWJ2Ch71FmFqu6Psc/eDrATtXw== X-Google-Smtp-Source: ABdhPJwyTPjZaCWLnMiC3snH3GqI4Sb2IRUhCLx4Iu4/+x0u9NejvQ1GU78eSglp9EA0KPbKmCHCMQ== X-Received: by 2002:a05:6a00:8f:b029:1e8:6975:395e with SMTP id c15-20020a056a00008fb02901e86975395emr22066650pfj.55.1613524123354; Tue, 16 Feb 2021 17:08:43 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:42 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet Subject: [PATCH bpf-next 10/17] scripts/bpf: Abstract eBPF API target parameter Date: Tue, 16 Feb 2021 17:08:14 -0800 Message-Id: <20210217010821.1810741-11-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer Abstract out the target parameter so that upcoming commits, more than just the existing "helpers" target can be called to generate specific portions of docs from the eBPF UAPI headers. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- scripts/bpf_doc.py | 87 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 26 deletions(-) diff --git a/scripts/bpf_doc.py b/scripts/bpf_doc.py index ca6e7559d696..5a4f68aab335 100755 --- a/scripts/bpf_doc.py +++ b/scripts/bpf_doc.py @@ -2,6 +2,7 @@ # SPDX-License-Identifier: GPL-2.0-only # # Copyright (C) 2018-2019 Netronome Systems, Inc. +# Copyright (C) 2021 Isovalent, Inc. # In case user attempts to run with Python 2. from __future__ import print_function @@ -165,10 +166,11 @@ class Printer(object): """ A generic class for printers. Printers should be created with an array of Helper objects, and implement a way to print them in the desired fashion. - @helpers: array of Helper objects to print to standard output + @parser: A HeaderParser with objects to print to standard output """ - def __init__(self, helpers): - self.helpers = helpers + def __init__(self, parser): + self.parser = parser + self.elements = [] def print_header(self): pass @@ -181,19 +183,23 @@ class Printer(object): def print_all(self): self.print_header() - for helper in self.helpers: - self.print_one(helper) + for elem in self.elements: + self.print_one(elem) self.print_footer() + class PrinterRST(Printer): """ - A printer for dumping collected information about helpers as a ReStructured - Text page compatible with the rst2man program, which can be used to - generate a manual page for the helpers. - @helpers: array of Helper objects to print to standard output + A generic class for printers that print ReStructured Text. Printers should + be created with a HeaderParser object, and implement a way to print API + elements in the desired fashion. + @parser: A HeaderParser with objects to print to standard output """ - def print_header(self): - header = '''\ + def __init__(self, parser): + self.parser = parser + + def print_license(self): + license = '''\ .. Copyright (C) All BPF authors and contributors from 2014 to present. .. See git log include/uapi/linux/bpf.h in kernel tree for details. .. @@ -223,7 +229,37 @@ class PrinterRST(Printer): .. located in file include/uapi/linux/bpf.h of the Linux kernel sources .. (helpers description), and from scripts/bpf_doc.py in the same .. repository (header and footer). +''' + print(license) + + def print_elem(self, elem): + if (elem.desc): + print('\tDescription') + # Do not strip all newline characters: formatted code at the end of + # a section must be followed by a blank line. + for line in re.sub('\n$', '', elem.desc, count=1).split('\n'): + print('{}{}'.format('\t\t' if line else '', line)) + + if (elem.ret): + print('\tReturn') + for line in elem.ret.rstrip().split('\n'): + print('{}{}'.format('\t\t' if line else '', line)) + + print('') + +class PrinterHelpersRST(PrinterRST): + """ + A printer for dumping collected information about helpers as a ReStructured + Text page compatible with the rst2man program, which can be used to + generate a manual page for the helpers. + @parser: A HeaderParser with Helper objects to print to standard output + """ + def __init__(self, parser): + self.elements = parser.helpers + + def print_header(self): + header = '''\ =========== BPF-HELPERS =========== @@ -264,6 +300,7 @@ kernel at the top). HELPERS ======= ''' + PrinterRST.print_license(self) print(header) def print_footer(self): @@ -380,27 +417,19 @@ SEE ALSO def print_one(self, helper): self.print_proto(helper) + self.print_elem(helper) - if (helper.desc): - print('\tDescription') - # Do not strip all newline characters: formatted code at the end of - # a section must be followed by a blank line. - for line in re.sub('\n$', '', helper.desc, count=1).split('\n'): - print('{}{}'.format('\t\t' if line else '', line)) - if (helper.ret): - print('\tReturn') - for line in helper.ret.rstrip().split('\n'): - print('{}{}'.format('\t\t' if line else '', line)) - print('') class PrinterHelpers(Printer): """ A printer for dumping collected information about helpers as C header to be included from BPF program. - @helpers: array of Helper objects to print to standard output + @parser: A HeaderParser with Helper objects to print to standard output """ + def __init__(self, parser): + self.elements = parser.helpers type_fwds = [ 'struct bpf_fib_lookup', @@ -589,8 +618,12 @@ script = os.path.abspath(sys.argv[0]) linuxRoot = os.path.dirname(os.path.dirname(script)) bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h') +printers = { + 'helpers': PrinterHelpersRST, +} + argParser = argparse.ArgumentParser(description=""" -Parse eBPF header file and generate documentation for eBPF helper functions. +Parse eBPF header file and generate documentation for the eBPF API. The RST-formatted output produced can be turned into a manual page with the rst2man utility. """) @@ -601,6 +634,8 @@ if (os.path.isfile(bpfh)): default=bpfh) else: argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h') +argParser.add_argument('target', nargs='?', default='helpers', + choices=printers.keys(), help='eBPF API target') args = argParser.parse_args() # Parse file. @@ -609,7 +644,7 @@ headerParser.run() # Print formatted output to standard output. if args.header: - printer = PrinterHelpers(headerParser.helpers) + printer = PrinterHelpers(headerParser) else: - printer = PrinterRST(headerParser.helpers) + printer = printers[args.target](headerParser) printer.print_all() From patchwork Wed Feb 17 01:08:15 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384270 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 99AF0C433E0 for ; Wed, 17 Feb 2021 01:12:37 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 64ABE64E2F for ; Wed, 17 Feb 2021 01:12:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231458AbhBQBMZ (ORCPT ); Tue, 16 Feb 2021 20:12:25 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47590 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231462AbhBQBJv (ORCPT ); Tue, 16 Feb 2021 20:09:51 -0500 Received: from mail-pf1-x436.google.com (mail-pf1-x436.google.com [IPv6:2607:f8b0:4864:20::436]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C5583C061797; Tue, 16 Feb 2021 17:08:53 -0800 (PST) Received: by mail-pf1-x436.google.com with SMTP id x136so7366519pfc.2; Tue, 16 Feb 2021 17:08:53 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=sHn1TcXA40LLznUdfZ0EnywfCC8GI0Od3igBD7EM/qA=; b=inLrmew4Cded46OMVXm440//MhXtGm/AFsHnPkZUJZ0Si7ZBGly2nyrIYt4eVXqxcT PMpocNArusisJd0qlkPyA3DTH1dMjPlc23YjUa59l22XmiX8bb++C+G9mUAB7/Y31a3i 7tF1TNy/soSno0eOqnG9ONKxyK1t+ZnYoeJ5JD+asBwyi+8nZyAfVvSsgF8iDcMlxFgF HYwyuDVU1n4fV+WPPd2J69Hd5bzAA4Z/gM5k8ibY7+sCJKopV8UlUlObq/GRXNutCuyl KM2QCoLQcV3hiZyzV1b7pmIryruBGrWvM5b0WqO1nVw+JmREvaQMKM8CEcv/rd1vR4QQ JiqA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=sHn1TcXA40LLznUdfZ0EnywfCC8GI0Od3igBD7EM/qA=; b=N61xoY9htilY5c24HLVrFUqB+YiTZ+p12u5UwUyc59EQx94ZY8CcTHBwQfYHPeDuvC EEXzWehBWXKXe6Ua3Kz23XZAljZPuPH+tMPJTMhbROfuhlJQOkxS6YGbq7tDzxoTGgke 0+4LUgczSybcrIuGBBSWdHsaTXkLSHao/IviMZYlZM0yy5gGlxBdFepgT+Gzf+Hi5smQ XobsvgiJaW/qUaTEiQmkO700TOyavshZ7BruZvXln3D/Ls5wor/jOurP/v0qdN5W1+4R OMnI48P6Sqz4pOKe+9TP5onpqOt4CPOxTzY5DG8umGOLipzEdsUq83+yhJ0OWJcK8GJE 9e0A== X-Gm-Message-State: AOAM531J5inh5hrxGyRKyy64etzkuawxG100MWwTflcyTeyG1s8pCKZB mXqDoeK2or0akqIaHD0w7UaZHquE5OtROA== X-Google-Smtp-Source: ABdhPJys71FeVg+7o5aVJCeZX3Mu9fkvHyCeuAc359Q8UbtC07NsulXwihDGuXTSL8QRccUrb/aD7A== X-Received: by 2002:a63:4507:: with SMTP id s7mr21678588pga.390.1613524132973; Tue, 16 Feb 2021 17:08:52 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:52 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet Subject: [PATCH bpf-next 11/17] scripts/bpf: Add syscall commands printer Date: Tue, 16 Feb 2021 17:08:15 -0800 Message-Id: <20210217010821.1810741-12-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer Add a new target to bpf_doc.py to support generating the list of syscall commands directly from the UAPI headers. Assuming that developer submissions keep the main header up to date, this should allow the man pages to be automatically generated based on the latest API changes rather than requiring someone to separately go back through the API and describe each command. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- scripts/bpf_doc.py | 98 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 89 insertions(+), 9 deletions(-) diff --git a/scripts/bpf_doc.py b/scripts/bpf_doc.py index 5a4f68aab335..72a2ba323692 100755 --- a/scripts/bpf_doc.py +++ b/scripts/bpf_doc.py @@ -14,6 +14,9 @@ import sys, os class NoHelperFound(BaseException): pass +class NoSyscallCommandFound(BaseException): + pass + class ParsingError(BaseException): def __init__(self, line='', reader=None): if reader: @@ -23,18 +26,27 @@ class ParsingError(BaseException): else: BaseException.__init__(self, 'Error parsing line: %s' % line) -class Helper(object): + +class APIElement(object): """ - An object representing the description of an eBPF helper function. - @proto: function prototype of the helper function - @desc: textual description of the helper function - @ret: description of the return value of the helper function + An object representing the description of an aspect of the eBPF API. + @proto: prototype of the API symbol + @desc: textual description of the symbol + @ret: (optional) description of any associated return value """ def __init__(self, proto='', desc='', ret=''): self.proto = proto self.desc = desc self.ret = ret + +class Helper(APIElement): + """ + An object representing the description of an eBPF helper function. + @proto: function prototype of the helper function + @desc: textual description of the helper function + @ret: description of the return value of the helper function + """ def proto_break_down(self): """ Break down helper function protocol into smaller chunks: return type, @@ -61,6 +73,7 @@ class Helper(object): return res + class HeaderParser(object): """ An object used to parse a file in order to extract the documentation of a @@ -73,6 +86,13 @@ class HeaderParser(object): self.reader = open(filename, 'r') self.line = '' self.helpers = [] + self.commands = [] + + def parse_element(self): + proto = self.parse_symbol() + desc = self.parse_desc() + ret = self.parse_ret() + return APIElement(proto=proto, desc=desc, ret=ret) def parse_helper(self): proto = self.parse_proto() @@ -80,6 +100,18 @@ class HeaderParser(object): ret = self.parse_ret() return Helper(proto=proto, desc=desc, ret=ret) + def parse_symbol(self): + p = re.compile(' \* ?(.+)$') + capture = p.match(self.line) + if not capture: + raise NoSyscallCommandFound + end_re = re.compile(' \* ?NOTES$') + end = end_re.match(self.line) + if end: + raise NoSyscallCommandFound + self.line = self.reader.readline() + return capture.group(1) + def parse_proto(self): # Argument can be of shape: # - "void" @@ -141,16 +173,29 @@ class HeaderParser(object): break return ret - def run(self): - # Advance to start of helper function descriptions. - offset = self.reader.read().find('* Start of BPF helper function descriptions:') + def seek_to(self, target, help_message): + self.reader.seek(0) + offset = self.reader.read().find(target) if offset == -1: - raise Exception('Could not find start of eBPF helper descriptions list') + raise Exception(help_message) self.reader.seek(offset) self.reader.readline() self.reader.readline() self.line = self.reader.readline() + def parse_syscall(self): + self.seek_to('* Start of BPF syscall commands:', + 'Could not find start of eBPF syscall descriptions list') + while True: + try: + command = self.parse_element() + self.commands.append(command) + except NoSyscallCommandFound: + break + + def parse_helpers(self): + self.seek_to('* Start of BPF helper function descriptions:', + 'Could not find start of eBPF helper descriptions list') while True: try: helper = self.parse_helper() @@ -158,6 +203,9 @@ class HeaderParser(object): except NoHelperFound: break + def run(self): + self.parse_syscall() + self.parse_helpers() self.reader.close() ############################################################################### @@ -420,6 +468,37 @@ SEE ALSO self.print_elem(helper) +class PrinterSyscallRST(PrinterRST): + """ + A printer for dumping collected information about the syscall API as a + ReStructured Text page compatible with the rst2man program, which can be + used to generate a manual page for the syscall. + @parser: A HeaderParser with APIElement objects to print to standard + output + """ + def __init__(self, parser): + self.elements = parser.commands + + def print_header(self): + header = '''\ +=== +bpf +=== +------------------------------------------------------------------------------- +Perform a command on an extended BPF object +------------------------------------------------------------------------------- + +:Manual section: 2 + +COMMANDS +======== +''' + PrinterRST.print_license(self) + print(header) + + def print_one(self, command): + print('**%s**' % (command.proto)) + self.print_elem(command) class PrinterHelpers(Printer): @@ -620,6 +699,7 @@ bpfh = os.path.join(linuxRoot, 'include/uapi/linux/bpf.h') printers = { 'helpers': PrinterHelpersRST, + 'syscall': PrinterSyscallRST, } argParser = argparse.ArgumentParser(description=""" From patchwork Wed Feb 17 01:08:18 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384272 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 60D9BC433E0 for ; Wed, 17 Feb 2021 01:11:37 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2C37E64E57 for ; Wed, 17 Feb 2021 01:11:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230225AbhBQBLb (ORCPT ); Tue, 16 Feb 2021 20:11:31 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47442 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231424AbhBQBJa (ORCPT ); Tue, 16 Feb 2021 20:09:30 -0500 Received: from mail-pg1-x52a.google.com (mail-pg1-x52a.google.com [IPv6:2607:f8b0:4864:20::52a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4A582C0617AA; Tue, 16 Feb 2021 17:08:58 -0800 (PST) Received: by mail-pg1-x52a.google.com with SMTP id b21so7435190pgk.7; Tue, 16 Feb 2021 17:08:58 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=3coyZNplS0LrMWPP0wgM19MymToF1400w+CLXHenGHM=; b=jblR5dfpywIdXTajNjYPhJ5csCZ6narFit+XUpIiYKYUO+DLlfTKmxRsCDita4xcIB 1mJ5VZiIx5cyG7bP+nvE7duPz9o5Pq5vqaz0ql1TDBk8koIjVPcYb6rqkxXdVrwqn38+ t4SPQSkODJjAdjXLbIEbNYs95GRq2rFa6S5J+H+JzEy+LlfrfZMnLRUzRN5AU+eVhW66 TXmVPkX6fMINzRf4SF20phDDPC8ty6lQGD78ZjrHRW7EQ8nAOk/kWHl2SEKosfN1g8Jt phAglXMw8tovVGdCuRXAjz1JObSOh1pfsaAdsaI7e9qDjuNm27rhjeg9tCMAykyzKfsz lZyg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=3coyZNplS0LrMWPP0wgM19MymToF1400w+CLXHenGHM=; b=XVOqZ1rK6imLTKhedAu130AyaDKfDvPpEdQ/1l0gFSA5EU1B0DkuCGKycPJjuvV87G ZlhaA/b+VIZdZOlsS0nii8i57nvKOUcgHlFTho/vQ6o/uwqyxMglpsxCttierKjz/HA/ +PiL9yC8cvchQee6RxhwTFhaPIu/r8Ibcd4+J1coRPC8MwF7aLltkM1xZTaZLat/2oGv V1S+jRlfaP/sXnDnFYtWgjbfWS9g0QRkQtqR0p18xSnJyI4+Pqt5JFUvGSldu2foMCBb LTgEfGentdxSgZeQPEP37fmkW8kIcwDsvuyDX5PdRRChyR9nY+8wjm4DyBdrHnxNLoLU nr8A== X-Gm-Message-State: AOAM5325TPwdogUhEY3zrQZPbyxUMc1OgDeki9u8smyArZ2fEf9G6G9n wMZ7GonBbfCopvBugDS4E9X/8njjqs0wAw== X-Google-Smtp-Source: ABdhPJxiTaUQhGo4hc6n7VF01FZrHfbbN/Rv7kzE4J5uUYc6QwrKgyztLAY2bE1qcpyQRsTbMS9ULA== X-Received: by 2002:a63:5453:: with SMTP id e19mr21445728pgm.439.1613524137537; Tue, 16 Feb 2021 17:08:57 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:56 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet Subject: [PATCH bpf-next 14/17] tools/bpf: Build bpf-sycall.2 in Makefile.docs Date: Tue, 16 Feb 2021 17:08:18 -0800 Message-Id: <20210217010821.1810741-15-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer Add building of the bpf(2) syscall commands documentation as part of the docs building step in the build. This allows us to pick up on potential parse errors from the docs generator script as part of selftests. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- tools/bpf/Makefile.docs | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/tools/bpf/Makefile.docs b/tools/bpf/Makefile.docs index 7111888ca5d8..47da582cdaf2 100644 --- a/tools/bpf/Makefile.docs +++ b/tools/bpf/Makefile.docs @@ -21,18 +21,27 @@ endif prefix ?= /usr/local mandir ?= $(prefix)/man +man2dir = $(mandir)/man2 man7dir = $(mandir)/man7 +SYSCALL_RST = bpf-syscall.rst +MAN2_RST = $(SYSCALL_RST) + HELPERS_RST = bpf-helpers.rst MAN7_RST = $(HELPERS_RST) +_DOC_MAN2 = $(patsubst %.rst,%.2,$(MAN2_RST)) +DOC_MAN2 = $(addprefix $(OUTPUT),$(_DOC_MAN2)) + _DOC_MAN7 = $(patsubst %.rst,%.7,$(MAN7_RST)) DOC_MAN7 = $(addprefix $(OUTPUT),$(_DOC_MAN7)) -DOCTARGETS := helpers +DOCTARGETS := helpers syscall docs: $(DOCTARGETS) +syscall: man2 helpers: man7 +man2: $(DOC_MAN2) man7: $(DOC_MAN7) RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null) @@ -70,9 +79,10 @@ endef # Create the make targets to generate manual pages by name and section $(eval $(call DOCS_RULES,helpers,7)) +$(eval $(call DOCS_RULES,syscall,2)) docs-clean: $(foreach doctarget,$(DOCTARGETS), docs-clean-$(doctarget)) docs-install: $(foreach doctarget,$(DOCTARGETS), docs-install-$(doctarget)) docs-uninstall: $(foreach doctarget,$(DOCTARGETS), docs-uninstall-$(doctarget)) -.PHONY: docs docs-clean docs-install docs-uninstall man7 +.PHONY: docs docs-clean docs-install docs-uninstall man2 man7 From patchwork Wed Feb 17 01:08:19 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 384269 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER, INCLUDES_PATCH, MAILING_LIST_MULTI, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1F2A7C433E0 for ; Wed, 17 Feb 2021 01:13:22 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id DF08D64E2E for ; Wed, 17 Feb 2021 01:13:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230355AbhBQBNT (ORCPT ); Tue, 16 Feb 2021 20:13:19 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47608 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231476AbhBQBJz (ORCPT ); Tue, 16 Feb 2021 20:09:55 -0500 Received: from mail-pj1-x1036.google.com (mail-pj1-x1036.google.com [IPv6:2607:f8b0:4864:20::1036]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D149DC0617AB; Tue, 16 Feb 2021 17:08:59 -0800 (PST) Received: by mail-pj1-x1036.google.com with SMTP id cl8so471430pjb.0; Tue, 16 Feb 2021 17:08:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=C6HlPPfLSW8B0FR1o4nfrvuLVT84DuSdSXqFu2lS9ys=; b=Ue/A2zISy74IPfcHxCddBc19QJp0r6Y1nUTzx5pdJMt/SXHkcXAC9IdpI6OYCVjKCX PaK/8J/7cZWml6YDlQ2Whb8VkcnTNu9eYLoFRMODKpcDq/z29iGOnuh7gHFp+fimMmI7 Q1psz9mcev9kTmIrd02QVuX9FqN5HaFV0EHyIR9nonbW0icbLk1/eVqmSgnAoJRdLb5j KGqUKh/BLfBEsXW6wIpn4hGLEUqlA4hmH0DS6xXRlbnKR1GV87SCo+aMImTP2BMdvg6U K55E7ulzY/4abrSsQra4E6pt+5oAubI4YzbIWMFDxt9pS37w8UiwHpzQ2xajp4Z0h3cD RzTg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=C6HlPPfLSW8B0FR1o4nfrvuLVT84DuSdSXqFu2lS9ys=; b=Waaow0Y9opW05K+SMuWjCToCvJ5JztLjsWlVa1qOhwJYdCkhtGvQtDMtsKsbPACzG+ G+rYrkKDRt/dSWcdgZHHpKXIFJY55ovr94lLXzDJTk/zWtrgAmVMpbzE74Ts3jalPt2y PT1vwFslS1e2LbE2tbMUg3wqput9Y/+iKdpaQw0fzP9JMpgd3Ol9ANU5FmTyf+C94xQE 3zwQYM/nQUvYh52mE4OlzNOtEPIvRjtJ8e3Uok/gYw2zhaHg1N//kH4e2Hoeu2bTQKfO RIZQJJmZ8BedcZEuuYjPbohvdn6Zy4XkARJHKZ9hfrPXRJyHunnNUm6oBbP+6G7NGhxx vRhA== X-Gm-Message-State: AOAM531lDqN9F4oTXoob80ODdZvzZU/o7qb7JobdWXaEMfxhkXOGVTZt 0+pGzkA7hVvNWmweOmsJF6ct6MZMW1kQlw== X-Google-Smtp-Source: ABdhPJzzaC8WUWfKmlD2Kw05sS4PXZHfAvexPlWCrXwPx2JnAClh3FgCdftadH5PP40cS56xDiVpIw== X-Received: by 2002:a17:903:181:b029:df:c7e5:8e39 with SMTP id z1-20020a1709030181b02900dfc7e58e39mr22525292plg.25.1613524139051; Tue, 16 Feb 2021 17:08:59 -0800 (PST) Received: from localhost.localdomain (c-73-93-5-123.hsd1.ca.comcast.net. [73.93.5.123]) by smtp.gmail.com with ESMTPSA id c22sm175770pfc.12.2021.02.16.17.08.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:58 -0800 (PST) Sender: Joe Stringer From: Joe Stringer To: bpf@vger.kernel.org Cc: Joe Stringer , netdev@vger.kernel.org, daniel@iogearbox.net, ast@kernel.org, mtk.manpages@gmail.com, Quentin Monnet Subject: [PATCH bpf-next 15/17] selftests/bpf: Add docs target Date: Tue, 16 Feb 2021 17:08:19 -0800 Message-Id: <20210217010821.1810741-16-joe@wand.net.nz> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz> References: <20210217010821.1810741-1-joe@wand.net.nz> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org From: Joe Stringer This docs target will run the scripts/bpf_doc.py against the BPF UAPI headers to ensure that the parser used for generating manual pages from the headers doesn't trip on any newly added API documentation. While we're at it, remove the bpftool-specific docs check target since that would just be duplicated with the new target anyhow. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- tools/testing/selftests/bpf/Makefile | 20 +++++++++++++----- .../selftests/bpf/test_bpftool_build.sh | 21 ------------------- tools/testing/selftests/bpf/test_doc_build.sh | 13 ++++++++++++ 3 files changed, 28 insertions(+), 26 deletions(-) create mode 100755 tools/testing/selftests/bpf/test_doc_build.sh diff --git a/tools/testing/selftests/bpf/Makefile b/tools/testing/selftests/bpf/Makefile index 044bfdcf5b74..e1a76444670c 100644 --- a/tools/testing/selftests/bpf/Makefile +++ b/tools/testing/selftests/bpf/Makefile @@ -68,6 +68,7 @@ TEST_PROGS := test_kmod.sh \ test_bpftool_build.sh \ test_bpftool.sh \ test_bpftool_metadata.sh \ + test_docs_build.sh \ test_xsk.sh TEST_PROGS_EXTENDED := with_addr.sh \ @@ -103,6 +104,7 @@ override define CLEAN $(call msg,CLEAN) $(Q)$(RM) -r $(TEST_GEN_PROGS) $(TEST_GEN_PROGS_EXTENDED) $(TEST_GEN_FILES) $(EXTRA_CLEAN) $(Q)$(MAKE) -C bpf_testmod clean + $(Q)$(MAKE) docs-clean endef include ../lib.mk @@ -180,6 +182,7 @@ $(OUTPUT)/runqslower: $(BPFOBJ) | $(DEFAULT_BPFTOOL) cp $(SCRATCH_DIR)/runqslower $@ $(TEST_GEN_PROGS) $(TEST_GEN_PROGS_EXTENDED): $(OUTPUT)/test_stub.o $(BPFOBJ) +$(TEST_GEN_FILES): docs $(OUTPUT)/test_dev_cgroup: cgroup_helpers.c $(OUTPUT)/test_skb_cgroup_id_user: cgroup_helpers.c @@ -200,11 +203,16 @@ $(DEFAULT_BPFTOOL): $(wildcard $(BPFTOOLDIR)/*.[ch] $(BPFTOOLDIR)/Makefile) \ CC=$(HOSTCC) LD=$(HOSTLD) \ OUTPUT=$(HOST_BUILD_DIR)/bpftool/ \ prefix= DESTDIR=$(HOST_SCRATCH_DIR)/ install - $(Q)mkdir -p $(BUILD_DIR)/bpftool/Documentation - $(Q)RST2MAN_OPTS="--exit-status=1" $(MAKE) $(submake_extras) \ - -C $(BPFTOOLDIR)/Documentation \ - OUTPUT=$(BUILD_DIR)/bpftool/Documentation/ \ - prefix= DESTDIR=$(SCRATCH_DIR)/ install + +docs: + $(Q)RST2MAN_OPTS="--exit-status=1" $(MAKE) $(submake_extras) \ + -C $(TOOLSDIR)/bpf -f Makefile.docs \ + prefix= OUTPUT=$(OUTPUT)/ DESTDIR=$(OUTPUT)/ $@ + +docs-clean: + $(Q)$(MAKE) $(submake_extras) \ + -C $(TOOLSDIR)/bpf -f Makefile.docs \ + prefix= OUTPUT=$(OUTPUT)/ DESTDIR=$(OUTPUT)/ $@ $(BPFOBJ): $(wildcard $(BPFDIR)/*.[ch] $(BPFDIR)/Makefile) \ ../../../include/uapi/linux/bpf.h \ @@ -476,3 +484,5 @@ EXTRA_CLEAN := $(TEST_CUSTOM_PROGS) $(SCRATCH_DIR) $(HOST_SCRATCH_DIR) \ prog_tests/tests.h map_tests/tests.h verifier/tests.h \ feature \ $(addprefix $(OUTPUT)/,*.o *.skel.h no_alu32 bpf_gcc bpf_testmod.ko) + +.PHONY: docs docs-clean diff --git a/tools/testing/selftests/bpf/test_bpftool_build.sh b/tools/testing/selftests/bpf/test_bpftool_build.sh index 2db3c60e1e61..ac349a5cea7e 100755 --- a/tools/testing/selftests/bpf/test_bpftool_build.sh +++ b/tools/testing/selftests/bpf/test_bpftool_build.sh @@ -85,23 +85,6 @@ make_with_tmpdir() { echo } -make_doc_and_clean() { - echo -e "\$PWD: $PWD" - echo -e "command: make -s $* doc >/dev/null" - RST2MAN_OPTS="--exit-status=1" make $J -s $* doc - if [ $? -ne 0 ] ; then - ERROR=1 - printf "FAILURE: Errors or warnings when building documentation\n" - fi - ( - if [ $# -ge 1 ] ; then - cd ${@: -1} - fi - make -s doc-clean - ) - echo -} - echo "Trying to build bpftool" echo -e "... through kbuild\n" @@ -162,7 +145,3 @@ make_and_clean make_with_tmpdir OUTPUT make_with_tmpdir O - -echo -e "Checking documentation build\n" -# From tools/bpf/bpftool -make_doc_and_clean diff --git a/tools/testing/selftests/bpf/test_doc_build.sh b/tools/testing/selftests/bpf/test_doc_build.sh new file mode 100755 index 000000000000..7eb940a7b2eb --- /dev/null +++ b/tools/testing/selftests/bpf/test_doc_build.sh @@ -0,0 +1,13 @@ +#!/bin/bash +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +# Assume script is located under tools/testing/selftests/bpf/. We want to start +# build attempts from the top of kernel repository. +SCRIPT_REL_PATH=$(realpath --relative-to=$PWD $0) +SCRIPT_REL_DIR=$(dirname $SCRIPT_REL_PATH) +KDIR_ROOT_DIR=$(realpath $PWD/$SCRIPT_REL_DIR/../../../../) +cd $KDIR_ROOT_DIR + +for tgt in docs docs-clean; do + make -s -C $PWD/$SCRIPT_REL_DIR $tgt; +done