Hi Sandra.
> 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. Thank you so much for fixing these issues in the manual. Very much appreciated :) > > -Sandra > > commit 7ffbc74c8c202a16a5e987134f03c2359c531f0e > Author: Sandra Loosemore <san...@codesourcery.com> > 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