• Introduction
• Première partie: Android et Java
• Deuxième partie: Architecture générale
• Troisième partie: Implémenter le CPU
• Quatrième partie: Une première image
• Cinquième partie: Mémoire Tandy 16 couleurs vers Bitmap
• Sixième partie: Erreurs d'implémentation
• Septième partie: Support du clavier
• Huitième partie: Bugs en jeu
• Neuvième partie: Optimisations pour accélérer l'émulation
• Dixième partie: Interface usager
• Onzième partie: Libérer le CPU
• Douzième partie: Et que le son soit!
• À suivre, mais essayez le jeu dès maintenant!

Introduction

Ce projet n'est pas terminé. Mises à jour à venir!

Toutefois, une version beta est déjà disponible. Pourquoi ne pas l'essayer?

• Je souhaite maîtriser et comprendre l'ensemble du système.
  Rien de tel que de tout faire soi-même pour cela!
  
  
• Je prévois augmenter le jeu en utilisant des éléments standard de l'interface utilisateur du système.
  Je vais tenter de remplacer les menus fonctionnant avec les lettres du clavier par des boutons standard. Peut-être même utiliser des Spinners pour choisir l'angle et la force de tir facilement sur l'écran tactile. Pour se faire, l'émulateur injectera du code dans le jeu pour remplacer certaines routines par des appels système spéciaux.
  
  L'utilisation d'un gros morceau que je n'ai pas créé (DOSBox) beaucoup trop complet, puissant et complexe pour le peu de ressources qu'utilise mon jeu serait sans doute un plus gros obstacle que d'écrire mon propre émulateur.
  
  
• Je veux que l'ensemble de l'oeuvre soit ma propriété, afin de pouvoir faire comme bon me semble.
  Ainsi, si je souhaite vendre un jeu utilisant cet émulateur, il n'y aura pas de complications à cause de licences.

Première partie: Android et Java

Deuxième partie: Architecture générale

    mCPU = new Cpu8088();

Zones mémoires

public interface Memory {
    boolean isAddressInRange(int address);
    void write8(int address, int b);
    void write16(int address, int w);
    int read8(int address);
    int read16(int address);
}

	MemoryBlock stack = new MemoryBlock(0x400, MemoryBlock.SIZE_64K);
	MemoryBlock program = new MemoryBlock(0x10000, MemoryBlock.SIZE_64K * 4);
	cga_vram = new MemoryBlock(Cpu8088.getLinearAddress(0xB800, 0), MemoryBlock.SIZE_64K/2);
	MemoryBlock ivt = new MemoryBlock(0, 0x400);

	mCPU.addMemoryRange(program);
	mCPU.addMemoryRange(cga_vram);
	mCPU.addMemoryRange(stack);
	mCPU.addMemoryRange(ivt);

	/* Charge l'exécutable du jeu (gametga.com) dans le bloc de mémoire 'program' à partir de
	 * l'adresse 0x100. (Les exécutables .COM ont une origine de 0x100). */
	program.load(this.getResources().openRawResource(R.raw.gametga), 0x100);

• Un pour le code du jeu. L'exécutable du jeu (un fichier .com) est stocké comme ressource de type raw dans le projet.
• Un autre bloc pour la mémoire vidéo. Le jeu dans l'émulateur accédera à cette zone mémoire normalement, comme s'il s'agissait de la mémoire d'une carte vidéo. Le code d'affichage Android que je mettrai en place n'aura qu'à la lire et convertir le contenu vidéo en format Tandy 16 couleurs vers son format natif.
• Encore un autre bloc pour la pile.
• Et finalement, un petit block pour le vecteur d'interruption. (RATillery y accède directement pour installer le gestionnaire d'interruption s'occupant du son.

Services du BIOS

public interface Int {
	public void handle(Cpu8088 cpu);
	public int getNumber();
}

public class Int10 implements Int, Constants {
    private int current_mode = 0x03; // 80x25 color

