From patchwork Fri Mar 17 04:02:04 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 66494 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 BF828385041A for ; Fri, 17 Mar 2023 04:02:31 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa1.mentor.iphmx.com (esa1.mentor.iphmx.com [68.232.129.153]) by sourceware.org (Postfix) with ESMTPS id 741E238515D6 for ; Fri, 17 Mar 2023 04:02:09 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 741E238515D6 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com X-IronPort-AV: E=Sophos;i="5.98,267,1673942400"; d="scan'208";a="104683650" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa1.mentor.iphmx.com with ESMTP; 16 Mar 2023 20:02:07 -0800 IronPort-SDR: +Q/tYKr+v0qJqN4N4CNuVnyLE5ftdzyzQrHANDQZJVpT86Vd58vCv0B3Rw8fw812NQnNO2D7uN hh4u8yOmKGzgnMBb6PlL0QWuiRk43oPj9P12oKiDYRjtqno4rzvgdEPQ9T8DlbdiBu0GQsimXp aAHi1qXHpBeVDQJoCfUMSy1hVyBqQrIJOZo6u1UKPV8rbE+KZxpIwk4RoI4if8IUOUrq0hQJiT emtGIhEJeWrDcXhygBH9k8ZHfSXBk8NDR0ghWb4nHe8Nqlse2F/E6JeZDzjE57XA6YmazEsrlh iCE= Message-ID: Date: Thu, 16 Mar 2023 22:02:04 -0600 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.7.1 Content-Language: en-US To: "gcc-patches@gcc.gnu.org" CC: "Jose E. Marchesi" From: Sandra Loosemore Subject: [committed] Docs: Fix formatting issues in BPF built-ins documentation X-ClientProxiedBy: svr-orw-mbx-15.mgc.mentorg.com (147.34.90.215) To svr-orw-mbx-13.mgc.mentorg.com (147.34.90.213) X-Spam-Status: No, score=-9.8 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, SPF_HELO_PASS, SPF_PASS, TXREP 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.29 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 Sender: "Gcc-patches" This section of the GCC manual had some issues with lines in the example overflowing into the right margin of the PDF-format document, but as I looked at it more closely I also saw that it was full of missing or incorrect Texinfo markup, too. I've cleaned it up thusly. -Sandra commit 7ffbc74c8c202a16a5e987134f03c2359c531f0e Author: Sandra Loosemore Date: Thu Mar 16 21:07:18 2023 +0000 Docs: Fix formatting issues in BPF built-ins documentation. gcc/ChangeLog: * doc/extend.texi (BPF Built-in Functions): Fix numerous markup issues. Add more line breaks to example so it doesn't overflow the margins. diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 39d45df8d89..8ecd9611201 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -15715,23 +15715,23 @@ void __builtin_bfin_ssync (void); The following built-in functions are available for eBPF targets. -@deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset}) +@deftypefn {Built-in Function} {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. @end deftypefn -@deftypefn {Built-in Function} 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. +@deftypefn {Built-in Function} {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. @end deftypefn -@deftypefn {Built-in Function} 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. +@deftypefn {Built-in Function} {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. @end deftypefn -@deftypefn {Built-in Function} void * __builtin_preserve_access_index (@var{expr}) +@deftypefn {Built-in Function} {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). @end deftypefn -@deftypefn {Built-in Function} unsigned int __builtin_preserve_field_info (@var{expr}, unsigned int @var{kind}) +@deftypefn {Built-in Function} {unsigned int} __builtin_preserve_field_info (@var{expr}, unsigned int @var{kind}) BPF Compile Once-Run Everywhere (CO-RE) support. This builtin is used to extract information to aid in struct/union relocations. @var{expr} is an access to a field of a struct or union. Depending on @var{kind}, different @@ -15739,15 +15739,15 @@ information is returned to the program. A CO-RE relocation for the access in @var{expr} with kind @var{kind} is recorded if @code{-mco-re} is in effect. The following values are supported for @var{kind}: -@table @var +@table @code @item FIELD_BYTE_OFFSET = 0 The returned value is the offset, in bytes, of the field from the -beginning of the containing structure. For bitfields, the byte offset +beginning of the containing structure. For bit-fields, this is the byte offset of the containing word. @item FIELD_BYTE_SIZE = 1 -The returned value is the size, in bytes, of the field. For bitfields, -the size in bytes of the containing word. +The returned value is the size, in bytes, of the field. For bit-fields, +this is the size in bytes of the containing word. @item FIELD_EXISTENCE = 2 The returned value is 1 if the field exists, 0 otherwise. Always 1 at @@ -15759,25 +15759,26 @@ The returned value is 1 if the field is signed, 0 otherwise. @item FIELD_LSHIFT_U64 = 4 @itemx FIELD_RSHIFT_U64 = 5 The returned value is the number of bits of left- or right-shifting -respectively needed in order to recover the original value of the field, -after it has been loaded by a read of FIELD_BYTE_SIZE bytes into an -unsigned 64-bit value. Primarily useful for reading bitfield values -from structures which may change between kernel versions. +(respectively) needed in order to recover the original value of the field, +after it has been loaded by a read of @code{FIELD_BYTE_SIZE} bytes into an +unsigned 64-bit value. Primarily useful for reading bit-field values +from structures that may change between kernel versions. @end table Note that the return value is a constant which is known at -compile-time. If the field has a variable offset then -FIELD_BYTE_OFFSET, FIELD_LSHIFT_U64 and FIELD_RSHIFT_U64 are not -supported. Similarly, if the field has a variable size then -FIELD_BYTE_SIZE, FIELD_LSHIFT_U64 and FIELD_RSHIFT_U64 are not -supported. - -For example, __builtin_preserve_field_info can be used to reliably -extract bitfield values from a structure which may change between +compile time. If the field has a variable offset then +@code{FIELD_BYTE_OFFSET}, @code{FIELD_LSHIFT_U64}, +and @code{FIELD_RSHIFT_U64} are not supported. +Similarly, if the field has a variable size then +@code{FIELD_BYTE_SIZE}, @code{FIELD_LSHIFT_U64}, +and @code{FIELD_RSHIFT_U64} are not supported. + +For example, @code{__builtin_preserve_field_info} can be used to reliably +extract bit-field values from a structure that may change between kernel versions: -@example +@smallexample struct S @{ short a; @@ -15789,8 +15790,10 @@ int read_y (struct S *arg) @{ unsigned long long val; - unsigned int offset = __builtin_preserve_field_info (arg->y, FIELD_BYTE_OFFSET); - unsigned int size = __builtin_presrve_field_info (arg->y, FIELD_BYTE_SIZE); + unsigned int offset + = __builtin_preserve_field_info (arg->y, FIELD_BYTE_OFFSET); + unsigned int size + = __builtin_preserve_field_info (arg->y, FIELD_BYTE_SIZE); /* Read size bytes from arg + offset into val. */ bpf_probe_read (&val, size, arg + offset); @@ -15798,14 +15801,15 @@ read_y (struct S *arg) val <<= __builtin_preserve_field_info (arg->y, FIELD_LSHIFT_U64); if (__builtin_preserve_field_info (arg->y, FIELD_SIGNEDNESS)) - val = ((long long) val >> __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64)); + val = ((long long) val + >> __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64)); else val >>= __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64); return val; @} -@end example +@end smallexample @end deftypefn @node FR-V Built-in Functions