François
6b56ab5c42
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>
75 lines
2.5 KiB
Markdown
75 lines
2.5 KiB
Markdown
# 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
|
||
|
||
```sh
|
||
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
|
||
|
||
```cmake
|
||
find_package(bsdl REQUIRED)
|
||
target_link_libraries(my_app PRIVATE bsdl::bsdl)
|
||
```
|
||
|
||
## API
|
||
|
||
```c
|
||
#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](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.
|