From 6c676d38f23b9d8afdf710fb6c7bc4ea386efc76 Mon Sep 17 00:00:00 2001 From: francois Date: Wed, 20 May 2026 22:26:35 +0200 Subject: [PATCH] translate README to English Match the existing project convention (Viveris code, commit messages). Co-Authored-By: Claude Opus 4.7 --- README.md | 142 +++++++++++++++++++++++++++--------------------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 9835cc4..eb8e5c3 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,33 @@ # 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. +Command-line tool to explore a JTAG chain, drive an FPGA's pins through +boundary scan (BSDL), and — eventually — program SPI memories attached +to the FPGA (Xilinx and others) by bit-banging SPI on I/O pins placed +in EXTEST. -Basé sur la librairie [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner) -de Viveris (LGPL). +Based on the [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner) +library by Viveris (LGPL). -## État +## Status -- 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** +- JTAG chain detection through FTDI / J-Link / Linux GPIO probes: OK +- Automatic BSDL loading by IDCODE: OK +- Pin control in SAMPLE / EXTEST: OK +- SPI bit-bang on 4 FPGA pins (MOSI/MISO/CS/CLK): OK (low-level primitive) +- SPI flash programming (JEDEC detect, erase, page program, verify): **planned** +- Multi-FPGA abstraction (per-target pin → flash mapping): **planned** -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/`. +Only one BSDL is bundled so far: Xilinx Kintex UltraScale+ KU15P +(`bsdl_files/xcku15p_ffve1517.bsd`). Add more by dropping `.bsd` files +in `bsdl_files/`. -## Dépendances +## Dependencies - CMake ≥ 3.10, gcc/clang -- `readline` (Arch : `readline`, Debian/Ubuntu : `libreadline-dev`) -- `libftd2xx` pour les sondes FTDI (vendoré dans `libs/libftd2xx/`) +- `readline` (Arch: `readline`, Debian/Ubuntu: `libreadline-dev`) +- `libftd2xx` for FTDI probes (vendored in `libs/libftd2xx/`) -## Compilation +## Build ```sh mkdir build && cd build @@ -35,101 +35,101 @@ cmake .. make ``` -Le binaire est produit dans `build/bs/bs`. +The binary is produced at `build/bs/bs`. -## Lancement +## Run ```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. +At startup, `bs_explorer` looks for a `config.script` file in the +current directory to override default settings (FTDI clock, TRST/SRST +pin mapping, etc.). See `modules/config/config.script` for the full +list of variables. ## REPL -- `` complète les noms de commande. -- Historique géré par GNU readline (flèches haut/bas, Ctrl-R…). -- `help` ou `?` liste les commandes ; `help ` détaille une commande. -- `exit`, `quit` ou Ctrl-D pour quitter. +- `` completes command names. +- History handled by GNU readline (up/down arrows, Ctrl-R, …). +- `help` or `?` lists commands; `help ` shows details. +- `exit`, `quit`, or Ctrl-D to leave. -## Flow typique +## Typical flow ```sh -# 1. Ouvrir une sonde (1 = première sonde détectée) +# 1. Open a probe (1 = first detected probe) bs_explorer> jtag_get_probes_list bs_explorer> jtag_open_probe 1 -# 2. Scanner la chaîne et charger les BSDL automatiquement +# 2. Scan the chain and auto-load BSDL files bs_explorer> jtag_autoinit -# 3. Passer le device 0 en EXTEST (contrôle direct des broches) +# 3. Switch device 0 to EXTEST (direct pin control) 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é) +# 4. Wire the 4 SPI pins onto the FPGA's BSDL pins +# (exact names depend on the loaded BSDL) bs_explorer> jtag_set_spi_cs_pin 0 0 bs_explorer> jtag_set_spi_clk_pin 0 0 bs_explorer> jtag_set_spi_mosi_pin 0 0 bs_explorer> jtag_set_spi_miso_pin 0 0 -# 5. Lire le JEDEC ID de la flash (0x9F + 3 dummies) +# 5. Read the flash JEDEC ID (0x9F + 3 dummies) bs_explorer> jtag_spi_rd_wr 9F000000 ``` -Un fichier d'exemple minimal est fourni dans `scripts/example_script.txt`. +A minimal example script is provided in `scripts/example_script.txt`. -## Commandes principales +## Main commands -| 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` | +| Category | Commands | +|----------|----------| +| Script control | `set`, `print`, `print_env_var`, `if`, `goto`, `call`, `return`, `rand`, `init_array`, `system`, `pause` | +| Probe / chain | `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 over BS pins | `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 ` pour l'aide détaillée. +Use `help ` for per-command help. -## Sondes supportées +## Supported probes -- **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. +- **FTDI** MPSSE (FT2232D/H, FT4232H, …) — see the `PROBE_FTDI_*` block + in `modules/config/config.script` for pin mapping and TCK frequency. - **SEGGER J-Link** -- **Linux GPIO** (sysfs ; déprécié sur kernels récents, à migrer vers libgpiod) +- **Linux GPIO** (sysfs; deprecated on recent kernels, libgpiod migration TBD) -## Limitations connues sur Xilinx +## Known Xilinx caveats -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. +On 7-Series / UltraScale / UltraScale+, `CCLK` is not a regular I/O pin +and goes through the `STARTUPE3` primitive, so it cannot be driven +directly in EXTEST. Known workarounds: +- use the private `ISC_DISABLE` instruction; +- route the SPI clock through another user pin of the FPGA. -À traiter lors de l'ajout de la couche d'abstraction FPGA. +To be handled when the FPGA abstraction layer is added. -## Structure du dépôt +## Repository layout ``` -bs/ Application (REPL readline) +bs/ Application (readline REPL) 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 +├── bsdl_parser/ .bsd loader +├── bus_over_jtag/ SPI / I²C / MDIO / parallel mem bit-bang ├── 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é +├── script/ Script engine (40+ commands) +├── config/ Built-in config.script +├── os_interface/ Portable fs/network wrappers +└── natsort/ Natural-order pin-name sorting +bsdl_files/ BSDL files for target FPGAs +scripts/ Example scripts +libs/libftd2xx/ Vendored FTDI SDK ``` -## Licence +## License -`modules/jtag_core/` et les fichiers d'origine Viveris sont sous LGPL 2.1. -Voir `LICENSE` et `modules/jtag_core/COPYING.LESSER`. +`modules/jtag_core/` and the original Viveris files are under LGPL 2.1. +See `LICENSE` and `modules/jtag_core/COPYING.LESSER`.