emuko

Un émulateur RISC-V en Rust. Il démarre Linux.

emuko.dev

La machine implémente RV64IMAFDC avec les niveaux de privilège M/S/U et la mémoire virtuelle Sv39. Elle exécute un JIT sur les hôtes ARM64 et x86_64, avec un interpréteur en secours si nécessaire. Les périphériques sont UART 16550, CLINT, PLIC et SBI 1.0. Une seule dépendance externe : zstd.

Ce n'est pas l'émulateur le plus rapide. En mode interpréteur, il est environ trois fois plus lent que QEMU. En mode JIT, environ vingt-neuf fois plus lent. Le chaînage de blocs de code n'est pas encore implémenté ; cela améliora les performances. Nous disons cela clairement pour que vous sachiez ce que vous obtenez.

Ce qu'il fait bien : il est simple à utiliser, expose une API HTTP pour le contrôle de la machine, peut exécuter un ELF bare-metal sans noyau, et peut sauvegarder et restaurer l'état complet de la machine. Ce sont des fonctionnalités utiles pour le travail système et les tests.

Compilation

cargo build --release

Le binaire est target/release/emuko. Créez un alias.

alias emuko=target/release/emuko

Démarrage rapide

Obtenir un noyau

emuko dow

Télécharge un noyau et un initrd Debian RISC-V netboot dans ~/.emuko/. Le SHA256 est vérifié. Aucun noyau propre n'est nécessaire.

Démarrer Linux

emuko start

L'émulateur s'exécute en tant que démon. Vous êtes attaché à sa console. Vous verrez le noyau démarrer. Vous obtiendrez un shell.

Contrôler une machine en cours d'exécution

emuko start            # rattacher la console
emuko dump             # afficher l'état du CPU
emuko stop             # suspendre l'exécution
emuko con              # continuer
emuko step 1000        # exécuter pas à pas N instructions
emuko snap             # prendre un instantané
emuko kill             # arrêter

Le démon écoute sur http://127.0.0.1:7788/v1/api/ et accepte les connexions console WebSocket sur ws://127.0.0.1:7788/v1/ws/uart. Les deux sont utilisables depuis des scripts.

Exécution d'ELF bare-metal

Parfois, vous ne voulez pas de système d'exploitation. Vous voulez la machine, un binaire, et rien d'autre entre eux.

emuko run ./my_program.elf

Le démon réinitialise la machine, charge les segments ELF à leurs adresses physiques, et commence l'exécution. La sortie arrive sur la console UART. Le démon doit déjà être en cours d'exécution.

Pour écrire sur la console depuis le bare-metal : stockez un octet à 0x1000_0000.

Exemples

Le répertoire examples/ contient des programmes qui s'exécutent de cette façon.

Un compilateur croisé RISC-V est nécessaire pour les compiler. Sur macOS : brew install riscv64-elf-gcc. Sur Linux : apt install gcc-riscv64-linux-gnu.

emuko start
cd examples/bare_printf
make run

Instantanés

L'état de la machine — registres, mémoire, tout — peut être sauvegardé et restauré.

emuko snap                  # instantané maintenant
emuko snap 5000000          # instantané automatique toutes les 5M étapes
emuko snap stop             # arrêter les instantanés automatiques
emuko ls                    # lister les instantanés
emuko restore <snapshot>    # restaurer

Carte mémoire

La machine virtuelle utilise une disposition MMIO fixe compatible avec la plateforme virt QEMU RISC-V.

Disposition de la RAM au démarrage de Linux

Avec les paramètres par défaut (load_addr=0x80200000, 1 Gio de RAM) :

0x8000_0000  ── Base RAM
                (espace — utilisable par les programmes bare-metal)
0x8020_0000  ── Image du noyau
                │  .text / .rodata / .data / .bss
                └─ fin du noyau
                (libre)
             ── initrd
             ── DTB
             ── Region EFI    (128 Kio, noyaux PE/UEFI uniquement)
0xBFFF_FFFF  ── Fin RAM

Le DTB, l'initrd et l'EFI sont placés vers le bas à partir du sommet de la RAM. L'émulateur vérifie les chevauchements avec le noyau au démarrage et s'arrête avec une erreur claire si la RAM est trop petite.

Disposition de la RAM pour ELF bare-metal

Les segments PT_LOAD de l'ELF sont placés à leurs adresses p_vaddr. bare_printf est lié à 0x8000_0000 :

0x8000_0000  ── .text
             ── .rodata
             ── .data
             ── .bss   (mis à zéro par start.S)
             ── pile   (16 Kio au-dessus de BSS)

Pas de noyau. Pas d'initrd. Pas de DTB. Les registres démarrent à zéro sauf sp, que l'émulateur initialise à ram_base + 0x100000 avant que start.S ne prenne le relais.

Configuration

Les options peuvent être passées en ligne de commande, définies comme variables d'environnement ou placées dans emuko.yml.

Comparaison

Comparaison directe avec les émulateurs RISC-V couramment utilisés. ✅ = supporté et documenté. — = non intégré.

Sources : QEMU virt · Spike · Renode

Licence

Apache 2.0. Voir LICENSE.