phase 1: cleanup, REPL polish, README

- 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>
2026-05-20 22:22:05 +02:00
parent 9e0ca10a71
commit 7cb3627754
17 changed files with 247 additions and 481 deletions
--- a/README.md
+++ b/README.md
@@ -1,16 +1,135 @@
-# My application for boundary scan
+# bs_explorer — Boundary Scan Explorer

-Basée sur la librairie de l'application [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner).
+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.

-## Usage
+Basé sur la librairie [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner)
+de Viveris (LGPL).

-TBD
+## État

-## How to compile
+- 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**

-```
-mkdir build
-cd build
+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`.