Construire Hazard3-Doom
Important
Environnement de build Bash/WSL
Ces commandes de build sont des commandes Linux/Bash. Sous Windows,
exécutez-les depuis WSL avec Ubuntu. PowerShell et cmd.exe ne sont
pas des shells de build pris en charge pour les scripts .sh du dépôt.
Builds complets des cartes
Les wrappers de build complets des cartes sont la manière la plus sûre de construire un ensemble cohérent FPGA, moniteur et image Doom pour une cible.
ULX3S 85F, 64 Mio, 50 MHz :
./scripts/build-ulx3s-85f-doom.sh
Cible compacte ULX3S 12F, 32 Mio par défaut, 40 MHz :
./scripts/build-ulx3s-12f-doom.sh
ULX4M-LD 85F, cartographie logicielle 64 Mio, Hazard3 à 40 MHz et LiteDRAM à 60 MHz. Le build normal doit respecter toutes les contraintes d’horloge :
./scripts/build-ulx4m-ld-doom.sh
Les wrappers complets conservent les artifacts propres à chaque cible dans des répertoires propres à la carte. En particulier, les images Doom à téléverser sont :
build/ulx3s-85f/doom-image/hazard3-doom.h3img
build/ulx3s-12f/doom-image/hazard3-doom.h3img
build/ulx4m-ld/doom-image/hazard3-doom.h3img
La commande autonome doom/build-doom-image.sh documentée plus loin sur cette
page continue d’utiliser le répertoire générique build/doom-image/ sauf si
HAZARD3_DOOM_BUILD_DIR est défini.
Le build utilise les paramètres ULX4M-LD communs définis dans
scripts/build-ecp5-bitstream-common.sh et résumés dans
Profils de cartes. Le point de contrôle historique seed 2 figé
et versionné a également réussi la qualification DDR
complète sur une carte ULX4M-LD équipée de mémoire Micron. Un nouveau build
complet crée toutefois un nouveau netlist : relancez le sweep de timing et les
tests matériels pour tout artifact de release. ALLOW_TIMING_FAILURE=1 est
réservé aux expériences explicites de sweep ULX4M-LD, et non aux builds de
release. Voir Profils de cartes et
Sweeps de timing et de seeds ECP5.
Le wrapper 12F prend en charge une cartographie SDRAM 32 Mio ou 64 Mio, mais utilise 32 Mio par défaut. Si la cartographie 64 Mio est sélectionnée, gardez le moniteur et l’image Doom cohérents :
HAZARD3_MEMORY_PROFILE=64m ./scripts/build-ulx3s-12f-doom.sh
La cible compacte 12F prend volontairement en charge uniquement le chemin
Doom/vidéo 320x200. Son EBR de 1 Kio ne peut pas contenir le moniteur complet ;
le build complet génère donc un petit bootstrap UART résident et l’intègre dans
fpga_ulx3s_12f.bit. Au démarrage à froid, ce bootstrap initialise la console
à 115200 bauds et indique que le moniteur complet réside en SDRAM. Après avoir
programmé le bitstream 12F, exécutez :
./scripts/load-firmware-12f.sh
L’outil réutilise un serveur OpenOCD déjà à l’écoute sur localhost:3333 ou
lance automatiquement scripts/start-openocd.sh, attend le serveur GDB,
charge et vérifie build/ulx3s-12f/monitor/hazard3-boot-monitor.elf, puis
arrête uniquement le processus OpenOCD qu’il a lui-même lancé.
Moniteur résident uniquement
Le constructeur générique du moniteur utilise par défaut la cartographie 64 Mio à 50 MHz :
./scripts/build.sh
Sorties typiques :
build/hazard3-boot-monitor.elf
build/hazard3-boot-monitor.map
build/hazard3-boot-monitor.bin
Les wrappers complets des cartes règlent pour vous le profil mémoire, l’horloge
système et le script de linker propres à la cible. Pour les builds manuels, les
principaux contrôles sont HAZARD3_MEMORY_PROFILE, HAZARD3_SYS_CLK_HZ et
HAZARD3_MONITOR_LINKER_SCRIPT.
Pour une mise à jour logicielle seule du moniteur ULX4M-LD sur un FPGA déjà configuré à 40 MHz, conservez la sortie séparée du preload résident :
HAZARD3_BUILD_DIR="$PWD/build/ulx4m-ld-monitor-test/monitor" \
HAZARD3_MEMORY_PROFILE=64m \
HAZARD3_SYS_CLK_HZ=40000000 \
./scripts/build.sh
Chargez-la dans une session OpenOCD déjà active avec :
./scripts/load-firmware.sh \
./build/ulx4m-ld-monitor-test/monitor/hazard3-boot-monitor.elf
Cette opération met à jour uniquement le logiciel processeur dans le FPGA en cours d’exécution et ne reroute pas le bitstream connu comme bon.
Image Doom liée uniquement
Pour le profil 64 Mio utilisé par ULX3S 85F et ULX4M-LD 85F :
HAZARD3_MEMORY_PROFILE=64m ./doom/build-doom-image.sh
Pour une image 12F 32 Mio :
HAZARD3_MEMORY_PROFILE=32m \
HAZARD3_DOOM_HDMI_RESOLUTION=320x200 \
./doom/build-doom-image.sh
Sorties typiques :
build/doom-image/hazard3-doom.elf
build/doom-image/hazard3-doom.map
build/doom-image/hazard3-doom.bin
build/doom-image/hazard3-doom.h3img
Tester un autre checkout Hazard3
Vous pouvez tester un checkout matériel sans modifier le pointeur du sous-module Hazard3-Doom épinglé :
HAZARD3_ROOT=/mnt/c/workspace/Hazard3 \
./scripts/build-ulx3s-85f-doom.sh
Préparation et vérification des sous-modules
Initialisez les sous-modules nécessaires au build :
./scripts/setup-submodules.sh
Cela initialise DoomGeneric et Hazard3 ainsi que les sous-modules Hazard3
imbriqués scripts et example_soc/libfpga. Pour initialiser l’arbre
récursif complet :
HAZARD3_INIT_ALL_SUBMODULES=1 ./scripts/setup-submodules.sh
Pour les diagnostics d’historique de source et de sous-modules, voir
Référence des scripts. En particulier, la commande Windows
check_submodules.bat valide les gitlinks enregistrés localement, tandis que
hazard3-doom-source-status.sh compare les branches entre les forks GitHub
associés.
Sélection des seeds
Ne réutilisez pas aveuglément un seed nextpnr précédemment bon après une modification importante de la netlist. Utilisez les scripts de placement seul pour classer rapidement les candidats, puis les sweeps routés pour le timing autoritatif et la génération du bitstream.
Par exemple, le flux 12F peut utiliser :
SWEEP_JOBS=30 ./scripts/sweep-peek-ulx3s-12f.sh --all
SWEEP_JOBS=30 ./scripts/sweep-ulx3s-12f.sh --all
Voir Référence des scripts pour le catalogue des outils de sweep et Sweeps de timing et de seeds ECP5 pour la matrice GitHub Actions, le choix des paramètres, le moniteur de timing en direct, les timeouts, les artifacts et les règles de reproductibilité.
Propriété du build
Le projet conserve volontairement le matériel FPGA/CPU réutilisable dans Hazard3, tandis que le moniteur et l’application spécifiques à Doom restent dans Hazard3-Doom. Voir Organisation des dépôts et propriété.