From The Linux Foundation
Jump to: navigation, search

HeaderCheck - Runtime LSB Conformance test tool

Problem Statement: Library binary compatibility

Some of the ways the library ABI breakage happens are listed below:

  1. Intentional ABI breakage during version changes (typically at major version changes)
2. Conditional compilation can lead to different structure sizes. E.g. PNG library has many ifdefed structure definitions
3. Bugs, mistakes leading to structure size changes or interface parameter type changes

LSB runtime test suites try to catch these and other types of ABI incompatibilites (compared to what is specified in LSB) by using automated test suites like lsb-runtime-test, lsb-vsw4, lsb-c++ etc. LSB also has a tool called lsblibchk to make sure the runtime exposes all symbols and their versions where applicable.

The LSB runtime test suites have far from sufficient coverage to guarantee LSB conformance. Many of the covered libraries have very little test coverage. It is extremely labor intensive to develop all possible test scenarios for all the interfaces covered in LSB.

lsblibchk tool does not go beyond making sure the presence of the symbol along with the right symbol version string (where applicable).

Solution Proposal

The LSB runtime test suites focus on behavioral aspects of each interface tested. In addition to that following tests/checks for each library will increase LSB test coverage further:

  • For each interface validate:
  • return type
  • number of parameters
  • all parameters
  • For each exposed structure validate:
  • total size
  • size of each member
  • offsets for each member
  • Validation of global variables
  • Validation of constants (#defines)
  • C++ aspects: TBD

These tests can not be performed on the runtime directly as the libraries lack this information (in their release build). That is the reason for lsblibchk to stop its testing at symbol versioning and presence of each symbol.

The new tool proposed here will run on the header files used by the OSVs while building the runtime. Headers will have all the required ABI information discussed above. In general, this tool will make sure that the LSB stub header is the proper subset of the header used by OSV while building the runtime library.

To some extend the tool is similar to the devchk tools LSB uses internally for LSB DB validations.

We understand the limitation of this tool (it is not a runtime test tool) and the extra burdon on the OSVs to validate the headers. The main advantage of this tool is the additional test coverage provided to test for LSB conformance.

Needs further Work

The proposal currently covers only the C interfaces. C++ interfaces may/will provide additional challenges.

To add comments to this page, click on [wiki:HeaderCheck/Comments User Comments] and select edit.