 //  ####  ######    ####  #######   ####  ------------------------- //
//  ##  ##  ##  ##  ##  ##  ##   #  ##  ##  CPCEC, plain text Amstrad //
// ##       ##  ## ##       ## #   ##       CPC emulator written in C //
// ##       #####  ##       ####   ##       as a postgraduate project //
// ##       ##     ##       ## #   ##       by Cesar Nicolas-Gonzalez //
//  ##  ##  ##      ##  ##  ##   #  ##  ##  since 2018-12-01 till now //
 //  ####  ####      ####  #######   ####  ------------------------- //
//- home page, news and updates - http://cngsoft.no-ip.org/cpcec.htm -//

Introduccin
---

CPCEC es un emulador de la familia de microordenadores domsticos
Amstrad CPC (modelos 464, 664 y 6128) cuyo objetivo es ser fiel al
hardware original y eficiente en sistemas modernos corrientes. Para ello
ofrece una emulacin fidedigna del microprocesador Z80 y reproduce el
comportamiento de los chips de imagen CRTC 6845 y Gate Array, del chip
de sonido PSG AY-3-8912, de los dems circuitos presentes en el hardware
original, y de las unidades de cinta y disco que hacan posible la carga
y ejecucin del software existente.

El cdigo fuente y los binarios de CPCEC siguen la licencia GNU General
Public License v3, descrita en el fichero GPL.TXT adjunto al paquete.

Requisitos e instalacin
---

CPCEC requiere un sistema operativo Microsoft Windows 2000 o posterior.
El hardware mnimo es el propio de dichos sistemas operativos, y se
recomienda que el microprocesador central funcione a 400 MHz por lo
menos. La resolucin de pantalla en pxeles debe ser 800x600 como
mnimo. Una tarjeta de sonido es opcional, as como emplear un joystick.

El emulador se compone de varios ficheros: el ejecutable propiamente
dicho CPCEC.EXE y los ficheros de firmware CPC464.ROM, CPC664.ROM,
CPC6128.ROM y CPCADOS.ROM. Todos ellos deben ser copiados en un mismo
directorio, idealmente creado para alojar el emulador.

El binario puede ser compilado a partir de los ficheros fuente siguiendo
las instrucciones incluidas en su interior. GCC 4.9.2 y TCC 0.9.27
funcionan correctamente; GCC 4.7.1 comete fallos graves en la
compilacin y genera binarios invlidos.

Configuracin y ficheros
---

El funcionamiento de CPCEC se configura especificando parmetros
opcionales en la lnea de comandos. Para que los parmetros preferidos
por el usuario sean estables se recomienda crear en el men del sistema
un enlace al emulador que contenga dichos parmetros. Las opciones
pueden ser abreviadas al estilo Unix: por ejemplo '-C -d -J' se abrevia
'-CdJ'. En caso de duda, el parmetro '-h' muestra una breve explicacin
de las opciones disponibles.

	* -C : emular un monitor verde en lugar de (por defecto) uno a
	todo color;
	* -c0 : elegir el tipo de scanlines medio;
	* -c1 : elegir el tipo de scanlines normal (por defecto);
	* -c2 : elegir el tipo de scanlines entrelazado simple;
	* -c3 : elegir el tipo de scanlines entrelazado doble;
	* -d : iniciar la emulacin con el debugger activo (por defecto
	inactivo);
	* -g0 : emular el tipo de CRTC 0 (por defecto);
	* -g1, -g2, -g3, -g4 : dem para los otros cuatro tipos de CRTC;
	* -h : ayuda breve;
	* -j : activar la emulacin del joystick por teclado (cursores y
	teclas Z, X y C);
	* -J : deshabilitar el uso de un joystick conectado al sistema;
	* -K : emular solamente 64k de RAM en vez de (por defecto) 128k;
	* -m0 : iniciar la emulacin con el modelo CPC464;
	* -m1 : iniciar la emulacin con el modelo CPC664;
	* -m2 : iniciar la emulacin con el modelo CPC6128, por defecto;
	* -O : ocultar indicadores en pantalla (por defecto visibles);
	* -R : deshabilitar emulacin en tiempo real (por defecto
	habilitada);
	* -S : deshabilitar sonido (por defecto habilitado si hay una
	tarjeta de sonido);
	* -X : deshabilitar emulacin de unidades de disco (por defecto
	habilitada);
	* -Y : deshabilitar el anlisis de cinta (por defecto
	habilitado; ver ms adelante);
	* -Z : deshabilitar la aceleracin de cinta (por defecto
	habilitada).

