dwarfidl is a textual syntax for (mostly) the .debug_info fragment of
DWARF debugging information. It describes data types, functions
('subprograms'), their interfaces and (optionally) aspects of their
internals.
dwarfidl can be used to describe interfaces at the binary level, more precisely than in C or any other low-level programming language I know of. This is because DWARF makes ABI details explicit. Rather than leaving to the compiler details such as structure padding, primitive types' sizes and encodings, argument-passing conventions, and so on, all of these can be rendered explicitly using DWARF and therefore in dwarfidl. For example,
XXX an infamously ABI-dependent structure? 'stat' perhaps? or 'timespec'? something with 'off_t'?
Unlike conventional 'IDLs', or interface /definition/ languages, dwarfidl is suited to post-hoc use and to /descriptive/ or supplemental applications. Rather than the inflexible CORBA-style approach of writing a canonical interface description in the IDL and generating stub code from that, you can instead define your interface in a language of your choice and see the compiler's rendering of it reflected in the generated dwarfidl -- generated from the DWARF that is generated by the compiler. There is some code for 'merging' a partial dwarfidl description with underlying DWARF information, so that the dwarfidl can be a curated, annotated overlay that adds semantic information to a basic interface that is maintained in code elsewhere.
The dwarfidl language has a complicated history, and remains something of a mess. Originally, dwarfidl was a fragment of the Cake language. It was born as a separate entity in 2011 by isolating the part of that language used to describe binary interfaces by augmentation of (or substitution for missing) debugging information.
The Cake-derived grammar was modified in 2014 (ed95f92) to yield what is
now called the 'dwarfidlSimple' grammar, intended to temporarily replace
the Cake-derived one and to be more uniform (intending improvements to
be back-ported, but this still hasn't happened). This is the grammar
used by liballocs to describe composite types implied by code like
malloc(sizeof (T) + sizeof (S)), processed by the create_dies
function. There is an unfinished dumper in this syntax, dwarfidldump,
in examples/ and the underlying print code is in src/print.cpp. Examples
of the syntax can be generated by liballocs's tools in the '.allocs'
files; after building liballocs, see
/usr/lib/meta/path/to/liballocs/tests/offsetof/offsetof.allocs for one
example.
In 2015 Jon French wrote a new grammar to serve the libfootprints project, which consists of tools for specifying and checking the memory access footprints of system calls and the like. This grammar is now called 'dwarfidlNew' and its last significant changes were in 50ca031. The printing code is in src/dwarfprint.cpp and does work. A test case called `dwarfprint' (added in 2020) exercises this code. A sample of the syntax as dumped is in tests/dwarfprint/sample-output.txt.
A long-neglected goal has been to unite these two strands, possibly as part of publishing the libfootprints work.
| syntax | print code | test/example dumper | example syntax | |--------|--------------------|---------------------------|------------------------------------|| | simple | src/print.cpp | examples/dwarfidldump.cpp | see liballocs | | new | src/dwarfprint.cpp | tests/dwarfprint | tests/dwarfprint/sample-output.txt |