Z80
v0.2-pre-2024-09-21
La biblioteca Z80 implementa un emulador rápido, pequeño y preciso del Zilog Z80. Emula todo lo que se sabe que se sabe sobre esta CPU, incluidos los comportamientos indocumentados, MEMPTR, Q y el reinicio especial. También tiene el honor de haber sido el primer proyecto de código abierto en proporcionar una emulación completa del modo de interrupción 0.
El código fuente está escrito en Ansi C para la máxima portabilidad y se comenta ampliamente. El objetivo ha sido escribir una pieza de software bien estructurada y fácil de entender; Algo sólido y elegante que puede soportar la prueba del tiempo sin necesidad de cambios importantes.
Este emulador de CPU Z80 tiene un diseño clásico con granularidad a nivel de instrucción que ofrece el mejor rendimiento, al tiempo que ofrece una flexibilidad razonable para lograr la precisión hasta el nivel del estado t.
La granularidad a nivel de instrucción implica que, excepto en algunos casos bien definidos, la ejecución de una instrucción dada no puede detenerse hasta que todos sus ciclos M internos se hayan procesado (es decir, las instrucciones no se dividen en microoperaciones). Además, los registros se modifican solo una vez por instrucción y el contador de estado t normalmente se actualiza después de que se ha ejecutado una instrucción completa.
Dicho esto, las instrucciones, las banderas, los accesos de memoria, las interrupciones, los ciclos de reloj, etc., se emulan con precisión de acuerdo con la documentación técnica disponible, los resultados realizados después de décadas de investigación sobre el Z80 y las simulaciones electrónicas. Y, por supuesto, el emulador pasa las pruebas más exhaustivas escritas hasta la fecha, incluidas las tres principales suites de prueba:
Este conjunto de programas está destinado a ayudar a los autores emuladores a alcanzar el nivel deseado de la autenticidad de la emulación de la CPU. Cada uno de los programas incluidos realiza un cálculo exhaustivo utilizando cada una de las instrucciones Z80 probadas, compara los resultados con los valores obtenidos de un espectro Sinclair ZX 48K real con CPU Zilog Z80 e informa cualquier desviación detectada.
z80full.tap Prueba todas las banderas y registros. | z80doc.tap Prueba todos los registros, pero solo se documentan oficialmente banderas. |
z80flags.tap Prueba todas las banderas, ignora los registros. | z80docflags.tap Pruebas solo de banderas documentadas, ignora los registros. |
z80ccf.tap Prueba todas las banderas después de ejecutar ccf después de cada instrucción probada. | z80memptr.tap Prueba todas las banderas después de ejecutar bit N,(hl) después de cada instrucción probada. |
z80full.tap Prueba todas las banderas y registros. | z80doc.tap Prueba todos los registros, pero solo se documentan oficialmente banderas. |
z80flags.tap Prueba todas las banderas, ignora los registros. | z80docflags.tap Pruebas solo de banderas documentadas, ignora los registros. |
z80ccf.tap Prueba todas las banderas después de ejecutar ccf después de cada instrucción probada. | z80memptr.tap Prueba todas las banderas después de ejecutar bit N,(hl) después de cada instrucción probada. |
Esta suite realiza una serie de pruebas para verificar los documentos MEMPTR (inglés, ruso) , que son acertados, así como un breve ejecutado a través de varios de los rangos de opcodos CBh/DDh/FDh . Los resultados de la prueba en el programa se comparan con los de una CPU NEC D780C-1, pero Simon Conway probó amablemente varios otros clones Z80, confirmando los mismos resultados.
z80tests.tap | |
El ejercicio del conjunto de instrucciones Z80 de Frank Cringle intenta ejecutar cada código de operación Z80, colocándolos a través de un ciclo de pruebas y comparando los resultados con los resultados reales de ejecutar el código en un Z80 real. El ejercicio se suministra con Yaze de Frank (otro emulador Z80). A menudo es difícil rastrear, por lo que Jonathan Graham Harston lo reúne aquí, así como algunas conversiones. El último lanzamiento de Yaze está disponible en el sitio web de Andreas Gerlich.
zexdoc.tap Pruebas Efectos de la bandera documentados oficialmente. | zexall.tap Prueba todos los cambios de bandera. |
zexfix.tap Prueba todos los cambios de bandera. | zexbit.tap Prueba todos los cambios de bandera de las instrucciones bit . |
zexall2.tap |
Primero, agregue el repositorio zxe y actualice el índice de paquetes:
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 updateA continuación, instale el paquete de la biblioteca:
sudo apt install libz80En caso de que necesite crear un software que requiera la biblioteca Z80, instale el paquete de desarrollo también:
sudo apt install libz80-dev Primero, agregue y sincronice la superposición zxe :
eselect repository add zxe git https://github.com/redcode/zxe-gentoo-overlay.git
emaint sync --repo zxeLuego instale la biblioteca:
emerge emulation-libs/z80brew install redcode/zxe/z80Los binarios preconstruidos para Windows están disponibles en la página de descarga.
Necesitará Cmake v3.14 o posterior para construir el paquete y, opcionalmente, versiones recientes de doxygen, sphinx y respirar para compilar la documentación. Además, asegúrese de tener látex con soporte PDF instalado en su sistema si desea generar la documentación en formato PDF.
El emulador requiere algunos tipos y macros incluidos en ZETA, una biblioteca de solo encabezado sin dependencia utilizada para retener la compatibilidad con la mayoría de los compiladores C. Instale Zeta o extraiga su código fuente Tarball al directorio raíz del proyecto Z80 o su directorio principal. Zeta es la única dependencia; El emulador es una implementación independiente y, como tal, no depende de la biblioteca estándar C.
Una vez que se cumplan los requisitos previos, cree un directorio y ejecute cmake desde allí para preparar el sistema de compilación:
mkdir build
cd build
cmake [options] < Z80-project-directory > Los archivos de compilación resultantes se pueden configurar pasando opciones a cmake . Para mostrar una lista completa de los disponibles junto con su configuración actual, escriba lo siguiente:
cmake -LAH -N -B .En caso de duda, lea la documentación de CMake para obtener más información sobre las opciones de configuración. Las siguientes son algunas de las opciones estándar más relevantes de CMake:
Genere bibliotecas compartidas en lugar de bibliotecas estáticas.
El valor predeterminado es NO .
-DCMAKE_BUILD_TYPE=(Debug|Release|RelWithDebInfo|MinSizeRel)
Elija el tipo de compilación (configuración) para generar.
El valor predeterminado es Release .
-DCMAKE_INSTALL_NAME_DIR="<path>"
Especifique la parte del directorio del nombre de instalación de la biblioteca dinámica en las plataformas Apple (para bibliotecas compartidas instaladas).
No definido por defecto.
-DCMAKE_INSTALL_PREFIX="<path>"
Especifique el prefijo de instalación.
El valor predeterminado es "/usr/local" (en sistemas operativos de unix y unix).
Las opciones específicas del paquete tienen el prefijo Z80_ y se pueden dividir en dos grupos. El primero controla aspectos no relacionados con el código fuente de la biblioteca:
-DZ80_DEPOT_LOCATION="<location>"
Especifique el directorio o URL del depósito que contiene los archivos de prueba (es decir, el firmware y el software requeridos por la herramienta de prueba).
El valor predeterminado es "http://zxe.io/depot" .
-DZ80_FETCH_TEST_FILES=(YES|NO)
Copie o descargue los archivos de prueba del depósito al directorio de compilación.
El valor predeterminado es NO .
-DZ80_INSTALL_CMAKEDIR="<path>"
Especifique el directorio en el que instalar el paquete CMake Config-File.
El valor predeterminado es "${CMAKE_INSTALL_LIBDIR}/cmake/Z80" .
-DZ80_INSTALL_PKGCONFIGDIR="<path>"
Especifique el directorio para instalar el archivo PKG-Config.
El valor predeterminado es "${CMAKE_INSTALL_LIBDIR}/pkgconfig" .
-DZ80_NOSTDLIB_FLAGS=(Auto|"[<flag>[;<flag>...]]")
Especifique los indicadores de enlazador utilizados para evitar vincular con bibliotecas del sistema.
El valor predeterminado es Auto (indicadores de Autoconfigure). Si obtiene errores de enlace, configure esta opción en "" .
-DZ80_OBJECT_LIBS=(YES|NO)
Construya el emulador como una biblioteca de objetos.
Esta opción tiene prioridad sobre BUILD_SHARED_LIBS y Z80_SHARED_LIBS . Si está habilitado, el sistema de compilación ignorará Z80_WITH_CMAKE_SUPPORT y Z80_WITH_PKGCONFIG_SUPPORT , ya que no se instalarán bibliotecas o archivos de soporte.
El valor predeterminado es NO .
Construya el emulador como una biblioteca compartida, en lugar de estática.
Esta opción tiene prioridad sobre BUILD_SHARED_LIBS .
No definido por defecto.
-DZ80_SPHINX_HTML_THEME="[<name>]"
Especifique el tema Sphinx para la documentación en formato HTML.
El valor predeterminado es "" (use el tema predeterminado).
-DZ80_WITH_CMAKE_SUPPORT=(YES|NO)
Genere e instale el paquete de archivo de configuración Cmake.
El valor predeterminado es NO .
-DZ80_WITH_HTML_DOCUMENTATION=(YES|NO)
Construya e instale la documentación en formato HTML.
Requiere doxígeno, esfinge y respirando.
El valor predeterminado es NO .
-DZ80_WITH_PDF_DOCUMENTATION=(YES|NO)
Construya e instale la documentación en formato PDF.
Requiere doxygen, esfinge, respiración y látex con soporte PDF.
El valor predeterminado es NO .
-DZ80_WITH_PKGCONFIG_SUPPORT=(YES|NO)
Genere e instale el archivo PKG-Config.
El valor predeterminado es NO .
-DZ80_WITH_STANDARD_DOCUMENTS=(YES|NO)
Instale los documentos de texto estándar distribuidos con el paquete: AUTHORS , COPYING , COPYING.LESSER Merente, HISTORY , README y THANKS .
El valor predeterminado es NO .
-DZ80_WITH_TESTS=(YES|NO)
Construya la herramienta de prueba.
El valor predeterminado es NO .
El segundo grupo de opciones específicas del paquete configura el código fuente de la biblioteca predefiniendo macros que habilitan características opcionales:
-DZ80_WITH_EXECUTE=(YES|NO)
Cree la implementación de la función z80_execute .
El valor predeterminado es NO .
-DZ80_WITH_FULL_IM0=(YES|NO)
Cree la implementación completa del modo de interrupción 0 en lugar del reducido.
El valor predeterminado es NO .
-DZ80_WITH_IM0_RETX_NOTIFICATIONS=(YES|NO)
Habilite notificaciones opcionales para cualquier instrucción reti o retn ejecutada durante la respuesta del modo de interrupción 0.
El valor predeterminado es NO .
-DZ80_WITH_Q=(YES|NO)
Cree la implementación de Q.
El valor predeterminado es NO .
-DZ80_WITH_SPECIAL_RESET=(YES|NO)
Cree la implementación del reinicio especial.
El valor predeterminado es NO .
-DZ80_WITH_UNOFFICIAL_RETI=(YES|NO)
Configure las instrucciones indocumentadas ED5Dh , ED6Dh y ED7Dh como reti en lugar de retn .
El valor predeterminado es NO .
-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=(YES|NO)
Cree la implementación del error que afecta el ZILOG Z80 NMOS, que hace que la bandera P/V se reinicie cuando se acepta una interrupción enmascarable durante la ejecución de las instrucciones ld a,{i|r} .
El valor predeterminado es NO .
Se alienta a los mantenedores de paquetes a usar al menos las siguientes opciones para la biblioteca compartida:
-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
Finalmente, una vez que el sistema de compilación se configura de acuerdo con sus necesidades, cree e instale el paquete:
cmake --build . [--config (Debug | Release | RelWithDebInfo | MinSizeRel)]
cmake --install . [--config < configuration > ] [--strip] La opción --config solo es necesaria para aquellos generadores de CMake que ignoran CMAKE_BUILD_TYPE (por ejemplo, Xcode y Visual Studio). Use --strip para eliminar la información de depuración y los símbolos no públicos al instalar construcciones no debilitas de la biblioteca compartida.
Use lo siguiente para construir el emulador como una biblioteca compartida e instálela junto con los archivos de desarrollo en $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 --stripconstruir y instalar a z80.sh
El paquete incluye una herramienta llamada test-Z80 capaz de ejecutar las versiones de espectro CP/M y ZX más relevantes de las principales suites de prueba. Configure el sistema de compilación con -DZ80_WITH_TESTS=YES para habilitar su compilación y -DZ80_FETCH_TEST_FILES=YES para descargar el firmware y el software requeridos. También tenga en cuenta que la biblioteca Z80 debe construirse con -DZ80_WITH_Q=YES para poder pasar las pruebas de Patrik Rak.
Una vez que haya creado el paquete, escriba lo siguiente para ejecutar todas las pruebas:
./test-Z80 -p depot/firmware -p depot/software/POSIX -p " depot/software/ZX Spectrum " -a La herramienta admite opciones y puede ejecutar las pruebas individualmente (escriba ./test-Z80 -h para obtener ayuda). Si prefiere ejecutar todas las pruebas a través de CTEST, use este comando:
ctest --verbose --build-config (Debug | Release | RelWithDebInfo | MinSizeRel) Aquí están disponibles los registros completos generados por test-Z80 emulando diferentes variantes de CPU:
Nota
Los errores de CRC en los registros de la variante NEC NMOS son normales y coinciden con los valores obtenidos en hardware real. La variante ST CMOS está actualmente bajo investigación.
Use lo siguiente para construir y probar el emulador:
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 biblioteca Z80 incluye un paquete de archivo de configuración para la integración en proyectos basados en Cmake que deben instalarse para el desarrollo. Use find_package para encontrar el paquete Z80 . Esto crea el objetivo de la biblioteca importada Z80 , que conlleva las dependencias de enlaces transitivos necesarias. Opcionalmente, el método de enlace se puede seleccionar especificando el componente Shared o Static .
Ejemplo:
find_package (Z80 REQUIRED Shared)
target_link_libraries (your- target Z80) Cuando no se especifica como un componente, el método de enlace se selecciona de acuerdo con Z80_SHARED_LIBS . Si esta opción no está definida, el archivo de configuración utiliza el tipo de biblioteca que se instala en el sistema y, si encuentra las versiones compartidas y estáticas, BUILD_SHARED_LIBS determina con quién vincularse.
Para incrustar la biblioteca Z80 como subproyecto CMake, extraiga los tarballas del código fuente de Zeta y Z80 (o clone sus respectivos repositorios) en un subdirectorio de otro proyecto. Luego use add_subdirectory en el proyecto principal para agregar el árbol de código fuente Z80 al proceso de compilación (NB, el subproyecto Z80 encontrará automáticamente Zeta e importarálo como una biblioteca de interfaz).
Es aconsejable configurar la biblioteca Z80 en CMakeLists.txt del proyecto principal. Esto evitará que el usuario tenga que especificar las opciones de configuración para el subproyecto Z80 a través de la línea de comando al construir el proyecto principal.
Ejemplo:
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) Es importante establecer la opción Z80_SHARED_LIBS . De lo contrario, Cmake construirá el tipo de biblioteca indicado por BUILD_SHARED_LIBS , que puede no ser el deseado.
El código fuente del emulador se puede configurar en el tiempo de compilación predefiniendo una serie de macros. Tanto Z80.h como Z80.c obedecen a los dos primeros explicados a continuación. El resto de las macros solo son relevantes al compilar Z80.c :
#define Z80_EXTERNAL_HEADER "header-name.h"
Especifica el único encabezado externo a #include , reemplazando a todos los demás.
Predefine esta macro para proporcionar un archivo de encabezado que define los tipos externos y las macros utilizadas por el emulador, evitando así que su proyecto dependa de ZETA. Puede usar esto al compilar Z80.c como parte de su proyecto o (si sus tipos no rompen la compatibilidad binaria) cuando incluye <Z80.h> y se vincula con una biblioteca Z80 prebuilada.
#define Z80_STATIC
Restringe la visibilidad de los símbolos públicos.
Esta macro es necesaria si está construyendo Z80.c como una biblioteca estática, compilándola directamente como parte de su proyecto o vinculando su programa con la versión estática de la biblioteca Z80. En cualquiera de estos casos, asegúrese de que esta macro se define antes de incluir "Z80.h" o <Z80.h> .
#define Z80_WITH_LOCAL_HEADER
Le dice Z80.c a #include "Z80.h" en lugar de <Z80.h> .
Las características opcionales del emulador mencionado en "Instalación de fuentes" están deshabilitadas de forma predeterminada. Si compila Z80.c como parte de su proyecto, habilite las características que necesita predefiniendo sus respectivas macros de activación. Tienen el mismo nombre que sus equivalentes de 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 Excepto para Z80_EXTERNAL_HEADER , las macros anteriores pueden estar vacías; El código fuente solo verifica si están definidos.
Nota
La activación de algunas de las características opcionales afecta la velocidad del emulador debido a varios factores (lea la documentación para obtener más detalles).
Este emulador ha sido utilizado por los siguientes proyectos (enumerados en orden alfabético):
Muchas gracias a los siguientes individuos (en orden alfabético):
ccf/scf .ccf/scf en hardware real. 2, 3ccf/scf . 5, 6ccf/scf . 12out (c),0 se comporta en el cMOS ZILOG Z80. 16ccf/scf en hardware real. 12, 23ccf/scf .ccf/scf .ccf/scf . 15, 30ccf/scf .ccf/scf . 2, 3reti/retn diferen la aceptación de la interrupción enmascarable. 34ccf/scf . 36Copyright © 1999-2024 Manuel Sainz de Baranda y Goñi.
Esta biblioteca es un software gratuito: puede redistribuirla y/o modificarla bajo los términos de la Licencia Pública General Lesser GNU Publicado por la Free Software Foundation, ya sea la versión 3 de la licencia o (a su opción) cualquier versión posterior.
Esta biblioteca se distribuye con la esperanza de que sea útil, pero sin ninguna garantía; Sin siquiera la garantía implícita de comerciabilidad o estado físico para un propósito particular . Vea la licencia pública general de GNU Lesser para obtener más detalles.
Debería haber recibido una copia de la Licencia Pública General Lesser de GNU junto con esta biblioteca. Si no, consulte https://www.gnu.org/licenses/.
Los proyectos donde los términos de la Licencia Pública General Lesser General de GNU evitan el uso de esta biblioteca, o requieren una publicación no deseada del código fuente de productos comerciales, pueden solicitar una licencia especial.