Tambin es posible aadir nombres de fichero a la lnea de comandos: el
emulador intentar cargar y ejecutar los ficheros especificados. Gracias
a ello CPCEC puede ser vinculado a las extensiones de fichero CDT, CSW,
DSK y SNA para cargar dichos ficheros automticamente.

Los tipos de fichero admitidos por el emulador se dividen en tres tipos:

	* WAV, CSW y CDT: ficheros de cinta, es decir volcados digitales
	de los contenidos de una cinta magntica utilizada para
	almacenar y distribuir datos y software.
	* DSK: ficheros de disco, representaciones virtuales de la
	estructura y los contenidos de un disco flexible magntico capaz
	de contener datos y software.
	* SNA: instantneas o "snapshots", copias integrales del estado
	de un sistema emulado que hacen posible reanudar ms tarde dicho
	estado de emulacin.

La lectura de cintas emplea dos mtodos (habilitados por defecto) para
mejorar la experiencia de usuario abreviando un proceso que entonces
era muy lento: un programa tpico en cinta tardaba cinco minutos en
cargar. El primer mtodo (aceleracin de cinta) simplemente detecta si
hay una cinta insertada y el motor del cassette est en funcionamiento:
entonces el emulador se pone a funcionar a la mxima velocidad posible.
El segundo mtodo (anlisis de cinta) examina el estado actual del Z80 y
detecta si ste intenta leer la cinta de una forma conocida: entonces
manipula su estado para generar al instante los resultados de la lectura
en lugar de esperar a que la cinta genere la siguiente seal.

La ejecucin automtica de ficheros de disco intenta detectar por s
misma el mtodo de arranque necesario. Dado que algunos discos tenan
ms de un arranque posible y el emulador corre el riesgo de elegir uno
distinto al esperado, el usuario puede establecerlo a mano tecleando la
orden RUN"NOMBRE (donde NOMBRE es el fichero de arranque, que suele
venir especificado en las instrucciones del software, o ser simplemente
DISC o DISK) en el sistema emulado y pulsando RETURN. En caso de duda,
la orden CAT muestra la lista de ficheros contenidos en el disco.

Teclas de funcin
---

Una vez en funcionamiento, CPCEC muestra la pantalla del sistema emulado
y obedece a las rdenes del usuario, que adems de las pertinentes a
dicho sistema (pulsaciones de teclas alfanumricas y de control,
movimientos del joystick real o emulado mediante teclado) incluye una
serie de teclas de funcin especiales. En caso de duda, la tecla F1
muestra un breve ndice de dichas teclas de funcin.

	* F1: ayuda breve;
	* F1+Control: autora del emulador;
	* F2: grabar el estado actual de la emulacin en una
	instantnea;
	* F2+Control: volver a grabar la ltima instantnea
	seleccionada;
	* F3: cargar y ejecutar un fichero de cinta, de disco o una
	instantnea;
	* F3+Control: volver a cargar la ltima instantnea
	seleccionada;
	* F4: habilitar (o deshabilitar) la emulacin de sonido;
	* F4+Control: habilitar (o deshabilitar) el joystick por
	teclado;
	* F5: elegir el firmware del modelo de CPC emulado;
	* F5+Control: reiniciar la emulacin;
	* F6: habilitar (o deshabilitar) la emulacin en tiempo real;
	* F6+Control: elevar la velocidad del Z80 emulado de 4 MHz a 8,
	12 y 16 MHz;
	* F6+Control+Mays: reducir su velocidad a 12, 8 y 4 MHz;
	* F7: insertar un fichero de disco en la disquetera virtual A;
	* F7+Mays: insertar un fichero de disco en la disquetera virtual
	B;
	* F7+Control: extraer el disco de la disquetera virtual A;
	* F7+Control+Mays: extraer el disco de la disquetera virtual B;
	* F8: insertar un fichero de cinta en el cassette virtual;
	* F8+Mays: empezar a grabar un fichero de cinta nuevo;
	* F8+Control: extraer la cinta del cassette virtual;
	* F9: habilitar el debugger (ver ms adelante);
	* F9+Mays: mostrar (u ocultar) los indicadores en pantalla;
	* F9+Control: habilitar (o deshabilitar) la aceleracin de
	cinta;
	* F9+Control+Mays: habilitar (o deshabilitar) el anlisis de
	cinta;
	* F11: cambiar el modo de color entre verde y tres gamas de
	color de claridad creciente;
	* F11+Mays: dem en sentido contrario, recorriendo las gamas por
	orden decreciente;
	* F11+Control: cambiar el tipo de scanlines, de medio a
	entrelazado doble;
	* F11+Control+Mays: dem en sentido contrario, de entrelazado
	doble a medio;
	* F12: grabar el contenido de la pantalla en un fichero BMP;
	* F12+Control: comenzar a grabar (o terminar) el sonido en un
	fichero WAV;
	* F12+Control+Mays: comenzar a grabar (o terminar) el sonido en
	un fichero YM;
	* Pausa: detener (o reanudar) la emulacin;
	* Alt+Return: maximizar (o restaurar) la ventana.