    @Override
    public void handle(Cpu8088 cpu) {
        switch(cpu.AX >> 8)
        {
            case 0x0:
                current_mode = cpu.AX & 0xff;
                Log.d(LOG, "int10: Set video mode to 0x" + Integer.toHexString(current_mode));
                break;
            case 0xF: // Get Video State
                Log.d(LOG, "int10: Get video state");
                // AH : number of screen columns
                // AL : mode currently set
                // BH : current display page
                cpu.setAH(80);
                cpu.setAL(current_mode);
                cpu.setBH(0);
                break;
            case 0xB: // Set palette
                Log.d(LOG, "int10: Set palette (ignored)");
                break;
            default:
                cpu.halt("Int10: subservice 0x" + Integer.toHexString(cpu.AX >> 8));
        }
    }

    @Override
    public int getNumber() {
        return 0x10;
    }

• Service 10h (video): Utilisé pour entrer et sortir du mode graphique
• Service 16h (clavier): Utilisé pour recevoir des événements de touche du clavier.
• Service 1Ah (chronomètre): Utilisé pour obtenir l'heure qui sert de valeur initiale au générateur pseudo-aléatoire.

	mCPU.addIntHandler(new Int1a()); // Time
	mCPU.addIntHandler(new Int10()); // Video
	keyboardInt = new Int16();
	mCPU.addIntHandler(keyboardInt);

Ports d'E/S

public interface IOPort {
	public boolean isPortHandled(int port);
	public int in8(int port);
	public int in16(int port);
	public void out8(int port, int value);
	public void out16(int port, int value);
}

• Port 0x3DA: Le jeu lit ce port pour se synchroniser au rafraîchissement vertical de l'écran. (Le jeu s'en sert pour avoir une vitesse constante)
• Ports 0x40-0x5F, 0x61: Le jeu contrôle le haut-parleur et configure la fréquence à laquelle le gestionnaire d'interruption s'occupant de la musique est exécuté avec quelques écritures vers ces ports.

	vcard_ports = new VideoCardPorts();
	mCPU.addIOPort(vcard_ports);
	mCPU.addIOPort(new PITPorts());

Troisième partie: Implémenter le CPU

switch (opcode)
{
	case 0x50: push16(AX); break; // PUSH AX
	case 0x58: AX = pop16(); break; // POP AX
	case 0x40: AX = alu.add(AX, 1, ALU.WORDMODE); break; // INC AX
	case 0x34: // XOR AL,IMMED8
		immed8 = getInstructionByte();
		 setAL(alu.xor(AX & 0xff, immed8, ALU.BYTEMODE));
		 break;
	case 0xAC: // LODSB
		setAL(read8(getLinearAddress(DS_CUR, SI)));
		if ((FLAGS & DF) == DF) {
			SI = (SI-1) & 0xffff;
		} else {
			SI = (SI+1) & 0xffff;
		}
		break;
}

Hmm, c'est un peu long. Ne faisons qu'implémenter le nécessaire... - Échec!

- Génial, je peux voir le programme appeler des sous-routines et le retour fonctionner!

- Il y a quand même beaucoup d'instructions manquantes...

- Oh, je dois implémenter le préfixe de répétition REP. Utilisons la récursion.

- Hmm, il y a quand même vraiment beaucoup d'instructions manquantes...

- Oh là là, c'est bien toutes ces instructions qui opèrent au choix sur la mémoire ou sur des registres, mais il faut tout décortiquer..

- C'est encore pire. Il peut y avoir un déplacement codé sur 8 ou 16 bits qu'il faut prendre en compte...

- Mais les instructions 0x80,0x81,0x83 sont infernales! Elles sont suivies d'une deuxième octet pour choisir l'opération.

Un premier bug dans l'émulateur à résoudre

- Le code est pris dans une boucle infinie. Je regarde le source de RATillery pour comprendre... Je suis l'exécution dans l'émulateur une ligne à la fois très attentivement... Bon. Certains sauts conditionnels ne fonctionnent pas correctement car j'ai mal implémenté les flags pour certaines opérations...

