Z80
v0.2-pre-2024-09-21
La bibliothèque Z80 met en œuvre un émulateur rapide, petit et précis du Zilog Z80. Il émule tout ce qui est connu à ce jour sur ce processeur, y compris les comportements sans papiers, Memptr, Q et la réinitialisation spéciale. Il a également l'honneur d'avoir été le premier projet open-source à fournir une émulation complète du mode d'interruption 0.
Le code source est écrit dans ANSI C pour la portabilité maximale et est largement commenté. L'objectif a été d'écrire un logiciel bien structuré et facile à comprendre; Quelque chose de solide et d'élégant qui peut résister à l'épreuve du temps sans avoir besoin de changements majeurs.
Cet émulateur de processeur Z80 a une conception classique avec une granularité au niveau de l'instruction qui offre les meilleures performances, tout en offrant une flexibilité raisonnable pour atteindre la précision jusqu'au niveau en T.
La granularité au niveau de l'enseignement implique que, sauf dans quelques cas bien définis, l'exécution d'une instruction donnée ne peut pas s'arrêter jusqu'à ce que tous ses cycles M internes aient été traités (c'est-à-dire, les instructions ne sont pas divisées en micro-opérations). De plus, les registres ne sont modifiés qu'une fois par instruction et le compteur de l'état T est normalement mis à jour après l'exécution d'une instruction complète.
Cela dit, les instructions, les drapeaux, les accès à la mémoire, les interruptions, les cycles d'horloge, etc., sont émulés avec précision selon la documentation technique disponible, les résultats réalisés après des décennies de recherche sur les simulations Z80 et électroniques. Et, bien sûr, l'émulateur passe les tests les plus exhaustifs écrits à ce jour, y compris les trois principales suites de tests:
Cet ensemble de programmes est destiné à aider les auteurs de l'émulateur à atteindre le niveau souhaité de l'authenticité de l'émulation du CPU. Chacun des programmes inclus effectue un calcul exhaustif en utilisant chacune des instructions Z80 testées, compare les résultats avec des valeurs obtenues à partir d'un véritable spectre Sinclair ZX 48K avec le processeur Zilog Z80 et rapporte tous les écarts détectés.
z80full.tap Teste tous les drapeaux et registres. | z80doc.tap Teste tous les registres, mais seulement des drapeaux officiellement documentés. |
z80flags.tap Teste tous les drapeaux, ignore les registres. | z80docflags.tap Tests Seule les drapeaux documentés, ignore les registres. |
z80ccf.tap Teste tous les indicateurs après avoir exécuté ccf après chaque instruction testée. | z80memptr.tap Teste tous les indicateurs après avoir exécuté bit N,(hl) après chaque instruction testée. |
z80full.tap Teste tous les drapeaux et registres. | z80doc.tap Teste tous les registres, mais seulement des drapeaux officiellement documentés. |
z80flags.tap Teste tous les drapeaux, ignore les registres. | z80docflags.tap Tests Seule les drapeaux documentés, ignore les registres. |
z80ccf.tap Teste tous les indicateurs après avoir exécuté ccf après chaque instruction testée. | z80memptr.tap Teste tous les indicateurs après avoir exécuté bit N,(hl) après chaque instruction testée. |
Cette suite effectue une série de tests pour vérifier les documents MEMPTR (anglais, russe) , qui sont parfaits, ainsi qu'une brève exécution à travers plusieurs des gammes d'opcode CBh/DDh/FDh . Les résultats des tests dans le programme sont comparés à ceux d'un processeur NEC D780C-1, mais Simon Conway a gentiment testé plusieurs autres clones Z80, confirmant les mêmes résultats.
z80tests.tap | |
L'exercice de jeu d'instructions Z80 de Frank Cringle tente d'exécuter chaque opcode Z80, en les mettant à travers un cycle de tests et en comparant les résultats aux résultats réels de l'exécution du code sur un vrai Z80. L'exercice est fourni avec Frank's Yaze (encore un autre émulateur Z80). Il est souvent difficile de retrouver, donc Jonathan Graham Harston l'a mis en place ici, ainsi que quelques conversions. La dernière version de Yaze est disponible sur le site Web d'Andreas Gerlich.
zexdoc.tap Tests Effets de drapeau documentés officiellement. | zexall.tap Teste tous les changements de drapeau. |
zexfix.tap Teste tous les changements de drapeau. | zexbit.tap Teste tous les changements de drapeau des instructions bit . |
zexall2.tap |
Tout d'abord, ajoutez le référentiel zxe et mettez à jour l'index du package:
sudo mkdir -pm700 /root/.gnupg
sudo mkdir -pm755 /etc/apt/keyrings
sudo gpg --no-default-keyring --keyring /etc/apt/keyrings/zxe-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys FE214A38D6A0C01D9AF514EE841EA3BD3A7E1487
echo " deb [arch= $( dpkg --print-architecture ) signed-by=/etc/apt/keyrings/zxe-archive-keyring.gpg] https://zxe.io/repos/apt stable main " | sudo tee /etc/apt/sources.list.d/zxe.list
sudo apt updateEnsuite, installez le package de la bibliothèque:
sudo apt install libz80Dans le cas où vous avez besoin de créer un logiciel qui nécessite la bibliothèque Z80, installez également le package de développement:
sudo apt install libz80-dev Tout d'abord, ajoutez et synchronisez la superposition zxe :
eselect repository add zxe git https://github.com/redcode/zxe-gentoo-overlay.git
emaint sync --repo zxePuis installez la bibliothèque:
emerge emulation-libs/z80brew install redcode/zxe/z80Des binaires prédéfinis pour Windows sont disponibles sur la page de téléchargement.
Vous aurez besoin de CMake v3.14 ou ultérieure pour construire le package et, éventuellement, des versions récentes de Doxygen, Sphinx et Breathe pour compiler la documentation. Assurez-vous également que vous avez le latex avec la prise en charge PDF installée sur votre système si vous souhaitez générer la documentation au format PDF.
L'émulateur nécessite certains types et macros inclus dans Zeta, une bibliothèque en tête sans dépendance uniquement utilisée pour conserver la compatibilité avec la plupart des compilateurs C. Installez Zeta ou extraire son code source Tarball dans le répertoire racine du projet Z80 ou de son répertoire parent. Zeta est la seule dépendance; L'émulateur est une implémentation indépendante et en tant que tel ne dépend pas de la bibliothèque standard C.
Une fois les conditions préalables remplies, créez un répertoire et exécutez cmake à partir de là pour préparer le système de construction:
mkdir build
cd build
cmake [options] < Z80-project-directory > Les fichiers de construction résultants peuvent être configurés en passant des options à cmake . Pour afficher une liste complète des personnes disponibles avec leurs paramètres actuels, saisissez ce qui suit:
cmake -LAH -N -B .En cas de doute, lisez la documentation CMake pour plus d'informations sur les options de configuration. Voici quelques-unes des options standard les plus pertinentes de CMake:
Générez des bibliothèques partagées plutôt que des bibliothèques statiques.
La valeur par défaut est NO .
-DCMAKE_BUILD_TYPE=(Debug|Release|RelWithDebInfo|MinSizeRel)
Choisissez le type de build (configuration) à générer.
La valeur par défaut est Release .
-DCMAKE_INSTALL_NAME_DIR="<path>"
Spécifiez la partie répertoire du nom d'installation de la bibliothèque dynamique sur les plates-formes Apple (pour les bibliothèques partagées installées).
Non défini par défaut.
-DCMAKE_INSTALL_PREFIX="<path>"
Spécifiez le préfixe d'installation.
La valeur par défaut est "/usr/local" (sur les systèmes d'exploitation UNIX et Unix).
Les options spécifiques au package sont préfixées avec Z80_ et peuvent être divisées en deux groupes. Le premier contrôle les aspects non liés au code source de la bibliothèque:
-DZ80_DEPOT_LOCATION="<location>"
Spécifiez le répertoire ou l'URL du dépôt contenant les fichiers de test (c'est-à-dire le firmware et les logiciels requis par l'outil de test).
La valeur par défaut est "http://zxe.io/depot" .
-DZ80_FETCH_TEST_FILES=(YES|NO)
Copiez ou téléchargez les fichiers de test depuis le dépôt dans le répertoire de construction.
La valeur par défaut est NO .
-DZ80_INSTALL_CMAKEDIR="<path>"
Spécifiez le répertoire dans lequel installer le package de configuration CMake.
La valeur par défaut est "${CMAKE_INSTALL_LIBDIR}/cmake/Z80" .
-DZ80_INSTALL_PKGCONFIGDIR="<path>"
Spécifiez le répertoire dans lequel installer le fichier PKG-Config.
La valeur par défaut est "${CMAKE_INSTALL_LIBDIR}/pkgconfig" .
-DZ80_NOSTDLIB_FLAGS=(Auto|"[<flag>[;<flag>...]]")
Spécifiez les drapeaux de liaison utilisés pour éviter de lier aux bibliothèques système.
La valeur par défaut est Auto (indicateurs AutoConfigure). Si vous obtenez des erreurs de linker, définissez cette option sur "" .
-DZ80_OBJECT_LIBS=(YES|NO)
Construisez l'émulateur en tant que bibliothèque d'objets.
Cette option a priorité sur BUILD_SHARED_LIBS et Z80_SHARED_LIBS . S'il est activé, le système de construction ignorera Z80_WITH_CMAKE_SUPPORT et Z80_WITH_PKGCONFIG_SUPPORT , car aucune bibliothèque ou fichiers de support ne sera installé.
La valeur par défaut est NO .
Construisez l'émulateur en tant que bibliothèque partagée, plutôt que statique.
Cette option a la priorité sur BUILD_SHARED_LIBS .
Non défini par défaut.
-DZ80_SPHINX_HTML_THEME="[<name>]"
Spécifiez le thème Sphinx pour la documentation au format HTML.
La valeur par défaut est "" (utilisez le thème par défaut).
-DZ80_WITH_CMAKE_SUPPORT=(YES|NO)
Générez et installez le package CMake Config Config-File.
La valeur par défaut est NO .
-DZ80_WITH_HTML_DOCUMENTATION=(YES|NO)
Construisez et installez la documentation au format HTML.
Il faut du doxygène, du sphinx et du respirer.
La valeur par défaut est NO .
-DZ80_WITH_PDF_DOCUMENTATION=(YES|NO)
Construisez et installez la documentation au format PDF.
Il nécessite du doxygène, du sphinx, de la respiration et du latex avec un support PDF.
La valeur par défaut est NO .
-DZ80_WITH_PKGCONFIG_SUPPORT=(YES|NO)
Générer et installer le fichier PKG-Config.
La valeur par défaut est NO .
-DZ80_WITH_STANDARD_DOCUMENTS=(YES|NO)
Installez les documents texte standard distribués avec le package: AUTHORS , COPYING , COPYING.LESSER Unser, HISTORY , README et THANKS .
La valeur par défaut est NO .
-DZ80_WITH_TESTS=(YES|NO)
Construire l'outil de test.
La valeur par défaut est NO .
Le deuxième groupe d'options spécifiques à un package configure le code source de la bibliothèque en préduisant les macros qui permettent des fonctionnalités facultatives:
-DZ80_WITH_EXECUTE=(YES|NO)
Créez l'implémentation de la fonction z80_execute .
La valeur par défaut est NO .
-DZ80_WITH_FULL_IM0=(YES|NO)
Créez la mise en œuvre complète du mode d'interruption 0 plutôt que celle réduite.
La valeur par défaut est NO .
-DZ80_WITH_IM0_RETX_NOTIFICATIONS=(YES|NO)
Activez les notifications facultatives pour toute instruction reti ou retn exécutée pendant la réponse en mode d'interruption 0.
La valeur par défaut est NO .
-DZ80_WITH_Q=(YES|NO)
Créez la mise en œuvre de Q.
La valeur par défaut est NO .
-DZ80_WITH_SPECIAL_RESET=(YES|NO)
Créez la mise en œuvre de la réinitialisation spéciale.
La valeur par défaut est NO .
-DZ80_WITH_UNOFFICIAL_RETI=(YES|NO)
Configurez les instructions sans papiers ED5Dh , ED6Dh et ED7Dh en tant que reti au lieu de retn .
La valeur par défaut est NO .
-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=(YES|NO)
Construisez l'implémentation du bogue affectant les NMOS Zilog Z80, ce qui entraîne réinitialiser le drapeau P / V lorsqu'une interruption de masque est acceptée lors de l'exécution des instructions ld a,{i|r} .
La valeur par défaut est NO .
Les agents de colis sont encouragés à utiliser au moins les options suivantes pour la bibliothèque partagée:
-DZ80_WITH_EXECUTE=YES
-DZ80_WITH_FULL_IM0=YES
-DZ80_WITH_IM0_RETX_NOTIFICATIONS=YES
-DZ80_WITH_Q=YES
-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=YES
Enfin, une fois le système de construction configuré en fonction de vos besoins, créez et installez le package:
cmake --build . [--config (Debug | Release | RelWithDebInfo | MinSizeRel)]
cmake --install . [--config < configuration > ] [--strip] L'option --config est nécessaire uniquement pour les générateurs CMake qui ignorent CMAKE_BUILD_TYPE (par exemple, Xcode et Visual Studio). Utiliser --strip pour supprimer les informations de débogage et les symboles non publiques lors de l'installation des versions non-debug de la bibliothèque partagée.
Utilisez ce qui suit pour construire l'émulateur en tant que bibliothèque partagée et installez-la avec les fichiers de développement dans $HOME/.local :
mkdir work && cd work
git clone https://github.com/redcode/Zeta.git
git clone https://github.com/redcode/Z80.git
cd Zeta
mkdir build && cd build
cmake
-DCMAKE_BUILD_TYPE=Release
-DCMAKE_INSTALL_PREFIX= " $HOME /.local "
-DZeta_WITH_CMAKE_SUPPORT=YES
-DZeta_WITH_PKGCONFIG_SUPPORT=YES
..
cmake --install . --config Release
cd ../../Z80
mkdir build && cd build
cmake
-DBUILD_SHARED_LIBS=YES
-DCMAKE_BUILD_TYPE=Release
-DCMAKE_INSTALL_NAME_DIR= " $HOME /.local/lib "
-DCMAKE_INSTALL_PREFIX= " $HOME /.local "
-DZ80_WITH_CMAKE_SUPPORT=YES
-DZ80_WITH_PKGCONFIG_SUPPORT=YES
-DZ80_WITH_EXECUTE=YES
-DZ80_WITH_FULL_IM0=YES
-DZ80_WITH_IM0_RETX_NOTIFICATIONS=YES
-DZ80_WITH_Q=YES
-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=YES
..
cmake --build . --config Release
cmake --install . --config Release --stripbuild-and-stall-z80.sh
Le package comprend un outil appelé test-Z80 capable d'exécuter les versions Spectrum CP / M et ZX les plus pertinentes des principaux suites de test. Configurez le système de construction avec -DZ80_WITH_TESTS=YES pour activer sa compilation et -DZ80_FETCH_TEST_FILES=YES pour télécharger le firmware et le logiciel requis. Notez également que la bibliothèque Z80 doit être construite avec -DZ80_WITH_Q=YES pour pouvoir passer les tests de Patrik Rak.
Une fois que vous avez construit le package, saisissez ce qui suit pour exécuter tous les tests:
./test-Z80 -p depot/firmware -p depot/software/POSIX -p " depot/software/ZX Spectrum " -a L'outil prend en charge les options et peut exécuter les tests individuellement (tapez ./test-Z80 -h pour l'aide). Si vous préférez exécuter tous les tests via CTEST, utilisez cette commande:
ctest --verbose --build-config (Debug | Release | RelWithDebInfo | MinSizeRel) Les journaux complets générés par test-Z80 émulant différentes variantes de CPU sont disponibles ici:
Note
Les erreurs CRC dans les journaux de la variante NEC NMOS sont normales et correspondent aux valeurs obtenues sur du matériel réel. La variante ST CMOS est actuellement à l'étude.
Utilisez ce qui suit pour construire et tester l'émulateur:
mkdir work && cd work
git clone https://github.com/redcode/Zeta.git
git clone https://github.com/redcode/Z80.git
cd Z80
mkdir build && cd build
cmake
-DCMAKE_BUILD_TYPE=Release
-DZ80_FETCH_TEST_FILES=YES
-DZ80_WITH_TESTS=YES
-DZ80_WITH_EXECUTE=YES
-DZ80_WITH_FULL_IM0=YES
-DZ80_WITH_IM0_RETX_NOTIFICATIONS=YES
-DZ80_WITH_Q=YES
-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=YES
..
cmake --build . --config Release
ctest --verbose --build-config Releasebuild-and-test-z80.sh build-and-test-z80.bat
La bibliothèque Z80 comprend un package Config-File pour l'intégration dans des projets basés sur CMake qui doivent être installés pour le développement. Utilisez find_package pour trouver le package Z80 . Cela crée la cible de bibliothèque importée Z80 , qui transporte les dépendances de liaison transitive nécessaires. Facultativement, la méthode de liaison peut être sélectionnée en spécifiant le composant Shared ou Static .
Exemple:
find_package (Z80 REQUIRED Shared)
target_link_libraries (your- target Z80) Lorsqu'il n'est pas spécifié comme composant, la méthode de liaison est sélectionnée selon Z80_SHARED_LIBS . Si cette option n'est pas définie, la configuration file utilise le type de bibliothèque qui est installé sur le système et, s'il trouve à la fois les versions partagées et statiques, BUILD_SHARED_LIBS détermine à quoi vous lier.
Pour intégrer la bibliothèque Z80 en tant que sous-projet CMake, extrayez le code source Tarballs de Zeta et Z80 (ou clonez leurs référentiels respectifs) dans un sous-répertoire d'un autre projet. Utilisez ensuite add_subdirectory dans le projet parent pour ajouter l'arborescence de code source Z80 au processus de construction (NB, le sous-project Z80 trouvera automatiquement Zeta et l'importera en bibliothèque d'interface).
Il est conseillé de configurer la bibliothèque Z80 dans le CMakeLists.txt du projet parent. Cela empêchera l'utilisateur d'avoir à spécifier des options de configuration pour le sous-projet Z80 via la ligne de commande lors de la construction du projet principal.
Exemple:
set (Z80_SHARED_LIBS NO CACHE BOOL "" )
set (Z80_WITH_Q YES CACHE BOOL "" )
set (Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG YES CACHE BOOL "" )
add_subdirectory (dependencies/Z80)
target_link_libraries (your- target Z80) Il est important de définir l'option Z80_SHARED_LIBS . Sinon, CMake construira le type de bibliothèque indiqué par BUILD_SHARED_LIBS , qui n'est peut-être pas celui souhaité.
Le code source de l'émulateur peut être configuré au moment de la compilation en prédéfinissant une série de macros. Z80.h et Z80.c obéissent aux deux premiers expliqués ci-dessous. Les autres macros ne sont pertinents que lors de la compilation Z80.c :
#define Z80_EXTERNAL_HEADER "header-name.h"
Spécifie le seul en-tête externe vers #include , remplaçant tous les autres.
Prédéfinir cette macro pour fournir un fichier d'en-tête qui définit les types et macros externes utilisés par l'émulateur, empêchant ainsi votre projet de dépendre de Zeta. Vous pouvez l'utiliser lors de la compilation Z80.c dans le cadre de votre projet ou (si vos types ne cassent pas la compatibilité binaire) lorsque vous incluez <Z80.h> et liant à une bibliothèque Z80 pré-construite.
#define Z80_STATIC
Restreint la visibilité des symboles publics.
Cette macro est requise si vous construisez Z80.c en tant que bibliothèque statique, la compilant directement dans le cadre de votre projet, ou reliant votre programme à la version statique de la bibliothèque Z80. Dans l'un ou l'autre des cas, assurez-vous que cette macro est définie avant d'inclure "Z80.h" ou <Z80.h> .
#define Z80_WITH_LOCAL_HEADER
Raconte Z80.c à #include "Z80.h" au lieu de <Z80.h> .
Les caractéristiques facultatives de l'émulateur mentionnées dans "l'installation à partir de sources" sont désactivées par défaut. Si vous compilez Z80.c dans le cadre de votre projet, activez les fonctionnalités dont vous avez besoin en prédéfinissant leurs macros d'activation respectives. Ils ont le même nom que leurs équivalents CMake:
#define Z80_WITH_EXECUTE#define Z80_WITH_FULL_IM0#define Z80_WITH_IM0_RETX_NOTIFICATIONS#define Z80_WITH_Q#define Z80_WITH_SPECIAL_RESET#define Z80_WITH_UNOFFICIAL_RETI#define Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG Sauf pour Z80_EXTERNAL_HEADER , les macros ci-dessus peuvent être vides; Le code source vérifie uniquement s'ils sont définis.
Note
L'activation de certaines des caractéristiques facultatives affecte la vitesse de l'émulateur en raison de divers facteurs (lisez la documentation pour plus de détails).
Cet émulateur a été utilisé par les projets suivants (répertorié par ordre alphabétique):
Un grand merci aux personnes suivantes (par ordre alphabétique):
ccf/scf .ccf/scf sur le matériel réel. 2, 3ccf/scf . 5, 6ccf/scf . 12out (c),0 se comportent sur le Zilog Z80 CMOS. 16ccf/scf sur le matériel réel. 12, 23ccf/scf .ccf/scf .ccf/scf . 15, 30ccf/scf .ccf/scf . 2, 3reti/retn reportent l'acceptation de l'interruption masquable. 34ccf/scf . 36Copyright © 1999-2024 Manuel Sainz de Baranda Y Goñi.
Cette bibliothèque est un logiciel gratuit: vous pouvez le redistribuer et / ou le modifier en vertu des termes de la licence GNU moins générale publique publiée par la Free Software Foundation, soit la version 3 de la licence, soit (à votre option) n'importe quelle version ultérieure.
Cette bibliothèque est distribuée dans l'espoir qu'elle sera utile, mais sans aucune garantie; Sans même la garantie implicite de qualité marchande ou d'adéquation à un usage particulier . Voir la licence publique générale GNU Leser pour plus de détails.
Vous auriez dû recevoir une copie de la licence publique GNU Leser le moins avec cette bibliothèque. Sinon, voir https://www.gnu.org/licenses/.
Les projets où les termes de la licence publique générale de GNU moindre empêchent l'utilisation de cette bibliothèque ou nécessitent une publication indésirable du code source des produits commerciaux, peuvent demander une licence spéciale.
