gendwarfksyms: Add support for declaration-only data structures

If a source file refers to an opaque data structure, the DWARF
debugging information in the resulting object file will only contain a
structure declation, which means the contents of the structure are not
included when computing symbol versions. For example:

Source code:

  struct struct0;
  int func(struct struct0 *);

gendwarfksyms --debug:

  subprogram(
    formal_parameter pointer_type <unnamed> {
      structure_type struct0 {
        <declaration>
      }
    } byte_size(8),
  )
  -> base_type int byte_size(4) encoding(5);
  #SYMVER func 0x7e8284f9

The declaration can change into a full definition when an additional
include is added to the TU, which changes the version CRC, even though
the ABI has not changed. If this happens during an LTS update, a
distribution that wants to maintain a stable ABI needs a way to ensure
symbol versions remain unchanged.

With genksyms, the usual solution is to use #ifndef __GENKSYMS__ to
skip the newly added header file when computing symbol versions, but
that's not an option when we're processing a precompiled object file.

To support this use case, add a --stable command line flag that gates
kABI stability features that are not needed in mainline, but can be
useful for distributions, and add support for symbol annotations that
allow structures to always be treated as declarations when versions
are computed. If a __gendwarfksyms_declonly_<structname> symbol
exists in the object file's symbol table, the "structname" structure
is treated as a declaration only, and not expanded when computing
versions. The symbol can be defined using the following macro, for
example, which discards it from the final kernel binary:

  #define GENDWARFKSYMS_DECLONLY(structname) \
      static void *__gendwarfksyms_declonly_##structname __used \
        __section(".discard.gendwarfksyms")

Now, if we include struct0 definition in our source code, and add a
declaration-only annotation, we have:

  struct struct0 { int a; };
  GENDWARFKSYMS_DECLONLY(struct0);
  int func(struct struct0 *);

gendwarfksyms --debug reflects the added definition:

  subprogram(
    formal_parameter pointer_type <unnamed> {
      structure_type struct0 {
        member base_type int byte_size(4) encoding(5) data_member_location(0),
      } byte_size(4)
    } byte_size(8),
  )
  -> base_type int byte_size(4) encoding(5);
  #SYMVER func 0xc0de983d

But with --debug --stable, the definition is ignored and we again
have the original symbol version:

  subprogram(
    formal_parameter pointer_type <unnamed> {
      structure_type struct0 {
        <declaration>
      }
    } byte_size(8),
  )
  -> base_type int byte_size(4) encoding(5);
  #SYMVER func 0x7e8284f9

Signed-off-by: Sami Tolvanen <samitolvanen@google.com>

Author: samitolvanen

scripts/gendwarfksyms/dwarf.c

@@ -74,7 +74,30 @@ static bool is_declaration(Dwarf_Die *die)
 {
 	bool value;
 
-	return get_flag_attr(die, DW_AT_declaration, &value) && value;
+	/*
+	 * If the object file has a __gendwarfksyms_declonly_<structname>
+	 * symbol, we treat structures named "structname" as declarations,
+	 * i.e. they won't be expanded when calculating symbol versions.
+	 * This helps distributions maintain a stable kABI e.g., if extra
+	 * includes change a declaration into a definition.
+	 *
+	 * A simple way to mark a structure declaration-only in the source
+	 * code is to define a discarded symbol:
+	 *
+	 * #define GENDWARFKSYMS_DECLONLY(structname) \
+	 *   static void *__gendwarfksyms_declonly_##structname __used \
+	 *     __section(".discard.gendwarfksyms")
+	 *
+	 *  For example:
+	 *
+	 *  struct struct0 { int a; }
+	 *  GENDWARFKSYMS_DECLONLY(struct0);
+	 *
+	 *  Here, struct0 would be always be considered a declaration even
+	 *  though the definition is visible.
+	 */
+	return (get_flag_attr(die, DW_AT_declaration, &value) && value) ||
+	       is_struct_declonly(get_name(die));
 }
 
 /*

scripts/gendwarfksyms/examples/declonly.c

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * Copyright (C) 2024 Google LLC
+ *
+ * Declaration-only data structure example. See dwarf.c:is_declaration
+ * for details.
+ *
+ * $ gcc -g -c examples/declonly.c
+ * $ echo exported | ./gendwarfksyms --dump-dies declonly.o
+ * variable structure_type struct0 {
+ *   member base_type int byte_size(4) encoding(5) data_member_location(0),
+ * } byte_size(4)
+ *
+ * With --stable, struct0 is treated as a declaration:
+ *
+ * $ echo exported | ./gendwarfksyms --stable --dump-dies declonly.o
+ * variable structure_type struct0 {
+ * }
+ */
+
+#define GENDWARFKSYMS_DECLONLY(structname) \
+	static void *__gendwarfksyms_declonly_##structname \
+		__attribute__((__used__)) \
+		__attribute__((__section__(".discard.gendwarfksyms")));
+
+struct struct0 {
+	int a;
+};
+
+struct struct0 exported;
+GENDWARFKSYMS_DECLONLY(struct0);

