From patchwork Mon May 11 13:38:04 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Quentin Monnet X-Patchwork-Id: 1287736 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Original-To: incoming-bpf@patchwork.ozlabs.org Delivered-To: patchwork-incoming-bpf@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=vger.kernel.org (client-ip=23.128.96.18; helo=vger.kernel.org; envelope-from=bpf-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=isovalent.com Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=isovalent-com.20150623.gappssmtp.com header.i=@isovalent-com.20150623.gappssmtp.com header.a=rsa-sha256 header.s=20150623 header.b=WIaaTzUx; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by ozlabs.org (Postfix) with ESMTP id 49LMTF3G8Tz9sSw for ; Mon, 11 May 2020 23:38:25 +1000 (AEST) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729829AbgEKNiY (ORCPT ); Mon, 11 May 2020 09:38:24 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59684 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-FAIL-OK-FAIL) by vger.kernel.org with ESMTP id S1726934AbgEKNiW (ORCPT ); Mon, 11 May 2020 09:38:22 -0400 Received: from mail-wr1-x444.google.com (mail-wr1-x444.google.com [IPv6:2a00:1450:4864:20::444]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 96848C05BD09 for ; Mon, 11 May 2020 06:38:22 -0700 (PDT) Received: by mail-wr1-x444.google.com with SMTP id i15so10979213wrx.10 for ; Mon, 11 May 2020 06:38:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=isovalent-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=oMvuLrgtg4fujA+qHaz0E9TK2E50uwJmrNzLZd/PmYA=; b=WIaaTzUxcBxlyzNHEbjDWMcGZJ06DL2JdVGWbLjOrnD5okoQdgPixEqHyvis2OmJL3 MmRo/tgA4gNFwdZX3FNurhIMTQiIVQShhnvRGObLTtW1GFNboqRHH6jZDXCzsVFg9XW+ 2jQNou4Utt0kZYOl7uoCtZQ43G0uIl2rMpS6ENTZA1hyKej10djqI8e3V0/rHE+zMvmJ vVzHGhZonVP+G+74qGyCtV0fnWHWJDa7dFkrwtDcKs1fRNswgI8B+lOsK5eLpcO1QIgy F90e168ydiBqHisxLIz+pQDM4Rl+rSe9+a+F+azEhRM8nLIQGiF+UcDxoE8duIM8L19T Q/Cg== 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=oMvuLrgtg4fujA+qHaz0E9TK2E50uwJmrNzLZd/PmYA=; b=dCGYcXM/b63R9aK6U0DU3ObNzc4cBp5r/m5spFT4Xlv9P0LQvwlfa/5JGTuQz/wGdY rbgGLdkWyImiq3nXMrSnf/4PWv0GKYWs/hLvmgWjkNcTxOqj2o0Kzyd3abt1j8S8hVmn YdEkhK+mEXaLoRPOs3/95tLg7eA7V7ZBXnzygrzjRqE0emvuUYxQOTxluL8w9RwQwUJk +JNVUKSGr8pUadkBQjXgle8Ht58u7SvQhibIvDkHb0TU9BzGxR3/lZjp8kfyH7V9xhgj voAPY3OUpvIolzfGK36mp1VMK4RaUNOXBGTnXx+wtICPcHVzdoVQyMCCyzp8+tpyPXJW xIFA== X-Gm-Message-State: AGi0PuYC8NMPN4c9wKUQ9JFDw/sJiSoncR7hGKSl2U8RSf8V3uwW4B60 aBbbsmkxE+CSGvXRrjbOKtq1H4YfalWncw== X-Google-Smtp-Source: APiQypLSL0vJ+YBUGZa7VZclXrYM8MEBsxIa6Tld/8PEKwGr3QXcxAR2Do67+dgqgbQDLLr/Nnostw== X-Received: by 2002:a5d:54c4:: with SMTP id x4mr20328287wrv.73.1589204301316; Mon, 11 May 2020 06:38:21 -0700 (PDT) Received: from localhost.localdomain ([194.53.185.84]) by smtp.gmail.com with ESMTPSA id p4sm6932371wrq.31.2020.05.11.06.38.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2020 06:38:20 -0700 (PDT) From: Quentin Monnet To: Alexei Starovoitov , Daniel Borkmann Cc: bpf@vger.kernel.org, netdev@vger.kernel.org, Quentin Monnet Subject: [PATCH bpf-next 1/4] tools: bpftool: poison and replace kernel integer typedefs Date: Mon, 11 May 2020 14:38:04 +0100 Message-Id: <20200511133807.26495-2-quentin@isovalent.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200511133807.26495-1-quentin@isovalent.com> References: <20200511133807.26495-1-quentin@isovalent.com> MIME-Version: 1.0 Sender: bpf-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org Replace the use of kernel-only integer typedefs (u8, u32, etc.) by their user space counterpart (__u8, __u32, etc.). Similarly to what libbpf does, poison the typedefs to avoid introducing them again in the future. Signed-off-by: Quentin Monnet --- tools/bpf/bpftool/btf_dumper.c | 4 ++-- tools/bpf/bpftool/cfg.c | 4 ++-- tools/bpf/bpftool/main.h | 3 +++ tools/bpf/bpftool/map_perf_ring.c | 2 +- tools/bpf/bpftool/prog.c | 2 +- 5 files changed, 9 insertions(+), 6 deletions(-) diff --git a/tools/bpf/bpftool/btf_dumper.c b/tools/bpf/bpftool/btf_dumper.c index 497807bec675..ede162f83eea 100644 --- a/tools/bpf/bpftool/btf_dumper.c +++ b/tools/bpf/bpftool/btf_dumper.c @@ -271,8 +271,8 @@ static void btf_int128_print(json_writer_t *jw, const void *data, } } -static void btf_int128_shift(__u64 *print_num, u16 left_shift_bits, - u16 right_shift_bits) +static void btf_int128_shift(__u64 *print_num, __u16 left_shift_bits, + __u16 right_shift_bits) { __u64 upper_num, lower_num; diff --git a/tools/bpf/bpftool/cfg.c b/tools/bpf/bpftool/cfg.c index 3e21f994f262..1951219a9af7 100644 --- a/tools/bpf/bpftool/cfg.c +++ b/tools/bpf/bpftool/cfg.c @@ -157,7 +157,7 @@ static bool cfg_partition_funcs(struct cfg *cfg, struct bpf_insn *cur, return false; } -static bool is_jmp_insn(u8 code) +static bool is_jmp_insn(__u8 code) { return BPF_CLASS(code) == BPF_JMP || BPF_CLASS(code) == BPF_JMP32; } @@ -176,7 +176,7 @@ static bool func_partition_bb_head(struct func_node *func) for (; cur <= end; cur++) { if (is_jmp_insn(cur->code)) { - u8 opcode = BPF_OP(cur->code); + __u8 opcode = BPF_OP(cur->code); if (opcode == BPF_EXIT || opcode == BPF_CALL) continue; diff --git a/tools/bpf/bpftool/main.h b/tools/bpf/bpftool/main.h index a41cefabccaf..f89ac70ef973 100644 --- a/tools/bpf/bpftool/main.h +++ b/tools/bpf/bpftool/main.h @@ -18,6 +18,9 @@ #include "json_writer.h" +/* Make sure we do not use kernel-only integer typedefs */ +#pragma GCC poison u8 u16 u32 u64 s8 s16 s32 s64 + #define ptr_to_u64(ptr) ((__u64)(unsigned long)(ptr)) #define NEXT_ARG() ({ argc--; argv++; if (argc < 0) usage(); }) diff --git a/tools/bpf/bpftool/map_perf_ring.c b/tools/bpf/bpftool/map_perf_ring.c index d9b29c17fbb8..825f29f93a57 100644 --- a/tools/bpf/bpftool/map_perf_ring.c +++ b/tools/bpf/bpftool/map_perf_ring.c @@ -39,7 +39,7 @@ struct event_ring_info { struct perf_event_sample { struct perf_event_header header; - u64 time; + __u64 time; __u32 size; unsigned char data[]; }; diff --git a/tools/bpf/bpftool/prog.c b/tools/bpf/bpftool/prog.c index f6a5974a7b0a..b6e5ba568f98 100644 --- a/tools/bpf/bpftool/prog.c +++ b/tools/bpf/bpftool/prog.c @@ -238,7 +238,7 @@ int prog_parse_fd(int *argc, char ***argv) return fd; } -static void show_prog_maps(int fd, u32 num_maps) +static void show_prog_maps(int fd, __u32 num_maps) { struct bpf_prog_info info = {}; __u32 len = sizeof(info); From patchwork Mon May 11 13:38:05 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Quentin Monnet X-Patchwork-Id: 1287739 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Original-To: patchwork-incoming-netdev@ozlabs.org Delivered-To: patchwork-incoming-netdev@ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=vger.kernel.org (client-ip=23.128.96.18; helo=vger.kernel.org; envelope-from=netdev-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=isovalent.com Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=isovalent-com.20150623.gappssmtp.com header.i=@isovalent-com.20150623.gappssmtp.com header.a=rsa-sha256 header.s=20150623 header.b=ovC8iK5t; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by ozlabs.org (Postfix) with ESMTP id 49LMTH5rq6z9sRf for ; Mon, 11 May 2020 23:38:27 +1000 (AEST) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729949AbgEKNi0 (ORCPT ); Mon, 11 May 2020 09:38:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59684 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-FAIL-OK-FAIL) by vger.kernel.org with ESMTP id S1729819AbgEKNiY (ORCPT ); Mon, 11 May 2020 09:38:24 -0400 Received: from mail-wr1-x441.google.com (mail-wr1-x441.google.com [IPv6:2a00:1450:4864:20::441]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B1E69C061A0C for ; Mon, 11 May 2020 06:38:23 -0700 (PDT) Received: by mail-wr1-x441.google.com with SMTP id i15so10979297wrx.10 for ; Mon, 11 May 2020 06:38:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=isovalent-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=79u6MzGyKGGnMZC4QQ9o+3pXZzxlwfR+y0BnNMPOM3U=; b=ovC8iK5tHRPRc6Wk6dQpWFd/5H36cvTKMYuipdXG+HkAyvO3xFN4QiComuUYrs1nFs 0SPSNa2xjCHMFAZZ1qTgmeKzpF1f0nH1hY4OtvcJrArJ4CpeLMXfFQXidBlnGMO8EKTa Az8ottRY2Uvd5b1i+KQvXgU4vG4pTDljr2EsT+AXWydG7oKBmN49/hEGbuUpf3zdZp6O /9g/jt7gpjtxdks9vK32K4oqVWEhWoXSHSTj0CsfqhzkPOvMkWTfxXKCO3IXKvME3J4U XM3ei2X1ahSlfq7NCFz4NM9jXpDhBi/0no+7FwB26nuUFkvqKr1ktRgxOwsUt+JblHJ3 9uRw== 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=79u6MzGyKGGnMZC4QQ9o+3pXZzxlwfR+y0BnNMPOM3U=; b=W3T/IFuxXZDcoZkMQ/i54RCOgRMpkXM/k2lQCdS86PMjltHRO3E0/7v7cegXaMnmzA MysKmbswIGY8DqsfEcORC/Veaz3azwb3apfzqAHH0OzWn9TKJ64213QZCb44AqjaRbdn iQh7PBce3PS02xzQYgoib++LxRHBnrXaA77UqCLQC+VLFMDWbESKGz/JFFG0JyfsSCC6 /NUa5bRBsJXmcGwkzXITSsMOR7xoJRz8K1Ha9mKXgf+M84KCb3qyapwtlw1oDKR/bZ7d eEox+hTHGsOj7YzENgKdKspZG/HlQnhv0qHYvfHcf2B4gnqoPuaKuLeLv++SkcZGJhEl 81kw== X-Gm-Message-State: AGi0PuZDF/pSgy9QsifcXFRg5B8mpuNZL+LlKW61qize9t9gHxUO20WF RtmgpW9h7OHa88q32qUURc/GNw== X-Google-Smtp-Source: APiQypKw2HkNUK1jqnTn7VWii0vLch+PFngRxlDWtNiwc0UDInocq9PA408sb8ogvxAfZyG1PfNGOA== X-Received: by 2002:a5d:4685:: with SMTP id u5mr18098813wrq.98.1589204302153; Mon, 11 May 2020 06:38:22 -0700 (PDT) Received: from localhost.localdomain ([194.53.185.84]) by smtp.gmail.com with ESMTPSA id p4sm6932371wrq.31.2020.05.11.06.38.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2020 06:38:21 -0700 (PDT) From: Quentin Monnet To: Alexei Starovoitov , Daniel Borkmann Cc: bpf@vger.kernel.org, netdev@vger.kernel.org, Quentin Monnet Subject: [PATCH bpf-next 2/4] tools: bpftool: minor fixes for documentation Date: Mon, 11 May 2020 14:38:05 +0100 Message-Id: <20200511133807.26495-3-quentin@isovalent.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200511133807.26495-1-quentin@isovalent.com> References: <20200511133807.26495-1-quentin@isovalent.com> MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org Bring minor improvements to bpftool documentation. Fix or harmonise formatting, update map types (including in interactive help), improve description for "map create", fix a build warning due to a missing line after the double-colon for the "bpftool prog profile" example, complete/harmonise/sort the list of related bpftool man pages in footers. Signed-off-by: Quentin Monnet --- .../bpf/bpftool/Documentation/bpftool-btf.rst | 11 ++++-- .../bpftool/Documentation/bpftool-cgroup.rst | 12 ++++--- .../bpftool/Documentation/bpftool-feature.rst | 12 ++++--- .../bpf/bpftool/Documentation/bpftool-gen.rst | 21 ++++++----- .../bpftool/Documentation/bpftool-iter.rst | 12 +++---- .../bpftool/Documentation/bpftool-link.rst | 9 +++-- .../bpf/bpftool/Documentation/bpftool-map.rst | 35 ++++++++++++------- .../bpf/bpftool/Documentation/bpftool-net.rst | 12 ++++--- .../bpftool/Documentation/bpftool-perf.rst | 12 ++++--- .../bpftool/Documentation/bpftool-prog.rst | 23 +++++++----- .../Documentation/bpftool-struct_ops.rst | 11 +++--- tools/bpf/bpftool/Documentation/bpftool.rst | 11 +++--- tools/bpf/bpftool/map.c | 3 +- 13 files changed, 115 insertions(+), 69 deletions(-) diff --git a/tools/bpf/bpftool/Documentation/bpftool-btf.rst b/tools/bpf/bpftool/Documentation/bpftool-btf.rst index 39615f8e145b..ce3a724f50c1 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-btf.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-btf.rst @@ -230,9 +230,14 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-map**\ (8), - **bpftool-prog**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), - **bpftool-perf**\ (8) + **bpftool-perf**\ (8), + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst index 06a28b07787d..e4d9da654e84 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst @@ -20,7 +20,7 @@ SYNOPSIS CGROUP COMMANDS =============== -| **bpftool** **cgroup { show | list }** *CGROUP* [**effective**] +| **bpftool** **cgroup** { **show** | **list** } *CGROUP* [**effective**] | **bpftool** **cgroup tree** [*CGROUP_ROOT*] [**effective**] | **bpftool** **cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*] | **bpftool** **cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG* @@ -160,9 +160,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-prog**\ (8), - **bpftool-map**\ (8), + **bpftool-btf**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-feature.rst b/tools/bpf/bpftool/Documentation/bpftool-feature.rst index 1fa755f55e0c..8609f06e71de 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-feature.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-feature.rst @@ -28,7 +28,7 @@ DESCRIPTION =========== **bpftool feature probe** [**kernel**] [**full**] [**macros** [**prefix** *PREFIX*]] Probe the running kernel and dump a number of eBPF-related - parameters, such as availability of the **bpf()** system call, + parameters, such as availability of the **bpf**\ () system call, JIT status, eBPF program types availability, eBPF helper functions availability, and more. @@ -93,9 +93,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-prog**\ (8), - **bpftool-map**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-gen.rst b/tools/bpf/bpftool/Documentation/bpftool-gen.rst index 94d91322895a..df85dbd962c0 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-gen.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-gen.rst @@ -14,7 +14,7 @@ SYNOPSIS *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } - *COMMAND* := { **skeleton | **help** } + *COMMAND* := { **skeleton** | **help** } GEN COMMANDS ============= @@ -36,12 +36,12 @@ DESCRIPTION etc. Skeleton eliminates the need to lookup mentioned components by name. Instead, if skeleton instantiation succeeds, they are populated in skeleton structure as valid - libbpf types (e.g., struct bpf_map pointer) and can be + libbpf types (e.g., **struct bpf_map** pointer) and can be passed to existing generic libbpf APIs. In addition to simple and reliable access to maps and - programs, skeleton provides a storage for BPF links (struct - bpf_link) for each BPF program within BPF object. When + programs, skeleton provides a storage for BPF links (**struct + bpf_link**) for each BPF program within BPF object. When requested, supported BPF programs will be automatically attached and resulting BPF links stored for further use by user in pre-allocated fields in skeleton struct. For BPF @@ -82,14 +82,14 @@ DESCRIPTION - **example__open** and **example__open_opts**. These functions are used to instantiate skeleton. It - corresponds to libbpf's **bpf_object__open()** API. + corresponds to libbpf's **bpf_object__open**\ () API. **_opts** variants accepts extra **bpf_object_open_opts** options. - **example__load**. This function creates maps, loads and verifies BPF programs, initializes global data maps. It corresponds to - libppf's **bpf_object__load** API. + libppf's **bpf_object__load**\ () API. - **example__open_and_load** combines **example__open** and **example__load** invocations in one commonly used @@ -296,10 +296,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-map**\ (8), - **bpftool-prog**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-iter.rst b/tools/bpf/bpftool/Documentation/bpftool-iter.rst index 13b173d93890..8dce698eab79 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-iter.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-iter.rst @@ -22,7 +22,6 @@ ITER COMMANDS | | *OBJ* := /a/file/of/bpf_iter_target.o - DESCRIPTION =========== **bpftool iter pin** *OBJ* *PATH* @@ -65,19 +64,18 @@ EXAMPLES Create a file-based bpf iterator from bpf_iter_netlink.o and pin it to /sys/fs/bpf/my_netlink - SEE ALSO ======== **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-prog**\ (8), - **bpftool-map**\ (8), - **bpftool-link**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) - **bpftool-gen**\ (8) + **bpftool-prog**\ (8), **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-link.rst b/tools/bpf/bpftool/Documentation/bpftool-link.rst index ee6500d6e6e4..0e43d7b06c11 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-link.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-link.rst @@ -109,10 +109,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-prog\ (8), - **bpftool-map**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-map.rst b/tools/bpf/bpftool/Documentation/bpftool-map.rst index cdeae8ae90ba..3177fe3fd969 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-map.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-map.rst @@ -21,7 +21,7 @@ SYNOPSIS MAP COMMANDS ============= -| **bpftool** **map { show | list }** [*MAP*] +| **bpftool** **map** { **show** | **list** } [*MAP*] | **bpftool** **map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \ | **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*] | **bpftool** **map dump** *MAP* @@ -49,7 +49,7 @@ MAP COMMANDS | | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** | | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash** | | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** -| | **queue** | **stack** } +| | **queue** | **stack** | **sk_storage** | **struct_ops** } DESCRIPTION =========== @@ -66,6 +66,13 @@ DESCRIPTION Create a new map with given parameters and pin it to *bpffs* as *FILE*. + *FLAGS* should be an integer which is the combination of + desired flags, e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h + UAPI header for existing flags). + + Keyword **dev** expects a network interface name, and is used + to request hardware offload for the map. + **bpftool map dump** *MAP* Dump all entries in a given *MAP*. In case of **name**, *MAP* may match several maps which will all be dumped. @@ -100,10 +107,10 @@ DESCRIPTION extensions of *bpffs*. **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] - Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map. + Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map. Install perf rings into a perf event array map and dump - output of any bpf_perf_event_output() call in the kernel. + output of any **bpf_perf_event_output**\ () call in the kernel. By default read the number of CPUs on the system and install perf ring for each CPU in the corresponding index in the array. @@ -116,24 +123,24 @@ DESCRIPTION receiving events if it installed its rings earlier. **bpftool map peek** *MAP* - Peek next **value** in the queue or stack. + Peek next value in the queue or stack. **bpftool map push** *MAP* **value** *VALUE* - Push **value** onto the stack. + Push *VALUE* onto the stack. **bpftool map pop** *MAP* - Pop and print **value** from the stack. + Pop and print *VALUE* from the stack. **bpftool map enqueue** *MAP* **value** *VALUE* - Enqueue **value** into the queue. + Enqueue *VALUE* into the queue. **bpftool map dequeue** *MAP* - Dequeue and print **value** from the queue. + Dequeue and print *VALUE* from the queue. **bpftool map freeze** *MAP* Freeze the map as read-only from user space. Entries from a frozen map can not longer be updated or deleted with the - **bpf\ ()** system call. This operation is not reversible, + **bpf**\ () system call. This operation is not reversible, and the map remains immutable from user space until its destruction. However, read and write permissions for BPF programs to the map remain unchanged. @@ -269,9 +276,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-prog**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-net.rst b/tools/bpf/bpftool/Documentation/bpftool-net.rst index 8651b00b81ea..aa7450736179 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-net.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-net.rst @@ -20,7 +20,7 @@ SYNOPSIS NET COMMANDS ============ -| **bpftool** **net { show | list }** [ **dev** *NAME* ] +| **bpftool** **net** { **show** | **list** } [ **dev** *NAME* ] | **bpftool** **net attach** *ATTACH_TYPE* *PROG* **dev** *NAME* [ **overwrite** ] | **bpftool** **net detach** *ATTACH_TYPE* **dev** *NAME* | **bpftool** **net help** @@ -194,9 +194,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-prog**\ (8), - **bpftool-map**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-perf.rst b/tools/bpf/bpftool/Documentation/bpftool-perf.rst index e252bd0bc434..9c592b7c6775 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-perf.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-perf.rst @@ -20,7 +20,7 @@ SYNOPSIS PERF COMMANDS ============= -| **bpftool** **perf { show | list }** +| **bpftool** **perf** { **show** | **list** } | **bpftool** **perf help** DESCRIPTION @@ -85,9 +85,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-prog**\ (8), - **bpftool-map**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), - **bpftool-btf**\ (8) + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-prog.rst b/tools/bpf/bpftool/Documentation/bpftool-prog.rst index 9f19404f470e..5948e9d89c8d 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-prog.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-prog.rst @@ -21,11 +21,11 @@ SYNOPSIS PROG COMMANDS ============= -| **bpftool** **prog { show | list }** [*PROG*] +| **bpftool** **prog** { **show** | **list** } [*PROG*] | **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual** | **linum**}] | **bpftool** **prog dump jited** *PROG* [{**file** *FILE* | **opcodes** | **linum**}] | **bpftool** **prog pin** *PROG* *FILE* -| **bpftool** **prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*] +| **bpftool** **prog** { **load** | **loadall** } *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*] | **bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*] | **bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*] | **bpftool** **prog tracelog** @@ -49,7 +49,7 @@ PROG COMMANDS | *ATTACH_TYPE* := { | **msg_verdict** | **stream_verdict** | **stream_parser** | **flow_dissector** | } -| *METRIC* := { +| *METRICs* := { | **cycles** | **instructions** | **l1d_loads** | **llc_misses** | } @@ -155,7 +155,7 @@ DESCRIPTION **bpftool prog tracelog** Dump the trace pipe of the system to the console (stdout). Hit to stop printing. BPF programs can write to this - trace pipe at runtime with the **bpf_trace_printk()** helper. + trace pipe at runtime with the **bpf_trace_printk**\ () helper. This should be used only for debugging purposes. For streaming data from BPF programs to user space, one can use perf events (see also **bpftool-map**\ (8)). @@ -195,9 +195,9 @@ DESCRIPTION **bpftool prog profile** *PROG* [**duration** *DURATION*] *METRICs* Profile *METRICs* for bpf program *PROG* for *DURATION* - seconds or until user hits Ctrl-C. *DURATION* is optional. + seconds or until user hits . *DURATION* is optional. If *DURATION* is not specified, the profiling will run up to - UINT_MAX seconds. + **UINT_MAX** seconds. **bpftool prog help** Print short help message. @@ -267,7 +267,7 @@ EXAMPLES | | **# bpftool prog dump xlated id 10 file /tmp/t** -| **# ls -l /tmp/t** +| **$ ls -l /tmp/t** :: @@ -325,6 +325,7 @@ EXAMPLES | **# bpftool prog profile id 337 duration 10 cycles instructions llc_misses** :: + 51397 run_cnt 40176203 cycles (83.05%) 42518139 instructions # 1.06 insns per cycle (83.39%) @@ -335,9 +336,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-map**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst b/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst index f045cc89dd6d..d93cd1cb8b0f 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst @@ -105,12 +105,13 @@ SEE ALSO **bpf**\ (2), **bpf-helpers**\ (7), **bpftool**\ (8), - **bpftool-prog**\ (8), - **bpftool-map**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8) - **bpftool-gen**\ (8) - + **bpftool-prog**\ (8) diff --git a/tools/bpf/bpftool/Documentation/bpftool.rst b/tools/bpf/bpftool/Documentation/bpftool.rst index 34239fda69ed..420d4d5df8b6 100644 --- a/tools/bpf/bpftool/Documentation/bpftool.rst +++ b/tools/bpf/bpftool/Documentation/bpftool.rst @@ -75,11 +75,14 @@ SEE ALSO ======== **bpf**\ (2), **bpf-helpers**\ (7), - **bpftool-prog**\ (8), - **bpftool-map**\ (8), + **bpftool-btf**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), + **bpftool-gen**\ (8), + **bpftool-iter**\ (8), + **bpftool-link**\ (8), + **bpftool-map**\ (8), **bpftool-net**\ (8), **bpftool-perf**\ (8), - **bpftool-btf**\ (8), - **bpftool-gen**\ (8), + **bpftool-prog**\ (8), + **bpftool-struct_ops**\ (8) diff --git a/tools/bpf/bpftool/map.c b/tools/bpf/bpftool/map.c index 693a632f6813..85cbe9a19170 100644 --- a/tools/bpf/bpftool/map.c +++ b/tools/bpf/bpftool/map.c @@ -1589,7 +1589,8 @@ static int do_help(int argc, char **argv) " percpu_array | stack_trace | cgroup_array | lru_hash |\n" " lru_percpu_hash | lpm_trie | array_of_maps | hash_of_maps |\n" " devmap | devmap_hash | sockmap | cpumap | xskmap | sockhash |\n" - " cgroup_storage | reuseport_sockarray | percpu_cgroup_storage }\n" + " cgroup_storage | reuseport_sockarray | percpu_cgroup_storage |\n" + " queue | stack | sk_storage | struct_ops }\n" " " HELP_SPEC_OPTIONS "\n" "", bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2], From patchwork Mon May 11 13:38:06 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Quentin Monnet X-Patchwork-Id: 1287738 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Original-To: incoming-bpf@patchwork.ozlabs.org Delivered-To: patchwork-incoming-bpf@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=vger.kernel.org (client-ip=23.128.96.18; helo=vger.kernel.org; envelope-from=bpf-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=isovalent.com Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=isovalent-com.20150623.gappssmtp.com header.i=@isovalent-com.20150623.gappssmtp.com header.a=rsa-sha256 header.s=20150623 header.b=AmhTPXQt; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by ozlabs.org (Postfix) with ESMTP id 49LMTG0HrPz9sT4 for ; Mon, 11 May 2020 23:38:26 +1000 (AEST) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729897AbgEKNiZ (ORCPT ); Mon, 11 May 2020 09:38:25 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59682 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-FAIL-OK-FAIL) by vger.kernel.org with ESMTP id S1726934AbgEKNiY (ORCPT ); Mon, 11 May 2020 09:38:24 -0400 Received: from mail-wm1-x341.google.com (mail-wm1-x341.google.com [IPv6:2a00:1450:4864:20::341]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6E8D0C05BD0A for ; Mon, 11 May 2020 06:38:24 -0700 (PDT) Received: by mail-wm1-x341.google.com with SMTP id d207so3961630wmd.0 for ; Mon, 11 May 2020 06:38:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=isovalent-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=BeM3yfMB5vX2Kgioa2PToWWe+/ytXj3p9vZHiizHUAg=; b=AmhTPXQtTdfVFH0kcjlLoGczu0o1IAn8vTfK0HB9dhynxtoVIxGoHSr3Dx78HoeBqd OG9zCWHlcV6t+tqc8mfaBZdYO7ntVrZsmmUiB8tnyQiMsjVAenSHMWwfMHdWSQ3HrCPg nHAwKDAMCP5hN3geJ5cgtSfGBzI/oYrIqhLk0cBx0G33xtKjMjjCdoFYQAYJR2f1gufa 6aNJYKtRu+x1S6QjUAj4mtDI6SEbIQxRFtFDCIgckLmwD7KW+X2Mayk9RLIH3RSlgA2q Wgkx/7e0zzhoPl02XCvDHrn+6xlJo31+0NQWBf4fmY376G9iBxQxXbAbEpQLoYaKsv8E FXgA== 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=BeM3yfMB5vX2Kgioa2PToWWe+/ytXj3p9vZHiizHUAg=; b=BJ4N+mYIfeuv91ud9CiwcmuQsVa3udgBNn2TmRe1+ImC2qYUocSNqhCpkfMhaqx1J6 jHnVSDBEiGwapzODqbXVoYLZHz26th08hESI8JTPXRyUUVP3F4ErspntjUpF57zkDLGU 2FhHfJyiuZm+oM3whF2iWjcv3QQjdo7OUamCsXbkaujrC2AR6r301Nmhre7flIOyA8iF Gqz+U/n8ljU0yXnoLcdBlgx5d3giBzFVU4HhBddi9ZtW6vB/DoIz5o7DiGmlaEqJ5e1s Rwa/rrBN+APjeiDR306PWWFHXFP6UH9GVRvhADriBJWRwUpfYYsj+H5pUHTmTiu/cmKs sjhw== X-Gm-Message-State: AGi0Pub/W8/w4M4G/JEjyknsJJIFeRoE5+OoKgesYeAjRflr1tubyGbP DKF1pTF4n5nlsiRUvESxcOaAaA== X-Google-Smtp-Source: APiQypJfvT+3+ZFQWGKWoLiJN2GvgxbSVTUl6We0vuZjALIMe//DmSF6JSMKV216WRO93lG/KBfjsw== X-Received: by 2002:a7b:c459:: with SMTP id l25mr31023396wmi.52.1589204303069; Mon, 11 May 2020 06:38:23 -0700 (PDT) Received: from localhost.localdomain ([194.53.185.84]) by smtp.gmail.com with ESMTPSA id p4sm6932371wrq.31.2020.05.11.06.38.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2020 06:38:22 -0700 (PDT) From: Quentin Monnet To: Alexei Starovoitov , Daniel Borkmann Cc: bpf@vger.kernel.org, netdev@vger.kernel.org, Quentin Monnet , Florian Weimer , Richard Palethorpe , Michael Kerrisk Subject: [PATCH bpf-next 3/4] bpf: minor fixes to BPF helpers documentation Date: Mon, 11 May 2020 14:38:06 +0100 Message-Id: <20200511133807.26495-4-quentin@isovalent.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200511133807.26495-1-quentin@isovalent.com> References: <20200511133807.26495-1-quentin@isovalent.com> MIME-Version: 1.0 Sender: bpf-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org Minor improvements to the documentation for BPF helpers: * Fix formatting for the description of "bpf_socket" for bpf_getsockopt() and bpf_setsockopt(), thus suppressing two warnings from rst2man about "Unexpected indentation". * Fix formatting for return values for bpf_sk_assign() and seq_file helpers. * Fix and harmonise formatting, in particular for function/struct names. * Remove blank lines before "Return:" sections. * Replace tabs found in the middle of text lines. * Fix typos. * Add a note to the footer (in Python script) about "bpftool feature probe", including for listing features available to unprivileged users, and add a reference to bpftool man page. Thanks to Florian for reporting two typos (duplicated words). Cc: Florian Weimer Cc: Richard Palethorpe Cc: Michael Kerrisk Signed-off-by: Quentin Monnet --- include/uapi/linux/bpf.h | 109 ++++++++++++++++++++----------------- scripts/bpf_helpers_doc.py | 6 ++ 2 files changed, 65 insertions(+), 50 deletions(-) diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index 9d1932e23cec..bfb31c1be219 100644 --- a/include/uapi/linux/bpf.h +++ b/include/uapi/linux/bpf.h @@ -675,8 +675,8 @@ union bpf_attr { * For tracing programs, safely attempt to read *size* bytes from * kernel space address *unsafe_ptr* and store the data in *dst*. * - * Generally, use bpf_probe_read_user() or bpf_probe_read_kernel() - * instead. + * Generally, use **bpf_probe_read_user**\ () or + * **bpf_probe_read_kernel**\ () instead. * Return * 0 on success, or a negative error in case of failure. * @@ -684,7 +684,7 @@ union bpf_attr { * Description * Return the time elapsed since system boot, in nanoseconds. * Does not include time the system was suspended. - * See: clock_gettime(CLOCK_MONOTONIC) + * See: **clock_gettime**\ (**CLOCK_MONOTONIC**) * Return * Current *ktime*. * @@ -1543,11 +1543,11 @@ union bpf_attr { * int bpf_probe_read_str(void *dst, u32 size, const void *unsafe_ptr) * Description * Copy a NUL terminated string from an unsafe kernel address - * *unsafe_ptr* to *dst*. See bpf_probe_read_kernel_str() for + * *unsafe_ptr* to *dst*. See **bpf_probe_read_kernel_str**\ () for * more details. * - * Generally, use bpf_probe_read_user_str() or bpf_probe_read_kernel_str() - * instead. + * Generally, use **bpf_probe_read_user_str**\ () or + * **bpf_probe_read_kernel_str**\ () instead. * Return * On success, the strictly positive length of the string, * including the trailing NUL character. On error, a negative @@ -1575,7 +1575,7 @@ union bpf_attr { * * u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx) * Description - * Equivalent to bpf_get_socket_cookie() helper that accepts + * Equivalent to **bpf_get_socket_cookie**\ () helper that accepts * *skb*, but gets socket from **struct bpf_sock_ops** context. * Return * A 8-byte long non-decreasing number. @@ -1604,6 +1604,7 @@ union bpf_attr { * The option value of length *optlen* is pointed by *optval*. * * *bpf_socket* should be one of the following: + * * * **struct bpf_sock_ops** for **BPF_PROG_TYPE_SOCK_OPS**. * * **struct bpf_sock_addr** for **BPF_CGROUP_INET4_CONNECT** * and **BPF_CGROUP_INET6_CONNECT**. @@ -1672,12 +1673,12 @@ union bpf_attr { * * The lower two bits of *flags* are used as the return code if * the map lookup fails. This is so that the return value can be - * one of the XDP program return codes up to XDP_TX, as chosen by - * the caller. Any higher bits in the *flags* argument must be + * one of the XDP program return codes up to **XDP_TX**, as chosen + * by the caller. Any higher bits in the *flags* argument must be * unset. * - * See also bpf_redirect(), which only supports redirecting to an - * ifindex, but doesn't require a map to do so. + * See also **bpf_redirect**\ (), which only supports redirecting + * to an ifindex, but doesn't require a map to do so. * Return * **XDP_REDIRECT** on success, or the value of the two lower bits * of the *flags* argument on error. @@ -1785,7 +1786,7 @@ union bpf_attr { * the time running for event since last normalization. The * enabled and running times are accumulated since the perf event * open. To achieve scaling factor between two invocations of an - * eBPF program, users can can use CPU id as the key (which is + * eBPF program, users can use CPU id as the key (which is * typical for perf array usage model) to remember the previous * value and do the calculation inside the eBPF program. * Return @@ -1812,6 +1813,7 @@ union bpf_attr { * *opval* and of length *optlen*. * * *bpf_socket* should be one of the following: + * * * **struct bpf_sock_ops** for **BPF_PROG_TYPE_SOCK_OPS**. * * **struct bpf_sock_addr** for **BPF_CGROUP_INET4_CONNECT** * and **BPF_CGROUP_INET6_CONNECT**. @@ -1833,7 +1835,7 @@ union bpf_attr { * The first argument is the context *regs* on which the kprobe * works. * - * This helper works by setting setting the PC (program counter) + * This helper works by setting the PC (program counter) * to an override function which is run in place of the original * probed function. This means the probed function is not run at * all. The replacement function just returns with the required @@ -2300,7 +2302,7 @@ union bpf_attr { * **bpf_rc_keydown**\ () again with the same values, or calling * **bpf_rc_repeat**\ (). * - * Some protocols include a toggle bit, in case the button was + * Some protocols include a toggle bit, in case the button was * released and pressed again between consecutive scancodes. * * The *ctx* should point to the lirc sample as passed into @@ -2646,7 +2648,6 @@ union bpf_attr { * * *th* points to the start of the TCP header, while *th_len* * contains **sizeof**\ (**struct tcphdr**). - * * Return * 0 if *iph* and *th* are a valid SYN cookie ACK, or a negative * error otherwise. @@ -2829,7 +2830,6 @@ union bpf_attr { * * *th* points to the start of the TCP header, while *th_len* * contains the length of the TCP header. - * * Return * On success, lower 32 bits hold the generated SYN cookie in * followed by 16 bits which hold the MSS value for that cookie, @@ -2912,7 +2912,7 @@ union bpf_attr { * // size, after checking its boundaries. * } * - * In comparison, using **bpf_probe_read_user()** helper here + * In comparison, using **bpf_probe_read_user**\ () helper here * instead to read the string would require to estimate the length * at compile time, and would often result in copying more memory * than necessary. @@ -2930,14 +2930,14 @@ union bpf_attr { * int bpf_probe_read_kernel_str(void *dst, u32 size, const void *unsafe_ptr) * Description * Copy a NUL terminated string from an unsafe kernel address *unsafe_ptr* - * to *dst*. Same semantics as with bpf_probe_read_user_str() apply. + * to *dst*. Same semantics as with **bpf_probe_read_user_str**\ () apply. * Return - * On success, the strictly positive length of the string, including + * On success, the strictly positive length of the string, including * the trailing NUL character. On error, a negative value. * * int bpf_tcp_send_ack(void *tp, u32 rcv_nxt) * Description - * Send out a tcp-ack. *tp* is the in-kernel struct tcp_sock. + * Send out a tcp-ack. *tp* is the in-kernel struct **tcp_sock**. * *rcv_nxt* is the ack_seq to be sent out. * Return * 0 on success, or a negative error in case of failure. @@ -2965,19 +2965,19 @@ union bpf_attr { * int bpf_read_branch_records(struct bpf_perf_event_data *ctx, void *buf, u32 size, u64 flags) * Description * For an eBPF program attached to a perf event, retrieve the - * branch records (struct perf_branch_entry) associated to *ctx* - * and store it in the buffer pointed by *buf* up to size + * branch records (**struct perf_branch_entry**) associated to *ctx* + * and store it in the buffer pointed by *buf* up to size * *size* bytes. * Return * On success, number of bytes written to *buf*. On error, a * negative value. * * The *flags* can be set to **BPF_F_GET_BRANCH_RECORDS_SIZE** to - * instead return the number of bytes required to store all the + * instead return the number of bytes required to store all the * branch entries. If this flag is set, *buf* may be NULL. * * **-EINVAL** if arguments invalid or **size** not a multiple - * of sizeof(struct perf_branch_entry). + * of **sizeof**\ (**struct perf_branch_entry**\ ). * * **-ENOENT** if architecture does not support branch records. * @@ -2985,8 +2985,8 @@ union bpf_attr { * Description * Returns 0 on success, values for *pid* and *tgid* as seen from the current * *namespace* will be returned in *nsdata*. - * - * On failure, the returned value is one of the following: + * Return + * 0 on success, or one of the following in case of failure: * * **-EINVAL** if dev and inum supplied don't match dev_t and inode number * with nsfs of current task, or if dev conversion to dev_t lost high bits. @@ -3025,8 +3025,8 @@ union bpf_attr { * a global identifier that can be assumed unique. If *ctx* is * NULL, then the helper returns the cookie for the initial * network namespace. The cookie itself is very similar to that - * of bpf_get_socket_cookie() helper, but for network namespaces - * instead of sockets. + * of **bpf_get_socket_cookie**\ () helper, but for network + * namespaces instead of sockets. * Return * A 8-byte long opaque number. * @@ -3061,57 +3061,66 @@ union bpf_attr { * * The *flags* argument must be zero. * Return - * 0 on success, or a negative errno in case of failure. + * 0 on success, or a negative error in case of failure: * - * * **-EINVAL** Unsupported flags specified. - * * **-ENOENT** Socket is unavailable for assignment. - * * **-ENETUNREACH** Socket is unreachable (wrong netns). - * * **-EOPNOTSUPP** Unsupported operation, for example a - * call from outside of TC ingress. - * * **-ESOCKTNOSUPPORT** Socket type not supported (reuseport). + * **-EINVAL** if specified *flags* are not supported. + * + * **-ENOENT** if the socket is unavailable for assignment. + * + * **-ENETUNREACH** if the socket is unreachable (wrong netns). + * + * **-EOPNOTSUPP** if the operation is not supported, for example + * a call from outside of TC ingress. + * + * **-ESOCKTNOSUPPORT** if the socket type is not supported + * (reuseport). * * u64 bpf_ktime_get_boot_ns(void) * Description * Return the time elapsed since system boot, in nanoseconds. * Does include the time the system was suspended. - * See: clock_gettime(CLOCK_BOOTTIME) + * See: **clock_gettime**\ (**CLOCK_BOOTTIME**) * Return * Current *ktime*. * * int bpf_seq_printf(struct seq_file *m, const char *fmt, u32 fmt_size, const void *data, u32 data_len) * Description - * seq_printf uses seq_file seq_printf() to print out the format string. + * **bpf_seq_printf**\ () uses seq_file **seq_printf**\ () to print + * out the format string. * The *m* represents the seq_file. The *fmt* and *fmt_size* are for * the format string itself. The *data* and *data_len* are format string - * arguments. The *data* are a u64 array and corresponding format string + * arguments. The *data* are a **u64** array and corresponding format string * values are stored in the array. For strings and pointers where pointees * are accessed, only the pointer values are stored in the *data* array. - * The *data_len* is the *data* size in term of bytes. + * The *data_len* is the size of *data* in bytes. * * Formats **%s**, **%p{i,I}{4,6}** requires to read kernel memory. * Reading kernel memory may fail due to either invalid address or * valid address but requiring a major memory fault. If reading kernel memory * fails, the string for **%s** will be an empty string, and the ip * address for **%p{i,I}{4,6}** will be 0. Not returning error to - * bpf program is consistent with what bpf_trace_printk() does for now. + * bpf program is consistent with what **bpf_trace_printk**\ () does for now. * Return - * 0 on success, or a negative errno in case of failure. + * 0 on success, or a negative error in case of failure: + * + * **-EBUSY** if per-CPU memory copy buffer is busy, can try again + * by returning 1 from bpf program. + * + * **-EINVAL** if arguments are invalid, or if *fmt* is invalid/unsupported. + * + * **-E2BIG** if *fmt* contains too many format specifiers. * - * * **-EBUSY** Percpu memory copy buffer is busy, can try again - * by returning 1 from bpf program. - * * **-EINVAL** Invalid arguments, or invalid/unsupported formats. - * * **-E2BIG** Too many format specifiers. - * * **-EOVERFLOW** Overflow happens, the same object will be tried again. + * **-EOVERFLOW** if an overflow happened: The same object will be tried again. * * int bpf_seq_write(struct seq_file *m, const void *data, u32 len) * Description - * seq_write uses seq_file seq_write() to write the data. + * **bpf_seq_write**\ () uses seq_file **seq_write**\ () to write the data. * The *m* represents the seq_file. The *data* and *len* represent the - * data to write in bytes. + * data to write in bytes. * Return - * 0 on success, or a negative errno in case of failure. + * 0 on success, or a negative error in case of failure: * - * * **-EOVERFLOW** Overflow happens, the same object will be tried again. + * **-EOVERFLOW** if an overflow happened: The same object will be tried again. */ #define __BPF_FUNC_MAPPER(FN) \ FN(unspec), \ diff --git a/scripts/bpf_helpers_doc.py b/scripts/bpf_helpers_doc.py index ded304c96a05..91fa668fa860 100755 --- a/scripts/bpf_helpers_doc.py +++ b/scripts/bpf_helpers_doc.py @@ -318,6 +318,11 @@ may be interested in: of eBPF maps are used with a given helper function. * *kernel/bpf/* directory contains other files in which additional helpers are defined (for cgroups, sockmaps, etc.). +* The bpftool utility can be used to probe the availability of helper functions + on the system (as well as supported program and map types, and a number of + other parameters). To do so, run **bpftool feature probe** (see + **bpftool-feature**\ (8) for details). Add the **unprivileged** keyword to + list features available to unprivileged users. Compatibility between helper functions and program types can generally be found in the files where helper functions are defined. Look for the **struct @@ -338,6 +343,7 @@ SEE ALSO ======== **bpf**\ (2), +**bpftool**\ (8), **cgroups**\ (7), **ip**\ (8), **perf_event_open**\ (2), From patchwork Mon May 11 13:38:07 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Quentin Monnet X-Patchwork-Id: 1287741 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Original-To: patchwork-incoming-netdev@ozlabs.org Delivered-To: patchwork-incoming-netdev@ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=vger.kernel.org (client-ip=23.128.96.18; helo=vger.kernel.org; envelope-from=netdev-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=isovalent.com Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=isovalent-com.20150623.gappssmtp.com header.i=@isovalent-com.20150623.gappssmtp.com header.a=rsa-sha256 header.s=20150623 header.b=uSvHUSRX; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by ozlabs.org (Postfix) with ESMTP id 49LMTK0h4Fz9sSr for ; Mon, 11 May 2020 23:38:29 +1000 (AEST) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729964AbgEKNi1 (ORCPT ); Mon, 11 May 2020 09:38:27 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59682 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-FAIL-OK-FAIL) by vger.kernel.org with ESMTP id S1729931AbgEKNi0 (ORCPT ); Mon, 11 May 2020 09:38:26 -0400 Received: from mail-wm1-x342.google.com (mail-wm1-x342.google.com [IPv6:2a00:1450:4864:20::342]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9AC0EC061A0C for ; Mon, 11 May 2020 06:38:25 -0700 (PDT) Received: by mail-wm1-x342.google.com with SMTP id h4so18078032wmb.4 for ; Mon, 11 May 2020 06:38:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=isovalent-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=nn3QJVCLtMqQCDVuxpusYbBzp2Vc+q+5U4KtJW9U8QA=; b=uSvHUSRX5cNhnR34KdowI6ucIwo8CVsczRi+TND5V+d/E6Upykvc1LHYvgeAXv9Jw6 CPzd2KYapEWprUdxQVTKMqEM5i6mNaH/cGDUU0bO2dV4eMv2fg1YD3ACTGHpiBVwZhM6 iT1XEjowzTd7CS9ipozE04XVAJvSZT3co/X2ZRRs/Pd90WUC94M4JAbEDKNSKAJu8yiG YrMjbmWdMmX4hc4VXuUXSxmCQtpK2uUNCc5vsct0o6kcIpq0UQka1xpL30NAvjkmM+Xw CWsLV5qC1b6W23itTqexZcg+zZqYOPXTRmkTgKIpETVCelD+94EBX94DkBctJwWuU6KC O4iQ== 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=nn3QJVCLtMqQCDVuxpusYbBzp2Vc+q+5U4KtJW9U8QA=; b=bmxhqP31Fyv6XsPnoHCKqBhvIyOyreJ4K9BWcoLODlSVMWx20ghGy0cAyfeorLEVrQ Ti8lo2+1u4fQKB6aAAlzos89xKzdX9Nw2BMsPeU8BV+uFalvXIZgkcCOYdczPqpfnKKL WRUfvhLHfUjdsjsEFmhkawND/O0U05CSadGe7tH3mEFb4yiB/uf8rSXfU3DlSkNHD89A B8Ps5TU0W2meWxeKxUEBSfsyicVWM89CAWSii1qzd9f/38CP0m5MRAtWuxinwMJ7WW3I UTKBgOtVcEXZvqX7MilNU7c03tcOwVYqhXHYj8u1JPt2YSn5K7JSHc9LwOL3U5QZoS7/ Cc2w== X-Gm-Message-State: AGi0Pub5NOCTQ6QtTGhOJXvSiGQ5O26eUif0iMie8ix0JIdOwZ5LdcIp 2WAv/1UjdZvyLeGAtKytpAGyag== X-Google-Smtp-Source: APiQypI2PsFfqd2NdcoIoqdH+JJRC0ggKAEUEEujxLFK5svSIx0rhoIxNmpiUEl1mdX73ue+JQ00pA== X-Received: by 2002:a7b:c399:: with SMTP id s25mr30591748wmj.169.1589204304078; Mon, 11 May 2020 06:38:24 -0700 (PDT) Received: from localhost.localdomain ([194.53.185.84]) by smtp.gmail.com with ESMTPSA id p4sm6932371wrq.31.2020.05.11.06.38.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2020 06:38:23 -0700 (PDT) From: Quentin Monnet To: Alexei Starovoitov , Daniel Borkmann Cc: bpf@vger.kernel.org, netdev@vger.kernel.org, Quentin Monnet Subject: [PATCH bpf-next 4/4] tools: bpf: synchronise BPF UAPI header with tools Date: Mon, 11 May 2020 14:38:07 +0100 Message-Id: <20200511133807.26495-5-quentin@isovalent.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200511133807.26495-1-quentin@isovalent.com> References: <20200511133807.26495-1-quentin@isovalent.com> MIME-Version: 1.0 Sender: netdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org Synchronise the bpf.h header under tools, to report the fixes recently brought to the documentation for the BPF helpers. Signed-off-by: Quentin Monnet --- tools/include/uapi/linux/bpf.h | 109 ++++++++++++++++++--------------- 1 file changed, 59 insertions(+), 50 deletions(-) diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h index 9d1932e23cec..bfb31c1be219 100644 --- a/tools/include/uapi/linux/bpf.h +++ b/tools/include/uapi/linux/bpf.h @@ -675,8 +675,8 @@ union bpf_attr { * For tracing programs, safely attempt to read *size* bytes from * kernel space address *unsafe_ptr* and store the data in *dst*. * - * Generally, use bpf_probe_read_user() or bpf_probe_read_kernel() - * instead. + * Generally, use **bpf_probe_read_user**\ () or + * **bpf_probe_read_kernel**\ () instead. * Return * 0 on success, or a negative error in case of failure. * @@ -684,7 +684,7 @@ union bpf_attr { * Description * Return the time elapsed since system boot, in nanoseconds. * Does not include time the system was suspended. - * See: clock_gettime(CLOCK_MONOTONIC) + * See: **clock_gettime**\ (**CLOCK_MONOTONIC**) * Return * Current *ktime*. * @@ -1543,11 +1543,11 @@ union bpf_attr { * int bpf_probe_read_str(void *dst, u32 size, const void *unsafe_ptr) * Description * Copy a NUL terminated string from an unsafe kernel address - * *unsafe_ptr* to *dst*. See bpf_probe_read_kernel_str() for + * *unsafe_ptr* to *dst*. See **bpf_probe_read_kernel_str**\ () for * more details. * - * Generally, use bpf_probe_read_user_str() or bpf_probe_read_kernel_str() - * instead. + * Generally, use **bpf_probe_read_user_str**\ () or + * **bpf_probe_read_kernel_str**\ () instead. * Return * On success, the strictly positive length of the string, * including the trailing NUL character. On error, a negative @@ -1575,7 +1575,7 @@ union bpf_attr { * * u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx) * Description - * Equivalent to bpf_get_socket_cookie() helper that accepts + * Equivalent to **bpf_get_socket_cookie**\ () helper that accepts * *skb*, but gets socket from **struct bpf_sock_ops** context. * Return * A 8-byte long non-decreasing number. @@ -1604,6 +1604,7 @@ union bpf_attr { * The option value of length *optlen* is pointed by *optval*. * * *bpf_socket* should be one of the following: + * * * **struct bpf_sock_ops** for **BPF_PROG_TYPE_SOCK_OPS**. * * **struct bpf_sock_addr** for **BPF_CGROUP_INET4_CONNECT** * and **BPF_CGROUP_INET6_CONNECT**. @@ -1672,12 +1673,12 @@ union bpf_attr { * * The lower two bits of *flags* are used as the return code if * the map lookup fails. This is so that the return value can be - * one of the XDP program return codes up to XDP_TX, as chosen by - * the caller. Any higher bits in the *flags* argument must be + * one of the XDP program return codes up to **XDP_TX**, as chosen + * by the caller. Any higher bits in the *flags* argument must be * unset. * - * See also bpf_redirect(), which only supports redirecting to an - * ifindex, but doesn't require a map to do so. + * See also **bpf_redirect**\ (), which only supports redirecting + * to an ifindex, but doesn't require a map to do so. * Return * **XDP_REDIRECT** on success, or the value of the two lower bits * of the *flags* argument on error. @@ -1785,7 +1786,7 @@ union bpf_attr { * the time running for event since last normalization. The * enabled and running times are accumulated since the perf event * open. To achieve scaling factor between two invocations of an - * eBPF program, users can can use CPU id as the key (which is + * eBPF program, users can use CPU id as the key (which is * typical for perf array usage model) to remember the previous * value and do the calculation inside the eBPF program. * Return @@ -1812,6 +1813,7 @@ union bpf_attr { * *opval* and of length *optlen*. * * *bpf_socket* should be one of the following: + * * * **struct bpf_sock_ops** for **BPF_PROG_TYPE_SOCK_OPS**. * * **struct bpf_sock_addr** for **BPF_CGROUP_INET4_CONNECT** * and **BPF_CGROUP_INET6_CONNECT**. @@ -1833,7 +1835,7 @@ union bpf_attr { * The first argument is the context *regs* on which the kprobe * works. * - * This helper works by setting setting the PC (program counter) + * This helper works by setting the PC (program counter) * to an override function which is run in place of the original * probed function. This means the probed function is not run at * all. The replacement function just returns with the required @@ -2300,7 +2302,7 @@ union bpf_attr { * **bpf_rc_keydown**\ () again with the same values, or calling * **bpf_rc_repeat**\ (). * - * Some protocols include a toggle bit, in case the button was + * Some protocols include a toggle bit, in case the button was * released and pressed again between consecutive scancodes. * * The *ctx* should point to the lirc sample as passed into @@ -2646,7 +2648,6 @@ union bpf_attr { * * *th* points to the start of the TCP header, while *th_len* * contains **sizeof**\ (**struct tcphdr**). - * * Return * 0 if *iph* and *th* are a valid SYN cookie ACK, or a negative * error otherwise. @@ -2829,7 +2830,6 @@ union bpf_attr { * * *th* points to the start of the TCP header, while *th_len* * contains the length of the TCP header. - * * Return * On success, lower 32 bits hold the generated SYN cookie in * followed by 16 bits which hold the MSS value for that cookie, @@ -2912,7 +2912,7 @@ union bpf_attr { * // size, after checking its boundaries. * } * - * In comparison, using **bpf_probe_read_user()** helper here + * In comparison, using **bpf_probe_read_user**\ () helper here * instead to read the string would require to estimate the length * at compile time, and would often result in copying more memory * than necessary. @@ -2930,14 +2930,14 @@ union bpf_attr { * int bpf_probe_read_kernel_str(void *dst, u32 size, const void *unsafe_ptr) * Description * Copy a NUL terminated string from an unsafe kernel address *unsafe_ptr* - * to *dst*. Same semantics as with bpf_probe_read_user_str() apply. + * to *dst*. Same semantics as with **bpf_probe_read_user_str**\ () apply. * Return - * On success, the strictly positive length of the string, including + * On success, the strictly positive length of the string, including * the trailing NUL character. On error, a negative value. * * int bpf_tcp_send_ack(void *tp, u32 rcv_nxt) * Description - * Send out a tcp-ack. *tp* is the in-kernel struct tcp_sock. + * Send out a tcp-ack. *tp* is the in-kernel struct **tcp_sock**. * *rcv_nxt* is the ack_seq to be sent out. * Return * 0 on success, or a negative error in case of failure. @@ -2965,19 +2965,19 @@ union bpf_attr { * int bpf_read_branch_records(struct bpf_perf_event_data *ctx, void *buf, u32 size, u64 flags) * Description * For an eBPF program attached to a perf event, retrieve the - * branch records (struct perf_branch_entry) associated to *ctx* - * and store it in the buffer pointed by *buf* up to size + * branch records (**struct perf_branch_entry**) associated to *ctx* + * and store it in the buffer pointed by *buf* up to size * *size* bytes. * Return * On success, number of bytes written to *buf*. On error, a * negative value. * * The *flags* can be set to **BPF_F_GET_BRANCH_RECORDS_SIZE** to - * instead return the number of bytes required to store all the + * instead return the number of bytes required to store all the * branch entries. If this flag is set, *buf* may be NULL. * * **-EINVAL** if arguments invalid or **size** not a multiple - * of sizeof(struct perf_branch_entry). + * of **sizeof**\ (**struct perf_branch_entry**\ ). * * **-ENOENT** if architecture does not support branch records. * @@ -2985,8 +2985,8 @@ union bpf_attr { * Description * Returns 0 on success, values for *pid* and *tgid* as seen from the current * *namespace* will be returned in *nsdata*. - * - * On failure, the returned value is one of the following: + * Return + * 0 on success, or one of the following in case of failure: * * **-EINVAL** if dev and inum supplied don't match dev_t and inode number * with nsfs of current task, or if dev conversion to dev_t lost high bits. @@ -3025,8 +3025,8 @@ union bpf_attr { * a global identifier that can be assumed unique. If *ctx* is * NULL, then the helper returns the cookie for the initial * network namespace. The cookie itself is very similar to that - * of bpf_get_socket_cookie() helper, but for network namespaces - * instead of sockets. + * of **bpf_get_socket_cookie**\ () helper, but for network + * namespaces instead of sockets. * Return * A 8-byte long opaque number. * @@ -3061,57 +3061,66 @@ union bpf_attr { * * The *flags* argument must be zero. * Return - * 0 on success, or a negative errno in case of failure. + * 0 on success, or a negative error in case of failure: * - * * **-EINVAL** Unsupported flags specified. - * * **-ENOENT** Socket is unavailable for assignment. - * * **-ENETUNREACH** Socket is unreachable (wrong netns). - * * **-EOPNOTSUPP** Unsupported operation, for example a - * call from outside of TC ingress. - * * **-ESOCKTNOSUPPORT** Socket type not supported (reuseport). + * **-EINVAL** if specified *flags* are not supported. + * + * **-ENOENT** if the socket is unavailable for assignment. + * + * **-ENETUNREACH** if the socket is unreachable (wrong netns). + * + * **-EOPNOTSUPP** if the operation is not supported, for example + * a call from outside of TC ingress. + * + * **-ESOCKTNOSUPPORT** if the socket type is not supported + * (reuseport). * * u64 bpf_ktime_get_boot_ns(void) * Description * Return the time elapsed since system boot, in nanoseconds. * Does include the time the system was suspended. - * See: clock_gettime(CLOCK_BOOTTIME) + * See: **clock_gettime**\ (**CLOCK_BOOTTIME**) * Return * Current *ktime*. * * int bpf_seq_printf(struct seq_file *m, const char *fmt, u32 fmt_size, const void *data, u32 data_len) * Description - * seq_printf uses seq_file seq_printf() to print out the format string. + * **bpf_seq_printf**\ () uses seq_file **seq_printf**\ () to print + * out the format string. * The *m* represents the seq_file. The *fmt* and *fmt_size* are for * the format string itself. The *data* and *data_len* are format string - * arguments. The *data* are a u64 array and corresponding format string + * arguments. The *data* are a **u64** array and corresponding format string * values are stored in the array. For strings and pointers where pointees * are accessed, only the pointer values are stored in the *data* array. - * The *data_len* is the *data* size in term of bytes. + * The *data_len* is the size of *data* in bytes. * * Formats **%s**, **%p{i,I}{4,6}** requires to read kernel memory. * Reading kernel memory may fail due to either invalid address or * valid address but requiring a major memory fault. If reading kernel memory * fails, the string for **%s** will be an empty string, and the ip * address for **%p{i,I}{4,6}** will be 0. Not returning error to - * bpf program is consistent with what bpf_trace_printk() does for now. + * bpf program is consistent with what **bpf_trace_printk**\ () does for now. * Return - * 0 on success, or a negative errno in case of failure. + * 0 on success, or a negative error in case of failure: + * + * **-EBUSY** if per-CPU memory copy buffer is busy, can try again + * by returning 1 from bpf program. + * + * **-EINVAL** if arguments are invalid, or if *fmt* is invalid/unsupported. + * + * **-E2BIG** if *fmt* contains too many format specifiers. * - * * **-EBUSY** Percpu memory copy buffer is busy, can try again - * by returning 1 from bpf program. - * * **-EINVAL** Invalid arguments, or invalid/unsupported formats. - * * **-E2BIG** Too many format specifiers. - * * **-EOVERFLOW** Overflow happens, the same object will be tried again. + * **-EOVERFLOW** if an overflow happened: The same object will be tried again. * * int bpf_seq_write(struct seq_file *m, const void *data, u32 len) * Description - * seq_write uses seq_file seq_write() to write the data. + * **bpf_seq_write**\ () uses seq_file **seq_write**\ () to write the data. * The *m* represents the seq_file. The *data* and *len* represent the - * data to write in bytes. + * data to write in bytes. * Return - * 0 on success, or a negative errno in case of failure. + * 0 on success, or a negative error in case of failure: * - * * **-EOVERFLOW** Overflow happens, the same object will be tried again. + * **-EOVERFLOW** if an overflow happened: The same object will be tried again. */ #define __BPF_FUNC_MAPPER(FN) \ FN(unspec), \