Los ficheros BMP y WAV son los ficheros de imagen y sonido estndares
homnimos. Los ficheros YM son volcados del estado del chip de sonido,
que por haber sido usado en ms plataformas adems de Amstrad CPC
(Spectrum 128, MSX, Atari ST...) pueden ser emulados y reproducidos
independientemente en programas terceros tales como STSOUND y AY-EMUL.
Ntese que el modo de scanlines (opcin que simula varios tipos de
monitor) se refleja en las grabaciones igual que en la pantalla, y que
cada modo tiene un impacto distinto en el rendimiento del programa: el
modo normal consume ms esfuerzo, y el entrelazado doble, menos.

Los indicadores en pantalla muestran el estado de las unidades de disco
(nmero de pista, actividad), la cinta (actividad) y el joystick.

Las siguientes teclas ajustan el "frameskip" o salto de "frames": a
mayor valor de este parmetro, menor consumo de potencia de proceso,
pero tambin menor suavidad visual. Idealmente debe mantenerse su valor
a 0 a menos que 1.- el sistema no tenga potencia de proceso suficiente,
o 2.- el usuario necesite acelerar la emulacin durante un tiempo.

	* Num.+ : incrementa el valor de "frameskip", hasta 50;
	* Num.- : decrementa el valor de "frameskip", hasta 0;
	* Num.* : establece el valor de "frameskip" al mximo, 50;
	* Num./ : establece el valor de "frameskip" al mnimo, 0.

CPCEC permite arrastrar y soltar ficheros. stos sern automticamente
ejecutados (como con F3) a menos que la tecla Mays est pulsada, en
cuyo caso sern simplemente insertados como con F7 y F8.

Debugger
---

