francois
7cb3627754
- fix format-string in jprint/script_print (printf(msg) -> fputs)
- fix bsexp_deinit: deinit_script guarded by sctx, not jc
- silence "config.script not found" when the optional override is absent
- remove dead code: bs/cmds/, bs/args.{c,h}, bs/utils.h, commented blocks
- REPL: welcome banner with version, readline tab-completion on
script_commands_list, skip blank lines, clean Ctrl-D exit
- README: build, REPL usage, typical SPI flow, command table, probes,
Xilinx STARTUPE3/CCLK caveat
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
136 lines
4.9 KiB
Markdown
136 lines
4.9 KiB
Markdown
# bs_explorer — Boundary Scan Explorer
|
|
|
|
Outil en ligne de commande pour explorer une chaîne JTAG, contrôler les
|
|
broches d'un FPGA via le boundary scan (BSDL), et — à terme — programmer
|
|
les mémoires SPI connectées au FPGA (Xilinx et autres) en bit-bangeant
|
|
SPI sur les pins d'I/O placés en EXTEST.
|
|
|
|
Basé sur la librairie [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner)
|
|
de Viveris (LGPL).
|
|
|
|
## État
|
|
|
|
- Détection de la chaîne JTAG via sondes FTDI / J-Link / Linux GPIO : OK
|
|
- Chargement automatique d'un BSDL par IDCODE : OK
|
|
- Pilotage de pins en SAMPLE / EXTEST : OK
|
|
- SPI bit-bang sur 4 pins du FPGA (MOSI/MISO/CS/CLK) : OK (primitive bas niveau)
|
|
- Programmation de flash SPI (détection JEDEC, erase, page program, verify) : **à venir**
|
|
- Abstraction multi-FPGA (mapping pins → flash par cible) : **à venir**
|
|
|
|
Seul BSDL embarqué pour l'instant : Xilinx Kintex UltraScale+ KU15P
|
|
(`bsdl_files/xcku15p_ffve1517.bsd`). En ajouter d'autres se fait en
|
|
déposant le `.bsd` dans `bsdl_files/`.
|
|
|
|
## Dépendances
|
|
|
|
- CMake ≥ 3.10, gcc/clang
|
|
- `readline` (Arch : `readline`, Debian/Ubuntu : `libreadline-dev`)
|
|
- `libftd2xx` pour les sondes FTDI (vendoré dans `libs/libftd2xx/`)
|
|
|
|
## Compilation
|
|
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake ..
|
|
make
|
|
```
|
|
|
|
Le binaire est produit dans `build/bs/bs`.
|
|
|
|
## Lancement
|
|
|
|
```sh
|
|
cd build
|
|
./bs/bs
|
|
```
|
|
|
|
Au démarrage, `bs_explorer` cherche un fichier `config.script` dans le
|
|
répertoire courant pour surcharger les variables par défaut (clock FTDI,
|
|
mapping des broches TRST/SRST, etc.). Voir `modules/config/config.script`
|
|
pour la liste des variables disponibles.
|
|
|
|
## REPL
|
|
|
|
- `<Tab>` complète les noms de commande.
|
|
- Historique géré par GNU readline (flèches haut/bas, Ctrl-R…).
|
|
- `help` ou `?` liste les commandes ; `help <cmd>` détaille une commande.
|
|
- `exit`, `quit` ou Ctrl-D pour quitter.
|
|
|
|
## Flow typique
|
|
|
|
```sh
|
|
# 1. Ouvrir une sonde (1 = première sonde détectée)
|
|
bs_explorer> jtag_get_probes_list
|
|
bs_explorer> jtag_open_probe 1
|
|
|
|
# 2. Scanner la chaîne et charger les BSDL automatiquement
|
|
bs_explorer> jtag_autoinit
|
|
|
|
# 3. Passer le device 0 en EXTEST (contrôle direct des broches)
|
|
bs_explorer> jtag_set_mode 0 EXTEST
|
|
|
|
# 4. Configurer les 4 pins SPI sur les broches BSDL du FPGA
|
|
# (les noms exacts dépendent du BSDL chargé)
|
|
bs_explorer> jtag_set_spi_cs_pin 0 <PIN_CS> 0
|
|
bs_explorer> jtag_set_spi_clk_pin 0 <PIN_CLK> 0
|
|
bs_explorer> jtag_set_spi_mosi_pin 0 <PIN_MOSI> 0
|
|
bs_explorer> jtag_set_spi_miso_pin 0 <PIN_MISO> 0
|
|
|
|
# 5. Lire le JEDEC ID de la flash (0x9F + 3 dummies)
|
|
bs_explorer> jtag_spi_rd_wr 9F000000
|
|
```
|
|
|
|
Un fichier d'exemple minimal est fourni dans `scripts/example_script.txt`.
|
|
|
|
## Commandes principales
|
|
|
|
| Catégorie | Commandes |
|
|
|---------------|-----------|
|
|
| Contrôle script | `set`, `print`, `print_env_var`, `if`, `goto`, `call`, `return`, `rand`, `init_array`, `system`, `pause` |
|
|
| Sonde / chaîne | `jtag_get_probes_list`, `jtag_open_probe`, `jtag_init_scan`, `jtag_autoinit`, `jtag_get_nb_of_devices`, `jtag_get_devices_list` |
|
|
| BSDL / pins | `jtag_load_bsdl`, `jtag_get_pins_list`, `jtag_set_mode`, `jtag_set_pin_dir`, `jtag_set_pin_state`, `jtag_get_pin_state`, `jtag_push_pop` |
|
|
| I²C / MDIO / SPI sur pins BS | `jtag_set_i2c_*_pin`, `jtag_i2c_rd`, `jtag_i2c_wr`, `jtag_set_mdio_*_pin`, `jtag_mdio_rd`, `jtag_mdio_wr`, `jtag_set_spi_*_pin`, `jtag_spi_rd_wr` |
|
|
| Misc | `help`, `?`, `version`, `exit` |
|
|
|
|
Utiliser `help <commande>` pour l'aide détaillée.
|
|
|
|
## Sondes supportées
|
|
|
|
- **FTDI** MPSSE (FT2232D/H, FT4232H…) — voir le bloc `PROBE_FTDI_*` dans
|
|
`modules/config/config.script` pour le mapping des broches et la fréquence TCK.
|
|
- **SEGGER J-Link**
|
|
- **Linux GPIO** (sysfs ; déprécié sur kernels récents, à migrer vers libgpiod)
|
|
|
|
## Limitations connues sur Xilinx
|
|
|
|
Sur 7-Series / UltraScale / UltraScale+, `CCLK` n'est pas une broche
|
|
d'I/O classique et passe par la primitive `STARTUPE3`. Elle n'est donc
|
|
pas directement pilotable en EXTEST. Workarounds connus :
|
|
- utiliser l'instruction privée `ISC_DISABLE` ;
|
|
- câbler l'horloge SPI sur un autre pin utilisateur du FPGA.
|
|
|
|
À traiter lors de l'ajout de la couche d'abstraction FPGA.
|
|
|
|
## Structure du dépôt
|
|
|
|
```
|
|
bs/ Application (REPL readline)
|
|
modules/
|
|
├── jtag_core/ TAP state machine, IR/DR shifts
|
|
├── bsdl_parser/ Chargement de .bsd
|
|
├── bus_over_jtag/ SPI / I²C / MDIO / mem parallèle bit-bangés
|
|
├── drivers/ FTDI, J-Link, Linux GPIO, LPT
|
|
├── script/ Moteur de scripts (40+ commandes)
|
|
├── config/ config.script intégré
|
|
├── os_interface/ Wrappers fs/network portables
|
|
└── natsort/ Tri naturel des noms de pin
|
|
bsdl_files/ Fichiers BSDL des FPGAs cibles
|
|
scripts/ Exemples de scripts
|
|
libs/libftd2xx/ SDK FTDI vendoré
|
|
```
|
|
|
|
## Licence
|
|
|
|
`modules/jtag_core/` et les fichiers d'origine Viveris sont sous LGPL 2.1.
|
|
Voir `LICENSE` et `modules/jtag_core/COPYING.LESSER`.
|