From patchwork Wed Jan 17 02:35:40 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 84222 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 49F023858C3A for ; Wed, 17 Jan 2024 02:36:27 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa3.mentor.iphmx.com (esa3.mentor.iphmx.com [68.232.137.180]) by sourceware.org (Postfix) with ESMTPS id C8C673858C53 for ; Wed, 17 Jan 2024 02:35:56 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org C8C673858C53 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org C8C673858C53 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=68.232.137.180 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705458959; cv=none; b=YzezQSx7RSXSbUmxxOcG7qdIxZKe7tqkcA+1c3RbPWpWWkKBq1TmXuV85anehYK1y41cDBoiuAeZokQ/5uF8Oi0spRHJjMY8S9Vqy84aBBclADq4qbGT9bXHJvr5rI2hyjUOcAjxfJYQgj6ONv19dixiVknIbsiW3dR5QHOIf4Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705458959; c=relaxed/simple; bh=wn4fGMr15XoXc0vjE0OIQjWLs/cRTXz/00N03mQQv6A=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=kIr7TaZpvDyytjmZuy7ad8MXINX51mD5C0QXQ+N6j0NytU5qFUdMhxNUR1cMosBZA7wv40kqu3d5sLhWB+Ve+5OOaOKkSoS7jm6bn85xqSpurn68Raqxm7DoVCya5JCYx9Pbrbes7SSlAh5RBlIklBT+zuXjMyW5iqwTaxRtAmA= ARC-Authentication-Results: i=1; server2.sourceware.org X-CSE-ConnectionGUID: 9GkppyJQRVeEk38I/iLYUg== X-CSE-MsgGUID: fz1pHKCWQJK/38OuJOrLkQ== X-IronPort-AV: E=Sophos;i="6.05,200,1701158400"; d="scan'208";a="28191461" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa3.mentor.iphmx.com with ESMTP; 16 Jan 2024 18:35:53 -0800 IronPort-SDR: S2kocO+ckguYPoopywMMZ4ESLcjfpmB7XiP7Qd1mj7qjU0qB07BDBg0PCiPzfzgyVM1GSbNJKM eyQVXmWkwkwNMYqTS9TaEdY3FzO58sqWZLDmQMJ2tDEkDFSbAYX2zC8D+yhE9Sqb9V1lA6IBQG 1epQw/U05Ld3h+yV/n/yW3V32sTy7JY+SiLo62vQECIYh1V5W5YoDtyLPCJThnPodxYDGxYXnL 00bIWxaWlyCJ8i4e62uUIx9lr5PYXL9YQAIBy5rr7qBNOOX6+AzdA91MzOAdWmSKL0hfDBbMTN Odg= From: Sandra Loosemore To: Subject: [COMITTED] Tidy documentation for BPF builtins [PR112973] Date: Tue, 16 Jan 2024 19:35:40 -0700 Message-ID: <20240117023540.344749-1-sandra@codesourcery.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 X-ClientProxiedBy: svr-orw-mbx-14.mgc.mentorg.com (147.34.90.214) To svr-orw-mbx-13.mgc.mentorg.com (147.34.90.213) X-Spam-Status: No, score=-10.1 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, SPF_HELO_PASS, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org gcc/Changelog PR target/112973 * doc/extend.texi (BPF Built-in Functions): Wrap long lines and give the section a light copy-editing pass. --- gcc/doc/extend.texi | 38 ++++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index b9129d1b464..89e823629e3 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -16832,19 +16832,27 @@ void __builtin_bfin_ssync (void); The following built-in functions are available for eBPF targets. @defbuiltin{{unsigned long long} __builtin_bpf_load_byte (unsigned long long @var{offset})} -Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. +Load a byte from the @code{struct sk_buff} packet data pointed to by the +register @code{%r6}, and return it. @enddefbuiltin @defbuiltin{{unsigned long long} __builtin_bpf_load_half (unsigned long long @var{offset})} -Load 16 bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. +Load 16 bits from the @code{struct sk_buff} packet data pointed to by the +register @code{%r6}, and return it. @enddefbuiltin @defbuiltin{{unsigned long long} __builtin_bpf_load_word (unsigned long long @var{offset})} -Load 32 bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. +Load 32 bits from the @code{struct sk_buff} packet data pointed to by the +register @code{%r6}, and return it. @enddefbuiltin -@defbuiltin{{void *} __builtin_preserve_access_index (@var{expr})} -BPF Compile Once-Run Everywhere (CO-RE) support. Instruct GCC to generate CO-RE relocation records for any accesses to aggregate data structures (struct, union, array types) in @var{expr}. This builtin is otherwise transparent, the return value is whatever @var{expr} evaluates to. It is also overloaded: @var{expr} may be of any type (not necessarily a pointer), the return type is the same. Has no effect if @code{-mco-re} is not in effect (either specified or implied). +@defbuiltin{@var{type} __builtin_preserve_access_index (@var{type} @var{expr})} +BPF Compile Once-Run Everywhere (CO-RE) support. Instruct GCC to +generate CO-RE relocation records for any accesses to aggregate +data structures (struct, union, array types) in @var{expr}. This builtin +is otherwise transparent; @var{expr} may have any type and its value is +returned. This builtin has no effect if @code{-mco-re} is not in effect +(either specified or implied). @enddefbuiltin @defbuiltin{{unsigned int} __builtin_preserve_field_info (@var{expr}, unsigned int @var{kind})} @@ -16946,36 +16954,38 @@ The return value is the enum value in the target kernel. @defbuiltin{{unsigned int} __builtin_btf_type_id (@var{type}, unsigned int @var{kind})} BPF Compile Once-Run Everywhere (CO-RE) support. This builtin is used to get -the BTF type ID of a specified type. Depending on the @var{kind} argument, it -will either return the ID of the local BTF information, or the BTF type ID in +the BTF type ID of a specified @var{type}. +Depending on the @var{kind} argument, it +either returns the ID of the local BTF information, or the BTF type ID in the target kernel. The following values are supported for @var{kind}: @table @code @item BTF_TYPE_ID_LOCAL = 0 -Return the local BTF type ID. Always succeeds. +Return the local BTF type ID. Always succeeds. @item BTF_TYPE_ID_TARGET = 1 -Return the target BTF type ID. If type does not exist in the target, returns 0. +Return the target BTF type ID. If @var{type} does not exist in the target, +returns 0. @end table @enddefbuiltin @defbuiltin{{unsigned int} __builtin_preserve_type_info (@var{type}, unsigned int @var{kind})} BPF Compile Once-Run Everywhere (CO-RE) support. This builtin performs named type (struct/union/enum/typedef) verifications. The type of verification -dependents on the @var{kind} argument provided. This builtin will always -return 0 if type does not exists in the target kernel. +depends on the @var{kind} argument provided. This builtin always +returns 0 if @var{type} does not exist in the target kernel. The following values are supported for @var{kind}: @table @code @item BTF_TYPE_EXISTS = 0 -Checks if type exists in the target. +Checks if @var{type} exists in the target. @item BTF_TYPE_MATCHES = 1 -Checks if type matches the local definition in the target kernel. +Checks if @var{type} matches the local definition in the target kernel. @item BTF_TYPE_SIZE = 2 -Returns the size of the type within the target. +Returns the size of the @var{type} within the target. @end table @enddefbuiltin