François
b6719a8340
libbsdl stays LGPL-2.1 (inherited from the Viveris loader it derives from); essim consumes it as a dynamically-linked LGPL library, which the EUPL permits. Corrects an earlier wrong claim that essim was LGPL-2.1. 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), inherited from the Viveris JTAG
|
||
Core BSDL loader (© 2008–2024 Viveris Technologies, Jean-François DEL NERO)
|
||
this is derived from. `bs_explorer` is also LGPL-2.1 and links the struct
|
||
directly; `essim` is EUPL-1.2 and consumes libbsdl as a dynamically-linked
|
||
LGPL library, which the EUPL permits.
|