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 --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 -- 2.36.1