El debugger sirve para detener la emulacin y examinar su estado
interno. Para ello emplea un interfaz textual que muestra el estado
tcnico actual del sistema (valores de los registros del Z80 y de los
dispositivos Gate Array, CRTC y PSG) y espera que el usuario teclee una
orden. En caso de duda 'h' muestra un breve resumen de los comandos.

	* la cadena vaca (pulsar RETURN sin escribir nada) ejecuta la
	instruccin actual y pasa a la siguiente. En un debugger tpico
	esta operacin se llamara "step into".
	* 'af VALOR' asigna el valor numrico VALOR al registro AF del
	Z80. 'bc VALOR', 'de VALOR', 'hl VALOR', 'ir VALOR', 'ix VALOR',
	'iy VALOR', 'sp VALOR' hacen lo mismo con los registros del Z80
	BC, DE, HL, IR, IX, IY y SP.
	* 'j VALOR' (jump) establece el valor numrico del registro PC
	del Z80: equivale a que el Z80 "salte" a la direccin de VALOR.
	* 'd VALOR' (disassembly) muestra un desensamblado parcial de la
	memoria ubicada en la direccin especificada por VALOR. Si
	solamente se escribe 'd' el nuevo desensamblado contina donde
	termin el anterior.
	* 'm VALOR' (memory) muestra un volcado hexadecimal de la
	memoria a partir de la direccin especificada por VALOR. Si
	solamente se escribe 'm' contina donde termin el anterior.
	* 'p VALOR VALOR1 VALOR2 ...' (poke) escribe los valores VALOR1,
	VALOR2, etc. en las direcciones de memoria consecutivas a partir
	de VALOR.
	* 'r VALOR' (run to) desactiva el debugger y reanuda la
	emulacin hasta que el Z80 emulado deba ejecutar la instruccin
	ubicada en la direccin especificada por VALOR. Entonces la
	emulacin se interrumpir y el debugger se reactivar
	automticamente. Si solamente se escribe 'r' (step over) la
	interrupcin ocurrir en la instruccin posterior a la actual;
	ntese que esto no equivale a solamente ejecutar la instruccin
	actual si sta efecta un salto, pues la instruccin que se
	ejecuta tras la actual ya no es la posterior sino la que se
	encuentre en la direccin del salto.
	* 's VALOR VALOR1 VALOR2 ...' (search) busca la cadena de
	valores VALOR1, VALOR2, etc. en las direcciones de memoria a
	partir de VALOR. Enumera las direcciones que contengan dicha
	cadena; si son demasiadas, muestra '...' y se detiene.
	* 'h' (help) muestra una ayuda breve;
	* 'q' (quit) abandona el debugger y reanuda la emulacin.

El uso de maysculas y minsculas no es importante: el debugger no hace
distinciones. Los valores mostrados en pantalla y los parmetros de las
rdenes emplean notacin hexadecimal: por ejemplo, para escribir en la
direccin de memoria 32768 y consecutivas los valores 83, 79 y 83 hay
que escribir 'p 8000 53 4F 53' donde 32768 = $8000, 83 = $53 y 79 = $4F.
Finalmente, es perfectamente posible introducir secuencias de rdenes
escritas de antemano en un "script" mediante la redireccin de la
entrada estndar, i.e. "cpcec -d instantanea.sna < script.txt".

ZXSEC
---

ZXSEC es un emulador de la familia Sinclair Spectrum (48k, 128k,
+2/Plus2 y +3/Plus3) basado en los componentes compartidos con el
Amstrad CPC: el microprocesador Z80, el chip de sonido PSG AY-3-8912, el
sistema de cinta y la controladora de disco NEC765.

Se compone de los ficheros ZXSEC.EXE, SPECTRUM.ROM, SPEC128K.ROM,
SPEC-P-2.ROM y SPEC-P-3.ROM, y por lo dems funciona igual que CPCEC,
con varias salvedades:

	* la opcin -mX elige uno de cuatro modelos posibles: -m0 (48k),
	-m1 (128k), -m2 (+2)  -m3 (+3);
	* la opcin -K deshabilita el chip de sonido PSG AY-3-8912
	(habilitado por defecto) si el modelo elegido es Spectrum 48k;
	* la opcin -X deshabilita la unidad de disco si el modelo
	elegido es Spectrum +3, que as se convierte en un +2A;
	* Control+Mays+F8 sirve para poner en marcha (o detener) el
	motor de cinta, dado que el hardware de CPC dispone de control
	de cinta incorporado, mientras que el de Spectrum carece de l.
	* las opciones de joystick se refieren al interfaz Kempston por
	defecto; el men permite elegir el tipo de joystick.

La emulacin es menos precisa que la de CPCEC. "Starion" y "Vectron"
muestran correctamente sus efectos raster en modo 48k, pero la emulacin
de la ULA Issue 2 (la opcin -I) es extremadamente bsica, y todava no
hay contencin de memoria.

Agradecimientos
---

