[committed] Docs: Fix formatting issues in BPF built-ins documentation
Commit Message
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
Comments
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 <sandra@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
commit 7ffbc74c8c202a16a5e987134f03c2359c531f0e
Author: Sandra Loosemore <sandra@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.
@@ -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