# 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.