Este emulador debe su existencia a una serie de personas y sociedades
que enumero a continuacin:

	* Los ficheros de firmware incluidos en el paquete son propiedad
	de Amstrad, que autoriza la emulacin de sus antiguos sistemas
	informticos y permite la distribucin de sus firmwares siempre
	que se respete su autora y su contenido, y a quien agradezco de
	todo corazn la creacin de aquellos magnficos ordenadores y la
	buena voluntad hacia la emulacin de los mismos.
	* Este emulador fue mi proyecto de fin de mster en Ingeniera
	Informtica para la Universidad Nacional de Enseanza a
	Distancia (UNED), que estuvo dirigido por el profesor Jos
	Manuel Daz Martnez y result galardonado con un diez con
	derecho a matrcula de honor.
	* La documentacin sobre el sistema procede de cpcwiki.eu,
	cpc-power.com, cpcrulez.fr y quasar.cpcscene.net.
	* Las pruebas alfa corrieron a cargo del fiel y leal Denis
	Lechevalier.

Historial de versiones
---

	* 20190408 -- sptima versin pblica. Corrige un bug en la
	grabacin de ficheros YM3, otro en los tiempos internos de ZXSEC
	y otro en los comandos del debugger con parmetros opcionales.
	* 20190404 -- sexta versin pblica. Corrige un bug del Z80 en
	la lgica del IRQ. La configuracin (modelo emulado y ubicacin
	de ficheros) se conserva entre sesiones en un fichero INI.
	* 20190331 -- quinta versin pblica. Se puede recorrer cintas
	por posicin (WAV y CSW) o por bloques (CDT, TZX y TAP).
	* 20190325 -- cuarta versin pblica. Indicadores en pantalla
	(se ocultan con -O); corrige un bug en ZXSEC que ralentizaba la
	emulacin si el "frameskip" no era nulo, y otro en la grabacin
	de sonido en ficheros WAV.
	* 20190318 -- tercera versin pblica. Por defecto la ventana
	muestra un men; la nueva opcin -+ lo oculta.
	* 20190317 -- segunda versin pblica. Corrige bugs de joystick
	en Win32: JoyGetPos devuelve CERO en EXITO, no en ERROR.
	* 20190314 -- primera versin pblica.

Apndice: casos de pruebas
---

A continuacin se enumeran los cien ttulos que sirvieron para hacer el
grueso de las pruebas del emulador durante su desarrollo. Algunos
abarcan varias pruebas (por ejemplo "Donkey Kong" es a la vez una cinta
protegida y un caso medio de varios modos de imagen simultneos); se les
menciona solamente en la primera de ellas.

Diagnsticos:

	* Z80 Instruction Exerciser ZEXALL (2004 dominio pblico)
	* PLUSTEST (2002 Richard Wilson)

Casos simples:

	* Sultan's Maze / Laberinto del Sultn (1984 Gem Software / Amsoft)
	* Oh Mummy (1984 Gem Software / Amsoft)
	* Roland on the Ropes / Fred (1984 Indescomp / Amsoft)
	* Roland in the Caves / La Pulga (1984 Indescomp / Amsoft)

Ficheros de cinta:

	* Sin proteccin:
		* Roland in Time (1984 Gem Software / Amsoft)
		* Manic Miner (1985 Software Projects / Amsoft)
		* Jet Set Willy (1985 Software Projects / Amsoft)
		* Knight Lore (1985 Ultimate)
		* Alien 8 (1986 Ultimate)
	* Protecciones simples:
		* Technician Ted (1985 Hewson)
		* Abu Simbel Profanation (1986 Dinamic)
		* Deflektor (1987 Costa Panayi / Gremlin Graphics)
		* Desperado (1987 Topo Soft)
		* Humphrey (1988 Made in Spain / Zigurat)
	* Protecciones medias:
		* Donkey Kong (1986 Arcana / Ocean)
		* Samurai Trilogy (1987 Gremlin Graphics)
		* Operation Wolf (1988 Imagine)
		* Rainbow Islands (1989 Graftgold / Ocean)
	* Protecciones complejas:
		* Rasputin (1985 Paul Hibbard / Firebird)
		* Spiky Harold (1985 A.Rogers / Firebird)
		* Druid (1986 Firebird)
		* Split Personalities (1986 Domark)
		* Last Mission (1986 Opera Soft)
		* Marmalade (1987 MBC Informatique)
		* Gonzzlezz (1989 Opera Soft)
		* Twinworld (1990 Ubi Soft)

