diff mbox series

[9/9] doc: document btf_decl_tag attribute

Message ID 20230711215716.12980-10-david.faust@oracle.com
State Unresolved
Headers
Series Add btf_decl_tag C attribute |

Checks

Context Check Description
snail/gcc-patch-check warning Git am fail log

Commit Message

David Faust July 11, 2023, 9:57 p.m. UTC 
  Add documentation for the btf_decl_tag attribute.

gcc/

	* doc/extend.texi (Common Function Attributes): Document btf_decl_tag.
	(Common Variable Attributes): Likewise.
---
 gcc/doc/extend.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
diff mbox series

Patch

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index d88fd75e06e..57923621c46 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -2856,6 +2856,29 @@  declares that @code{my_alloc1} returns 16-byte aligned pointers and
 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
 to 8.
 
+@cindex @code{btf_decl_tag} function attribute
+@item btf_type_tag (@var{argument})
+The @code{btf_decl_tag} attribute may be used to associate (to ``tag'')
+function declarations with arbitrary strings.  Debugging information will
+be emitted to associate the @var{argument} string with the attributed function.
+In DWARF, a @code{DW_TAG_GNU_annotation} DIE will be emitted in the DWARF
+information as a child of the DIE for the function and holding the
+@var{argument} string.  In BTF, a @code{BTF_KIND_DECL_TAG} record is emitted
+in the .BTF ELF section.
+
+For example
+
+@smallexample
+extern int bar (char, int) __attribute__((btf_decl_tag("for_user")))
+@end smallexample
+
+associates the string ``for_user'' to the function ``bar''. This
+string will be recorded in the BTF and/or DWARF information associated
+with the function.
+
+The @code{btf_decl_tag} attribute can also be used on variables
+(@pxref{Common Variable Attributes})  and field declarations.
+
 @cindex @code{cold} function attribute
 @item cold
 The @code{cold} attribute on functions is used to inform the compiler that
@@ -7570,6 +7593,30 @@  This warning can be disabled by @option{-Wno-if-not-aligned}.
 The @code{warn_if_not_aligned} attribute can also be used for types
 (@pxref{Common Type Attributes}.)
 
+@cindex @code{btf_decl_tag} variable attribute
+@item btf_decl_tag (@var{argument})
+The @code{btf_decl_tag} attribute may be used to associate (to ``tag'')
+variable declarations with arbitrary strings.  Debugging information will
+be emitted to associate the @var{argument} string with the attributed variable.
+In DWARF, a @code{DW_TAG_GNU_annotation} DIE will be emitted in the DWARF
+information as a child of the DIE for the variable and holding the
+@var{argument} string.  In BTF, a @code{BTF_KIND_DECL_TAG} record is emitted
+in the .BTF ELF section.
+
+For example
+
+@smallexample
+int * foo __attribute__((btf_decl_tag("user")));
+@end smallexample
+
+@noindent
+associates the string ``user'' to the variable ``foo''. This string
+will be recorded in the BTF and/or DWARF information associated with
+the variable.
+
+The @code{btf_decl_tag} attribute can also be used on functions
+(@pxref{Common Function Attributes}) and field declarations.
+
 @cindex @code{strict_flex_array} variable attribute
 @item strict_flex_array (@var{level})
 The @code{strict_flex_array} attribute should be attached to the trailing