dwarf: create annotation DIEs for btf tags

dafaust · dafaust · commit ac7027f180b8 · 2025-10-09T14:13:23.000-07:00
The btf_decl_tag and btf_type_tag attributes provide a means to annotate
declarations and types respectively with arbitrary user provided
strings.  These strings are recorded in debug information for
post-compilation uses, and despite the name they are meant to be
recorded in DWARF as well as BTF.  New DWARF extensions
DW_TAG_GNU_annotation and DW_AT_GNU_annotation are used to represent
these user annotations in DWARF.

This patch introduces the new DWARF extension DIE and attribute, and
generates them as necessary to represent user annotations from
btf_decl_tag and btf_type_tag.

The format of the new DIE is as follows:

    DW_TAG_GNU_annotation
        DW_AT_name: "btf_decl_tag" or "btf_type_tag"
        DW_AT_const_value: &lt;arbitrary user-supplied string&gt;
        DW_AT_GNU_annotation: &lt;reference to another TAG_GNU_annotation DIE&gt;

DW_AT_GNU_annotation is a new attribute extension used to refer to these
new annotation DIEs.  If non-null in any given declaration or type DIE,
it is a reference to a DW_TAG_GNU_annotation DIE holding an annotation
for that declaration or type.  In addition, the DW_TAG_GNU_annotation
DIEs may also have a non-null DW_AT_GNU_annotation, referring to another
annotation DIE.  This allows chains of annotation DIEs to be formed,
such as in the case where a single declaration has multiple instances of
btf_decl_tag with different string annotations.

gcc/
	* dwarf2out.cc (struct annotation_node, struct annotation_node_hasher)
	(btf_tag_htab): New ancillary structures and hash table.
	(annotation_node_hasher::hash, annotation_node_hasher::equal): New.
	(hash_btf_tag, gen_btf_tag_dies, maybe_gen_btf_type_tag_dies)
	(maybe_gen_btf_decl_tag_dies): New functions.
	(modified_type_die): Add new argument to pass type attributes.
	Handle btf_type_tag, and update recursive calls.
	(base_type_for_mode): Add new arg for modified_type_die call.
	(add_type_attribute): Likewise.
	(gen_array_type_die): Call maybe_gen_btf_type_tag_dies for the type.
	(gen_formal_parameter_die): Call maybe_gen_btf_decl_tag_dies for the
	parameter.
	(override_type_for_decl_p): Add new arg for modified_type_die call.
	(force_type_die): Likewise.
	(gen_tagged_type_die): Call maybe_gen_btf_type_tag_dies for the type.
	(gen_decl_die): Call maybe_gen_btf_decl_tag_dies for the decl.
	(dwarf2out_finish): Empty btf_tag_htab.
	(dwarf2out_cc_finalize): Delete btf_tag_htab hash table.

include/
	* dwarf2.def (DW_TAG_GNU_annotation): New DWARF extension.
	(DW_AT_GNU_annotation): Likewise.

gcc/testsuite/
	* gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-1.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-2.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-3.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-1.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-2.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-3.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-4.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-5.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-6.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-7.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-8.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-9.c: New test.
	* gcc.dg/debug/dwarf2/dwarf-btf-type-tag-10.c: New test.