Casos extraos:

	* Z80:
		* Sabre Wulf (1985 Ultimate)
		* Bigfoot (1989 Codemasters)
	* PIO:
		* Nodes of Yesod (1986 Odin)
		* Prehistorik (1991 Titus)
		* Antiriad / Sacred Armour of Antiriad (1987 Palace Software)
	* Puertos:
		* Skweek (1989 Loriciels)
		* Night Shift (1990 Lucasarts)
		* Hero Quest (1991 Gremlin Graphics)

Casos medios:

	* Varios modos de imagen o paletas de color a la vez:
		* Sorcery (1985 Gang of Five / Virgin Games)
		* Kong Strikes Back (1985 Ocean)
		* Crafton & Xunk (1986 Ere Software)
		* Elite (1986 Bell and Braben / Firebird)
		* Amaurote (1987 Binary Design / Mastertronic)
		* Feud (1987 Binary Design / Mastertronic)
		* Gauntlet (1987 Gremlin Graphics)
		* Renegade (1987 Arcana / Imagine)
	* Scroll rpido y suave por hardware:
		* TLL / Tornado Low Level (1985 Vortex Software)
		* Thing on a Spring (1986 Gremlin Graphics)
		* Ghosts'n Goblins (1986 Elite)
		* Prohibition (1987 Infogrames)
	* Pantalla de tamao mayor ("overscan"):
		* Arkanoid (1987 Probe / Imagine)
		* Arkanoid 2: Revenge of Doh (1988 Imagine)
	* Doble bfer por hardware:
		* Sol Negro (1988 Opera Soft)
		* Mutan Zone (1988 Opera Soft)
		* Rescate Atlntida (1989 Creep Soft / Dinamic)
		* AMC / Astro Marine Corps (1989 Creep Soft / Dinamic)
	* Sonido digitalizado:
		* Enigma de Aceps (1986 ACE Software)
		* Dragon Ninja (1988 Imagine)
		* Robocop (1988 Ocean)

Ficheros de disco:

	* CP/M 2.2 (1984 Digital Research / Amstrad)
	* CP/M Plus (1985 Digital Research / Amstrad)
	* Abada del Crimen (1987 Opera Soft)
	* Corsarios (1990 Opera Soft)
	* Ghostbusters 2 (1989 Software Studios / Activision)
	* SWIV (1991 Storm / Sales Curve)
	* Addams Family / La familia Addams (1991 Ocean)
	* 5KB Demo 3 (1999 varios autores)

Casos avanzados:

	* Mission Genocide (1987 Paul Shirley / Firebird)
	* Warhawk (1987 Proteus / Firebird)
	* Dynamic Duo (1988 Probe / Firebird)
	* Rastan (1988 Probe / Imagine)
	* Skateball (1988 Ubi Soft)
	* Turrican (1990 Probe / Rainbow Arts)

Casos muy avanzados:

	* Turrican 2 (1991 Enigma Variations / Rainbow Arts)
	* Facehugger Megademo (1991 Face Hugger)
	* Zap't'Balls (1992 Amstrad CPC International)
	* Super Cauldron (1992 Titus)
	* Prodatron Megademo (1992 Prodatron)
	* Prehistorik 2 (1993 Titus)
	* Voyage '93 (1993 varios autores)
	* Overflow 5 Previews (1994 Overflow)
	* Big'O Full'O Dem'O (1998 Arkos)
	* Byte '98 (1999 Mortel & Overlanders)
	* cole Buissonire (2000 Overlanders)
	* DTC (2006 Arkos)
	* Orion Prime (2009 Cargosoft)
	* Edge Grinder (2011 Cosine & Format War)
	* Batman Returns (2011 Batman Group)
	* Bloc Us (2011 Benediction)
	* Super Edge Grinder (2012 Cosine & Format War)
	* R-Type 128 (2012 Easter Egg)
	* Still Rising (2013 Vanity)
	* Yet Another Plasma! (2012 Logon System)
	* Breaking Baud (2015 CRTC & 3LN)
	* Megablasters: Escape from Castle in the Clouds (2015 Project Argon)
	* Imperial Mahjong (2016 Cargosoft)
	* Logon's Run (2017 Logon System)
	* Wunderbar (2017 Arkos & Benediction)
	* Isometrikum (2018 Vanity)
	* Still Scrolling (2018 Music2Eye & Praline)
	* PhX (2018 Condense)
