Files

François 6b56ab5c42 libbsdl: scaffold + working BSDL parser (struct + JSON, C ABI)

Standalone LGPL-2.1 parser for BSDL (IEEE 1149.1), shared by essim and
bs_explorer. The parser is ported from the Viveris JTAG Core loader,
decoupled from jtag_core, and extended with two extractions the original
lacks:
  - PIN_MAP_STRING -> per-port physical package pin, scalar and vector;
  - TAP_SCAN_*     -> TAP signal roles (TDI/TDO/TMS/TCK/TRST).

Exposes a stable C ABI (bsdl_parse_file/buffer -> bsdl_t, bsdl_to_json)
with a dependency-free JSON serializer and a bsdl2json CLI. CMake builds a
versioned shared library with install/export rules for find_package(bsdl).

Verified against m2gl010t, xcku040 and xcku15p (100% pin mapping, correct
IDCODEs and TAP roles); api and parse regression tests pass, clean build.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-03 10:27:13 +02:00

2.5 KiB

Raw Blame History

libbsdl

A small, standalone parser for BSDL (IEEE 1149.1 Boundary-Scan Description Language) files, exposing a stable C ABI plus an optional JSON output.

It is designed to be shared by two consumers:

bs_explorer (C) — links the library and reads the bsdl_t struct directly (boundary chain, instructions) to drive JTAG hardware.
essim (C++) — consumes it either out-of-process via the bsdl2json CLI, or in-process through the extern "C" API, for connectivity verification.

The parser core is seeded from the Viveris JTAG Core BSDL loader and extended with the two attributes that loader omits but a netlist cross-check needs:

PIN_MAP_STRING → each port's physical package ball/pin (physical_pin);
TAP_SCAN_* → each TAP signal's role (TDI/TDO/TMS/TCK/TRST, tap_role).

Status

Working. The parser extracts entity, IDCODE (+ mask), port directions, the scalar and vector PIN_MAP_STRING (physical pins), TAP_SCAN_* roles, the boundary register (with pin↔cell links) and the instruction opcodes. Verified against real devices — m2gl010t (484 pins), xcku040 (1156), xcku15p (1517) — with 100% pin mapping and correct IDCODEs/TAP roles. api and parse regression tests pass.

Build

cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

Produces libbsdl.so (+ .so.0 / .so.0.1.0), the bsdl2json tool, and runs the test suite. Options: -DBSDL_BUILD_CLI=OFF, -DBSDL_BUILD_TESTS=OFF, -DBUILD_SHARED_LIBS=OFF (static).

Use from CMake

find_package(bsdl REQUIRED)
target_link_libraries(my_app PRIVATE bsdl::bsdl)

API

#include <bsdl/bsdl.h>

bsdl_opts_t opts;
bsdl_opts_default(&opts);

bsdl_t* m = bsdl_parse_file("device.bsd", &opts);
if (m) {
    char* json = bsdl_to_json(m);   /* compact JSON; free with bsdl_string_free */
    /* ... or walk m->pins / m->chain / m->instructions directly ... */
    bsdl_string_free(json);
    bsdl_free(m);
}

See include/bsdl/bsdl.h for the full contract. The bsdl_t model is a superset: extend it additively so the shared ABI stays stable for both consumers.

License

LGPL-2.1-or-later — see LICENSE. The same license as its two consumers (essim and bs_explorer are both LGPL-2.1), so code and the parser can be shared freely; dynamic linking keeps the library replaceable. Derived from the Viveris JTAG Core BSDL loader (© 2008–2024 Viveris Technologies, Jean-François DEL NERO), also LGPL-2.1.

2.5 KiB Raw Blame History Unescape Escape