electronics/bs_explorer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

translate README to English

Browse Source 
Match the existing project convention (Viveris code, commit messages).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Foué
2026-05-20 22:26:35 +02:00
parent 7cb3627754
commit 6c676d38f2
1 changed files with 71 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
README.md
View File

@@ -1,33 +1,33 @@
# bs_explorer — Boundary Scan Explorer # bs_explorer — Boundary Scan Explorer
Outil en ligne de commande pour explorer une chaîne JTAG, contrôler les Command-line tool to explore a JTAG chain, drive an FPGA's pins through
broches d'un FPGA via le boundary scan (BSDL), et — à terme — programmer boundary scan (BSDL), and — eventually — program SPI memories attached
les mémoires SPI connectées au FPGA (Xilinx et autres) en bit-bangeant to the FPGA (Xilinx and others) by bit-banging SPI on I/O pins placed
SPI sur les pins d'I/O placés en EXTEST. in EXTEST.
Basé sur la librairie [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner) Based on the [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner)
de Viveris (LGPL). library by Viveris (LGPL).
## État ## Status
- Détection de la chaîne JTAG via sondes FTDI / J-Link / Linux GPIO : OK - JTAG chain detection through FTDI / J-Link / Linux GPIO probes: OK
- Chargement automatique d'un BSDL par IDCODE : OK - Automatic BSDL loading by IDCODE: OK
- Pilotage de pins en SAMPLE / EXTEST : OK - Pin control in SAMPLE / EXTEST: OK
- SPI bit-bang sur 4 pins du FPGA (MOSI/MISO/CS/CLK) : OK (primitive bas niveau) - SPI bit-bang on 4 FPGA pins (MOSI/MISO/CS/CLK): OK (low-level primitive)
- Programmation de flash SPI (détection JEDEC, erase, page program, verify) : **à venir** - SPI flash programming (JEDEC detect, erase, page program, verify): **planned**
- Abstraction multi-FPGA (mapping pins → flash par cible) : **à venir** - Multi-FPGA abstraction (per-target pin → flash mapping): **planned**
Seul BSDL embarqué pour l'instant : Xilinx Kintex UltraScale+ KU15P Only one BSDL is bundled so far: Xilinx Kintex UltraScale+ KU15P
(`bsdl_files/xcku15p_ffve1517.bsd`). En ajouter d'autres se fait en (`bsdl_files/xcku15p_ffve1517.bsd`). Add more by dropping `.bsd` files
déposant le `.bsd` dans `bsdl_files/`. in `bsdl_files/`.
## Dépendances ## Dependencies
- CMake ≥ 3.10, gcc/clang - CMake ≥ 3.10, gcc/clang
- `readline` (Arch : `readline`, Debian/Ubuntu : `libreadline-dev`) - `readline` (Arch: `readline`, Debian/Ubuntu: `libreadline-dev`)
- `libftd2xx` pour les sondes FTDI (vendoré dans `libs/libftd2xx/`) - `libftd2xx` for FTDI probes (vendored in `libs/libftd2xx/`)
## Compilation ## Build
```sh ```sh
mkdir build && cd build mkdir build && cd build
@@ -35,101 +35,101 @@ cmake ..
make make
``` ```
Le binaire est produit dans `build/bs/bs`. The binary is produced at `build/bs/bs`.
## Lancement ## Run
```sh ```sh
cd build cd build
./bs/bs ./bs/bs
``` ```
Au démarrage, `bs_explorer` cherche un fichier `config.script` dans le At startup, `bs_explorer` looks for a `config.script` file in the
répertoire courant pour surcharger les variables par défaut (clock FTDI, current directory to override default settings (FTDI clock, TRST/SRST
mapping des broches TRST/SRST, etc.). Voir `modules/config/config.script` pin mapping, etc.). See `modules/config/config.script` for the full
pour la liste des variables disponibles. list of variables.
## REPL ## REPL
- `<Tab>` complète les noms de commande. - `<Tab>` completes command names.
- Historique géré par GNU readline (flèches haut/bas, Ctrl-R…). - History handled by GNU readline (up/down arrows, Ctrl-R, …).
- `help` ou `?` liste les commandes ; `help <cmd>` détaille une commande. - `help` or `?` lists commands; `help <cmd>` shows details.
- `exit`, `quit` ou Ctrl-D pour quitter. - `exit`, `quit`, or Ctrl-D to leave.
## Flow typique ## Typical flow
```sh ```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_get_probes_list
bs_explorer> jtag_open_probe 1 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 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 bs_explorer> jtag_set_mode 0 EXTEST
# 4. Configurer les 4 pins SPI sur les broches BSDL du FPGA # 4. Wire the 4 SPI pins onto the FPGA's BSDL pins
# (les noms exacts dépendent du BSDL chargé) # (exact names depend on the loaded BSDL)
bs_explorer> jtag_set_spi_cs_pin 0 <PIN_CS> 0 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_clk_pin 0 <PIN_CLK> 0
bs_explorer> jtag_set_spi_mosi_pin 0 <PIN_MOSI> 0 bs_explorer> jtag_set_spi_mosi_pin 0 <PIN_MOSI> 0
bs_explorer> jtag_set_spi_miso_pin 0 <PIN_MISO> 0 bs_explorer> jtag_set_spi_miso_pin 0 <PIN_MISO> 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 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 | | Category | Commands |
|---------------|-----------| |----------|----------|
| Contrôle script | `set`, `print`, `print_env_var`, `if`, `goto`, `call`, `return`, `rand`, `init_array`, `system`, `pause` | | Script control | `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` | | 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` | | 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` | | 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` | | Misc | `help`, `?`, `version`, `exit` |
Utiliser `help <commande>` pour l'aide détaillée. Use `help <command>` for per-command help.
## Sondes supportées ## Supported probes
- **FTDI** MPSSE (FT2232D/H, FT4232H…) — voir le bloc `PROBE_FTDI_*` dans - **FTDI** MPSSE (FT2232D/H, FT4232H, …) — see the `PROBE_FTDI_*` block
`modules/config/config.script` pour le mapping des broches et la fréquence TCK. in `modules/config/config.script` for pin mapping and TCK frequency.
- **SEGGER J-Link** - **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 On 7-Series / UltraScale / UltraScale+, `CCLK` is not a regular I/O pin
d'I/O classique et passe par la primitive `STARTUPE3`. Elle n'est donc and goes through the `STARTUPE3` primitive, so it cannot be driven
pas directement pilotable en EXTEST. Workarounds connus : directly in EXTEST. Known workarounds:
- utiliser l'instruction privée `ISC_DISABLE` ; - use the private `ISC_DISABLE` instruction;
- câbler l'horloge SPI sur un autre pin utilisateur du FPGA. - 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/ modules/
├── jtag_core/ TAP state machine, IR/DR shifts ├── jtag_core/ TAP state machine, IR/DR shifts
├── bsdl_parser/ Chargement de .bsd ├── bsdl_parser/ .bsd loader
├── bus_over_jtag/ SPI / I²C / MDIO / mem parallèle bit-bangés ├── bus_over_jtag/ SPI / I²C / MDIO / parallel mem bit-bang
├── drivers/ FTDI, J-Link, Linux GPIO, LPT ├── drivers/ FTDI, J-Link, Linux GPIO, LPT
├── script/ Moteur de scripts (40+ commandes) ├── script/ Script engine (40+ commands)
├── config/ config.script intégré ├── config/ Built-in config.script
├── os_interface/ Wrappers fs/network portables ├── os_interface/ Portable fs/network wrappers
└── natsort/ Tri naturel des noms de pin └── natsort/ Natural-order pin-name sorting
bsdl_files/ Fichiers BSDL des FPGAs cibles bsdl_files/ BSDL files for target FPGAs
scripts/ Exemples de scripts scripts/ Example scripts
libs/libftd2xx/ SDK FTDI vendoré libs/libftd2xx/ Vendored FTDI SDK
``` ```
## Licence ## License
`modules/jtag_core/` et les fichiers d'origine Viveris sont sous LGPL 2.1. `modules/jtag_core/` and the original Viveris files are under LGPL 2.1.
Voir `LICENSE` et `modules/jtag_core/COPYING.LESSER`. See `LICENSE` and `modules/jtag_core/COPYING.LESSER`.