From patchwork Tue Mar 2 17:19:33 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112757 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id E0CA9C433E9 for ; Wed, 3 Mar 2021 03:56:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B07F364E6F for ; Wed, 3 Mar 2021 03:56:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352515AbhCCDui (ORCPT ); Tue, 2 Mar 2021 22:50:38 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50132 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S240792AbhCBRiu (ORCPT ); Tue, 2 Mar 2021 12:38:50 -0500 Received: from mail-pj1-x1029.google.com (mail-pj1-x1029.google.com [IPv6:2607:f8b0:4864:20::1029]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A1564C061A2B for ; Tue, 2 Mar 2021 09:20:34 -0800 (PST) Received: by mail-pj1-x1029.google.com with SMTP id jx13so2376154pjb.1 for ; Tue, 02 Mar 2021 09:20:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=cZPyA9m3sp7GWzupY4xnewRoMydoMiMPf4WFOI3CF9w=; b=sJ2OJLwmwqDDPUf35eKDe6NU8HZy6R5/C9TvVUeRumZ9EyXhSA8h8QolBQYVIGEN3+ sjISVk5hmKpVotMoC6UygTqdDwxXci49TMiDryrojQJTntTO6DIwRbfX2NFNfItree7x C7BAyAFlxavkRwkLf7sxBHmaw3ED/rv53Y6tRW/1IhShcs2ltLS5YQ6FgsbBqIROgkYA fM+Ix6srOLtyQ0/iwdookdICuoar/FA9pgawiIFa0X/QW/HYWNqQw5w9g+srowA9OM/V YYbJprgQcsn0hJflHr828zG+XIi0BAjXSo/wbl8mQ1w9yYi50Sht7if7badDtS4JC388 2lSA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=cZPyA9m3sp7GWzupY4xnewRoMydoMiMPf4WFOI3CF9w=; b=S2Zqd0U81U6HsbnGSyBlpblwimeUcr/JFZDY2FcHIWB78S9qdpBz86wM0dIADsx1NP 6rizR1kWGjR9zoDPU+Zbwq4N/dgqnp7ryqpX95W40KFk07il8RPTeevJs8H16LWPZp7f kO6Yxkq/Z6LToQ25+eKVLeHk5kgFem8CY0x9J1dJPKSn/4WNgDKFOzrBPzSwEQKPKsGg OGuW3bRQiBITD2fEayjLDuOAiZ1QJjOW5T/alBeaboQjVgBJhLYmBz03/zCPlIcNJmhX srMAF9BXrCxdRUyjeuOxsyEckLu0jIMsWx4ZBUyCleVgCXjJ3vT0/c2fe+S8GNVRkMga GOWw== X-Gm-Message-State: AOAM531/wrmdH1yb70Av/iJ+NKXURU8E5a/8F/ZUObwahKG8EWhsqOtG OIfIo/SIQH4N8+PwAJoJJkVXIHh6ExMYUakI X-Google-Smtp-Source: ABdhPJz+91huBG/Dlm8J0g83YpRM8aSMTTD4XhyVsTbpSADsoEBemrdz+CbGvbQH2oxc1uXLp/0Zpg== X-Received: by 2002:a17:90b:110c:: with SMTP id gi12mr5436954pjb.48.1614705633830; Tue, 02 Mar 2021 09:20: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 b15sm20073923pgg.85.2021.03.02.09.20.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:33 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet , Michael Kerrisk Subject: [PATCHv2 bpf-next 01/15] bpf: Import syscall arg documentation Date: Tue, 2 Mar 2021 09:19:33 -0800 Message-Id: <20210302171947.2268128-2-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Co-authored-by: Alexei Starovoitov Co-authored-by: Michael Kerrisk Signed-off-by: Joe Stringer Acked-by: Yonghong Song --- include/uapi/linux/bpf.h | 122 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 1 deletion(-) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index b89af20cfa19..fb16c590e6d9 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -93,7 +93,127 @@ 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. */ +/** + * DOC: eBPF Syscall Preamble + * + * 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*. + */ +/** + * DOC: eBPF 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 Tue Mar 2 17:19:34 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112751 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id E4350C433E0 for ; Wed, 3 Mar 2021 03:55:58 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 9038264E76 for ; Wed, 3 Mar 2021 03:55:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352503AbhCCDuZ (ORCPT ); Tue, 2 Mar 2021 22:50:25 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50138 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1349778AbhCBRga (ORCPT ); Tue, 2 Mar 2021 12:36:30 -0500 Received: from mail-pj1-x102a.google.com (mail-pj1-x102a.google.com [IPv6:2607:f8b0:4864:20::102a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D5F85C061A30 for ; Tue, 2 Mar 2021 09:20:35 -0800 (PST) Received: by mail-pj1-x102a.google.com with SMTP id jx13so2376184pjb.1 for ; Tue, 02 Mar 2021 09:20:35 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=uozbbnIbmkxFj/HIjxQ8WJQUr6vi8vUHNtiv9TAUsWg=; b=OxJj6Gwx86HVTrnPp9BaOKPNRaezKTLP7TX2wps4YmLsKGHZcFmQAzK8TUUHao3FPu 8TNG0CyaA8NPFvTxtHIcIMWp26eJNLOrfeWrR5OKukQUxM/ze+qAH001UKAJ3lRegWMy vwHFYHnl5UR02YpAy5Mh5SRBNy0/uQSknjg+NbD3liUIZfD0IOa2RjQbW2kGa8eei8/2 vBVWE57jvS+qXRtzL07HQrtfToQNhv1r61OnrtwLuA7JUUa7Y0/VAO6+Y+VMwfOX6rnI /nfHQ8bB9REmQPFtz8wE2A9N5pfXKftaGk/xkc2zitJq2VLofGcRLfGTaM3y5A32/3ib Kh+A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=uozbbnIbmkxFj/HIjxQ8WJQUr6vi8vUHNtiv9TAUsWg=; b=ec3XjDpQrm6bJ2xHNO1oO67EOtZdJQ9kWudaI8xJa4JZxLAl9ri6hHWQwKzxbTiBIE i1vY4mGyoVtqP3bSSQNMo16jJBriPi2XAC6y6UJd1zj3/9E6q8rNaCZdm9tlUN/FgGvL 6zaoIDNTGzpuM9nJWxvvAWmWdDgPJmdK/Kjlo2F6dQ0bVnFuyILrQWBG2R+8odDA0Hlh Rt09sSiBXmJXCJs/w113YOZPbPsha68EuxjnUbqMak2CvRNB6KWZIGE1e4LI0thhlKhM zCyLi9mQe0JqFKS40/ns7Ydvnt2vjtz88ruRXAJod1zb1OP0jvup3vKgxziYCObTws2W Z3mA== X-Gm-Message-State: AOAM53207StdaFZWhLbv5W1sNpj84KLOJDlUJSxJYJlGxQKYINl87qkv CH4SnOR2zln8bV1WK3l8IuQocPexbaCyX2u1 X-Google-Smtp-Source: ABdhPJx+YkvABLuhZmo1HaocVUC3PQfUgQid0eo7udB08w+vpgyft1oyH7k/T770tY5EwOpwN7oakA== X-Received: by 2002:a17:90a:cb0a:: with SMTP id z10mr1136091pjt.170.1614705634975; Tue, 02 Mar 2021 09:20:34 -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 b15sm20073923pgg.85.2021.03.02.09.20.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:34 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 02/15] bpf: Add minimal bpf() command documentation Date: Tue, 2 Mar 2021 09:19:34 -0800 Message-Id: <20210302171947.2268128-3-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer Acked-by: Yonghong Song --- 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 fb16c590e6d9..052bbfe65f77 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -204,6 +204,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 Tue Mar 2 17:19:35 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112753 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1074DC433E0 for ; Wed, 3 Mar 2021 03:56:03 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id BABB164E76 for ; Wed, 3 Mar 2021 03:56:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352512AbhCCDue (ORCPT ); Tue, 2 Mar 2021 22:50:34 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50116 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241170AbhCBRiu (ORCPT ); Tue, 2 Mar 2021 12:38:50 -0500 Received: from mail-pf1-x42a.google.com (mail-pf1-x42a.google.com [IPv6:2607:f8b0:4864:20::42a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id ACB09C0610CB for ; Tue, 2 Mar 2021 09:20:36 -0800 (PST) Received: by mail-pf1-x42a.google.com with SMTP id 201so14264489pfw.5 for ; Tue, 02 Mar 2021 09:20:36 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=4OQ4Fa3XDb0vqLtsUsGhKWRVVUdgFV/a7640/4sVzCI=; b=VEn+KrqTLvXG4lYjWiPEl63hjQynBvGUaNH9btc9bqSkGLG/SAwpdWRGUsHJLQmmyr 5/AnNoFDms5Nd4h39i4ird96IfTOdmVttHfudZZ6jJP6oY3ipvAab/lfXqN0Z/bJvUJZ TOAjHzM5LXPGwEz91/2sx9pWdQuJ6LrwlhH5czJwLZY3ysSYB8hgkqf57Fmrr1IEnAoy 5rjTpDWxJi8LfpPz5/D4eOzdm4/nICzedFqu2mMK86GUPRcR+WosqRM2XRNc797Z5tAZ bsSss/XNt6HY/Jq+UwhxhR/Tp1GaQ6X7aNoiEtE026hQCaStKvzbWYCErMP/15MezB0D m5LA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=4OQ4Fa3XDb0vqLtsUsGhKWRVVUdgFV/a7640/4sVzCI=; b=dWznvYB8wdcd98eU2Td9aUqyb5CDj3jHCVvnGOE/6tAjZkD205uHeoTJzQLx0dD4h+ SQIuB8RlTtu9mygF6BVJPE9Iph5FS2rDINagvOmLDBwmyrwkRNYqlopkZkbFCEWNfI68 coYs7Fff6yaTHyYpU4gV1NM7MuYkVWxjBZ4MvoBln/XNXMKF6mi4OfQ7ycrYqlbVjUe1 pT94tClB3Vdw18w/c/GvK2/3rnF7GVG9NhlaSfuFgEBCcB6JoDltYek+FQ6++NRFv91e MD3frXYZ3NMi/5sWUFKWVD86JuXTuq6QaxTS4uRoHfUHyvQbvuWzwOfS1TcvKJBSxo9/ PXdQ== X-Gm-Message-State: AOAM533UZ9PkCu6HjuutM1yRE5pM+gCwG3po2SlVTS4UtiFBrDqYcLan 2pno1/Cw95YZEOQfXBc4pclq8yFYbTxpkyk/ X-Google-Smtp-Source: ABdhPJxA2lvb0g3CuazPgmOebM0zd3D5/1CGdNrCBlzqn02l1xdSIJobPdOgKhL6LIUuS3t1rZO3AQ== X-Received: by 2002:a63:505d:: with SMTP id q29mr18501814pgl.218.1614705636133; Tue, 02 Mar 2021 09:20:36 -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 b15sm20073923pgg.85.2021.03.02.09.20.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:35 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 03/15] bpf: Document BPF_F_LOCK in syscall commands Date: Tue, 2 Mar 2021 09:19:35 -0800 Message-Id: <20210302171947.2268128-4-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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"). Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer Acked-by: Yonghong Song --- 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 052bbfe65f77..eb9f059f0569 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -123,6 +123,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. @@ -140,6 +148,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 Tue Mar 2 17:19:36 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112747 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 22BE5C4332E for ; Wed, 3 Mar 2021 03:55:39 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id E332864E12 for ; Wed, 3 Mar 2021 03:55:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352501AbhCCDuX (ORCPT ); Tue, 2 Mar 2021 22:50:23 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50132 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1349773AbhCBRga (ORCPT ); Tue, 2 Mar 2021 12:36:30 -0500 Received: from mail-pg1-x531.google.com (mail-pg1-x531.google.com [IPv6:2607:f8b0:4864:20::531]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 22D7EC061A86 for ; Tue, 2 Mar 2021 09:20:38 -0800 (PST) Received: by mail-pg1-x531.google.com with SMTP id o10so14272455pgg.4 for ; Tue, 02 Mar 2021 09:20:38 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=PLtlvyaPh/9T56HasU+WSMU0kz49t2tHiOoZMMkTowk=; b=KOb5TwQX9FBBkprFm/htpAAUQeFnhX03SiYO3cltYiXu02VFt63RgxKdA9dChGxLGX qDVRO5bziB1NphRiYWyi3eMF/ZalwYDjRmsaH6hAGJ0rl3xFIsgYa/80AUz87nqvIpV/ 01gOYgYOIRFJ6kl7Enk49pmHzXMuHoLOG1Un8ijL5vAQcgRIsDJ26DcXkAQA8NeU7GFy DrlesMGqoPqYOrrfOexGmVun8Gaw2OAFkTyFABjQYYptNSuN8adrxa2gLG3BG/BTr5/k jmLpgnI8NHNsvE3Xzy9rqdhhUshdief1DM9qMfW7tnq0AoGTwi5/x8/DLGHaEbHxhoXU 2D0g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=PLtlvyaPh/9T56HasU+WSMU0kz49t2tHiOoZMMkTowk=; b=SXRFKHQCcfrrymoGLvT+VyszlOqupE3V2BsbiS5XLUS+CKZQG0VY+cgfPpRGci1AgH VXX+OTEhHOSgJ7iDeUQ3dmfkzvHRVIIXiSB5uNPrSrmLztygdcJR5tjRW6v+2RydzEZ4 ajInLFzCWPNXdDPMY1J4CRflwUeIoU0zZJrsXgDrn1yIeE2078MyNqzfKxI4XLfW/9+m zalCEyFQXhtSNcD5AdweTimtBA305x01HTYtZ2Jjtm7tPfHAt4aYKgqp0X3dH2rqjCQN +iX4HOZd7aWL05HxQ+SS6dT7z18L5PR128qYojgEH0V56TetTxa/jvihykeJ8MWyAhUe 5BwA== X-Gm-Message-State: AOAM532Ev+y0WMD+7ZrFY5KFJHFhFfRqIlQk+l1vPEDmz3Bv6ccFUN26 CYucVEkPe5H2QdzOXMBQS6qTFiFXWMzL+5wa X-Google-Smtp-Source: ABdhPJz3kypQd3bHxFkEeV/1MTPv662VAv9XKyEsN2c3ppcIx1ZRCI7lLCQahJF6lnqjjaciXNJYsg== X-Received: by 2002:aa7:8057:0:b029:1ee:6534:2a95 with SMTP id y23-20020aa780570000b02901ee65342a95mr4094571pfm.57.1614705637437; Tue, 02 Mar 2021 09:20: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 b15sm20073923pgg.85.2021.03.02.09.20.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:37 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 04/15] bpf: Document BPF_PROG_PIN syscall command Date: Tue, 2 Mar 2021 09:19:36 -0800 Message-Id: <20210302171947.2268128-5-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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") Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer Acked-by: Yonghong Song --- CC: Daniel Borkmann --- include/uapi/linux/bpf.h | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index eb9f059f0569..6946dde90c56 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -219,6 +219,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. @@ -584,13 +600,19 @@ 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 Tue Mar 2 17:19:37 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112749 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 41200C28CFB for ; Wed, 3 Mar 2021 03:55:38 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 04A5264E7C for ; Wed, 3 Mar 2021 03:55:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352494AbhCCDuP (ORCPT ); Tue, 2 Mar 2021 22:50:15 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49822 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1347086AbhCBRgT (ORCPT ); Tue, 2 Mar 2021 12:36:19 -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 6CA64C061D73 for ; Tue, 2 Mar 2021 09:20:39 -0800 (PST) Received: by mail-pg1-x52a.google.com with SMTP id x29so6015853pgk.6 for ; Tue, 02 Mar 2021 09:20:39 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=F4TZNoz7ocIF56TKRbY3Vad3YXgKTVwOO2I7OPJ9bdI=; b=Rq8g8G4z1aYt5VEo1BJL1lomrPLJDL8MogcsKXho9qnTQQsZjjcYppdO7Pgzg5rQ6p Yv3KwyxgU1SCK009bDta+0kKTZ0BUumGgSC7wCyx+vUYFINpAQupYFbSL6p73A2fORuy cYdiPm1jxd5z69yFQM+JbIA4fWaI47ocd3a+NlCBhfcGed8Yzs3nSMjoemCWHg4TZlgQ pQQZWhm3lwDtOQy6Q3BGJWUh8vIcDK5cdD8jArYQwjhW0b4nI/wtSLAIaoKWD5p5DxbQ yTOcJ6hyAuE2hLln6ldOtmK35PCndBIL7qUndNBnO7X3q22S14ihOneSfegT61NUPlrk Ia6A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=F4TZNoz7ocIF56TKRbY3Vad3YXgKTVwOO2I7OPJ9bdI=; b=euGGXEpaMfiI/fE0JMYsmjaRXG5Ich0QSgJWZbThsOOYnpTO7HkFqzWNGrzB2L+Lb1 IWhQHI294IjfKOhlh8loUKPf0bkwMRH9C8pQ48leqyVxRo+I+svk0Y4hWdypIsxvUxRt +vMO+G1rPbH2WqIiaS0Yra19Wp7OiYKXURRPuXrRcfsZ/BNGfehn511nctMSIbMPY74H /l787UrpomFbKUfvQzoweDIcBam5JGwW70lyNQtP8HeTFlTbzkoKhH5kiPNxMirEM8Ku 00yBINfEA/533JnBU0EwaCXfV3r8Ub8mJGy6oulc4XgNFiB0ZBnqWxhcQW4H313L++eb YfiQ== X-Gm-Message-State: AOAM530x9L3YmHWXxLEEEV8WFtfJvtKezP1CUCnd+n/KKRsT5Yl5jFLe +JQUh48oJq5dT6Ashx7g3EqQoBEBvTnendG8 X-Google-Smtp-Source: ABdhPJzzrU4EnuhRv5vP5CvUvDAT9MZzHUjANL8z8fBWR9KhipnfIrGMov1YV2gpQAV0C3+I1u4/Ig== X-Received: by 2002:a05:6a00:1e:b029:1ed:b82c:bb64 with SMTP id h30-20020a056a00001eb02901edb82cbb64mr20018658pfk.78.1614705638819; Tue, 02 Mar 2021 09:20: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 b15sm20073923pgg.85.2021.03.02.09.20.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:38 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet , Daniel Mack , John Fastabend , Sean Young , Petar Penkov Subject: [PATCHv2 bpf-next 05/15] bpf: Document BPF_PROG_ATTACH syscall command Date: Tue, 2 Mar 2021 09:19:37 -0800 Message-Id: <20210302171947.2268128-6-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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") Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer Acked-by: Yonghong Song --- 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 6946dde90c56..a8f2964ec885 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -253,6 +253,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 Tue Mar 2 17:19:38 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112755 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7593EC433DB for ; Wed, 3 Mar 2021 03:56:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 3E9A964E7C for ; Wed, 3 Mar 2021 03:56:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352508AbhCCDu2 (ORCPT ); Tue, 2 Mar 2021 22:50:28 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50130 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241293AbhCBRiu (ORCPT ); Tue, 2 Mar 2021 12:38:50 -0500 Received: from mail-pg1-x52b.google.com (mail-pg1-x52b.google.com [IPv6:2607:f8b0:4864:20::52b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B50A1C061D7E for ; Tue, 2 Mar 2021 09:20:40 -0800 (PST) Received: by mail-pg1-x52b.google.com with SMTP id b21so14263755pgk.7 for ; Tue, 02 Mar 2021 09:20:40 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=LGedM16svrVRIDLBK09BZkJurYK/adPWABtIqUN11XE=; b=nec8Qf4JnqZveYNQRUt7giQ1HrgeOLBYYbLnenTVr1+XsPqLZx9H4T93/uPCFY99dV CvMWnXF0Q4e78JMkkeSHeqJPsj5AJYQG6dqcOu8prQgpDlsLk/2PM604XmGKLDS+H0Kv 1LcC65OfH1Xt23i3jXtcGsdn8W0QFiP2u3piZAWQJ1rbHA1AwtvtqcOPEwMYwRvWFu28 NEfIo+hOnGkj2ykivDKe08SuraOa0BgrsdkI3sdK3QYdQY2A9hUseVRfbfhhQpNKa6B2 vHmEDzrQeOpaVV6PbmnpglsgtP6l5G8hAhgjdfLkV/uH9UiOAGniC4sqPl7yvWPmVncu HSKQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=LGedM16svrVRIDLBK09BZkJurYK/adPWABtIqUN11XE=; b=L/TckWjtQzUGRlhGQwuNQZuy97nqhpjGJpauc92zt92HYfoKwzgAvTYMX3ERdvWqfa PwQj7CD0OYB3s61S5bVFKDkLgTw2qFXMP2RpGy47N5UyZlsEibsedPPAcigwobJAfWAr mJrm0Ik9WNYgcZs3OZibPQQm3GjmJqfSpAeAWOWrw93A5mJTvW/UckZvaWwDh+mHz/Ut jb4QmbIEB1xq/XU8DEUJ7doxpAq0YkS/UabMXPCHWAP0nIsoIpHCG58OJrsNoVg9YMJr P/iKNmXH2wKB9u3XHx5YXy0oUQP3pShqKrPLn7jdzLs7dY/+fxSCNODVWlKHdzR2ArK8 2SjA== X-Gm-Message-State: AOAM530LJDzeWd1S9eLa5QfQMBGryUVqy1K4Fw1DCTkHjJMVsOXzjY6f 6h7ANxfiMxXNi7Mg+diwFR9rd+d72H3ibmN2 X-Google-Smtp-Source: ABdhPJx/uvf1QBj7cHKKClRTL89yGb95dwPDCdF0a63SosyR+2cPWBJqf5GeKY0fbP9QjO6nOPhTjA== X-Received: by 2002:a05:6a00:22d6:b029:1cb:35ac:d8e0 with SMTP id f22-20020a056a0022d6b02901cb35acd8e0mr4023406pfj.17.1614705640111; Tue, 02 Mar 2021 09:20: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 b15sm20073923pgg.85.2021.03.02.09.20.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:39 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 06/15] bpf: Document BPF_PROG_TEST_RUN syscall command Date: Tue, 2 Mar 2021 09:19:38 -0800 Message-Id: <20210302171947.2268128-7-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Based on a brief read of the corresponding source code. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer Acked-by: Yonghong Song --- 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 a8f2964ec885..a6cd6650e23d 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -306,14 +306,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 Tue Mar 2 17:19:39 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112745 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id E5512C28D15 for ; Wed, 3 Mar 2021 03:55:38 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B97B964E75 for ; Wed, 3 Mar 2021 03:55:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352498AbhCCDuS (ORCPT ); Tue, 2 Mar 2021 22:50:18 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50134 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1349774AbhCBRga (ORCPT ); Tue, 2 Mar 2021 12:36:30 -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 09208C0698C1 for ; Tue, 2 Mar 2021 09:20:42 -0800 (PST) Received: by mail-pf1-x42e.google.com with SMTP id r5so14228278pfh.13 for ; Tue, 02 Mar 2021 09:20:42 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=z18YKbLroFUMGatWaH2sPxqJhja6Q90A29PeFQbc+yo=; b=Pd1EI/TpC8ppXGX0DvPNxNKLO4LBZUb5iWVW39mf7VL+Yku8YghXxLi1ngPO+TsrbW so6J/GGP32H8aiu44WZ1cWs5oVTZF7yfxNSFB0iPIBpeogJHoH+UCjHsgAmvV3dPZ6+/ WgZ6XVBb0OGFPrP9a0dTRg/QWoOahRBaAROtfFOIrdMeOCTvO9cGNG0GpqdnbyBLGJZ1 i7HSO8FEA//QEniDAOVW3NzwGurhiZtBzrlAEB16uU++MeTbT+PbVJlvcGyo2cbkx/UX Ov7Qy3F+OZGQoBVEBL67GAoSJBQwCQpNKLlOQdCNiqfgQouCYWsApBI4s8rr8IkRmeqv nNjw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=z18YKbLroFUMGatWaH2sPxqJhja6Q90A29PeFQbc+yo=; b=Rt/NlB/OMAl5LfHY//wSIdaadQO06tqJDBwCE8Z/tHM5qjuxKjkV2zGDrJp31jxsA1 GomICpkxzxkrCIU7J4I5BB7PoCEMRNKi7xMU5yyYWmApU/ezAYoyeguKO7tV51nDbHJq isCUtsr9WpLpz1Dlqek8irtnnUxvMDGlwhyKWkglcSUpoCQCX3HAzBeXyQE3ZLDdyVgW /H7Ls31PwFpUmKEXznI950VZ2iciMvxeHq+H+38UgI0rjPPnSw0eS5T8L99NZo0zTs/1 2irFbHK1vYDUs2rwzyDsqne3hOXPAzmU+Ko4/4OsXCOgv5nlrMOJZkw0HogFzY07GJcU okcA== X-Gm-Message-State: AOAM531lEcD3/hYOCFR8bYXwipkOpvCg06vCGbx/nPyNTe8KmHJrRLit UHoz+1Y+yXkv5kQpTlFdTDAtG1OCzm5pgBlL X-Google-Smtp-Source: ABdhPJxim7dzilHY/aBlpeWqGXwKtRtgJEUPj4lm/UAvJUStMTmJjPAbshFJ/EXYqAw/a1iQt999cw== X-Received: by 2002:a62:170a:0:b029:1ed:cc98:35aa with SMTP id 10-20020a62170a0000b02901edcc9835aamr4026123pfx.77.1614705641361; Tue, 02 Mar 2021 09:20: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 b15sm20073923pgg.85.2021.03.02.09.20.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:40 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 07/15] bpf: Document BPF_PROG_QUERY syscall command Date: Tue, 2 Mar 2021 09:19:39 -0800 Message-Id: <20210302171947.2268128-8-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer Acked-by: Yonghong Song --- 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 a6cd6650e23d..0cf92ef011f1 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -389,6 +389,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 Tue Mar 2 17:19:40 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112767 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 6ECBFC43331 for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4216364E75 for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352520AbhCCDum (ORCPT ); Tue, 2 Mar 2021 22:50:42 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51224 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1344085AbhCBRlc (ORCPT ); Tue, 2 Mar 2021 12:41:32 -0500 Received: from mail-pf1-x42d.google.com (mail-pf1-x42d.google.com [IPv6:2607:f8b0:4864:20::42d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9EC9FC0698C4 for ; Tue, 2 Mar 2021 09:20:43 -0800 (PST) Received: by mail-pf1-x42d.google.com with SMTP id j12so14221227pfj.12 for ; Tue, 02 Mar 2021 09:20:43 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=AThU4ci48FKxy/EX8TQpAEHDA9i5ZmNT/rLJMEkkHrM=; b=TRm4JPuM3dS20NhEZWk7JIzebqcxaxAjsqGFS5zL6ZusSg7H37Xa9iJXZUODP5okvA 6EmC7Quu6NbpvlZkJaKrXaJ6/2CjePLiQ0qMKsn8zWq3Q8tJHswz6F27RSKKdXbkzzTO Ep4Y7DkVGYZMmgeSu0Td4gmz0LOW47iLVUEjQm+k1Gc/T9Copy63Uypd9NGe+yRaM/bp In/0+dZQluaotcyb3QizHyPqAxNGb7zCYx+BpVIxaU60BL2Ti1HzaiAHeXbrgZAIjScu 4NhIu9uS709nR1F2IUkI3AJd75vakacFjFq9BXXSDE7PjlXLBe4WynJBe6jgxcKZcee4 FW1Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=AThU4ci48FKxy/EX8TQpAEHDA9i5ZmNT/rLJMEkkHrM=; b=thxMLvAzzVF5S5AHmHbORt4OfGBaOP/0505batR3jjzvLjsrPugB8x6i0c8c9d/Rof HjViJXcWC0YQFEk4XamRqLeKkUJGCYUQgXafx0gVFw16KVbqQQ5BKhRjsPIXnuBN6/X8 5XLBm1jaurcZEBVw/00jOqe1bz1ZXh2sUyzyDnPZiblufetq+Ai0ohniMmwgxJNWC0Ha 8Osz1Q3sB4HqFHqPyW4B6lr6E5nyjbvwCjnAzUpGmIJMcSJ4jzOK/VYf2jLaezCa8K0q YJQrJA4+6ikGyyLBQLw7vOE6CZ01LZOdxLT3c0ihexD9Qup8i+jj/LM9lkbNueTWnBO2 ktCQ== X-Gm-Message-State: AOAM531+Ibwh9wJVZvRMRNqO7lHp38wSEpAL8UYmo+RQw9yFIoV/J8I/ fBLj/m070xYS2Sbds8qvGG7mwe/vEZDLjpPv X-Google-Smtp-Source: ABdhPJzzVSbAzyjYnnbzdMLtBDQGJaOL0r5I5Nr5cA2wEk7ykjzOznxcSdJydzJkbN2d2iEG3ly2ng== X-Received: by 2002:a62:4e92:0:b029:1ee:251d:50a1 with SMTP id c140-20020a624e920000b02901ee251d50a1mr4010269pfb.53.1614705642736; Tue, 02 Mar 2021 09:20:42 -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 b15sm20073923pgg.85.2021.03.02.09.20.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:42 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet , Brian Vazquez , Yonghong Song Subject: [PATCHv2 bpf-next 08/15] bpf: Document BPF_MAP_*_BATCH syscall commands Date: Tue, 2 Mar 2021 09:19:40 -0800 Message-Id: <20210302171947.2268128-9-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Based roughly on the following commits: * Commit cb4d03ab499d ("bpf: Add generic support for lookup batch op") * Commit 057996380a42 ("bpf: Add batch ops to all htab bpf map") * Commit aa2e93b8e58e ("bpf: Add generic support for update and delete batch ops") Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer Acked-by: Brian Vazquez Acked-by: Yonghong Song --- CC: Brian Vazquez CC: Yonghong Song --- include/uapi/linux/bpf.h | 114 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 111 insertions(+), 3 deletions(-) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 0cf92ef011f1..c8b9d19fce22 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -553,13 +553,55 @@ union bpf_iter_link_info { * Description * Iterate and fetch multiple elements in a map. * + * Two opaque values are used to manage batch operations, + * *in_batch* and *out_batch*. Initially, *in_batch* must be set + * to NULL to begin the batched operation. After each subsequent + * **BPF_MAP_LOOKUP_BATCH**, the caller should pass the resultant + * *out_batch* as the *in_batch* for the next operation to + * continue iteration from the current point. + * + * The *keys* and *values* are output parameters which must point + * to memory large enough to hold *count* items based on the key + * and value size of the map *map_fd*. The *keys* buffer must be + * of *key_size* * *count*. The *values* buffer must be of + * *value_size* * *count*. + * + * The *elem_flags* argument may be specified as one of the + * following: + * + * **BPF_F_LOCK** + * Look up the value of a spin-locked map without + * returning the lock. This must be specified if the + * elements contain a spinlock. + * + * On success, *count* elements from the map are copied into the + * user buffer, with the keys copied into *keys* and the values + * copied into the corresponding indices in *values*. + * + * If an error is returned and *errno* is not **EFAULT**, *count* + * is set to the number of successfully processed elements. + * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. * + * May set *errno* to **ENOSPC** to indicate that *keys* or + * *values* is too small to dump an entire bucket during + * iteration of a hash-based map type. + * * BPF_MAP_LOOKUP_AND_DELETE_BATCH * Description - * Iterate and delete multiple elements in a map. + * Iterate and delete all elements in a map. + * + * This operation has the same behavior as + * **BPF_MAP_LOOKUP_BATCH** with two exceptions: + * + * * Every element that is successfully returned is also deleted + * from the map. This is at least *count* elements. Note that + * *count* is both an input and an output parameter. + * * Upon returning with *errno* set to **EFAULT**, up to + * *count* elements may be deleted without returning the keys + * and values of the deleted elements. * * Return * Returns zero on success. On error, -1 is returned and *errno* @@ -567,15 +609,81 @@ union bpf_iter_link_info { * * BPF_MAP_UPDATE_BATCH * Description - * Iterate and update multiple elements in a map. + * Update multiple elements in a map by *key*. + * + * The *keys* and *values* are input parameters which must point + * to memory large enough to hold *count* items based on the key + * and value size of the map *map_fd*. The *keys* buffer must be + * of *key_size* * *count*. The *values* buffer must be of + * *value_size* * *count*. + * + * Each element specified in *keys* is sequentially updated to the + * value in the corresponding index in *values*. The *in_batch* + * and *out_batch* parameters are ignored and should be zeroed. + * + * The *elem_flags* argument should be specified as one of the + * following: + * + * **BPF_ANY** + * Create new elements or update a existing elements. + * **BPF_NOEXIST** + * Create new elements only if they do not exist. + * **BPF_EXIST** + * Update existing elements. + * **BPF_F_LOCK** + * Update spin_lock-ed map elements. This must be + * specified if the map value contains a spinlock. + * + * On success, *count* elements from the map are updated. + * + * If an error is returned and *errno* is not **EFAULT**, *count* + * is set to the number of successfully processed elements. * * Return * Returns zero on success. On error, -1 is returned and *errno* * is set appropriately. * + * May set *errno* to **EINVAL**, **EPERM**, **ENOMEM**, or + * **E2BIG**. **E2BIG** indicates that the number of elements in + * the map reached the *max_entries* limit specified at map + * creation time. + * + * May set *errno* to one of the following error codes under + * specific circumstances: + * + * **EEXIST** + * If *flags* specifies **BPF_NOEXIST** and the element + * with *key* already exists in the map. + * **ENOENT** + * If *flags* specifies **BPF_EXIST** and the element with + * *key* does not exist in the map. + * * BPF_MAP_DELETE_BATCH * Description - * Iterate and delete multiple elements in a map. + * Delete multiple elements in a map by *key*. + * + * The *keys* parameter is an input parameter which must point + * to memory large enough to hold *count* items based on the key + * size of the map *map_fd*, that is, *key_size* * *count*. + * + * Each element specified in *keys* is sequentially deleted. The + * *in_batch*, *out_batch*, and *values* parameters are ignored + * and should be zeroed. + * + * The *elem_flags* argument may be specified as one of the + * following: + * + * **BPF_F_LOCK** + * Look up the value of a spin-locked map without + * returning the lock. This must be specified if the + * elements contain a spinlock. + * + * On success, *count* elements from the map are updated. + * + * If an error is returned and *errno* is not **EFAULT**, *count* + * is set to the number of successfully processed elements. If + * *errno* is **EFAULT**, up to *count* elements may be been + * deleted. * * Return * Returns zero on success. On error, -1 is returned and *errno* From patchwork Tue Mar 2 17:19:41 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112769 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id B6C39C43333 for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 8944564E75 for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352523AbhCCDuo (ORCPT ); Tue, 2 Mar 2021 22:50:44 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50656 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1344082AbhCBRlc (ORCPT ); Tue, 2 Mar 2021 12:41:32 -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 C7B67C0698C7 for ; Tue, 2 Mar 2021 09:20:44 -0800 (PST) Received: by mail-pj1-x1036.google.com with SMTP id e9so2474351pjj.0 for ; Tue, 02 Mar 2021 09:20:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=fRChbTS8wm3//f2BALQqTT/xFw+Hx0cBe+aJeD7Uh84=; b=qXgIqqi4ObJ6UdZYB5w747BTk9f9amHZx1zbj15a59wo3j1hcw5u6sHcTuAHT7onMU BVZhfAmy/WK0q4aWiIfTI0e2WJP0ljZ8OXEi94p851QdY9+kjbHFzIkPJzYc3N6H9HpC QA6az0JLL/E1Uz4uXm4IWqA+fpAXqH7/bqtqVXbqsu7s+03/evhsa8YrntRGCoEFaVrf pk+0N1LYEdjDe1Wsc61K+L9khdbNArLuIPw9DFHfl6jaC+FiU1kIOEWmHWBCIc3f0w6W cvgObljR+dTW9RFKKxXL8P0NZfTYviXe/ONvH8RXfRzCgVvQ+HaKR6S60RFkF1Pgct+o kKRQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=fRChbTS8wm3//f2BALQqTT/xFw+Hx0cBe+aJeD7Uh84=; b=s9HZZKlMWR5VCYGgmXKlgkMVka7/blBPtWYe9gMKDbKVW9jj5j9LhmBBp5jeGAM+UE P7AbU/zx5ynkR0qWCHddv5T2onMdMOFRWAKTwV3G88c4RktzuEiT+ZYiOyv7ND1M5G6l Uozl2DsZLseLKxy8zgpjUtqgAjtwhDiXfJoQRtcv6B+9MR72kmKK4XgOcRjF5wdDo+cL xPeJS/KZmFezHtfWO1LrGLGZWOpWydj66mltlHlTWLESL9yePnWH1WLz53A1sLXhTNRG jLMJqlfrBUYXEtn8fj6/pM+i877atm/32Jn+JXRpdXGeuckjpZj6wV33xXxNpUKNvXeI 8EsA== X-Gm-Message-State: AOAM533RCliiJ7ogLVnv9iT6fOmB2K1cMkJphpizv/ZYRwMgt/KXUU98 ugqlpkJrua+OLAO6Dn3yDfD4TilivwCwxCUa X-Google-Smtp-Source: ABdhPJy+RrBwQTGcQzFWXHdEQ7YNuC9XacWs/v2BYwcrWyiLn3qvoyC6OROFYlLSPxV0G/BLWTnZNA== X-Received: by 2002:a17:90a:39c9:: with SMTP id k9mr5395908pjf.121.1614705643910; Tue, 02 Mar 2021 09:20: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 b15sm20073923pgg.85.2021.03.02.09.20.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:43 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 09/15] scripts/bpf: Abstract eBPF API target parameter Date: Tue, 2 Mar 2021 09:19:41 -0800 Message-Id: <20210302171947.2268128-10-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- MAINTAINERS | 1 + include/uapi/linux/bpf.h | 2 +- scripts/{bpf_helpers_doc.py => bpf_doc.py} | 91 +++++++++++++++------- tools/bpf/Makefile.helpers | 2 +- tools/include/uapi/linux/bpf.h | 2 +- tools/lib/bpf/Makefile | 2 +- tools/perf/MANIFEST | 2 +- 7 files changed, 69 insertions(+), 33 deletions(-) rename scripts/{bpf_helpers_doc.py => bpf_doc.py} (92%) diff --git a/MAINTAINERS b/MAINTAINERS index a50a543e3c81..8d56c7044067 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3223,6 +3223,7 @@ F: net/core/filter.c F: net/sched/act_bpf.c F: net/sched/cls_bpf.c F: samples/bpf/ +F: scripts/bpf_doc.py F: tools/bpf/ F: tools/lib/bpf/ F: tools/testing/selftests/bpf/ diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index c8b9d19fce22..63a56ed6a785 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -1439,7 +1439,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 92% rename from scripts/bpf_helpers_doc.py rename to scripts/bpf_doc.py index 867ada23281c..5a4f68aab335 100755 --- a/scripts/bpf_helpers_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. .. @@ -221,9 +227,39 @@ 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). +''' + 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', @@ -511,7 +540,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 */''' @@ -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() 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 b89af20cfa19..b4c5c529ad17 100644 --- a/tools/include/uapi/linux/bpf.h +++ b/tools/include/uapi/linux/bpf.h @@ -729,7 +729,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 Tue Mar 2 17:19:42 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112759 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1672AC4332D for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id D82F364E75 for ; Wed, 3 Mar 2021 03:56:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352519AbhCCDul (ORCPT ); Tue, 2 Mar 2021 22:50:41 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51236 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1344097AbhCBRlc (ORCPT ); Tue, 2 Mar 2021 12:41:32 -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 07D1AC0698CA for ; Tue, 2 Mar 2021 09:20:46 -0800 (PST) Received: by mail-pf1-x429.google.com with SMTP id m6so14265343pfk.1 for ; Tue, 02 Mar 2021 09:20:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=y+YcpUVr7LDyGFtvHmMjDnyPsDr68hKJkv6AGVIRT3Y=; b=Rp5v5A14/uC75JpS8WLyl2oXZSjMYyIQFkEiPl4ZINMcxDxI348/xLTD6m0jtWk9Ec aleRvpbPKXhFyYT46yDQ4MPmlN49N3q96FOHck48avTz8LMfy/eqQg+UBMQquFr57H5p HwVlvfbD1+hdrjHyQ/WRM2790r9Jt9H25V5j3aGi55ZhyMU1tAU9iT10Bw5TzzBl8kr9 ZWkKme6tjLL6BqsfL2m0a9Z0qYhnaHArgqhsj5n1SRGiyJgnA3Pe/quB+KFLrPlcq7ng KsA4vcxLGPd/DS8PD727FS+xr8DkzQ0/LO4fpEj2GDqqbvo9LzKVPCxHJGYKNge+H5+i rH4A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=y+YcpUVr7LDyGFtvHmMjDnyPsDr68hKJkv6AGVIRT3Y=; b=EL1bJnjwl3x/WEwbiFSTGvNjOYuAY50vs1swwERDqWhoYCjpbTiOT9SBWsy8l0Cgdm jt+x6ivr2UkuAbjKpiaImpTNTDYp3SbYB0iAK9CIWQvpqfRFcpGnR0I5bvNJWyWs++WF e86gMdXA3Ji8CbJmXFq8GzhlsH13IYL6MLXkyGcbumKTiDSQgeAKmPaLzR1W4jFlVTtb 1C1vkJ3MdVztKHirys3q5EHlaUVUVfL9m7xa9vNt9lbtWkEh80qMp7v5pY7X4qIYq7MA OAS83e0UV0F6ZvSZyxS6t+I14R93boOxO2ujUnx5RDEXFo09ldB8OwoP3loAsD6qbHos vSEQ== X-Gm-Message-State: AOAM532oQIHSJqt3NBmhbuIwnk2OK2V/WYq25T1Wsp1dOzwPGy4oDjH9 nA+nMDUH5WeJBbzuMuMd07VSZnxLMacUDYKQ X-Google-Smtp-Source: ABdhPJzRmXxKE3NeYoNTv2Wb6UuOiXhbHE0sPmPP7v+b1QA2sVKS8vNLK86MDTp8LsIIIAsqUyq8fQ== X-Received: by 2002:a05:6a00:148a:b029:1ae:6d20:fbb3 with SMTP id v10-20020a056a00148ab02901ae6d20fbb3mr4055694pfu.55.1614705645090; Tue, 02 Mar 2021 09:20:45 -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 b15sm20073923pgg.85.2021.03.02.09.20.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:44 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 10/15] scripts/bpf: Add syscall commands printer Date: Tue, 2 Mar 2021 09:19:42 -0800 Message-Id: <20210302171947.2268128-11-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- scripts/bpf_doc.py | 100 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 91 insertions(+), 9 deletions(-) diff --git a/scripts/bpf_doc.py b/scripts/bpf_doc.py index 5a4f68aab335..2d94025b38e9 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('* DOC: eBPF 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=""" @@ -644,6 +724,8 @@ headerParser.run() # Print formatted output to standard output. if args.header: + if args.target != 'helpers': + raise NotImplementedError('Only helpers header generation is supported') printer = PrinterHelpers(headerParser) else: printer = printers[args.target](headerParser) From patchwork Tue Mar 2 17:19:43 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112771 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.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 92660C4361B for ; Wed, 3 Mar 2021 03:56:17 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 67BB564E6F for ; Wed, 3 Mar 2021 03:56:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352537AbhCCDvD (ORCPT ); Tue, 2 Mar 2021 22:51:03 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42454 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1346410AbhCBTLX (ORCPT ); Tue, 2 Mar 2021 14:11:23 -0500 Received: from mail-pg1-x52b.google.com (mail-pg1-x52b.google.com [IPv6:2607:f8b0:4864:20::52b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1EF67C0698CD for ; Tue, 2 Mar 2021 09:20:47 -0800 (PST) Received: by mail-pg1-x52b.google.com with SMTP id e6so14260959pgk.5 for ; Tue, 02 Mar 2021 09:20:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=hu2fl/gdmtemcdYzHoBNdDwL+TolrGxintCby5qolro=; b=gUeXZS2tsNTXS18Z4VONyksNUoioo/xd+y0QiZIsR+hxzg2BxZmWY/v7YFh3MicoyF Fcqm8KlHlNsXyIns2a0V9XbeqGHNqfAv/W++vmNiX9pfZM2W6JslFu/MQf823Y40U+AX xNfh0wj7eTi2NxM+BFt37IssX7tV0gE4zYELLAijxoewKKLulYTDpSLosnfHOkO2Pe2m WHIaJSecBWQJqWGG5sq29pl+t8gaUsOwUTrKKoVxoRaQZ2BIHBkBaTfxoGsJT3bsUXgi iYBwcfsN4k4nrNeAmodfhSHVCOXooHe+4w23bmUblDg7kD67WLx0wld/EezzdsvanNHk ZlBg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=hu2fl/gdmtemcdYzHoBNdDwL+TolrGxintCby5qolro=; b=kd2ZeVVBqlib1AFhRCBPB6D6XgEd3zKbPauaFESEoLfCXQcsl1L+gbPi/kN9QZQsbr pbRr7acKKeYq3Kbk4IDPsm/KgsagUvmYhYjMEUjfbmUF3xUG+RYjw4wVFx72W5rQiKjj aJ7li5WVgpw2bNQadYugx8JLBLc+rM4UenA753OozcnPP8BgWpfH0M2cwPm67QVStpC7 4zckBWO5hIpICVU8MaMcSf+nz87+2Il9OkFpojMh0QJL9RPr5h9tB0Zu1caUss6MHZve +aWerY9BsiRkCJJx9KzcfH1yHeORKBVT+ey7CeSeBOztlXPPq9Pn6BiNCP6Rt+wfCfbl Z9Bg== X-Gm-Message-State: AOAM530lh0ZF4PTgGAU4Hsr8+8KoJGfako/MgEu3yAQ6SIP5FKybE5ge gzTkU00CrkXsW7IqJi1o8GZsCnyr9JyQm+0f X-Google-Smtp-Source: ABdhPJzBegCXpYGBPuhfMSwsZrbAutCvoiFoc06DUlOYmxG7LD63nqFLBzLNBKT72gRfSqvMLazo0g== X-Received: by 2002:a62:ea19:0:b029:1ee:5911:c516 with SMTP id t25-20020a62ea190000b02901ee5911c516mr4070769pfh.67.1614705646358; Tue, 02 Mar 2021 09:20:46 -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 b15sm20073923pgg.85.2021.03.02.09.20.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:45 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 11/15] tools/bpf: Remove bpf-helpers from bpftool docs Date: Tue, 2 Mar 2021 09:19:43 -0800 Message-Id: <20210302171947.2268128-12-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net This logic is used for validating the manual pages from selftests, so move the infra under tools/testing/selftests/bpf/ and rely on selftests for validation rather than tying it into the bpftool build. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- tools/bpf/bpftool/.gitignore | 1 - tools/bpf/bpftool/Documentation/Makefile | 11 +++---- tools/testing/selftests/bpf/.gitignore | 1 + tools/testing/selftests/bpf/Makefile | 20 +++++++++--- .../selftests/bpf/Makefile.docs} | 32 ++++++++++--------- .../selftests/bpf/test_bpftool_build.sh | 21 ------------ tools/testing/selftests/bpf/test_doc_build.sh | 13 ++++++++ 7 files changed, 50 insertions(+), 49 deletions(-) rename tools/{bpf/Makefile.helpers => testing/selftests/bpf/Makefile.docs} (64%) create mode 100755 tools/testing/selftests/bpf/test_doc_build.sh diff --git a/tools/bpf/bpftool/.gitignore b/tools/bpf/bpftool/.gitignore index 944cb4b7c95d..05ce4446b780 100644 --- a/tools/bpf/bpftool/.gitignore +++ b/tools/bpf/bpftool/.gitignore @@ -3,7 +3,6 @@ /bootstrap/ /bpftool bpftool*.8 -bpf-helpers.* FEATURE-DUMP.bpftool feature libbpf diff --git a/tools/bpf/bpftool/Documentation/Makefile b/tools/bpf/bpftool/Documentation/Makefile index f33cb02de95c..c49487905ceb 100644 --- a/tools/bpf/bpftool/Documentation/Makefile +++ b/tools/bpf/bpftool/Documentation/Makefile @@ -16,15 +16,12 @@ prefix ?= /usr/local mandir ?= $(prefix)/man man8dir = $(mandir)/man8 -# Load targets for building eBPF helpers man page. -include ../../Makefile.helpers - MAN8_RST = $(wildcard bpftool*.rst) _DOC_MAN8 = $(patsubst %.rst,%.8,$(MAN8_RST)) DOC_MAN8 = $(addprefix $(OUTPUT),$(_DOC_MAN8)) -man: man8 helpers +man: man8 man8: $(DOC_MAN8) RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null) @@ -46,16 +43,16 @@ ifndef RST2MAN_DEP endif $(QUIET_GEN)( cat $< ; printf "%b" $(call see_also,$<) ) | rst2man $(RST2MAN_OPTS) > $@ -clean: helpers-clean +clean: $(call QUIET_CLEAN, Documentation) $(Q)$(RM) $(DOC_MAN8) -install: man helpers-install +install: man $(call QUIET_INSTALL, Documentation-man) $(Q)$(INSTALL) -d -m 755 $(DESTDIR)$(man8dir) $(Q)$(INSTALL) -m 644 $(DOC_MAN8) $(DESTDIR)$(man8dir) -uninstall: helpers-uninstall +uninstall: $(call QUIET_UNINST, Documentation-man) $(Q)$(RM) $(addprefix $(DESTDIR)$(man8dir)/,$(_DOC_MAN8)) $(Q)$(RMDIR) $(DESTDIR)$(man8dir) diff --git a/tools/testing/selftests/bpf/.gitignore b/tools/testing/selftests/bpf/.gitignore index c0c48fdb9ac1..a0d5ec3cfc24 100644 --- a/tools/testing/selftests/bpf/.gitignore +++ b/tools/testing/selftests/bpf/.gitignore @@ -1,4 +1,5 @@ # SPDX-License-Identifier: GPL-2.0-only +bpf-helpers* test_verifier test_maps test_lru_map diff --git a/tools/testing/selftests/bpf/Makefile b/tools/testing/selftests/bpf/Makefile index a81af15e4ded..b5827464c6b5 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) \ + -f Makefile.docs \ + prefix= OUTPUT=$(OUTPUT)/ DESTDIR=$(OUTPUT)/ $@ + +docs-clean: + $(Q)$(MAKE) $(submake_extras) \ + -f Makefile.docs \ + prefix= OUTPUT=$(OUTPUT)/ DESTDIR=$(OUTPUT)/ $@ $(BPFOBJ): $(wildcard $(BPFDIR)/*.[ch] $(BPFDIR)/Makefile) \ ../../../include/uapi/linux/bpf.h \ @@ -477,3 +485,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/bpf/Makefile.helpers b/tools/testing/selftests/bpf/Makefile.docs similarity index 64% rename from tools/bpf/Makefile.helpers rename to tools/testing/selftests/bpf/Makefile.docs index a26599022fd6..546c4a763b46 100644 --- a/tools/bpf/Makefile.helpers +++ b/tools/testing/selftests/bpf/Makefile.docs @@ -1,13 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only -ifndef allow-override - include ../scripts/Makefile.include - include ../scripts/utilities.mak -else - # Assume Makefile.helpers is being run from bpftool/Documentation - # subdirectory. Go up two more directories to fetch bpf.h header and - # associated script. - UP2DIR := ../../ -endif + +include ../../../scripts/Makefile.include +include ../../../scripts/utilities.mak INSTALL ?= install RM ?= rm -f @@ -29,13 +23,21 @@ 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: ../../../../include/uapi/linux/bpf.h + $$(QUIET_GEN)../../../../scripts/bpf_doc.py $1 \ + --filename $$< > $$@ $(OUTPUT)%.7: $(OUTPUT)%.rst ifndef RST2MAN_DEP @@ -43,18 +45,18 @@ ifndef RST2MAN_DEP endif $(QUIET_GEN)rst2man $< > $@ -helpers-clean: +docs-clean: $(call QUIET_CLEAN, eBPF_helpers-manpage) $(Q)$(RM) $(DOC_MAN7) $(OUTPUT)$(HELPERS_RST) -helpers-install: helpers +docs-install: helpers $(call QUIET_INSTALL, eBPF_helpers-manpage) $(Q)$(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) $(Q)$(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir) -helpers-uninstall: +docs-uninstall: $(call QUIET_UNINST, eBPF_helpers-manpage) $(Q)$(RM) $(addprefix $(DESTDIR)$(man7dir)/,$(_DOC_MAN7)) $(Q)$(RMDIR) $(DESTDIR)$(man7dir) -.PHONY: helpers helpers-clean helpers-install helpers-uninstall +.PHONY: docs docs-clean docs-install docs-uninstall 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 Tue Mar 2 17:19:44 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112763 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.7 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 E1240C43332 for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id AFFDD64E6F for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352526AbhCCDur (ORCPT ); Tue, 2 Mar 2021 22:50:47 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51322 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1344241AbhCBRlq (ORCPT ); Tue, 2 Mar 2021 12:41:46 -0500 Received: from mail-pg1-x52b.google.com (mail-pg1-x52b.google.com [IPv6:2607:f8b0:4864:20::52b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 40B07C0698D0 for ; Tue, 2 Mar 2021 09:20:48 -0800 (PST) Received: by mail-pg1-x52b.google.com with SMTP id l2so14290211pgb.1 for ; Tue, 02 Mar 2021 09:20:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=rmdTY77liaK5SCzblCmMtRzezZEYkkZ3aYrvDg9Bb+E=; b=p9hHu6afCZiTeY1E2o7wqOBNpd4yP9RN7pqA9fb8WlkZPV30o1OCEflhsc5apRPWv4 iMPtN5VkEsGOdttYFE5L+1Yt2IF4l15BtvKhXHmM/AOAtIepywDnEoFZH99Hkdxze+IO x7Vzhvw0CeSQhBlu3znvB4qUMuvygCNfjHUhwlSC7/bub5rtE24XV9muUvlWYk5MIwCj F0dwgDhTkY4tkWXKxYgGKpa7z17B9yC2O/h2UwS53Unuw6oh2FOe5uyyR9hzRI3nS3Mu 4Y7I609pruhVIOhhWGR9iEwcX293Uxuf6Q40VU/LQcymk7P0zlT+PeClA05jA5PR+K1V 2/ow== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=rmdTY77liaK5SCzblCmMtRzezZEYkkZ3aYrvDg9Bb+E=; b=lCmyui4ldWiQYFQXazwKtCwUSEyitVP0Rqz2CB6fhatbo18IDQ6o7enVFI2d1zA0KB nk58MBKIsQWrYiDRtiP/juVvQeQbPD1jclhTjC+ZrV9r4UuNe8Cyx7KtSLXfVVeQJag6 jre/htl/rZ2ALx1P4UKu/lykmK/8B1UY2EaCUxewAGLMMmq8W3RtDrZp3DvFk2mMClaX yerde8AetQXKLqxhQobiQuJCjMme2i+/CBjp/NW4o5fIGXxgXa8D12GPo44+hgsghiI/ MRveK4vnKN4o430CXgMn/3XQ3ndYiQnfweq+EAg9MwITJS1sdIS9PndDsDRELcUbrg27 4mvg== X-Gm-Message-State: AOAM531LlTADmyoVBdbhslrzoZXMKSYsXSBaVE6qCmhd5HU37eyV33DD xOjTtpg1MhZKRaDOV5DWX3xdohet4qJ97r8m X-Google-Smtp-Source: ABdhPJxzMU6Z6i/uOCRFlao8nR5bI1iSGEHnPO+VSAqFodLOhv1U+lT+DkshsxXusKr2knhcrf6mpA== X-Received: by 2002:a63:cc05:: with SMTP id x5mr18634644pgf.254.1614705647537; Tue, 02 Mar 2021 09:20:47 -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 b15sm20073923pgg.85.2021.03.02.09.20.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:47 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 12/15] selftests/bpf: Templatize man page generation Date: Tue, 2 Mar 2021 09:19:44 -0800 Message-Id: <20210302171947.2268128-13-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- tools/testing/selftests/bpf/Makefile.docs | 40 ++++++++++++++--------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/tools/testing/selftests/bpf/Makefile.docs b/tools/testing/selftests/bpf/Makefile.docs index 546c4a763b46..f39ad19317c8 100644 --- a/tools/testing/selftests/bpf/Makefile.docs +++ b/tools/testing/selftests/bpf/Makefile.docs @@ -39,24 +39,34 @@ $(OUTPUT)bpf-$1.rst: ../../../../include/uapi/linux/bpf.h $$(QUIET_GEN)../../../../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: - $(call QUIET_CLEAN, eBPF_helpers-manpage) - $(Q)$(RM) $(DOC_MAN7) $(OUTPUT)$(HELPERS_RST) +docs-clean-$1: + $$(call QUIET_CLEAN, eBPF_$1-manpage) + $(Q)$(RM) $$(DOC_MAN$2) $(OUTPUT)bpf-$1.rst -docs-install: helpers - $(call QUIET_INSTALL, eBPF_helpers-manpage) - $(Q)$(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) - $(Q)$(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir) +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: - $(call QUIET_UNINST, eBPF_helpers-manpage) - $(Q)$(RM) $(addprefix $(DESTDIR)$(man7dir)/,$(_DOC_MAN7)) - $(Q)$(RMDIR) $(DESTDIR)$(man7dir) +docs-uninstall-$1: + $$(call QUIET_UNINST, eBPF_$1-manpage) + $(Q)$(RM) $$(addprefix $(DESTDIR)$$(man$2dir)/,$$(_DOC_MAN$2)) + $(Q)$(RMDIR) $(DESTDIR)$$(man$2dir) -.PHONY: docs docs-clean docs-install docs-uninstall +.PHONY: $1 docs-clean-$1 docs-install-$1 docs-uninstall-$1 +endef + +# Create the make targets to generate manual pages by name and section +$(eval $(call DOCS_RULES,helpers,7)) + +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 From patchwork Tue Mar 2 17:19:45 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112765 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 1B35AC432C3 for ; Wed, 3 Mar 2021 03:56:14 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id DA37C64E75 for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236290AbhCCDus (ORCPT ); Tue, 2 Mar 2021 22:50:48 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51330 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1344228AbhCBRlq (ORCPT ); Tue, 2 Mar 2021 12:41:46 -0500 Received: from mail-pf1-x435.google.com (mail-pf1-x435.google.com [IPv6:2607:f8b0:4864:20::435]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 660A5C0698D3 for ; Tue, 2 Mar 2021 09:20:49 -0800 (PST) Received: by mail-pf1-x435.google.com with SMTP id q204so13193904pfq.10 for ; Tue, 02 Mar 2021 09:20:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=sdfyObE0E1JspOvROEYz/USdJ0MsLAvmGmtxjKiuziw=; b=hX1Bi349HGCRg4XxhEuiHPv8IhO8nCMLe1NF8WCH6A8WDN//ph/h8lvaH5r2lczDV1 wrB0kZ8auZwVQ++e7AnrEtrDanbuws/DC5Namddhl3/vNLA8kGdngV51GGXhpZV1xade TZHIOt6Agm3XH6WZL1D2jgzJRHFQgj6lzRyCmk+k7+FRzXF2j1SyAnxREGC2vfgVjdwt /o6FcUOFQigEC9sLMr9LX8X3mUyiIJM0BhlCghAY1B24xST7eaMJ1m84cV3lH3les6Rf iaiokLMplzD2gO1jSgVAxEPR7CMzIv0B7+wYO2hZpo1g9G62jJjOdh0engpN8omOwBZu yS3A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=sdfyObE0E1JspOvROEYz/USdJ0MsLAvmGmtxjKiuziw=; b=GChdgHXQMm6Rc8BsY+uu2nX3xN6KxI5smIeDI80rSJK3JCF3MJ6uxLR/RYE2Cpk6HU QzLQH1Cy54YbO1a3TeqV4Lohak2O1ZVDVI/9wkxQm9ic88S1OUlR67ObmKNZEYWTsENq Xe1LpVMqqnAJZyYQEMxdPmEMpYkBzjjBHAi7iOhyJd5o4FwLTE8Rmt6j+pS3ZHeDICfo p6vGeZ0CwKaNguPm2JV0f1KZnXEuhiUk4iyyrEeaJulWNvFZp5TfO6UCpF7OOuUH/juJ FoMCY8qkj5hIx89wwmVJB93Sx2vB3lLGEYBLzNfu9Ro1RCV4Z15E3oJf7XT45Etmb8BS O05w== X-Gm-Message-State: AOAM533rzgk0yq2VnZPV17ZgMO7b//hYSd/ntI9fAyOgcd5MFmhCBxgi 31oOAc9DGYhKMsrvfCmwnYc/khD+V+hwEwo4 X-Google-Smtp-Source: ABdhPJxu2ccLPZxQduQGZaDo7/+I565sDXZiuNJfYVTL+2FXqWypan6o8vAXbJYeQe0VhYMkd+Z72Q== X-Received: by 2002:a62:6304:0:b029:1c0:d62d:d213 with SMTP id x4-20020a6263040000b02901c0d62dd213mr4045441pfb.79.1614705648725; Tue, 02 Mar 2021 09:20:48 -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 b15sm20073923pgg.85.2021.03.02.09.20.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:48 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 13/15] selftests/bpf: Test syscall command parsing Date: Tue, 2 Mar 2021 09:19:45 -0800 Message-Id: <20210302171947.2268128-14-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net 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. The generated manual pages here are not intended for distribution, they are just a fragment that can be integrated into the other static text of bpf(2) to form the full manual page. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer Acked-by: Yonghong Song --- tools/testing/selftests/bpf/.gitignore | 1 + tools/testing/selftests/bpf/Makefile.docs | 14 ++++++++++++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/tools/testing/selftests/bpf/.gitignore b/tools/testing/selftests/bpf/.gitignore index a0d5ec3cfc24..4866f6a21901 100644 --- a/tools/testing/selftests/bpf/.gitignore +++ b/tools/testing/selftests/bpf/.gitignore @@ -1,5 +1,6 @@ # SPDX-License-Identifier: GPL-2.0-only bpf-helpers* +bpf-syscall* test_verifier test_maps test_lru_map diff --git a/tools/testing/selftests/bpf/Makefile.docs b/tools/testing/selftests/bpf/Makefile.docs index f39ad19317c8..ccf260021e83 100644 --- a/tools/testing/selftests/bpf/Makefile.docs +++ b/tools/testing/selftests/bpf/Makefile.docs @@ -15,18 +15,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) @@ -64,9 +73,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 Tue Mar 2 17:19:46 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112761 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=-21.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 920E6C4332E for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6687664E6F for ; Wed, 3 Mar 2021 03:56:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352524AbhCCDup (ORCPT ); Tue, 2 Mar 2021 22:50:45 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51376 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1344269AbhCBRlq (ORCPT ); Tue, 2 Mar 2021 12:41:46 -0500 Received: from mail-pg1-x52f.google.com (mail-pg1-x52f.google.com [IPv6:2607:f8b0:4864:20::52f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7F8B0C0698D6 for ; Tue, 2 Mar 2021 09:20:50 -0800 (PST) Received: by mail-pg1-x52f.google.com with SMTP id e6so14261073pgk.5 for ; Tue, 02 Mar 2021 09:20:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=m3P34ZfaEcKP5uSP2XHxCLx/BufSt6qtkFAu5J+XEKw=; b=b7qqfY67saC70WwhUWdvFwLduwR5bjWQdVPqvMMQYOrNZsxV+HyNS9i4m6UrLQJnZl cosTd+ZEy7e3dJGM+OmHRmRnl9ZqgSrqAdHJq4yFZ5uN+1E5wNYHjEuPfPz4llqnh+qZ zFd4zhIj8JBjyciMDjYZLZ6egWzxG7GHVT7PXrRPf80rKzU4BjXc/+00vx1gGF8X9wZr XkpyhdSl+ojyoYM/ciS9OeFobiAsssbunCb80qBhoqweCNxUi4euAzQd0vC+BdmQpXD1 ac1UmBPtGkx2p5d4wbobyX4AeFGBYDlxib9vFXJNMqNCHRbEtyQWnYHj0V0wN2FHqd+C sjqQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=m3P34ZfaEcKP5uSP2XHxCLx/BufSt6qtkFAu5J+XEKw=; b=n0iIJ7Cn2o4WwfinPTLckEaCwTGl8Wfyu5B7tI3v4FWQL15swOx+u6reiuWq3akNff 3Zgo+rodrfOeWh8Wwo6qqRNCOeoe40m9LKa0hEXWMti1xGqPR6shevSq7h0outEmTN/p nnamU+wGIDAegRKMsZncl3jWKSRW7Hn7/NdnGv7f6jzlrAuGX4J3tOCVp4BYx7onA8r3 tMUCLvknPVBt7/o1Gd5cEmY62Jw0EZa3ans08r2REVhpVOdPC9jOmRWcT6fsD6K+Zz6e cX8zJzk34v/Xl53bjgGV/gGNCh+ZU4LvlroDMTuNdVW7TUuKsoAAeu/96LJhiqKVluIA En9Q== X-Gm-Message-State: AOAM5308H+TAE8tzb/wHC3kZKYcHD2mAt8/EjL1pAYUUTs2ofMFMjMcR EqPYoqNc55vHPMp44NI8rod1F5t5JNY0pJFB X-Google-Smtp-Source: ABdhPJznxMzff9wTxkL7798tBHvE1eRQ1e22bBhq0XiAPiSvYqzLyKWUt0lHw97Q3g3+PIX8vymIQA== X-Received: by 2002:a63:1906:: with SMTP id z6mr19365033pgl.292.1614705649881; Tue, 02 Mar 2021 09:20:49 -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 b15sm20073923pgg.85.2021.03.02.09.20.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:49 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 14/15] docs/bpf: Add bpf() syscall command reference Date: Tue, 2 Mar 2021 09:19:46 -0800 Message-Id: <20210302171947.2268128-15-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Generate the syscall command reference from the UAPI header file and include it in the main bpf docs page. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- CC: linux-doc@vger.kernel.org --- Documentation/bpf/index.rst | 9 +++++--- Documentation/userspace-api/ebpf/index.rst | 17 ++++++++++++++ Documentation/userspace-api/ebpf/syscall.rst | 24 ++++++++++++++++++++ Documentation/userspace-api/index.rst | 1 + MAINTAINERS | 1 + 5 files changed, 49 insertions(+), 3 deletions(-) create mode 100644 Documentation/userspace-api/ebpf/index.rst create mode 100644 Documentation/userspace-api/ebpf/syscall.rst diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 4f2874b729c3..a702f67dd45f 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,12 @@ 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)`_. For more information about the userspace API, see +Documentation/userspace-api/ebpf/index.rst. Helper functions ================ diff --git a/Documentation/userspace-api/ebpf/index.rst b/Documentation/userspace-api/ebpf/index.rst new file mode 100644 index 000000000000..473dfba78116 --- /dev/null +++ b/Documentation/userspace-api/ebpf/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +eBPF Userspace API +================== + +eBPF is a kernel mechanism to provide a sandboxed runtime environment in the +Linux kernel for runtime extension and instrumentation without changing kernel +source code or loading kernel modules. eBPF programs can be attached to various +kernel subsystems, including networking, tracing and Linux security modules +(LSM). + +For internal kernel documentation on eBPF, see Documentation/bpf/index.rst. + +.. toctree:: + :maxdepth: 1 + + syscall diff --git a/Documentation/userspace-api/ebpf/syscall.rst b/Documentation/userspace-api/ebpf/syscall.rst new file mode 100644 index 000000000000..ea9918084221 --- /dev/null +++ b/Documentation/userspace-api/ebpf/syscall.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +eBPF Syscall +------------ + +:Authors: - Alexei Starovoitov + - Joe Stringer + - Michael Kerrisk + +The primary info for the bpf syscall is available in the `man-pages`_ +for `bpf(2)`_. + +bpf() subcommand reference +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/uapi/linux/bpf.h + :doc: eBPF Syscall Preamble + +.. kernel-doc:: include/uapi/linux/bpf.h + :doc: eBPF Syscall Commands + +.. Links: +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index d29b020e5622..1e2438b7afa0 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -21,6 +21,7 @@ place where this information is gathered. unshare spec_ctrl accelerators/ocxl + ebpf/index ioctl/index iommu media/index diff --git a/MAINTAINERS b/MAINTAINERS index 8d56c7044067..4446d1455354 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3209,6 +3209,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf.git T: git git://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git F: Documentation/bpf/ F: Documentation/networking/filter.rst +F: Documentation/userspace-api/ebpf/ F: arch/*/net/* F: include/linux/bpf* F: include/linux/filter.h From patchwork Tue Mar 2 17:19:47 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 12112743 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 11C70C28CFA for ; Wed, 3 Mar 2021 03:55:38 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id D0D2264E12 for ; Wed, 3 Mar 2021 03:55:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352492AbhCCDuO (ORCPT ); Tue, 2 Mar 2021 22:50:14 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47956 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1442192AbhCBRaF (ORCPT ); Tue, 2 Mar 2021 12:30:05 -0500 Received: from mail-pg1-x531.google.com (mail-pg1-x531.google.com [IPv6:2607:f8b0:4864:20::531]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B9988C0698D9 for ; Tue, 2 Mar 2021 09:20:52 -0800 (PST) Received: by mail-pg1-x531.google.com with SMTP id b21so14264204pgk.7 for ; Tue, 02 Mar 2021 09:20:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cilium-io.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=HEQxkAWVxKfAhnJZEqVH83QU9d0JTcZxuFMIl7N/AWk=; b=Kcm5lzcKJmmme98WiusxCbYjda57EG7myXpjWuDqNYUHsKS668SAb5vml2TuG+lH1Y Hv8chdonvIFmuqr6ww+iaHC3wq2wIU8fIESUvrSrjNpulDwJubzutObvAT2EtMxaZ/Oa WxYhER3twyy3ZRIdQOcR6DnJd0VwV5wU45sbiyaH/wkc6ttc8nLHqk1bkyL8I1bp0ZCo 0oeaLxMbJDGLy0SKoPti80CfU9n6K39qxLGu9BzM05uRp8BI4NA/qEGm2lHPGdlNbnYE zJ2nhNj9XXI7WVP675TZJDgVyfXyvbQjJXxv8w3P2LKSVtv4zGI6LUM0DkvSlqb2l371 C0IQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=HEQxkAWVxKfAhnJZEqVH83QU9d0JTcZxuFMIl7N/AWk=; b=FfJ1EF6k3+JH4JcmTqqclzTKNpIed9AeflsC1sS/zaKLSCCbhlzg4mdThAgZhzFAdp mQcAoEKnhplrlDsdZRK6G4ODQ3OvLmvQfrCywUTwTLfPIMUT/mYKTTRCRCK6joC3I7IS qgnDjqefxpWas2Nzgd+w0w4TC0abC1wOA7qBBjOql8RanEo6PK+XEyY+ie68Z5P/2MmG mN+qJJowB34KpCwscM9m9/TJp1JDmpjoLtTWkuxCeg3umc3kKy50c+bKirOjNoIhNMIb CG1DIqhSgnhAP5qCtRz/4MWL6eq6eKDk+B6ZZHgenm3pAWQDgLzv3rS47XyV0mZ8YpQ8 OvLw== X-Gm-Message-State: AOAM532jhjN/5Y/X1PXBpgRKYKUw1hJuudrngQnV9bsdqPfJUqxOSo3H du8HzlgdGR7jL0C1MwuAEs8gLgVbiCJvpEIm X-Google-Smtp-Source: ABdhPJyza10BtH3Gjy6DDPTKm+dAKrQ+c6UH2b/tw+tIS6jaEGybWZXnBewM/msRFZVzT7n2fKMsbQ== X-Received: by 2002:a63:4241:: with SMTP id p62mr18834555pga.453.1614705651481; Tue, 02 Mar 2021 09:20:51 -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 b15sm20073923pgg.85.2021.03.02.09.20.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Mar 2021 09:20:51 -0800 (PST) From: Joe Stringer To: bpf@vger.kernel.org Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org, linux-man@vger.kernel.org, =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Quentin Monnet Subject: [PATCHv2 bpf-next 15/15] tools: Sync uapi bpf.h header with latest changes Date: Tue, 2 Mar 2021 09:19:47 -0800 Message-Id: <20210302171947.2268128-16-joe@cilium.io> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210302171947.2268128-1-joe@cilium.io> References: <20210302171947.2268128-1-joe@cilium.io> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Synchronize the header after all of the recent changes. Acked-by: Toke Høiland-Jørgensen Reviewed-by: Quentin Monnet Signed-off-by: Joe Stringer --- tools/include/uapi/linux/bpf.h | 712 ++++++++++++++++++++++++++++++++- 1 file changed, 711 insertions(+), 1 deletion(-) diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h index b4c5c529ad17..63a56ed6a785 100644 --- a/tools/include/uapi/linux/bpf.h +++ b/tools/include/uapi/linux/bpf.h @@ -93,7 +93,717 @@ 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. */ +/** + * DOC: eBPF Syscall Preamble + * + * 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*. + */ +/** + * DOC: eBPF 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,