diff mbox series

[8/9] doc: document new attributes

Message ID 20220607214342.19463-9-david.faust@oracle.com
State New
Headers
Series Add debug_annotate attributes |

Commit Message

David Faust June 7, 2022, 9:43 p.m. UTC 
  gcc/

	* doc/extend.texi (Common Function Attributes): Document
	debug_annotate_decl attribute.
	(Common Variable Attributes): Likewise.
	(Common Type Attributes): Likewise. Also document
	debug_annotate_type attribute.
---
 gcc/doc/extend.texi | 106 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
diff mbox series

Patch

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index a2e2a303ff1..a4c114f0e81 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -2931,6 +2931,30 @@  extern __attribute__ ((alloc_size (1), malloc, nothrow))
 StrongAlias (allocate, alloc);
 @end smallexample
 
+@item debug_annotate_decl (@var{annotation})
+@cindex @code{debug_annotate_decl} function attribute
+The @code{debug_annotate_decl} attribute is used to add arbitrary
+string annotations to the debugging information produced for a given
+declaration. The attribute accepts a single string argument, and may be
+specified multiple times for a single declaration. The behavior is
+to record the string argument in debug information generated for the
+declaration. Currently, DWARF and BTF debug information are supported.
+There is no effect on code generation; the attribute has no effect at
+all if neither DWARF nor BTF are output.
+
+@smallexample
+int foo (int a, int b) __attribute__((debug_annotate_decl ("my_tag")));
+@end smallexample
+
+@noindent
+results in a DW_TAG_GNU_annotation DIE associating the string ``my_tag''
+to the function ``foo'', and/or a BTF_KIND_DECL_TAG BTF record to the
+same effect.
+
+The @code{debug_annotate_decl} attribute can also be used for
+variables and types (@pxref{Common Variable Attributes},
+@pxref{Common Type Attributes}.)
+
 @item deprecated
 @itemx deprecated (@var{msg})
 @cindex @code{deprecated} function attribute
@@ -7510,6 +7534,42 @@  but not attributes that affect a symbol's linkage or visibility such as
 attribute is also not copied.  @xref{Common Function Attributes}.
 @xref{Common Type Attributes}.
 
+@item debug_annotate_decl (@var{annotation})
+@cindex @code{debug_annotate_decl} variable attribute
+The @code{debug_annotate_decl} attribute is used to add arbitrary
+string annotations to the debugging information produced for a given
+declaration. The attribute accepts a single string argument, and may be
+specified multiple times for a single declaration. The behavior is
+to record the string argument in debug information generated for the
+declaration. Currently, DWARF and BTF debug information are supported.
+There is no effect on code generation; the attribute has no effect at
+all if neither DWARF nor BTF are output.
+
+@smallexample
+int my_var __attribute__((debug_annotate_decl ("my_tag")))
+@end smallexample
+
+@noindent
+results in a DW_TAG_GNU_annotation DIE associating the string ``my_tag''
+to the ``my_var'', and/or a BTF_KIND_DECL_TAG BTF record to the same
+effect.
+
+Annotations can be specified for declarations other than variables,
+such as struct fields. For example:
+
+@smallexample
+struct foo @{
+  int * x __attribute__ ((debug_annotate_decl ("my_tag")));
+@};
+@end smallexample
+has similar results, producing debug info which associates the string
+``my_tag'' to the struct field ``x''.
+
+@noindent
+The @code{debug_annotate_decl} attribute can also be used for
+functions and types (@pxref{Common Function Attributes},
+@pxref{Common Type Attributes}.)
+
 @item deprecated
 @itemx deprecated (@var{msg})
 @cindex @code{deprecated} variable attribute
@@ -8593,6 +8653,52 @@  A @{ /* @r{@dots{}} */ @};
 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
 @end smallexample
 
+@item debug_annotate_decl (@var{annotation})
+@cindex @code{debug_annotate_decl} type attribute
+The @code{debug_annotate_decl} attribute is used to add arbitrary
+string annotations to the debugging information produced for a given
+type declaration. The attribute accepts a single string argument, and
+may be specified multiple times for a type declaration. The behavior
+is to record the string argument in the debug information generated
+for the declaration. Currently, DWARF and BTF debug information are
+supported. There is no effect on code generation; the attribute has no
+effect at all if neither DWARF nor BTF are output.
+
+@smallexample
+struct t @{
+/* @r{@dots{}} */
+@} __attribute__((debug_annotate_decl ("my_tag")));
+@end smallexample
+
+@noindent
+results in a DW_TAG_GNU_annotation DIE associating the string
+``my_tag'' to the ``struct t'', and/or a BTF_KIND_DECL_TAG BTF record
+to the same effect.
+
+The @code{debug_annotate_decl} attribute can also be used for
+variables and functions (@pxref{Common Variable Attributes},
+@pxref{Common Function Attributes}.)
+
+@item debug_annotate_type (@var{annotation})
+@cindex @code{debug_annotate_type} type attribute
+The @code{debug_annotate_type} attribute is used to add arbitrary
+string annotations to the debugging information produced for a given
+type. The attribute accepts a single string argument, and may be
+specified multiple times for a type declaration. The behavior is to
+record the string argument in the debug information generated for the
+type. Currently, DWARF and BTF debug information are supported. There
+is no effect on code generation; the attribute has no effect at all if
+neither DWARF nor BTF are output.
+
+@smallexample
+int * __attribute__ ((debug_annotate_type ("foo"))) x;
+@end smallexample
+
+@noindent
+results in a DW_TAG_GNU_annotation DIE associating the string ``foo''
+to the pointer type of ``x'' in the case of DWARF, and/or a
+BTF_KIND_TYPE_TAG entry to the same effect in case of BTF debug info.
+
 @item deprecated
 @itemx deprecated (@var{msg})
 @cindex @code{deprecated} type attribute