Quatrième partie: Une première image

	private ImageView mScreen;
	private Bitmap mScreenBitmap;
	private final int clut[] = new int[16];
	...
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		...
		mScreen = findViewById(R.id.screen);

		mScreenBitmap = Bitmap.createBitmap(320, 200, Bitmap.Config.ARGB_8888);
		mScreenBitmap.eraseColor(Color.GREEN);
		mScreen.setImageBitmap(mScreenBitmap);
		...
		clut[0] = Color.rgb(0,0,0);
        clut[1] = Color.rgb(0x00, 0x00, 0xAA);
        clut[2] = Color.rgb(0x00, 0xAA, 0x00);
        clut[3] = Color.rgb(0x00, 0xAA, 0xAA);
        clut[4] = Color.rgb(0xAA, 0, 0);
        clut[5] = Color.rgb(0xAA,0x00,0xAA);
        clut[6] = Color.rgb(0xAA, 0x55, 0);
        clut[7] = Color.rgb(0xAA,0xAA,0xAA);
        clut[8] = Color.rgb(0x55, 0x55, 0x55);
        clut[9] = Color.rgb(0x55, 0x55, 0xff);
        clut[10] = Color.rgb(0x55, 0xff, 0xff);
        clut[11] = Color.rgb(0x55, 0xff, 0xff);
        clut[12] = Color.rgb(0xff,0x55,0x55);
        clut[13] = Color.rgb(0xff,0x55,0xff);
        clut[14] = Color.rgb(0xff, 0xff, 0x55);
        clut[15] = Color.rgb(0xff,0xff,0xff);

	}

Cinquième partie: Mémoire Tandy 16 couleurs vers Bitmap

Le mode 320x200x16 (16-Color Medium-Resolution)

Une première tentative

	byte[] tandy16 = ratillery.getVRAM(); // Retourne le byte[] array de la mémoire vidéo

	for (y=0; y < 200; y++) {
		for (x=0; x < 320; x+=2) {
			pixel1 = tandy16[y * 160+ x/2] >> 4;
			pixel2 = tandy16[y * 160 * x/2 + 1] & 0xf;
			mScreenBitmap.putPixel( x, y, clut[pixel1] );
			mScreenBitmap.putPixel( x+1, y, clut[pixel2] );
		}
	}

La bonne approche

	private int rowbuf[] = new int[320];
...
	private void doScanline(byte tandy16[], int src_offset, int screen_y)
	{
		int x;
		for (x=0; x<320; x+=2) {
			int pixelpair = tandy16[src_offset+(x/2)] &0xff;

			rowbuf[x] = clut[pixelpair >> 4];
			rowbuf[x+1] = clut[pixelpair & 0xf];
		}
		mScreenBitmap.setPixels(rowbuf, 0, 320, 0, screen_y, 320, 1);
	}

	private void syncVram() {
		int y;
		MemoryBlock vram = ratillery.getVRAM();
		final byte[] data = vram.getRawBytes();

		for (y=0; y<50; y++) {
			doScanline(data, 0 + y * 160, y * 4);
		}
		for (y=0; y<50; y++) {
			doScanline(data, 0x2000 + y * 160, y*4 + 1);
		}
		for (y=0; y<50; y++) {
			doScanline(data, 0x4000 + y * 160, y*4 + 2);
		}
		for (y=0; y<50; y++) {
			doScanline(data, 0x6000 + y * 160, y*4 + 3);
		}
	}

Première image

Seconde image

Sixième partie: Erreurs d'implémentation

Changement de programme: Utilisons un test simple

Le test simple dans DOSBox

Ça y est, les instructions non implémentées, ça recommence...

Test simple (résultat incorrect)

Anomalie 1: Il y des lignes en trop dans le texte!

Quel idiot! Le manuel est pourtant clair. L'instruction LOOP décrémente CX avant de vérifier s'il est rendu à zéro!

Eh oui, certaines boucles faisaient un tour de trop...

Anomalie 2: Pixels manquant dans le cadre

Test OK

De retour à RATillery pour voir:

Déception! J'espérais que tout serait réglé...

Ah ha! Mon implémentation du préfixe REP est incorrecte lorsque CX = 0.

Il se trouve que lorsque CX=0, l'instruction suivante (MOVSB, par exemple) était quand même exécutée une fois.

Victoire! Une autre étape importante de franchie: Le jeu affiche enfin l'écran titre correctement!

Septième partie: Support du clavier

public class Int16 implements Int {
	// TODO : Need a FIFO
	private boolean hasKeystroke = false;
	private int scancode;

	public void injectKeyStroke(int scancode) {
		this.scancode = scancode;
		hasKeystroke = true;
	}

