This is an automated email from the ASF dual-hosted git repository. simbit18 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 01a70e9daf45c3826931b1c87ac034134fb99e35 Author: anjiahao <[email protected]> AuthorDate: Tue Jan 27 14:58:51 2026 +0800 Documentation:update abicheck.py Add abicheck.py usage to documentation Signed-off-by: anjiahao <[email protected]> --- Documentation/components/tools/index.rst | 75 ++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/Documentation/components/tools/index.rst b/Documentation/components/tools/index.rst index c025e2f2704..8350d94f44f 100644 --- a/Documentation/components/tools/index.rst +++ b/Documentation/components/tools/index.rst @@ -10,6 +10,81 @@ and host C programs that are important parts of the NuttX build system: :backlinks: entry :depth: 2 +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 + cmpconfig.c -----------
