BPF Type Format support in libabigail 2.3

Following the support of a multi-front-end architecture in libabigail 2.2, version 2.3 of that Application Binary Interface analysis library added support of the BPF Type Format. This article presents a high-level view of how the BTF support was implemented.

Using the multi-front-end architecture of libabigail

In libabigail, a front end is the component that reads a particular type of information usually embedded in a binary and builds an intermediate representation of its Application Binary Interface (ABI).

Each front end understands the specifics of a particular format of type information. For instance, the DWARF front end reads the type information from the DWARF debug data embedded in binaries in the ELF format.

Adding support for the BTF debug information involved writing a new front end dedicated to reading BTF type information from an ELF binary.

The BTF front end is thus instantiated to analyze binaries that contain BTF debug info. Once the intermediate representation of the ABI is built, it is handed over to the existing middle-end for processing.

Organization of the BTF front end

The BTF front end is represented by a new implementation of the abigail::elf_based_reader interface. That implementation is instantiated by the abigail::btf::create_reader factory function. Client code of this function can thus use the BTF front end through the abigail::elf_based_reader abstract interface.

For the curious reader, the code of the BTF front end lies in the file abg-btf-reader.cc and uses the libbpf library to read the BTF type information from the ELF file.

Tools support

Various ABI analysis tools provided by the libabigail package have been adapted to support the new BTF front end.

Namely, abidiff, abipkgdiff, kmidiff, and abidw have all been adapted to support the new BTF format.

The –btf option forces any of these tools to use the BTF type information present in the input binary, or to fall back to using DWARF if no BTF debug information was found. By default, however, if the binary being analyzed is the Linux kernel and if the only debug information available is BTF, then the BTF front end is automatically used, even if the –btf option was not provided on the command line.

Usage example

Let’s write a first version of a simple function:

$ cat -n example-v0.c
     1  struct S
     2  {
     3    int a;
     4    char b;
     5  };
     6  
     7  int
     8  example_function(struct S *s)
     9  {
    10    return s->a;
    11  }
$ 

Now let’s compile that small example code using the GCC compiler and tell the compiler to emit BTF debug information:

$ gcc -c -gbtf example-v0.c
$ ls example-v0.o
example-v0.o
$

Note how we use the -gbtf switch to GCC. This instructs the compiler to emit debug information in the BTF format.

Let’s confirm that GCC hasn’t emitted any DWARF debug information using the eu-readelf command, from the elfutils project:

$ eu-readelf --debug-dump=info example-v0.o
eu-readelf: cannot get debug context descriptor: No DWARF information found
$

Note how the eu-readelf hasn’t found any debug information.

Now let’s use the bpftool command to confirm that some type information in the BTF format was emitted by GCC:

$ bpftool btf dump file example-v0.o
[1] STRUCT 'S' size=8 vlen=2
    'a' type_id=2 bits_offset=0
    'b' type_id=3 bits_offset=32
[2] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
[3] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
[4] FUNC_PROTO '(anon)' ret_type_id=2 vlen=1
    's' type_id=5
[5] PTR '(anon)' type_id=1
[6] FUNC 'example_function' type_id=4 linkage=global
$ 

Now we can use the abidw from libabigail to serialize the ABI information constructed from the BTF in the binary:

$ /home/dodji/git/libabigail/master/build/tools/abidw --annotate example-v0.o
<abi-corpus version='2.2' path='example-v0.o' architecture='elf-amd-x86_64'>
  <elf-function-symbols>
    <!-- example_function -->
    <elf-symbol name='example_function' type='func-type' binding='global-binding' visibility='default-visibility' is-defined='yes'/>
  </elf-function-symbols>
  <abi-instr address-size='64'>
    <!-- char -->
    <type-decl name='char' size-in-bits='8' id='type-id-1'/>
    <!-- int -->
    <type-decl name='int' size-in-bits='32' id='type-id-2'/>
    <!-- struct S -->
    <class-decl name='S' size-in-bits='64' is-struct='yes' visibility='default' id='type-id-3'>
      <data-member access='public' layout-offset-in-bits='0'>
    <!-- int S::a -->
    <var-decl name='a' type-id='type-id-2' visibility='default'/>
      </data-member>
      <data-member access='public' layout-offset-in-bits='32'>
    <!-- char S::b -->
    <var-decl name='b' type-id='type-id-1' visibility='default'/>
      </data-member>
    </class-decl>
    <!-- S* -->
    <pointer-type-def type-id='type-id-3' size-in-bits='64' id='type-id-4'/>
    <!-- int example_function(S*) -->
    <function-decl name='example_function' mangled-name='example_function' visibility='default' binding='global' size-in-bits='64' elf-symbol-id='example_function'>
      <!-- parameter of type 'S*' -->
      <parameter type-id='type-id-4' name='s'/>
      <!-- int -->
      <return type-id='type-id-2'/>
    </function-decl>
    <!-- int (S*) -->
    <function-type size-in-bits='64' id='type-id-5'>
      <!-- parameter of type 'S*' -->
      <parameter type-id='type-id-4' name='s'/>
      <!-- int -->
      <return type-id='type-id-2'/>
    </function-type>
  </abi-instr>
</abi-corpus>
$ 

Here we see that abidw was able to instantiate the BTF front end, construct an intermediate representation of the ABI of the example-v0.c program, and serialize it back into the ABIXML format.

Finally, let’s modify the example-v0.c program to change its ABI and see what the abidiff program tells us by looking at the BTF information:

$ cat -n example-v1.c
     1  struct S
     2  {
     3    int a;
     4    char b;
     5    int c;
     6  };
     7  
     8  int
     9  example_function(struct S *s,
    10           int b)
    11  {
    12    return s->a;
    13  }
$ 

For brevity, here is a diff of the change to the source code:

$ diff -u example-v0.c example-v1.c
--- example-v0.c    2023-07-23 19:30:10.309346718 +0200
+++ example-v1.c    2023-07-23 19:28:13.467415606 +0200
@@ -2,10 +2,12 @@
 {
   int a;
   char b;
+  int c;
 };

 int
-example_function(struct S *s)
+example_function(struct S *s,
+        int b)
 {
   return s->a;
 }
$ 

Let’s compile it and let abidiff analyze the changes between example-v0.o and example-v1.o:

$ gcc -c -gbtf example-v1.c
$ /home/dodji/git/libabigail/master/build/tools/abidiff example-v0.o example-v1.o
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

1 function with some indirect sub-type change:

  [C] 'function int example_function(S*)' has some indirect sub-type changes:
    parameter 1 of type 'S*' has sub-type changes:
      in pointed to type 'struct S':
    type size changed from 64 to 96 (in bits)
    1 data member insertion:
      'int c', at offset 64 (in bits)
    parameter 2 of type 'int' was added

$

Conclusion

As this article shows, the BTF front end enables the ABI analysis of binaries accompanied with type information in the BTF format, like the Linux Kernel, in the absence of type information in the DWARF format.

Because the type information in the BTF format is de-duplicated, the ABI analysis performed by libabigail should be much faster using the BTF front end than the default DWARF front end.

To learn more about the libabigail framework, engage with its development community either by joining the mailing list or via our IRC channel at irc://oftc.net#libabigail.