scripts/gendwarfksyms/gendwarfksyms.c

@@ -24,6 +24,8 @@ bool dump_die_map;
 bool dump_types;
 /* Print out expanded type strings used for version calculations */
 bool dump_versions;
+/* Support kABI stability features */
+bool stable;
 /* Produce a symtypes file */
 bool symtypes;
 static const char *symtypes_file;
@@ -38,6 +40,7 @@ static const struct {
 	{ "--dump-die-map", &dump_die_map, NULL },
 	{ "--dump-types", &dump_types, NULL },
 	{ "--dump-versions", &dump_versions, NULL },
+	{ "--stable", &stable, NULL },
 	{ "--symtypes", &symtypes, &symtypes_file },
 };
 
@@ -186,6 +189,7 @@ int main(int argc, const char **argv)
 
 		dwfl_end(dwfl);
 		close(fd);
+		symbol_free_declonly();
 	}
 
 	if (symfile)

scripts/gendwarfksyms/gendwarfksyms.h

@@ -24,6 +24,7 @@ extern bool dump_dies;
 extern bool dump_die_map;
 extern bool dump_types;
 extern bool dump_versions;
+extern bool stable;
 extern bool symtypes;
 
 #define MAX_INPUT_FILES 128
@@ -134,6 +135,9 @@ extern int symbol_set_crc(struct symbol *sym, unsigned long crc);
 extern int symbol_for_each(symbol_callback_t func, void *arg);
 extern void symbol_print_versions(void);
 
+extern bool is_struct_declonly(const char *name);
+extern void symbol_free_declonly(void);
+
 /*
  * die.c
  */

scripts/gendwarfksyms/symbols.c

@@ -5,12 +5,20 @@
 
 #include "gendwarfksyms.h"
 
+struct declonly {
+	const char *name;
+	struct hlist_node hash;
+};
+
 #define SYMBOL_HASH_BITS 15
+#define DECLONLY_HASH_BITS 10
 
 /* struct symbol_addr -> struct symbol */
 static DEFINE_HASHTABLE(symbol_addrs, SYMBOL_HASH_BITS);
 /* name -> struct symbol */
 static DEFINE_HASHTABLE(symbol_names, SYMBOL_HASH_BITS);
+/* name -> struct declonly */
+static DEFINE_HASHTABLE(declonly_structs, DECLONLY_HASH_BITS);
 
 static inline u32 symbol_addr_hash(const struct symbol_addr *addr)
 {
@@ -296,12 +304,36 @@ static int process_symbol(const char *name, GElf_Sym *sym, Elf32_Word xndx,
 			  void *arg)
 {
 	struct symbol_addr addr = { .section = xndx, .address = sym->st_value };
+	struct declonly *d;
 
 	/* Set addresses for exported symbols */
 	if (GELF_ST_BIND(sym->st_info) != STB_LOCAL &&
 	    addr.section != SHN_UNDEF)
 		checkp(for_each(name, true, set_symbol_addr, &addr));
 
+	if (!stable)
+		return 0;
+
+	/* Process declonly structs */
+	if (strncmp(name, SYMBOL_DECLONLY_PREFIX, SYMBOL_DECLONLY_PREFIX_LEN))
+		return 0;
+
+	d = malloc(sizeof(struct declonly));
+	if (!d) {
+		error("malloc failed");
+		return -1;
+	}
+
+	name += SYMBOL_DECLONLY_PREFIX_LEN;
+	d->name = strdup(name);
+	if (!d->name) {
+		error("strdup failed");
+		return -1;
+	}
+
+	hash_add(declonly_structs, &d->hash, name_hash(d->name));
+	debug("declaration-only: %s", d->name);
+
 	return 0;
 }
 
@@ -310,6 +342,35 @@ int symbol_read_symtab(int fd)
 	return elf_for_each_symbol(fd, process_symbol, NULL);
 }
 
+bool is_struct_declonly(const char *name)
+{
+	struct declonly *d;
+
+	if (!stable || !name)
+		return false;
+
+	hash_for_each_possible(declonly_structs, d, hash, name_hash(name)) {
+		if (!strcmp(name, d->name))
+			return true;
+	}
+
+	return false;
+}
+
+void symbol_free_declonly(void)
+{
+	struct hlist_node *tmp;
+	struct declonly *d;
+	int i;
+
+	hash_for_each_safe(declonly_structs, i, tmp, d, hash) {
+		free((void *)d->name);
+		free(d);
+	}
+
+	hash_init(declonly_structs);
+}
+
 void symbol_print_versions(void)
 {
 	struct hlist_node *tmp;