	@Override
	public void handle(Cpu8088 cpu) {
		switch(cpu.AX >> 8)
		{
			case 1: // Get keyboard status
				if (hasKeystroke) {
					cpu.AX = scancode;
					cpu.FLAGS &= ~cpu.ZF;
				} else {
					cpu.AX = 0; // scancode (none)
					cpu.FLAGS |= cpu.ZF;
				}
				break;
			case 0: // Note: This is incorrect as it does not block.
				cpu.AX = scancode;
				hasKeystroke = false;
				break;
			default:
				Log.e(LOG, String.format("int16: service AH=0x%02x not implemented", cpu.AX >> 8));
		}
	}

	...
}

Interface usager de fortune

Support d'un clavier physique

	@Override
	public boolean onKeyUp(int keyCode, KeyEvent event) {
		int unichar = event.getUnicodeChar();
		if (unichar >= 32 && unichar <= 128) {
			ratillery.pressAsciiKey((char)event.getUnicodeChar());
		}
		// extra code for ESC, ENTER and BACKSPACE keys not shown
		return true;
	}

Huitième partie: Bugs en jeu

1 - C'est toujours le tour du premier joueur

togglePlayerTurn:
	push ax
	mov al, [player_turn]
	not al
	and al, 1
	mov [player_turn], al
	pop ax
	ret

2 - Impossible d'abandonner

AND CX, 0xFFFF

int add16(int a, int b) {
	int result = a+b;

	if (r > 0xffff) {
		// set CF flag here
	} else {
		// clear CF flag here
	}

	// Code for other flags (OF, SF, ZF) not shown

	return result & 0xffff;
}

3 - L'écran des crédits s'affiche partiellement

Neuvième partie: Optimisations pour accélérer l'émulation

Bon, alors mesure initiale de 280000. Voyons ce que je peux faire.

Tableau pour les IOPorts: IPS maintenant à 317000. Pas mal, 20% plus rapide. À présent, quoi d'autre?

Memory memoryZones[] = new memoryZones[0x100000];

Tableau pour la mémoire: IPS maintenant à 1384000. Excellent, un gain instantané de 400% !

	private Memory getMemForAddress(int address) {
		return memoryZones[address];
	}

	public int read16(int address) {
		return getMemForAddress(address).read16(address);
	}

	public int read16(int address) {
		return memoryZones[address].read16(address);
	}

Et ça alors! Avec l'inlining, l'indice d'IPS est monté à 2003000!

• getInstructionByte()
• getInstructionWord()
• getInstrcutionInt16()
• getInstructionSX()

public int getInstructionWord() {
	int b = read16(CS, IP);
	IP = (IP + 2) & 0xFFFF;
	return b;
}

public int getInstructionWord() {
	int b = memoryZones[(CS<<4)+IP].read16(CX, IP);
	IP = (IP + 2) & 0xFFFF;
	return b;
}

Pas mal, IPS à 2227600

L'effet: On roule maintenant à 2599800 IPS

Résultat final: 2700000 instructions par seconde.

Des idées pour plus tard?

Bon, dès que j'ai écrit ces lignes, je n'ai pas pu résister et j'ai fait le changement. Et boom, 3545000 IPS! (12 fois rapide qu'au départ)

Dixième partie: Interface usager

Soyons réalistes. La majorité des gens qui voudront l'essayer seront sur un téléphone.

Écran titre

À ce moment, j'ai eu une révélation: Suffit de mettre les boutons dans cet espace!

• Quand l'usager appuie sur Story ou Credits, simule la touche S ou C au clavier, puis cache les boutons.
• Quand l'usager appuie n'importe où dans l'écran, simule la touche ESPACE au clavier, puis réaffiche les boutons. Si le jeu est déjà à l'écran titre, cela n'a pas d'effet (les boutons sont déjà visibles et ESPACE ne fait rien).
• Quand l'usager appuie sur le bouton RETOUR du téléphone, simule la touche ESPACE au clavier, puis réaffiche les boutons. (Ici encore, aucun effet au menu principal).

// Called when the Story button is pressed
public void doStory(View view) {
	ratillery.pressAsciiKey('s');
	mButtonBox_title.setVisibility(View.INVISIBLE);
}

// Called when the Credits button is pressed
public void doCredits(View view) {
	ratillery.pressAsciiKey('c');
	mButtonBox_title.setVisibility(View.INVISIBLE);
}

