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: 12090797 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 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 1AE4FC433E9 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 D5AF964EB3 for ; Wed, 17 Feb 2021 01:09:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229707AbhBQBJL (ORCPT ); Tue, 16 Feb 2021 20:09:11 -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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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: 12090801 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 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 E3274C433E0 for ; Wed, 17 Feb 2021 01:09:30 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 907F664E79 for ; Wed, 17 Feb 2021 01:09:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230292AbhBQBJP (ORCPT ); Tue, 16 Feb 2021 20:09:15 -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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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:07 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12090799 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 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 B0DA2C433DB for ; Wed, 17 Feb 2021 01:09:30 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6CB0264E57 for ; Wed, 17 Feb 2021 01:09:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231396AbhBQBJQ (ORCPT ); Tue, 16 Feb 2021 20:09:16 -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 S231251AbhBQBJN (ORCPT ); Tue, 16 Feb 2021 20:09:13 -0500 Received: from mail-pl1-x633.google.com (mail-pl1-x633.google.com [IPv6:2607:f8b0:4864:20::633]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0BFAEC061788; Tue, 16 Feb 2021 17:08:33 -0800 (PST) Received: by mail-pl1-x633.google.com with SMTP id k22so6498540pll.6; Tue, 16 Feb 2021 17:08:33 -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=3ZnA+7hfNqEFiLN330o/irmutXYLyaXm0jUQCg3QDWo=; b=LAO6dwoQ/da5DeUo368VDM5qD60mXd17TrohA9Pky89S2JYHrHmWwY2GNBPESVy/2o N3MD76TSVDf+rbLL+lcrBrnge8SBaEQytHDzNKP2GdofWKxEcuXrM2sRoVHIFUlZgTrp pynzLd7VspTCPqxh8R9FNx/tKqitDYUOuo0sYl6EYcWbyxWyfXemMlRvVvm7kVHxDD9z fwUrSo9mHuqsNrCV/FkzKmOf06Dz93wym/Tdc7r1eXWnGWXy1pvW6YWn+Pr8MWBAKPBm 3fZ97agyjYHJk6h6jfS9ADBHgIL8PcPa86TrTFLqWsWL5TXAFQnSXh0bExVIIHukkOKW ubhQ== 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=3ZnA+7hfNqEFiLN330o/irmutXYLyaXm0jUQCg3QDWo=; b=XDC8cyyD0KjDMuCnfK8tvlqanr8snaF3nHqP0L1ZvdyffQoczAGRcsl7LzwnJqr3Nx 1Ru4PlTdqTZze4AQs4iDzq46KICjPeiLyajhbIsrlT7T1Ca7kdTC9gyoj36W7AWoMMq4 1wQEAcT3GaVf3rTX+p+yCuGer1ATpm6ls9AmY0bLgFvOSF/I9evVb2K77Qx0FMgPIBgN GhrtnBD8oAoyS75JdavsMvDEOlb3UP/jye/rHzFTgwpyboAYXa6URUO+o5+4yz5pOvCz CvIFJwhUul+2ZNkG9c/eKEJr13mHNRauYFqH7Ahb+FjIRZjmAp2z0r2RxhrApAC9gG18 gaPA== X-Gm-Message-State: AOAM5330j+p2utVxRHnRWpJbSMoKjuUt2nH54CnJyCaxpL1LEZbLBYyh yOOBAl4S/ukSFEljqBhwXfTxKi6R5ee0HQ== X-Google-Smtp-Source: ABdhPJxtdHrKu1j9wclbUBGHvtcyRKfQEUqYvNMw25jotYrSxucVhnQiXDAaDN1C2TJ5I1PMWmiS4Q== X-Received: by 2002:a17:902:e80b:b029:e3:3df1:5e93 with SMTP id u11-20020a170902e80bb02900e33df15e93mr209266plg.80.1613524112320; Tue, 16 Feb 2021 17:08:32 -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.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:31 -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 03/17] bpf: Document BPF_F_LOCK in syscall commands Date: Tue, 16 Feb 2021 17:08:07 -0800 Message-Id: <20210217010821.1810741-4-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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Joe Stringer Document the meaning of the BPF_F_LOCK flag for the map lookup/update descriptions. Based on commit 96049f3afd50 ("bpf: introduce BPF_F_LOCK flag"). Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- CC: Alexei Starovoitov --- include/uapi/linux/bpf.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index ac6880d7b01b..d02259458fd6 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -120,6 +120,14 @@ union bpf_iter_link_info { * Look up an element with a given *key* in the map referred to * by the file descriptor *map_fd*. * + * The *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. + * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. @@ -137,6 +145,8 @@ union bpf_iter_link_info { * Create a new element only if it did not exist. * **BPF_EXIST** * Update an existing element. + * **BPF_F_LOCK** + * Update a spin_lock-ed map element. * * Return * Returns zero on success. On error, -1 is returned and *errno* 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: 12090805 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 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 3F127C433DB for ; Wed, 17 Feb 2021 01:09:33 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 1605064E6B for ; Wed, 17 Feb 2021 01:09:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231428AbhBQBJb (ORCPT ); Tue, 16 Feb 2021 20:09:31 -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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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:09 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12090807 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 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 D25C5C43381 for ; Wed, 17 Feb 2021 01:09:33 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id AD32664E6B for ; Wed, 17 Feb 2021 01:09:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231432AbhBQBJc (ORCPT ); Tue, 16 Feb 2021 20:09:32 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47460 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231400AbhBQBJQ (ORCPT ); Tue, 16 Feb 2021 20:09:16 -0500 Received: from mail-pg1-x535.google.com (mail-pg1-x535.google.com [IPv6:2607:f8b0:4864:20::535]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5F4AAC06174A; Tue, 16 Feb 2021 17:08:36 -0800 (PST) Received: by mail-pg1-x535.google.com with SMTP id o63so7430530pgo.6; Tue, 16 Feb 2021 17:08:36 -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=oVZywqg18g72Uzq75qJ/vikx7hpNBGSQLyL0+doduHA=; b=lc7S+6vTJrLsoF2Cqr7PFoEXJEiCRamcWJ16soKt3cE4CgePjTvcwcmXpZwCLCZJTZ 5f+Ev/tegpYYHw2iZslpubbwTjkRRle+rdGtGaMn/aLKUuX1WML8cfMTe4/aKG59AP5U k21jwfHR83ILsi93Pn3LDPjXDEO6KOzZPoWqVKYjxN0fUGAgLIx4XSOikQZh+1NWwMBg mm1t8N4iTCf1jAkMPaLo+cB9qf4gHobkowshsJWChMCnzT1nM1D+8Wfu/wc7uhgxyZls kH/jjXNmb4oQSY2+QnM3dKs6Zim1ilFSvl4smOQdqAq7JxdRZKpmaZ4xpBkHsM5Lg/EG sEvA== 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=oVZywqg18g72Uzq75qJ/vikx7hpNBGSQLyL0+doduHA=; b=GlWVLY8N13yY/g1+NO9RkM6iKUd9woN82l1IlFt9gjMSGH2RIcCsdeEqlTiZftQAEf K0xdjadv6OisxFxzv+FTaiAXN54xg3HIuoG/nEkf9PoXNabWR9yz3aqjfy10iLfnX2ua dgSR9Wb5pU+HXuw7tT2s3AlE3jiibWTmtQhxtkj1vaCQT2BaQWf2OEbQ8VSY3qQa5OGH SkG/FgyriqJtj1dE0Gpl0ljRt1kJIWhsiGb7A3mT+gDjV1lIr1qSPbul7MegamC7+jPk cEYl/whwJ9VwPmZhDC2tEnno6yoaWLuS0fkD1LoDJQo1UN/XeAX5SApXTxTZCNJT3BJz rviQ== X-Gm-Message-State: AOAM531pjcsHSFpycQdOVkTE3tosziFnimUX8+QX1mhw0qDHcJFZoaKk npICf3r0qTERkJdYXneNTPkZpMfXaI7PEQ== X-Google-Smtp-Source: ABdhPJzYiti8RcgJIeyzJvepBlP6NuqA8B0XcyaoG2664DoND4j8F6V+OstPNpVP976IjQ51I2ScvA== X-Received: by 2002:a05:6a00:854:b029:1b7:6233:c5f with SMTP id q20-20020a056a000854b02901b762330c5fmr22491350pfk.73.1613524115581; Tue, 16 Feb 2021 17:08:35 -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.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:34 -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 , Daniel Mack , John Fastabend , Sean Young , Petar Penkov Subject: [PATCH bpf-next 05/17] bpf: Document BPF_PROG_ATTACH syscall command Date: Tue, 16 Feb 2021 17:08:09 -0800 Message-Id: <20210217010821.1810741-6-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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Joe Stringer Document the prog attach command in more detail, based on git commits: * commit f4324551489e ("bpf: add BPF_PROG_ATTACH and BPF_PROG_DETACH commands") * commit 4f738adba30a ("bpf: create tcp_bpf_ulp allowing BPF to monitor socket TX/RX data") * commit f4364dcfc86d ("media: rc: introduce BPF_PROG_LIRC_MODE2") * commit d58e468b1112 ("flow_dissector: implements flow dissector BPF hook") Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- CC: Daniel Mack CC: John Fastabend CC: Sean Young CC: Petar Penkov --- include/uapi/linux/bpf.h | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 8301a19c97de..603605c5ca03 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -250,6 +250,43 @@ union bpf_iter_link_info { * Attach an eBPF program to a *target_fd* at the specified * *attach_type* hook. * + * The *attach_type* specifies the eBPF attachment point to + * attach the program to, and must be one of *bpf_attach_type* + * (see below). + * + * The *attach_bpf_fd* must be a valid file descriptor for a + * loaded eBPF program of a cgroup, flow dissector, LIRC, sockmap + * or sock_ops type corresponding to the specified *attach_type*. + * + * The *target_fd* must be a valid file descriptor for a kernel + * object which depends on the attach type of *attach_bpf_fd*: + * + * **BPF_PROG_TYPE_CGROUP_DEVICE**, + * **BPF_PROG_TYPE_CGROUP_SKB**, + * **BPF_PROG_TYPE_CGROUP_SOCK**, + * **BPF_PROG_TYPE_CGROUP_SOCK_ADDR**, + * **BPF_PROG_TYPE_CGROUP_SOCKOPT**, + * **BPF_PROG_TYPE_CGROUP_SYSCTL**, + * **BPF_PROG_TYPE_SOCK_OPS** + * + * Control Group v2 hierarchy with the eBPF controller + * enabled. Requires the kernel to be compiled with + * **CONFIG_CGROUP_BPF**. + * + * **BPF_PROG_TYPE_FLOW_DISSECTOR** + * + * Network namespace (eg /proc/self/ns/net). + * + * **BPF_PROG_TYPE_LIRC_MODE2** + * + * LIRC device path (eg /dev/lircN). Requires the kernel + * to be compiled with **CONFIG_BPF_LIRC_MODE2**. + * + * **BPF_PROG_TYPE_SK_SKB**, + * **BPF_PROG_TYPE_SK_MSG** + * + * eBPF map of socket type (eg **BPF_MAP_TYPE_SOCKHASH**). + * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. 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: 12090803 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 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 6ADD9C4332B for ; Wed, 17 Feb 2021 01:09:34 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 3F48B64E76 for ; Wed, 17 Feb 2021 01:09:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231441AbhBQBJd (ORCPT ); Tue, 16 Feb 2021 20:09:33 -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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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:11 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12090815 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 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 EBDAEC433E6 for ; Wed, 17 Feb 2021 01:10:11 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id A3BBD64E57 for ; Wed, 17 Feb 2021 01:10:11 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231478AbhBQBJ4 (ORCPT ); Tue, 16 Feb 2021 20:09:56 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47472 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231408AbhBQBJT (ORCPT ); Tue, 16 Feb 2021 20:09:19 -0500 Received: from mail-pf1-x431.google.com (mail-pf1-x431.google.com [IPv6:2607:f8b0:4864:20::431]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 747DBC06178B; Tue, 16 Feb 2021 17:08:39 -0800 (PST) Received: by mail-pf1-x431.google.com with SMTP id w18so7341362pfu.9; Tue, 16 Feb 2021 17:08:39 -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=ObgloKUUku0ihUpaDdYn1V0eSJ13PyKERfA5sVWUhWc=; b=ei5tAvN9oUhW3g3BORq/vbSQdflED2tsYzNcG8pVJUVHYA7B/X9CGaaBN5HNjIUtXv 0HYnH0CX4Z9Sv1zzx/luCQpwZ5DTXFsBfG0r2ep5cs/QhxFKB6cev0gtyhHZ0DiOJ8N4 wLH35Qjsn17Ta50oE5IvchMJEhCdj8x3m8t1zBIYeU+Gl8xvhUj0vXTw4cfJ6wO5gCPC FiWyYCAHvd3phZuLsvXKo0r4U18ALQFCc9uOwD1j8w0AfqYAF2s6HNQHiIvyQlTN616G zk9Yt995AJIb1TlMQ5AwC9RFmxxwf0aFyxhdJU2sEJHUmeCejnodnOSRZj/eGVdioQYI cpKw== 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=ObgloKUUku0ihUpaDdYn1V0eSJ13PyKERfA5sVWUhWc=; b=fd2L3uj/0IFzbr4jpRpU5sayqGvVj87I3PxkAOkJBUHRkAp8L1Qsf3hsKchjjQA1Ks bgVO8geSisW/dx8XL/FwTALj7hXUaImc5dEEMEyeZ+zL7gagjYCnmfw2xz5Xw5miZaCN KvQBEorX/CcTDyNiC7j63CDTR6UBr/V9F8s/YCwedSp7rTPS5/fzI+blZSZQKGjyw6xo nTSoj2obu1AZwDXLQ4qU/B4ALBS+qBZLOwGPoB8fseqN57pl05YfTxCfI/IwDiwWiWHU PcM+lBUhKT7rAQYYLuBPWIhtastmEM2Ham5w4Od+lu1/NpddqzhF7HvHdADSo/Q904I7 Bsdg== X-Gm-Message-State: AOAM532i1J02Jn+xanMRP+YV+LDTJsVAuVRh/VycXtW3jQ6pCfMmXx+r QhRpTnl1eHQcbIHTuVmqCeX5+BuLJHBl6A== X-Google-Smtp-Source: ABdhPJyn/Q0NAIioFBOpOucvNNZ3GX7DGPEm/wkHJOxhQUl24G3Yv7e3PNWnl/bRQav8LYxDm5eeSg== X-Received: by 2002:aa7:978a:0:b029:1e8:3607:9d3a with SMTP id o10-20020aa7978a0000b02901e836079d3amr21815371pfp.72.1613524118694; Tue, 16 Feb 2021 17:08:38 -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.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:38 -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 07/17] bpf: Document BPF_PROG_QUERY syscall command Date: Tue, 16 Feb 2021 17:08:11 -0800 Message-Id: <20210217010821.1810741-8-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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Joe Stringer Commit 468e2f64d220 ("bpf: introduce BPF_PROG_QUERY command") originally introduced this, but there have been several additions since then. Unlike BPF_PROG_ATTACH, it appears that the sockmap progs are not able to be queried so far. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- CC: Alexei Starovoitov --- include/uapi/linux/bpf.h | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 86fe0445c395..a07cecfd2148 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -386,6 +386,43 @@ union bpf_iter_link_info { * Obtain information about eBPF programs associated with the * specified *attach_type* hook. * + * The *target_fd* must be a valid file descriptor for a kernel + * object which depends on the attach type of *attach_bpf_fd*: + * + * **BPF_PROG_TYPE_CGROUP_DEVICE**, + * **BPF_PROG_TYPE_CGROUP_SKB**, + * **BPF_PROG_TYPE_CGROUP_SOCK**, + * **BPF_PROG_TYPE_CGROUP_SOCK_ADDR**, + * **BPF_PROG_TYPE_CGROUP_SOCKOPT**, + * **BPF_PROG_TYPE_CGROUP_SYSCTL**, + * **BPF_PROG_TYPE_SOCK_OPS** + * + * Control Group v2 hierarchy with the eBPF controller + * enabled. Requires the kernel to be compiled with + * **CONFIG_CGROUP_BPF**. + * + * **BPF_PROG_TYPE_FLOW_DISSECTOR** + * + * Network namespace (eg /proc/self/ns/net). + * + * **BPF_PROG_TYPE_LIRC_MODE2** + * + * LIRC device path (eg /dev/lircN). Requires the kernel + * to be compiled with **CONFIG_BPF_LIRC_MODE2**. + * + * **BPF_PROG_QUERY** always fetches the number of programs + * attached and the *attach_flags* which were used to attach those + * programs. Additionally, if *prog_ids* is nonzero and the number + * of attached programs is less than *prog_cnt*, populates + * *prog_ids* with the eBPF program ids of the programs attached + * at *target_fd*. + * + * The following flags may alter the result: + * + * **BPF_F_QUERY_EFFECTIVE** + * Only return information regarding programs which are + * currently effective at the specified *target_fd*. + * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. 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: 12090819 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 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 B31F0C433E0 for ; Wed, 17 Feb 2021 01:10:17 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 7337964E57 for ; Wed, 17 Feb 2021 01:10:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231510AbhBQBKK (ORCPT ); Tue, 16 Feb 2021 20:10:10 -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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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:13 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12090821 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 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 293F3C433E0 for ; Wed, 17 Feb 2021 01:10:21 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id F097664E57 for ; Wed, 17 Feb 2021 01:10:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231515AbhBQBKO (ORCPT ); Tue, 16 Feb 2021 20:10:14 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47580 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231460AbhBQBJs (ORCPT ); Tue, 16 Feb 2021 20:09:48 -0500 Received: from mail-pg1-x52e.google.com (mail-pg1-x52e.google.com [IPv6:2607:f8b0:4864:20::52e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9BCDCC061793; Tue, 16 Feb 2021 17:08:42 -0800 (PST) Received: by mail-pg1-x52e.google.com with SMTP id t11so7427742pgu.8; Tue, 16 Feb 2021 17:08:42 -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=7wkeXWSDW0rtEFRyuqfLBNSzMUu0eSr9sZboZSQF8RY=; b=aeXSQ9PJOXq9sym28oVJn+RaIHoNhyBCkjU+7UwOHB3XT934WY9lbWHTNtGnrZACmr Tww0LVkh3TjZuTGLdykEVoXowHb7MhIvw3tTPyV9Fw6zZsaRtJSM8xBWmFZw7FEcZIry oFKZi5IdKV8Le0YVe0c9fJ36gaQefR0+03K0TE/CTBJWMUbtSr9HtQ8orFqKxOPiaJzO X3PK27BAarfulFzjhTVHr2YF/THv9PeRnke02mtMPL3Er9OqUTNozLwecwJzvOGkQRNG 8ZZo8devZF4js9quyNyq68ep4ULAPraznKcsON+45y/WqCgDj6D3703N8bjIG8x1d//C vbdg== 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=7wkeXWSDW0rtEFRyuqfLBNSzMUu0eSr9sZboZSQF8RY=; b=epZihdieGEPS4ItFmvNx+nC6e84me56CEnFLigzkdIen+c4dbbEW3lYNhdCg686xbB +KL6pb8S+y9iB6GrPcxhZ7r1rZS5jKM3Pv9uI/LSRAYPXQ/fNR8LEgjPas03nOarrsrZ Z5eNnxu+88WCi80Ajdur6h1Q1+EndoQKcPfKRRbtW60gqqz5TPVarXBQDOX8uPPrQpLL d6tcmKBHM/1mCFDav+WaGPjc9kglf8I4FhM1WtTtdX57O6J0wDgtCbyZVtE1yzamoqD2 z0O1VXNLep+lyp2QN7P78+ogvAyhQcY9St/QIHAmmQEoljX/PRfFj5GG5MtqCM8SRnnh ZCeg== X-Gm-Message-State: AOAM532So7SuGVi5/Li2VQDPVR+puaNnFoq6qHFD5PQAhkyiEfOEImnD 0iKjqBOiYfxQ8H6LDyG2NjtHowgZDF+tlg== X-Google-Smtp-Source: ABdhPJwSSoxiLvIsHwDztS6GqR93ph5OPEXKNIFEL8Ieid7iac8rr0hkMLuFBUDc9gx0bewfHb0hMw== X-Received: by 2002:aa7:8c59:0:b029:1db:48a9:be70 with SMTP id e25-20020aa78c590000b02901db48a9be70mr380629pfd.68.1613524121827; Tue, 16 Feb 2021 17:08:41 -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.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:41 -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 09/17] scripts/bpf: Rename bpf_helpers_doc.py -> bpf_doc.py Date: Tue, 16 Feb 2021 17:08:13 -0800 Message-Id: <20210217010821.1810741-10-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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Joe Stringer Rename this file in anticipation of it being used for generating more than just helper man pages. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- include/uapi/linux/bpf.h | 2 +- scripts/{bpf_helpers_doc.py => bpf_doc.py} | 4 ++-- tools/bpf/Makefile.helpers | 2 +- tools/include/uapi/linux/bpf.h | 2 +- tools/lib/bpf/Makefile | 2 +- tools/perf/MANIFEST | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) rename scripts/{bpf_helpers_doc.py => bpf_doc.py} (99%) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 893803f69a64..4abf54327612 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -1425,7 +1425,7 @@ union bpf_attr { * parsed and used to produce a manual page. The workflow is the following, * and requires the rst2man utility: * - * $ ./scripts/bpf_helpers_doc.py \ + * $ ./scripts/bpf_doc.py \ * --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst * $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7 * $ man /tmp/bpf-helpers.7 diff --git a/scripts/bpf_helpers_doc.py b/scripts/bpf_doc.py similarity index 99% rename from scripts/bpf_helpers_doc.py rename to scripts/bpf_doc.py index 867ada23281c..ca6e7559d696 100755 --- a/scripts/bpf_helpers_doc.py +++ b/scripts/bpf_doc.py @@ -221,7 +221,7 @@ class PrinterRST(Printer): .. .. Please do not edit this file. It was generated from the documentation .. located in file include/uapi/linux/bpf.h of the Linux kernel sources -.. (helpers description), and from scripts/bpf_helpers_doc.py in the same +.. (helpers description), and from scripts/bpf_doc.py in the same .. repository (header and footer). =========== @@ -511,7 +511,7 @@ class PrinterHelpers(Printer): def print_header(self): header = '''\ -/* This is auto-generated file. See bpf_helpers_doc.py for details. */ +/* This is auto-generated file. See bpf_doc.py for details. */ /* Forward declarations of BPF structs */''' diff --git a/tools/bpf/Makefile.helpers b/tools/bpf/Makefile.helpers index 854d084026dd..a26599022fd6 100644 --- a/tools/bpf/Makefile.helpers +++ b/tools/bpf/Makefile.helpers @@ -35,7 +35,7 @@ man7: $(DOC_MAN7) RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null) $(OUTPUT)$(HELPERS_RST): $(UP2DIR)../../include/uapi/linux/bpf.h - $(QUIET_GEN)$(UP2DIR)../../scripts/bpf_helpers_doc.py --filename $< > $@ + $(QUIET_GEN)$(UP2DIR)../../scripts/bpf_doc.py --filename $< > $@ $(OUTPUT)%.7: $(OUTPUT)%.rst ifndef RST2MAN_DEP diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h index 4c24daa43bac..16f2f0d2338a 100644 --- a/tools/include/uapi/linux/bpf.h +++ b/tools/include/uapi/linux/bpf.h @@ -720,7 +720,7 @@ union bpf_attr { * parsed and used to produce a manual page. The workflow is the following, * and requires the rst2man utility: * - * $ ./scripts/bpf_helpers_doc.py \ + * $ ./scripts/bpf_doc.py \ * --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst * $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7 * $ man /tmp/bpf-helpers.7 diff --git a/tools/lib/bpf/Makefile b/tools/lib/bpf/Makefile index 887a494ad5fc..8170f88e8ea6 100644 --- a/tools/lib/bpf/Makefile +++ b/tools/lib/bpf/Makefile @@ -158,7 +158,7 @@ $(BPF_IN_STATIC): force $(BPF_HELPER_DEFS) $(Q)$(MAKE) $(build)=libbpf OUTPUT=$(STATIC_OBJDIR) $(BPF_HELPER_DEFS): $(srctree)/tools/include/uapi/linux/bpf.h - $(QUIET_GEN)$(srctree)/scripts/bpf_helpers_doc.py --header \ + $(QUIET_GEN)$(srctree)/scripts/bpf_doc.py --header \ --file $(srctree)/tools/include/uapi/linux/bpf.h > $(BPF_HELPER_DEFS) $(OUTPUT)libbpf.so: $(OUTPUT)libbpf.so.$(LIBBPF_VERSION) diff --git a/tools/perf/MANIFEST b/tools/perf/MANIFEST index 5d7b947320fb..f05c4d48fd7e 100644 --- a/tools/perf/MANIFEST +++ b/tools/perf/MANIFEST @@ -20,4 +20,4 @@ tools/lib/bitmap.c tools/lib/str_error_r.c tools/lib/vsprintf.c tools/lib/zalloc.c -scripts/bpf_helpers_doc.py +scripts/bpf_doc.py 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: 12090809 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 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 44B6EC433E0 for ; Wed, 17 Feb 2021 01:10:06 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 174A064E6B for ; Wed, 17 Feb 2021 01:10:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230201AbhBQBKD (ORCPT ); Tue, 16 Feb 2021 20:10: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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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: 12090823 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 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 AC4FAC433DB for ; Wed, 17 Feb 2021 01:10:24 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 7B6AB64E2E for ; Wed, 17 Feb 2021 01:10:24 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231516AbhBQBKR (ORCPT ); Tue, 16 Feb 2021 20:10:17 -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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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:16 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12090811 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 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 B9940C433E6 for ; Wed, 17 Feb 2021 01:10:07 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 8EF8864E57 for ; Wed, 17 Feb 2021 01:10:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230382AbhBQBKE (ORCPT ); Tue, 16 Feb 2021 20:10:04 -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 S231423AbhBQBJa (ORCPT ); Tue, 16 Feb 2021 20:09:30 -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 47AA9C0617A7; Tue, 16 Feb 2021 17:08:55 -0800 (PST) Received: by mail-pf1-x436.google.com with SMTP id y25so4065333pfp.5; Tue, 16 Feb 2021 17:08:55 -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=MiVaeokbQ1fWDcSWZ7ac5Jz6/tMfL2yhVQN5dJlBHbk=; b=QZncIX05i8DnwM1dMWrk2srvmO5i43J4JKbAIY6IdcppAilMWI34QmXeGt0Ut4yPRI MDpV3qEXH0FBTHJfRHl516QbhHcShsh+e5OT/n34IsMI8UHneyqa4hC5uBS+c1c31yQ3 LAb8RZD+jUOPn/ab0vbYRYSWrkMsA9CEiXFmKP9AkTQmZZsx4ui4xkjDwWejQp0jjPjf uaJ8qjt+yH4FSnhbXxkepxEb38GrvCP5++qNzWryau8UP/G9YvFMRMnbEG2D5xPOO8/i E55CiLVjUn/v/KqR52BGrQVztAtjSJN4nOP4dY7m5jUtjQMGbaZoHVkezCDOr04Go9Oh IEiQ== 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=MiVaeokbQ1fWDcSWZ7ac5Jz6/tMfL2yhVQN5dJlBHbk=; b=LW1OZ6fEOnJ+huV7AHQecaQSSdqJGLjqJK0biycOQR/GGpzWYBoySEBVBxnbbn4d6E VJUHvmVneOZCDVLwgo88Hyyt6kvhq9s4nt2eKUmUu6U+JDU1ofvFIpc/g36kFu6i0/7W qYjJLcZH4zjXDdNy+0qZCKyPt+1AhOPCO7VeBTr0P2C4ZF5Q8hd8XpWBRo0hpgi0tVr1 1wu6BiM2uvHG4iOT53eB68ruHouOxTcNrWOEXIJQDqs/m9KWf91OX4V+GX5DUZVVtNmC UxwKDKWYipKlonCPPgtWCsyePmbOpJfkgzgb4i6SNaIBg1CWUS+66n1JBO1FkVW1N7+I g8Ww== X-Gm-Message-State: AOAM530Jyk7/W2j8lnn2MUoxot5frg2xN5hKYPXyec3FMJhSyr8esSC6 hU1Y++wethFvfCp0KPdsOzYhByrb55gN+w== X-Google-Smtp-Source: ABdhPJxRyb2Ya6+5bqzpp6vf+uDq2zJoR2cCeXRkTc01HAVwai4MkGBGq+faEb+I6CSzGjokjJ2+Ew== X-Received: by 2002:a65:6418:: with SMTP id a24mr21847515pgv.33.1613524134543; Tue, 16 Feb 2021 17:08:54 -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.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:53 -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 12/17] tools/bpf: Rename Makefile.{helpers,docs} Date: Tue, 16 Feb 2021 17:08:16 -0800 Message-Id: <20210217010821.1810741-13-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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Joe Stringer In anticipation of including make targets for other manual pages in this makefile, rename it to something a bit more generic. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- tools/bpf/{Makefile.helpers => Makefile.docs} | 2 +- tools/bpf/bpftool/Documentation/Makefile | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename tools/bpf/{Makefile.helpers => Makefile.docs} (95%) diff --git a/tools/bpf/Makefile.helpers b/tools/bpf/Makefile.docs similarity index 95% rename from tools/bpf/Makefile.helpers rename to tools/bpf/Makefile.docs index a26599022fd6..dc4ce82ada33 100644 --- a/tools/bpf/Makefile.helpers +++ b/tools/bpf/Makefile.docs @@ -3,7 +3,7 @@ ifndef allow-override include ../scripts/Makefile.include include ../scripts/utilities.mak else - # Assume Makefile.helpers is being run from bpftool/Documentation + # Assume Makefile.docs is being run from bpftool/Documentation # subdirectory. Go up two more directories to fetch bpf.h header and # associated script. UP2DIR := ../../ diff --git a/tools/bpf/bpftool/Documentation/Makefile b/tools/bpf/bpftool/Documentation/Makefile index f33cb02de95c..bb7842efffd6 100644 --- a/tools/bpf/bpftool/Documentation/Makefile +++ b/tools/bpf/bpftool/Documentation/Makefile @@ -16,8 +16,8 @@ prefix ?= /usr/local mandir ?= $(prefix)/man man8dir = $(mandir)/man8 -# Load targets for building eBPF helpers man page. -include ../../Makefile.helpers +# Load targets for building eBPF man page. +include ../../Makefile.docs MAN8_RST = $(wildcard bpftool*.rst) From patchwork Wed Feb 17 01:08:17 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12090825 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 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 E52DBC433DB for ; Wed, 17 Feb 2021 01:10:26 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 9FC9F64E57 for ; Wed, 17 Feb 2021 01:10:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231519AbhBQBKV (ORCPT ); Tue, 16 Feb 2021 20:10:21 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47606 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231466AbhBQBJz (ORCPT ); Tue, 16 Feb 2021 20:09:55 -0500 Received: from mail-pf1-x429.google.com (mail-pf1-x429.google.com [IPv6:2607:f8b0:4864:20::429]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D535EC0617A9; Tue, 16 Feb 2021 17:08:56 -0800 (PST) Received: by mail-pf1-x429.google.com with SMTP id j12so7328580pfj.12; Tue, 16 Feb 2021 17:08:56 -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=HqCUBkziu5GrtC8jZXdR5IquLRlLWRFSCrlmdHa2zM8=; b=e/Lf/Y8VvOmA9hBvUmlL2KNcHxnrvfyKgst0Gj/Le7NuZDA66BiSJ3YxuNtW1TXjdc cj1IpJ9XgLG5242mrRj/uxmpWqTLbJA59n3vweAT1PJ2dUFudEi4n6Yp+T0zkUW9uzQd qRgDj+J+v15vDZTDrVpret8RRLeq92R0dxfO39KptAFwZ/Z1djqzC9wFiOFpRnMtAv0R cMpH7jhXu9lfnLBkG+EECIBbC6SM/hAHnqlA5sOXRPdZpmtRy+VunmUmn9NOSRykAkSi HI5n+ktVYd3VXj4ZiNelHQ0/2dCAB0DJwQxUBeQ3AYasaWYqkLyECR9DT/n73zyGpMmJ gnug== 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=HqCUBkziu5GrtC8jZXdR5IquLRlLWRFSCrlmdHa2zM8=; b=hNTSscJz4n5AGNqvQ+0ESPRQg2r9T+8XIw7HaXr9X2PdFqyroVSnLokUiwx+x/nkTJ M1RaRk4iq7NQBT6/4W+EeMHNBnrZ33Ti2ER9D6msgMc5F2YSwdrK4Bs3iHu4u4BdI4lN 8dkYQBT/tvXfCtx0wkU5wHGJX4uLobWChhQammtADzWS/R1lh9oDlK1oBnYPYP3bUStr WW3bfp/lkA9SCIB3SY9r0l717XYdTmlqQU0gsFfXF+zkACZFD13jEP2nb/5OGTSQ276B snHsnKplSpcLvfNo+AEExrP5gDsTo9GczWQfibShO2lQ2lIB5xvvTIkUbnRlxolo1Mpn w8Wg== X-Gm-Message-State: AOAM531CgRsK5thwXfcGiML3csxj2C1Rs/TzlSB2W64yiZSWU0krhUW9 2D9HdlnhHYYpdR/4VZly8R2KJ0bs2AUfvw== X-Google-Smtp-Source: ABdhPJyRs/QG3d+RPhMepnPwN5nz/ZgJ8UF30iiN1EUg2ZwfW0UHFxR3x6JzhjysP4KBrFimdO516w== X-Received: by 2002:a63:e442:: with SMTP id i2mr20972838pgk.12.1613524136052; Tue, 16 Feb 2021 17:08:56 -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.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:08:55 -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 13/17] tools/bpf: Templatize man page generation Date: Tue, 16 Feb 2021 17:08:17 -0800 Message-Id: <20210217010821.1810741-14-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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Joe Stringer Previously, the Makefile here was only targeting a single manual page so it just hardcoded a bunch of individual rules to specifically handle build, clean, install, uninstall for that particular page. Upcoming commits will generate manual pages for an additional section, so this commit prepares the makefile first by converting the existing targets into an evaluated set of targets based on the manual page name and section. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- tools/bpf/Makefile.docs | 52 ++++++++++++++++-------- tools/bpf/bpftool/Documentation/Makefile | 8 ++-- 2 files changed, 39 insertions(+), 21 deletions(-) diff --git a/tools/bpf/Makefile.docs b/tools/bpf/Makefile.docs index dc4ce82ada33..7111888ca5d8 100644 --- a/tools/bpf/Makefile.docs +++ b/tools/bpf/Makefile.docs @@ -29,32 +29,50 @@ MAN7_RST = $(HELPERS_RST) _DOC_MAN7 = $(patsubst %.rst,%.7,$(MAN7_RST)) DOC_MAN7 = $(addprefix $(OUTPUT),$(_DOC_MAN7)) +DOCTARGETS := helpers + +docs: $(DOCTARGETS) helpers: man7 man7: $(DOC_MAN7) RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null) -$(OUTPUT)$(HELPERS_RST): $(UP2DIR)../../include/uapi/linux/bpf.h - $(QUIET_GEN)$(UP2DIR)../../scripts/bpf_doc.py --filename $< > $@ +# Configure make rules for the man page bpf-$1.$2. +# $1 - target for scripts/bpf_doc.py +# $2 - man page section to generate the troff file +define DOCS_RULES = +$(OUTPUT)bpf-$1.rst: $(UP2DIR)../../include/uapi/linux/bpf.h + $$(QUIET_GEN)$(UP2DIR)../../scripts/bpf_doc.py $1 \ + --filename $$< > $$@ -$(OUTPUT)%.7: $(OUTPUT)%.rst +$(OUTPUT)%.$2: $(OUTPUT)%.rst ifndef RST2MAN_DEP - $(error "rst2man not found, but required to generate man pages") + $$(error "rst2man not found, but required to generate man pages") endif - $(QUIET_GEN)rst2man $< > $@ + $$(QUIET_GEN)rst2man $$< > $$@ + +docs-clean-$1: + $$(call QUIET_CLEAN, eBPF_$1-manpage) + $(Q)$(RM) $$(DOC_MAN$2) $(OUTPUT)bpf-$1.rst + +docs-install-$1: docs + $$(call QUIET_INSTALL, eBPF_$1-manpage) + $(Q)$(INSTALL) -d -m 755 $(DESTDIR)$$(man$2dir) + $(Q)$(INSTALL) -m 644 $$(DOC_MAN$2) $(DESTDIR)$$(man$2dir) + +docs-uninstall-$1: + $$(call QUIET_UNINST, eBPF_$1-manpage) + $(Q)$(RM) $$(addprefix $(DESTDIR)$$(man$2dir)/,$$(_DOC_MAN$2)) + $(Q)$(RMDIR) $(DESTDIR)$$(man$2dir) -helpers-clean: - $(call QUIET_CLEAN, eBPF_helpers-manpage) - $(Q)$(RM) $(DOC_MAN7) $(OUTPUT)$(HELPERS_RST) +.PHONY: $1 docs-clean-$1 docs-install-$1 docs-uninstall-$1 +endef -helpers-install: helpers - $(call QUIET_INSTALL, eBPF_helpers-manpage) - $(Q)$(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) - $(Q)$(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir) +# Create the make targets to generate manual pages by name and section +$(eval $(call DOCS_RULES,helpers,7)) -helpers-uninstall: - $(call QUIET_UNINST, eBPF_helpers-manpage) - $(Q)$(RM) $(addprefix $(DESTDIR)$(man7dir)/,$(_DOC_MAN7)) - $(Q)$(RMDIR) $(DESTDIR)$(man7dir) +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: helpers helpers-clean helpers-install helpers-uninstall +.PHONY: docs docs-clean docs-install docs-uninstall man7 diff --git a/tools/bpf/bpftool/Documentation/Makefile b/tools/bpf/bpftool/Documentation/Makefile index bb7842efffd6..f60b800584a5 100644 --- a/tools/bpf/bpftool/Documentation/Makefile +++ b/tools/bpf/bpftool/Documentation/Makefile @@ -24,7 +24,7 @@ MAN8_RST = $(wildcard bpftool*.rst) _DOC_MAN8 = $(patsubst %.rst,%.8,$(MAN8_RST)) DOC_MAN8 = $(addprefix $(OUTPUT),$(_DOC_MAN8)) -man: man8 helpers +man: man8 docs man8: $(DOC_MAN8) RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null) @@ -46,16 +46,16 @@ ifndef RST2MAN_DEP endif $(QUIET_GEN)( cat $< ; printf "%b" $(call see_also,$<) ) | rst2man $(RST2MAN_OPTS) > $@ -clean: helpers-clean +clean: docs-clean $(call QUIET_CLEAN, Documentation) $(Q)$(RM) $(DOC_MAN8) -install: man helpers-install +install: man docs-install $(call QUIET_INSTALL, Documentation-man) $(Q)$(INSTALL) -d -m 755 $(DESTDIR)$(man8dir) $(Q)$(INSTALL) -m 644 $(DOC_MAN8) $(DESTDIR)$(man8dir) -uninstall: helpers-uninstall +uninstall: docs-uninstall $(call QUIET_UNINST, Documentation-man) $(Q)$(RM) $(addprefix $(DESTDIR)$(man8dir)/,$(_DOC_MAN8)) $(Q)$(RMDIR) $(DESTDIR)$(man8dir) 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: 12090813 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 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 592D6C433DB for ; Wed, 17 Feb 2021 01:10:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 28BB864E57 for ; Wed, 17 Feb 2021 01:10:10 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231406AbhBQBKG (ORCPT ); Tue, 16 Feb 2021 20:10:06 -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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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: 12090827 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 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 7A037C433E0 for ; Wed, 17 Feb 2021 01:10:32 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4A26664E57 for ; Wed, 17 Feb 2021 01:10:32 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231524AbhBQBK0 (ORCPT ); Tue, 16 Feb 2021 20:10:26 -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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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 From patchwork Wed Feb 17 01:08:20 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12090817 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 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 6125AC433DB for ; Wed, 17 Feb 2021 01:10:14 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2882F64E57 for ; Wed, 17 Feb 2021 01:10:14 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231508AbhBQBKH (ORCPT ); Tue, 16 Feb 2021 20:10:07 -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 S231452AbhBQBJq (ORCPT ); Tue, 16 Feb 2021 20:09:46 -0500 Received: from mail-pl1-x62b.google.com (mail-pl1-x62b.google.com [IPv6:2607:f8b0:4864:20::62b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6AA48C061356; Tue, 16 Feb 2021 17:09:01 -0800 (PST) Received: by mail-pl1-x62b.google.com with SMTP id a24so6482605plm.11; Tue, 16 Feb 2021 17:09:01 -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=MNhCRc2GDeasyRbwo0O5IIW2sQmDlpog5LT65h+9PRk=; b=JpCYdxlyW95RjiZUbReMdnBgSVsTjSPc6zv/iVoYOlyEwC+66tXG4BHVep1YcmzR5w 8DzTWwMgqt/Wg7XuBxjyckL1UUX+nZcQver2h/Qo3syG3sa7PMp4AnfqPlnrrO+2wzu3 7oryBVvplwAotyQpNJRqsrQvc6hEIn+Sr0C22awd/9o7MvRgTEtaNyCD+VW2GrRo4OgS Upoki3j/vVvxNRkRNflFmGf/gMb7FjjriymFJZPzbZPi1WG70010h/fNPA1UOOBjK7mw tdZ06WjNmW+xrBsDuzrhq9C9OjTsDhSsdZXNi4Yxa/9mIv2ZUV00yD3Kr2UnJkdTVclt D93g== 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=MNhCRc2GDeasyRbwo0O5IIW2sQmDlpog5LT65h+9PRk=; b=jmJXtATQrxCHlWiYW8U6wnhEQ0Ch7bUFDzZYx/rbHcYXqCU8uiV6Xjk1HkI/rJ/wYb khNA00F2PpVzlA2NusxyaasyoM1vDc7VbIAS9+2KyI45X8clMXq1ORbVjdafmmuK4UeG b435Ev87LgGCgY90ZTGKMmcndmdlgzsvIAvprz2kJrBXYkBPbeTpxUT0Vv0rDEyPpXEo dKBD4v0rH1Z7OHtANo1P3+W2/RtOpfkz+QWOfjONan3kywLr7FtgE9IngigSVl2ACBmE waZ+9bdi9KO4aLHAOKhhx8JQOLrAgqVhuU6xIh7MAVlh3zkYCTQYGcAycK2WeMP10zZF AhQg== X-Gm-Message-State: AOAM533ZHhJi/9tou3zLRCck0+pkhlv4LjXq4Ho3ISRk23mCyFa0Dsgg hu/vc3p0leZbMasW48Vheb3MXMD8eVvvrA== X-Google-Smtp-Source: ABdhPJza3X35TyluBMjnuRZ4jXxdo+/2hoN/6FY/wDYY5xRQeCsZ5jevNQi6N2RQ/oY6k3aGYLvxLA== X-Received: by 2002:a17:902:d694:b029:e3:906a:61f8 with SMTP id v20-20020a170902d694b02900e3906a61f8mr848456ply.36.1613524140665; Tue, 16 Feb 2021 17:09:00 -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.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:09:00 -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 16/17] docs/bpf: Add bpf() syscall command reference Date: Tue, 16 Feb 2021 17:08:20 -0800 Message-Id: <20210217010821.1810741-17-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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Joe Stringer Generate the syscall command reference from the UAPI header file and include it in the main bpf docs page. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- Documentation/Makefile | 2 ++ Documentation/bpf/Makefile | 28 ++++++++++++++++++++++++++++ Documentation/bpf/bpf_commands.rst | 5 +++++ Documentation/bpf/index.rst | 14 +++++++++++--- 4 files changed, 46 insertions(+), 3 deletions(-) create mode 100644 Documentation/bpf/Makefile create mode 100644 Documentation/bpf/bpf_commands.rst diff --git a/Documentation/Makefile b/Documentation/Makefile index 9c42dde97671..408542825cc2 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -73,6 +73,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ + $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/bpf $2 && \ PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(PYTHON3) $(srctree)/scripts/jobserver-exec \ @@ -133,6 +134,7 @@ refcheckdocs: cleandocs: $(Q)rm -rf $(BUILDDIR) + $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/bpf clean $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean dochelp: diff --git a/Documentation/bpf/Makefile b/Documentation/bpf/Makefile new file mode 100644 index 000000000000..4f14db0891cc --- /dev/null +++ b/Documentation/bpf/Makefile @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Rules to convert a .h file to inline RST documentation + +SRC_DIR = $(srctree)/Documentation/bpf +PARSER = $(srctree)/scripts/bpf_doc.py +UAPI = $(srctree)/include/uapi/linux + +TARGETS = $(BUILDDIR)/bpf/bpf_syscall.rst + +$(BUILDDIR)/bpf/bpf_syscall.rst: $(UAPI)/bpf.h + $(PARSER) syscall > $@ + +.PHONY: all html epub xml latex linkcheck clean + +all: $(IMGDOT) $(BUILDDIR)/bpf $(TARGETS) + +html: all +epub: all +xml: all +latex: $(IMGPDF) all +linkcheck: + +clean: + -rm -f -- $(TARGETS) 2>/dev/null + +$(BUILDDIR)/bpf: + $(Q)mkdir -p $@ diff --git a/Documentation/bpf/bpf_commands.rst b/Documentation/bpf/bpf_commands.rst new file mode 100644 index 000000000000..da388ffac85b --- /dev/null +++ b/Documentation/bpf/bpf_commands.rst @@ -0,0 +1,5 @@ +************************** +bpf() subcommand reference +************************** + +.. kernel-include:: $BUILDDIR/bpf/bpf_syscall.rst diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 4f2874b729c3..631d02d4dc49 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -12,9 +12,6 @@ BPF instruction-set. The Cilium project also maintains a `BPF and XDP Reference Guide`_ that goes into great technical depth about the BPF Architecture. -The primary info for the bpf syscall is available in the `man-pages`_ -for `bpf(2)`_. - BPF Type Format (BTF) ===================== @@ -35,6 +32,17 @@ Two sets of Questions and Answers (Q&A) are maintained. bpf_design_QA bpf_devel_QA +Syscall API +=========== + +The primary info for the bpf syscall is available in the `man-pages`_ +for `bpf(2)`_. + +.. toctree:: + :maxdepth: 1 + + bpf_commands + Helper functions ================ From patchwork Wed Feb 17 01:08:21 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12090829 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 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 DCFC1C433DB for ; Wed, 17 Feb 2021 01:11:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 96CD464E57 for ; Wed, 17 Feb 2021 01:11:10 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231534AbhBQBLH (ORCPT ); Tue, 16 Feb 2021 20:11:07 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47666 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231513AbhBQBKL (ORCPT ); Tue, 16 Feb 2021 20:10:11 -0500 Received: from mail-pl1-x632.google.com (mail-pl1-x632.google.com [IPv6:2607:f8b0:4864:20::632]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 04204C06121C; Tue, 16 Feb 2021 17:09:04 -0800 (PST) Received: by mail-pl1-x632.google.com with SMTP id b8so6484505plh.12; Tue, 16 Feb 2021 17:09:04 -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=Q1UuE0qBxhnnVS107NY6bBjPoOkYenkq/PEKhaBEofQ=; b=ioAk5+TH38cqb12aanbaKhecpIESk6QbzMsAwhh6pDgbM+gxr4gjnh6awP7BFd4cC9 FpoDhaj8TnMKcUl8ThKf6V91Jhi1bsTv+6rXAOmn0zgV0WNJ+mX42AdvzQbSvPLfwEvg R6XEwVHXo09wPKqnY4aHiJuFf3CfnfY/F/UhjkZICbmh5hxnvDTclRFNwXGjSFvU9qoZ 8KE6oYlfCQj0u5AKLTqv79sMZTkNYoJOk7+88sMOm7CEbnn5xejyDgrQqGTly7nGLyC1 m14C1NbfAkhvv5OL1BJmbXZbWBOrHWSy4CTWyt8M6AH7IBNexPKo53LNNRyalXCogcm0 E+XQ== 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=Q1UuE0qBxhnnVS107NY6bBjPoOkYenkq/PEKhaBEofQ=; b=B1Znls1nCAYEk+Lysy3XL9VT+NRf0N3evK5SDdP/9FumR95L6dKLcTjJjIgYSp+210 5cilnIgE0sYfx/j1HtKO6yEcVMxk8R1NHHFKRGrmoWLgRKRXf+bNUkAZ6gCmoVV+WTnD /ZmS1Tg3HzyFUCBR/AT/ChtBAwy/eUTH70lKi6lHqtz+zOoP7ng4M3LMIIq9WuTFkJLf kWXZK8xgH7DfEiCzq/5O3Rmaa27eU9Io6USCWVWgZts5MB6j0LVfxfXlI7rD/lFtEMZg fl5mxEq1mytmwpZdiKtsW72fQf/3bkXVofAHvKdW20tIqJ2JJ6aLafOAXHlswsH11Z0B aGcA== X-Gm-Message-State: AOAM531lNaJR21R0SQTpV4EJQiHDdbwHv5tM0/wlZjtMGwsOCn0ZYQ24 TJODBWTQkoU5fNsyChcTiuw9KyEBA4dg3Q== X-Google-Smtp-Source: ABdhPJxB1OfExApGt5rtJ7PuBsbOi0c6Zx6yWiAksVmsIP1otyS5asm+uHspj0JtCFFhT9lIpiCNHA== X-Received: by 2002:a17:90b:1008:: with SMTP id gm8mr6928780pjb.174.1613524142407; Tue, 16 Feb 2021 17:09:02 -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.09.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Feb 2021 17:09:01 -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 17/17] tools: Sync uapi bpf.h header with latest changes Date: Tue, 16 Feb 2021 17:08:21 -0800 Message-Id: <20210217010821.1810741-18-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: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Joe Stringer Synchronize the header after all of the recent changes. Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- tools/include/uapi/linux/bpf.h | 707 ++++++++++++++++++++++++++++++++- 1 file changed, 706 insertions(+), 1 deletion(-) diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h index 16f2f0d2338a..4abf54327612 100644 --- a/tools/include/uapi/linux/bpf.h +++ b/tools/include/uapi/linux/bpf.h @@ -93,7 +93,712 @@ 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*. + * + * The *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. + * + * 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. + * **BPF_F_LOCK** + * Update a spin_lock-ed map 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). + * + * BPF_OBJ_PIN + * Description + * 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. + * + * 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. + * + * The *attach_type* specifies the eBPF attachment point to + * attach the program to, and must be one of *bpf_attach_type* + * (see below). + * + * The *attach_bpf_fd* must be a valid file descriptor for a + * loaded eBPF program of a cgroup, flow dissector, LIRC, sockmap + * or sock_ops type corresponding to the specified *attach_type*. + * + * The *target_fd* must be a valid file descriptor for a kernel + * object which depends on the attach type of *attach_bpf_fd*: + * + * **BPF_PROG_TYPE_CGROUP_DEVICE**, + * **BPF_PROG_TYPE_CGROUP_SKB**, + * **BPF_PROG_TYPE_CGROUP_SOCK**, + * **BPF_PROG_TYPE_CGROUP_SOCK_ADDR**, + * **BPF_PROG_TYPE_CGROUP_SOCKOPT**, + * **BPF_PROG_TYPE_CGROUP_SYSCTL**, + * **BPF_PROG_TYPE_SOCK_OPS** + * + * Control Group v2 hierarchy with the eBPF controller + * enabled. Requires the kernel to be compiled with + * **CONFIG_CGROUP_BPF**. + * + * **BPF_PROG_TYPE_FLOW_DISSECTOR** + * + * Network namespace (eg /proc/self/ns/net). + * + * **BPF_PROG_TYPE_LIRC_MODE2** + * + * LIRC device path (eg /dev/lircN). Requires the kernel + * to be compiled with **CONFIG_BPF_LIRC_MODE2**. + * + * **BPF_PROG_TYPE_SK_SKB**, + * **BPF_PROG_TYPE_SK_MSG** + * + * eBPF map of socket type (eg **BPF_MAP_TYPE_SOCKHASH**). + * + * 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 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. + * + * 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. + * + * The *target_fd* must be a valid file descriptor for a kernel + * object which depends on the attach type of *attach_bpf_fd*: + * + * **BPF_PROG_TYPE_CGROUP_DEVICE**, + * **BPF_PROG_TYPE_CGROUP_SKB**, + * **BPF_PROG_TYPE_CGROUP_SOCK**, + * **BPF_PROG_TYPE_CGROUP_SOCK_ADDR**, + * **BPF_PROG_TYPE_CGROUP_SOCKOPT**, + * **BPF_PROG_TYPE_CGROUP_SYSCTL**, + * **BPF_PROG_TYPE_SOCK_OPS** + * + * Control Group v2 hierarchy with the eBPF controller + * enabled. Requires the kernel to be compiled with + * **CONFIG_CGROUP_BPF**. + * + * **BPF_PROG_TYPE_FLOW_DISSECTOR** + * + * Network namespace (eg /proc/self/ns/net). + * + * **BPF_PROG_TYPE_LIRC_MODE2** + * + * LIRC device path (eg /dev/lircN). Requires the kernel + * to be compiled with **CONFIG_BPF_LIRC_MODE2**. + * + * **BPF_PROG_QUERY** always fetches the number of programs + * attached and the *attach_flags* which were used to attach those + * programs. Additionally, if *prog_ids* is nonzero and the number + * of attached programs is less than *prog_cnt*, populates + * *prog_ids* with the eBPF program ids of the programs attached + * at *target_fd*. + * + * The following flags may alter the result: + * + * **BPF_F_QUERY_EFFECTIVE** + * Only return information regarding programs which are + * currently effective at the specified *target_fd*. + * + * 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. + * + * 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 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* + * is set appropriately. + * + * BPF_MAP_UPDATE_BATCH + * Description + * 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 + * 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* + * 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. + * * 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, BPF_MAP_LOOKUP_ELEM,