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: 188657 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:42cf:b0:101:a8e8:374 with SMTP id q15csp655332dye; Tue, 16 Jan 2024 18:36:41 -0800 (PST) X-Google-Smtp-Source: AGHT+IF53pUTXwWkKScBpoqmsL+jZ/KKGOkxam1C7obN62qEsVLgDaHuUp16aiod8Jj8TOLyWqgl X-Received: by 2002:ae9:e007:0:b0:783:4d8:d178 with SMTP id m7-20020ae9e007000000b0078304d8d178mr9007078qkk.119.1705459001486; Tue, 16 Jan 2024 18:36:41 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1705459001; cv=pass; d=google.com; s=arc-20160816; b=r3+Fxhyf0D4Lsl3v0T2rjKddfdwQsMP8GTdx91EkN46i4hhG5UFYGlKXCmJQVuquoZ x3J/eb9Zx+nXVIOLek5k47KO7MXQK9TGZBQi4Cn4EWl4RrvxBVsfivPGqsaf+kpDNHsl o/juxjMCxqlKP19sizd2j7kda4C03TxM++BUtXxvZx/n0D8w+a1zBszWiZqYciWNzqu1 9O+vMgmb1MsMqZKbRmEV62xOB2oSx0sWXBL3tK9RNIbeVIosdi/4linDzVDl+cy8KEwB tviXvE/RSJpTYxP1pMmjENaAR9fPQIobDNjJyClDl4n6JUlLUQSVyhGKgkqq9SxeyyoO W+kw== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:message-id:date:subject:to:from:ironport-sdr :arc-filter:dmarc-filter:delivered-to; bh=WGLSs17KT6gO3lUjUOByMk6VyvRRaH4QQ0QVoQ1tPME=; fh=gk9A5O7Gbglvz1MjrRQ4hZ2i3c68kYkpOZJg1emXh+g=; b=g2jlGzw8af+caVjRiVFdCPw8w+EBY/uV2rPlzQWtqyq2HQZEad9hnfLvy/lTH2fyAI iRv0E9LWAy45uJTNZmVJWuEjwIJAx9FjA0rwxiB5m3yhlf8sDKnwiPD/hjfrZmpqtGo2 JrTso7x05k2WM5G9hqmCXHt0tC1Tt+Dl2us+Nkj14xN/Vxd5DDIvJugv5onPcCTGx6Kb HhsCfvf1yNm3caIPmplMHGBbWVHRzj5OvSIxEMEXBR7uqN0vXJQTGjNn77heenfzC/wI vTip5kryMCx/s4GSBq4tjbKUK0ru4YJGJGxB6pWOW3884AGh5J3m0jUbBzgpYPRgGWeB xqbw== ARC-Authentication-Results: i=2; mx.google.com; arc=pass (i=1); spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org" Received: from server2.sourceware.org (server2.sourceware.org. [8.43.85.97]) by mx.google.com with ESMTPS id h15-20020a05620a21cf00b007831a560be0si10941140qka.280.2024.01.16.18.36.41 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Jan 2024 18:36:41 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 as permitted sender) client-ip=8.43.85.97; Authentication-Results: mx.google.com; arc=pass (i=1); spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org" Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 352FB3858410 for ; Wed, 17 Jan 2024 02:36:41 +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+ouuuleilei=gmail.com@gcc.gnu.org X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788303377917957911 X-GMAIL-MSGID: 1788303377917957911 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