// Called when the screen is clicked/touched
public void onScreenClicked(View v) {
	ratillery.pressAsciiKey(' ');
	mButtonBox_title.setVisibility(View.VISIBLE);
}

// Called when a keyboard key is pressed (includes buttons on the device)
public boolean onKeyUp(int keyCode, KeyEvent event) {
	if (keyCode == KeyEvent.KEYCODE_BACK) {
		// in Story or Credits, cause the game to go back to the menu
		ratillery.pressAsciiKey(' ');
		mButtonBox_title.setVisibility(View.VISIBLE);
		return true;
	}
	...
}

Options pré-partie

En jeu!

Boîtes de dialogue

• Lorsque le jeu demande de confirmer l'abandon de la partie
• Lorsque le jeu demande si l'utilisateur souhaite rejouer
• Lorsque le projectile touche la cible ou un obstacle

Onzième partie: Libérer le CPU

1. Attends que le rafraîchissement vertical (vsync) commence (se produit 60 fois par seconde ou à chaque 16.67ms)
2. Change l'image du feu si c'est le temps (un compteur est utilisé pour suivre le progrès de l'animation)
3. Regarde si une touche du clavier a été appuyée.
4. Retour à la première étape.

  2458                              <3> waitVertRetrace:
  2459 000009BE E86FFA              <3>     call runAnimations
  2460                              <3> waitVertRetraceNoAnim:
  2461 000009C1 F606[9E00]FF        <3>     test byte [skip_vert_retrace], 0FFh
  2462 000009C6 7511                <3>     jnz _skip_vert_retrace
  2463                              <3>
  2464 000009C8 50                  <3>     push ax
  2465 000009C9 52                  <3>     push dx
  2466 000009CA BADA03              <3>     mov dx, 3DAh
  2467                              <3> _waitNotInRetrace:
  2468 000009CD EC                  <3>     in al, dx
  2469 000009CE A808                <3>     test al,08h
  2470 000009D0 74FB                <3>     jz _waitNotInRetrace
  2471                              <3> _notInRetrace:
  2472 000009D2 EC                  <3>     in al, dx
  2473 000009D3 A808                <3>     test al,08h
  2474 000009D5 75FB                <3>     jnz _notInRetrace
  2475 000009D7 5A                  <3>     pop dx
  2476 000009D8 58                  <3>     pop ax
  2477                              <3> _skip_vert_retrace:
  2478 000009D9 C3                  <3>     ret

• L'appel à runAnimation permet à un gestionnaire d'animation d'animer certains objets (utilisé pour animer la queue des rats)
• Il y a deux points d'entrée, waitVertRetrace et waitVertRetraceNoAnim. Ce dernier omet de faire tourner les animations.
• La variable skip_vert_retrace permet en fait de ne pas attendre (utilisé dans certaines circonstances)

Objectif: Temporairement arrêter l'émulation lorsque waitVertRetrace est appelé.

Remplacer l'attente par un appel à Thread.sleep(milliseconds)

private void patchWaitVsync()
{
        byte[] prg = mProgram.getRawBytes();
        int offset = 0x09C8 + TEXT_START;

		// Petite vérification, juste au cas...
		if ((prg[offset] & 0xff) != 0x50) {
            logE("Invalid address for patch wait vsync : Found 0x" + Integer.toHexString(prg[offset]));
        } else {
			// INT 80h
            prg[offset] = (byte)0xCD;
            prg[offset+1] = (byte)0x80;
			// RET
            prg[offset+2] = (byte)0xc3;
        }
}

public void handleInt(int number) {
	if (number == WAIT_VSYNC_INT_NO) {
		waitingForVSYNC = true;
		mCPU.suspend();
	}
}

	time_since_last_retrace = System.nanoTime() - prev_retrace_ts;
	time_to_next_retrace = (16670 * 1000) - time_since_last_retrace; // 16.67ms

	realSleep(time_to_next_retrace / 1000); // a wrapper around Thread.sleep which accepts microseconds

	waitingForVSYNC = false;
	mCPU.resume();

Douzième partie: Et que le son soit!

Un glorieux spécimen de PC speaker

1. Canal 0: Génération d'une interruption à 59.9 Hz: Régule la vitesse de la trame musicale
2. Canal 2: Génération d'une onde carrée destinée au haut parleur: La fréquence de cette onde change avec les notes.

Canal 0 du PIT

Canal 2 du PIT

Implémentation

{
	...
	realSleep(time_to_next_retrace / 1000);
	waitingForVSYNC = false;
	mCPU.resume();
	soundTick();
}

// Hack for 60Hz int8 sound routine. Call this ~60Hz
public void soundTick()
{
	if ((pit.getChannelFrequency(0)>59.0) && (pit.getChannelFrequency(0)<61.0)) {
		mCPU.callInt(8);
	}

	mSound.setTargetFreq(pit.getChannelFrequency(2));
}

Génération du son

À propos de la forme d'onde

Arrêt en douceur des notes

Code de génération du son

class Sound {
    private AudioTrack mTrack;
    private int mSampleRate;
    private short waveformBuffer[];
    private double waveAngle;
    private short last_sample = 0;

    ...

	Sound()
	{
        mSampleRate = AudioTrack.getNativeOutputSampleRate(AudioManager.STREAM_MUSIC);
        bufsize = AudioTrack.getMinBufferSize(mSampleRate, AudioFormat.CHANNEL_OUT_MONO,
                                                                  AudioFormat.ENCODING_PCM_16BIT);
        mTrack = new AudioTrack(AudioManager.STREAM_MUSIC, mSampleRate, AudioFormat.CHANNEL_OUT_MONO,
                AudioFormat.ENCODING_PCM_16BIT, bufsize, AudioTrack.MODE_STREAM);
        waveformBuffer = new short[mSampleRate];
	}

	...

    private void writeSound(int n_samples, double frequency)
    {
        int i;

        if (frequency < 15 || frequency > (mSampleRate / 3)) {
            // fade out to avoid clicks and pops
            for (i = 0; i < n_samples; i++) {
                waveformBuffer[i] = (short)(last_sample - (i * (last_sample / n_samples)));
            }

            // reset sine angle to 0, to avoid clicks/pops at next note attack
            waveAngle = 0;
            last_sample = 0;
        } else {
            double radians_per_second = 2.0 * Math.PI * frequency;
            for (i = 0; i < n_samples; i++) {
                double sample = Math.sin(waveAngle), coeff = 4.0;
                double sample3rd = Math.sin(waveAngle * 3.0), coeff3rd = 2.0;
                double sample5th = Math.sin(waveAngle * 5.0), coeff5th = 1.5;
                double square;
                double square_coeff = 0.5;
                int low_boost_thres = 200;

                if (sample < -0.5) {
                    square = -1;
                } else if (sample > 0.5) {
                    square = +1;
                } else {
                    square = 0;
                }

                // At low frequencies, increase square wave level (adds harmonics) for louder
                // reproduction in small phone speakers.
                if (frequency < low_boost_thres) {
                    square_coeff += (low_boost_thres - frequency) * 2.0 / (double)low_boost_thres;
                }

                double mixed =  (coeff * sample +
                                coeff3rd * sample3rd +
                                coeff5th * sample5th +
                                square_coeff * square)
                                /
                                (coeff + coeff3rd + coeff5th + square_coeff);

                last_sample = (short)((mixed * Short.MAX_VALUE));
                waveformBuffer[i] = last_sample;
                waveAngle += radians_per_second / mSampleRate;
            }
        }

        mTrack.write(waveformBuffer, 0, n_samples);
    }
}

À suivre, mais essayez le jeu dès maintenant!

• 2018-08-26: Lancement de la première version (Beta)
• 2018-09-15: Version 2:
  • Support pour deux joueurs (les valeurs de tir de chaque joueur sont mémorisées entre les tours)
  • Cache les champs d'entrée, le curseur et la boîte pour les paramètres de tir
  • Affiche et cache le bouton de mise à feu
  • Cache les contrôles d'angle et de force pendant les tirs (mode 2 joueurs seulement). En mode un joueur, les contrôles demeurent disponibles pour permettre au joueur de préparer son tir pendant le tour de l'adversaire.
• 2018-11-10: Versions 3 and 4:
  • Utilisation de l'unité centrale réduite
  • L'émulateur est maintenant arrêté lorsque l'application est suspendue
  • Support de la langue française
• 2018-11-17: Version 5: Émulation du PC Speaker (enfin du son!)