DWARF Debugging Format DWARF Debugging Standard Wiki

Incompatible changes between DWARF versions represent a significant obstacle in adoption of newer versions of DWARF. To reduce this impact, DWARF provides features which allow enhancements to the description while maintaining compatibility with previous versions. In this respect, DWARF is different from most other debugging formats.

DWARF’s extensible format is designed to permit a consumer (generally a debugger) to ignore parts of the DWARF description of a program which it either is not equipped to handle or which is does not know how to interpret. A consumer may know about certain TAGs or atrributes which it doesn’t support. These can be skipped, perhaps with a warning message.

TAGs or attributes which the consumer does not recognize represent a potential problem for the consumer. In general, the recommendation is that consumers skip DIEs which contain unrecognized TAGs, as well as all of their children DIEs. Similarly, unrecognized attributes should be skipped. The understanding is that by doing so, the consumer will be able interpret the remainder of the DWARF data correctly. Information in the skipped DIEs and attributes would be for features which the consumer did not support.

Incompatible Changes

This lead us to a definition: An incompatible change is one which an existing consumer of DWARF cannot interpret the remainder of the DWARF file by simply ignoring the additional information or one which changes the previous interpretation such that it would now be misinterpreted. An incompatible change is one which changes (not merely extends) the meaning of an existing TAG or attribute, replaces an existing TAG or attribute with another, or which eliminates a TAG or attribute which was previously used. A consumer must interpret the added or changed information correctly, or it will be unable to reasonably interpret the remainder of the DWARF data.

Example – Compatible Change

Example – Incompatible Change

Example – Incompatible Change

As can be seen from the last example, whether an incompatible change affects a consumer or not may depend upon factors unrelated to the DWARF Standard, such as target-specific register numbering. Rather than attempt to characterize which producers and consumers might be affected by a particular change, we identify these changes as incompatible by incrementing the version number of the affected data section.

A consumer which encounters a data section which has a version number which it does not recognize cannot continue. It is impossible for the consumer to determine whether the incompatible change is benign, like the last example above, or severe as in the preceeding example.

Adoption of Incompatible Changes

When it is determined that an improvement in DWARF cannot be achieved with a compatible change, the nature of the change can have a significant impact on both producers and consumers of DWARF. In the preceeding examples, the change from ubyte to LEB128 in the CIE description would require small changes to producers and consumers to change the format or, if the producers and consumer wished to depend on the value always being less than 128, no change. On the other hand, supporting DWARF-64 requires a number of changes in both producers and consumers.

Certain incompatible changes to DWARF may require changes in system components other than the producer (e.g., compiler) or consumer (e.g., debugger). These components (assembler, linker, etc.) may be developed by different organizations from those developing either the compiler or debugger. Changes in these components represent an additional effort which delays adoption of DWARF.

If there are different ways to define an extension in DWARF, it’s desirable to chose the method which will be easiest to implement by producers and consumers, and which reduce the impact on other system components.

DWARF Policy

To further the adoption of DWARF and reduce the impact of changes in the DWARF on the user community, it is desirable to avoid incompatible changes and reduce the difficulty of adopting incompatible changes.

DWARF Committee Policy is to adopt incompatible changes when they offer a significant improvement in the ability of DWARF to describe programs which cannot be achieved by a compatible change.

DWARF Committee Policy is to adopt incompatible changes which reduce the level of implementation effort which is required to adopt the change.

DWARF Committee Policy is to adopt incompatible changes which reduce the scope of changes to components other than producer or consumer.

dwarfstd.org is supported by Sourceware. Contributions are welcome.

All logos and trademarks in this site are property of their respective owner.
The comments are property of their posters, all the rest © 2007-2022 by DWARF Standards Committee.