diff --git a/gcc/dwarf2out.cc b/gcc/dwarf2out.cc
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-1.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-1.c
@@ -0,0 +1,11 @@
+/* Test simple generation of DW_TAG_GNU_annotation DIE for
+   btf_decl_tag attribute.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+int *foo __attribute__((btf_decl_tag ("my_foo")));
+
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_decl_tag\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_const_value: \"my_foo\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 1 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-2.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-2.c
@@ -0,0 +1,25 @@
+/* Test dwarf generation for btf_decl_tag on struct and union members.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+#define __tag1 __attribute__((btf_decl_tag ("decl1")))
+#define __tag2 __attribute__((btf_decl_tag ("decl2")))
+
+union U {
+  int i __tag1;
+  unsigned char ub[4];
+};
+
+struct S {
+  union U u;
+  int b __tag2;
+  char *z __tag1;
+};
+
+struct S my_s __tag1 __tag2;
+
+/* We must have two occurrences of one of the two annotation DIEs due to
+   the different attribute sets between declarations above.  */
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 3 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_decl_tag\"" 3 } } */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 5 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-3.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-decl-tag-3.c
@@ -0,0 +1,21 @@
+/* Test dwarf generation for btf_decl_tag on functions and function args. */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+#define __tag1 __attribute__((btf_decl_tag ("decl1")))
+#define __tag2 __attribute__((btf_decl_tag ("decl2")))
+
+int __tag1 __tag2 func (int arg_a __tag1, int arg_b __tag2)
+{
+  return arg_a * arg_b;
+}
+
+int foo (int x) {
+  return func (x, x + 1);
+}
+
+/* In this case one of the decl tag DIEs must be duplicated due to differing
+   DW_AT_GNU_annotation chain between the three uses.  */
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 3 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_decl_tag\"" 3 } } */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 4 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-1.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-1.c
@@ -0,0 +1,10 @@
+/* Test simple generation for btf_type_tag attribute.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+int * __attribute__((btf_type_tag("__user"))) ptr;
+
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_type_tag\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_const_value: \"__user\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 1 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-10.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-10.c
@@ -0,0 +1,20 @@
+/* Test btf_type_tag and btf_decl_tag on a function.
+   Here the decl_tag applies to the function, and the type_tag applies
+   to the return type.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+int * __attribute__((btf_type_tag ("A")))
+__attribute__((btf_decl_tag ("decl")))
+foo (int *x, int *y)
+{
+  if (x && y && *x > *y)
+    return x;
+  return y;
+}
+
+/* Ideally, verify that AT_GNU_annotation in the subprogram DIE refers to
+   the decl_tag annotation DIE, and the AT_GNU_annotation in the return
+   type refers to the type_tag...  */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_type_tag\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_decl_tag\"" 1 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-2.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-2.c
@@ -0,0 +1,31 @@
+/* Test that DW_TAG_GNU_annotation DIEs for attribute btf_type_tag are shared
+   where possible.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+#define __tag1 __attribute__((btf_type_tag("tag1")))
+#define __tag2 __attribute__((btf_type_tag("tag2")))
+
+int __tag1 foo;
+char * __tag1 __tag2 bar;
+
+struct S
+{
+  unsigned char bytes[8];
+  unsigned long __tag1 t;
+  void *ptr;
+};
+
+struct S * __tag1 __tag2 my_S;
+
+/* Only 2 DW_TAG_GNU_annotation DIEs should be generated, one each for "tag1"
+   and "tag2", and they should be reused.  */
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 2 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_type_tag\"" 2 } } */
+/* { dg-final { scan-assembler-times " DW_AT_const_value: \"tag1\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_const_value: \"tag2\"" 1 } } */
+
+/* Each attribute-ed type shall refer via DW_AT_GNU_annotation to the
+   appropriate annotation DIE, including the annotation DIE for "tag2" which
+   is always chained to the DIE for "tag1" in this construction.  */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 5 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-3.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-3.c
@@ -0,0 +1,15 @@
+/* Test dwarf generation for btf_type_tag with cv-quals and typedefs.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+#define __tag1 __attribute__((btf_type_tag ("tag1")))
+#define __tag2 __attribute__((btf_type_tag ("tag2")))
+
+typedef const int foo;
+typedef int __tag1 bar;
+
+foo __tag2 x;
+const bar y;
+
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 2 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_type_tag\"" 2 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-4.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-4.c
@@ -0,0 +1,34 @@
+/* Test generating annotation DIEs for struct/union/enum types.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+enum E
+{
+  ONE,
+  TWO
+} __attribute__((btf_type_tag("foo")));
+
+enum E some_e;
+
+struct S
+{
+  int i;
+  char c;
+} __attribute__((btf_type_tag("foo")));
+
+typedef struct S S1;
+S1 plain_s1;
+const S1 const_s1;
+
+union U
+{
+  int x;
+  char y;
+} __attribute__((btf_type_tag("foo")));
+
+volatile union U volatile_u;
+
+/* One annotation DIE may be shared by all three annotated types.  */
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_type_tag\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 3 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-5.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-5.c
@@ -0,0 +1,10 @@
+/* Test generation for btf_type_tag attribute on array type.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+int arr[8] __attribute__((btf_type_tag("tagged_arr")));
+
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_type_tag\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_const_value: \"tagged_arr\"" 1 } } */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 1 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-6.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-6.c
@@ -0,0 +1,27 @@
+/* Test generation for btf_type_tag attribute when applied to struct/union
+   types after definition.  Attributes applied after definition will be
+   ignored, so DW_TAG_GNU_annotations shall be generated.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+struct foo
+{
+  int a;
+  char c;
+};
+
+struct foo __attribute__((btf_type_tag ("tag1"))) x;  /* { dg-warning "ignoring attribute" } */
+typedef const struct foo c_foo;
+c_foo __attribute__((btf_type_tag ("tag2"))) y; /* { dg-warning "ignoring attribute" } */
+
+union bar
+{
+  int s;
+  unsigned int u;
+};
+
+typedef union bar __attribute__((btf_type_tag("tag3"))) tag_bar; /* { dg-warning "ignoring attribute" } */
+const tag_bar z;
+
+/* { dg-final { scan-assembler-not "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" } } */
+/* { dg-final { scan-assembler-not " DW_AT_GNU_annotation" } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-7.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-7.c
@@ -0,0 +1,25 @@
+/* Test generation for btf_type_tag attribute for pointer typedef with
+   tags appearing on both the typedef and the usage of the tyepdef.  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf -dA" } */
+
+#define __tag1 __attribute__((btf_type_tag ("tag1")))
+#define __tag2 __attribute__((btf_type_tag ("tag2")))
+
+typedef int __tag1 foo;
+
+foo a;
+foo __tag2 b;
+
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 2 } } */
+/* { dg-final { scan-assembler-times " DW_AT_name: \"btf_type_tag\"" 2 } } */
+
+/* Due to an ambiguity in the tree attribute list, it is not currently possible
+   to distinguish with certaianty whether "tag1" appears to the left or right
+   of "foo" in the declaration of "b" above.  This means that the DIE for
+   "tag1" is also referred in the AT_GNU_annotation chain of the duplicate
+   typedef DIE annotated wtih "tag2", for a total of 3 AT_GNU_annotations.  */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 3 } } */
+
+/* A duplicate typedef die must be created for the tagged use in 'b'.  */
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_typedef" 2 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-8.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-8.c
@@ -0,0 +1,23 @@
+/* Test that annotation DIEs are copied as needed to the
+   debug_types section (DW_UT_type for dwarf 5).  */
+/* { dg-do compile } */
+/* { dg-options "-gdwarf-5 -dA -fdebug-types-section" } */
+
+int __attribute__((btf_type_tag ("A"))) foo;
+
+struct S
+{
+  int x;
+  char * __attribute__((btf_type_tag ("B"))) c;
+} __attribute__((btf_type_tag ("A"))) some_struct;
+
+/* The struct type is placed in DW_UT_type, and the types of both members and
+   both tags are copied there too.  Since the tags and base types also exist in
+   the main compile unit, we have 4 annotation DIEs total.  But since they
+   are only referenced by 'foo' and by the struct members, there are only
+   3 AT_GNU_annotation. The DIE for tag "B" in the main compile unit is not
+   referred to by anything.  */
+
+/* { dg-final { scan-assembler-times " DW_UT_type" 1 } } */
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 4 } } */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 3 } } */
diff --git a/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-9.c b/gcc/testsuite/gcc.dg/debug/dwarf2/dwarf-btf-type-tag-9.c
@@ -0,0 +1,41 @@
+/* Stress test for several btf_type_tag on the same type and specified
+   in various ways.  */
+/* { dg-do compile } */
+/* { dg-options "-std=c23 -gdwarf -dA" } */
+
+typedef int __attribute__((btf_type_tag ("A"), btf_type_tag ("B"))) myint;
+
+myint x;
+
+struct S
+{
+  myint * __attribute__((btf_type_tag ("A"))) p;
+  unsigned long __attribute__((btf_type_tag ("A")))
+                __attribute__((btf_type_tag ("B")))
+                __attribute__((btf_type_tag ("C"))) l;
+};
+
+char * [[gnu::btf_type_tag ("B"), gnu::btf_type_tag ("C")]] str;
+
+unsigned long [[gnu::btf_type_tag ("B")]]
+do_thing (struct S * __attribute__((btf_type_tag ("C"),
+				    btf_type_tag ("B"),
+				    btf_type_tag ("A"))) arg)
+{
+  return arg->l * 2;
+}
+
+/* Expect the following chains of annotations off of the types:
+   1. int           |-> b -> a -> *
+   2. myint*        |-> a -> *
+   3. unsigned long |-> c -> b -> a -> *
+   4. char*         |-> c -> b -> *
+   4. unsigned long |-> b -> *
+   5. struct S*     |-> a -> b -> c -> *
+
+   a and b are reused in 1-3
+   new c,b created in 4, reused in 5
+   new a,b,c created in 5 (not yet deduplicated).  */
+
+/* { dg-final { scan-assembler-times "DIE \\(\[^\n\]*\\) DW_TAG_GNU_annotation" 8 } } */
+/* { dg-final { scan-assembler-times " DW_AT_GNU_annotation" 11 } } */
diff --git a/include/dwarf2.def b/include/dwarf2.def
@@ -174,6 +174,9 @@ DW_TAG (DW_TAG_GNU_formal_parameter_pack, 0x4108)
    are properly part of DWARF 5.  */
 DW_TAG (DW_TAG_GNU_call_site, 0x4109)
 DW_TAG (DW_TAG_GNU_call_site_parameter, 0x410a)
+
+DW_TAG (DW_TAG_GNU_annotation, 0x6001)
+
 /* Extensions for UPC.  See: http://dwarfstd.org/doc/DWARF4.pdf.  */
 DW_TAG (DW_TAG_upc_shared_type, 0x8765)
 DW_TAG (DW_TAG_upc_strict_type, 0x8766)
@@ -456,6 +459,7 @@ DW_AT (DW_AT_GNU_pubtypes, 0x2135)
 DW_AT (DW_AT_GNU_discriminator, 0x2136)
 DW_AT (DW_AT_GNU_locviews, 0x2137)
 DW_AT (DW_AT_GNU_entry_view, 0x2138)
+DW_AT (DW_AT_GNU_annotation, 0x2139)
 /* VMS extensions.  */
 DW_AT (DW_AT_VMS_rtnbeg_pd_address, 0x2201)
 /* GNAT extensions.  */
