mirror of
https://github.com/apache/nuttx.git
synced 2026-05-20 12:33:27 +08:00
Matteo Golin
53fdfa68b9
All of the tools listed on the original documentation are now given their own individual doc pages. This makes it much easier to cross-reference them from other documentation locations (as many are used in CI/for specific architectures) and it also makes it easier for users to digest the information. Signed-off-by: Matteo Golin <matteo.golin@gmail.com>
76 lines
3.3 KiB
ReStructuredText
76 lines
3.3 KiB
ReStructuredText
================
|
|
``abi_check.py``
|
|
================
|
|
|
|
``abi_check.py`` is a Python tool for checking binary compatibility based on
|
|
DWARF debug information.
|
|
|
|
It supports three related workflows:
|
|
|
|
1. Given one or more static libraries (``.a``) and an ELF file, collect the
|
|
undefined (external) symbols referenced by the libraries, locate those
|
|
functions in the ELF file, and write their function signatures to a JSON
|
|
file.
|
|
2. Generate two JSON files from two different ELF files (for example, an old
|
|
build and a new build), and compare the signatures of functions with the
|
|
same name (return type, parameters, and for structs also size, member
|
|
offsets, member types, etc.).
|
|
3. Given a single ELF file, detect structs with the same name but different
|
|
members.
|
|
|
|
Prerequisites:
|
|
|
|
- Python 3
|
|
- ``pyelftools`` (used to read ELF/DWARF)
|
|
- ``ar`` (used to extract object files from ``.a`` archives)
|
|
- ``pahole`` (only for ``--struct_check``)
|
|
|
|
.. note::
|
|
|
|
Although the help text mentions ``.so``, the current implementation uses
|
|
``ar x`` on each ``--lib`` input, so it expects ``.a`` archives.
|
|
|
|
Help message::
|
|
|
|
$ python3 tools/abi_check.py -h
|
|
usage: abi_check.py [-h] [-a LIB [LIB ...]] [-e ELF] [-c] [-d] [-j JSON] [-s]
|
|
[-i INPUT_JSON INPUT_JSON]
|
|
|
|
This tool is used to check the binary compatibility of static libraries and has the following features:
|
|
1. The input consists of multiple static libraries and an ELF file. The tool searches
|
|
for external APIs used by the static libraries, then locates these API function signatures
|
|
in the ELF file, and outputs the results as a JSON file.
|
|
2. Using the first feature, with the static libraries unchanged,
|
|
the tool can take a new ELF file and an old ELF file as input, output two JSON files,
|
|
and compare the function signatures of functions with the same name in the two JSON files.
|
|
The comparison includes return values, parameters, and if they are structures,
|
|
it also compares the structure size, member offsets, member types, etc.
|
|
3.When the input is a single ELF file, the tool can check if structures with the same name have different members.
|
|
|
|
options:
|
|
-h, --help show this help message and exit
|
|
-a LIB [LIB ...], --lib LIB [LIB ...]
|
|
Path to liba.so or lib.a
|
|
-e ELF, --elf ELF Path to elf file
|
|
-c, --check If the static library contains debug information,
|
|
try to find the function in the static library,
|
|
and output the result to lib_<json> file
|
|
-d, --dump Dump result
|
|
-j JSON, --json JSON Save result to json file
|
|
-s, --struct_check Dump struct different
|
|
-i INPUT_JSON INPUT_JSON, --input_json INPUT_JSON INPUT_JSON
|
|
Diff two json files
|
|
|
|
Examples::
|
|
|
|
# 1) Extract signatures for external APIs referenced by one or more archives
|
|
$ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx -j out.json
|
|
|
|
# 2) Compare signatures across two ELF files
|
|
$ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx_old -j old.json
|
|
$ python3 tools/abi_check.py -a libfoo.a libbar.a -e nuttx_new -j new.json
|
|
$ python3 tools/abi_check.py -i old.json new.json
|
|
|
|
# 3) Find struct definition mismatches within a single ELF
|
|
$ python3 tools/abi_check.py -e nuttx -s
|