Incompatible Change Policy

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

The addition of the DW_AT_ENDIANITY attribute to DWARF version 3 was a compatible change from DWARF version 2. An existing consumer which did not recognize this attribute could skip over it and still be able to interpret the remaining information in the DIE correctly. Only consumers which supported explictly entering or displaying data in a non-default byte order would need to interpret this attribute. While it is possible that by not being able to interpret this attribute that a consumer might display data incorrectly, but this would be no different than if the attribute had not been specified.

Example -- Incompatible Change

DWARF version 3 supports debugging files larger than can be addressed with 32 bits. If a consumer does not interpret the length field value correctly, it would not be able to interpret the remainder of the DWARF data. The consumer application might crash/coredump or it might simply report erroneous data.

Example -- Incompatible Change

DWARF version 3 changed the interpretation of the return address register entry in the CIE from ubyte to LEB128. For targets which specified a value less than 128, the representation is the same for both ubyte and LEB128. If the return address register was equal to or greater than 128, then the consumer would interpet this field (and subsequent field) incorrectly.

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.