-----------------------------------------------
History
-------
$Id: introduction.txt,v 1.1.1.1 2001/11/30 22:10:58 cvsroman Exp $
$Log: introduction.txt,v $
Revision 1.1.1.1  2001/11/30 22:10:58  cvsroman
Initial CVS release.

-----------------------------------------------


  Dokumentace k programu ZX2MZ verze 0.1
  --------------------------------------


  Tento program je urcen k prevadeni programu a her z pocitace ZX Spectrum
na pocitac Sharp MZ-800.

  Program byl napsan v jazyku Java. Pro svuj beh vyzaduje JDK 1.3 a knihovny
Xerces (1.3.x) a JDOM (beta7).
  Druha cast programu - emulacni rutiny hardwaru ZX - byla napsana ve strojovem
kodu Z80 a nachazi se take u tohoto programu ('etc/emu.mzf').


  Cely proces konverze hry se sklada z nasledujicich kroku
  --------------------------------------------------------

* nejprve je nutne upravit nejaky emulator ZX Spectra, aby generoval
  reportovaci soubor o jeho behu. Ja jsem pouzil emulator XZX verze
  2.9.3, diff soubory pro jeho upravu jsou soucasti tohoto programu.
  Lze pouzit i emulator ZX48 napsany Zdenkem Adlerem, jehoz soucasti
  jiz zmineny generator reportu je.

* Spustime upraveny emulator, jeho vystup presmerujeme do souboru ('> soubor').
  Pote vybereme hru, kterou chceme prekonvertovat a spustime ji v emulatoru.

* Dostatecne dlouho hru hrajeme, abychom zajistili, ze emulator prosel
  vsechna mista pristupu hry na hardware Spectra (zkousime vsechny typy
  obrazovek hry, ruzna ovladani - klavesnice/kempston, atd..). Kdyz jsme
  si jisti, ze jsme prosli vsim, cim jsme meli, ukoncime emulator (XZX - F10).

* Souboru s vystupem z emulatoru dame priponu .log, je to nas emulacni
  'report', ze ktereho budeme vychazet.

* Z log souboru vytahneme reportovy XML soubor (zacina na '<?xml').

* Z logu zjistime, kde se hra spousti (startovaci adresa) a jake bloky
  natahuje pri nahravani (viz ukazky na konci tohoto dokumentu).

* Spustime konvertor se spravnymi parametry (viz ukazky na konci)
  a mame MZF soubor, ktery pouzijeme na Sharpu.


  Jak konverze funguje
  --------------------

  Reportovy XML soubor z emulatoru v idealnim pripade obsahuje seznam vsech
instrukci, ktere v konvertovanem programu pristupuji na hardware ZX Spectra.
V seznamu je vzdy obsazena adresa, pocet vykonani i samotna instrukce.
Konverze probiha tak, ze se vsechny takoveto instrukce nahradi volanim RST.
Takove volani pak instrukce provede take, ale tak, aby to na Sharpu fungovalo.

  Cely heuristicky proces prirazeni jednotlivych instrukci ruznym RST je
trochu slozitejsi, nez se na prvni pohled zda. Nebudu ho zde sahodlouze
popisovat, ale v principu jde o to, ze instrukce, ktere jsou vykonavane
nejcasteji, dostanou vlastni RST (cca 5 volnych volani) a ostatni jsou
vykonavane pres jedno sdilene RST.


  Co je emulovano
  ---------------

* zapis do VRAM ZX Spectra

    Toto je to nejpomalejsi na cele emulaci. Vysledna rychlost hry zavisi
  hodne na tom, jak moc hra na obrazovku zapisuje. Pokud prenasi cele bloky
  z nejake sve vlastni vedlejsi 'obrazovky', bude rychlost zalostna.

    V emulacnich rutinach je pripravena emulace cernobila (nejrychlejsi),
  barevna bez podkladu (stredne rychla) a take barevna s podkladem (nejpomalejsi).
  Standardne je zapnuta emulace barevna bez podkladu.

* Cteni klavesnice ZX

    Klavesnice je emulovana 'skoro' plne, je mozne, ze nektere hry by mohly
  mit problemy, pokud by testovaly vic klavesovych rad soucasne.
    Emulace emuluje klavesnici ZX, nerozsiruje ji na klavesnici MZ. Pokud
  by bylo treba toto casem doplnit, je to mozne (rutina existuje).

* Cteni Kempston Joysticku

    Nejcastejsi joystick ZX Spectra je emulovan na Joysticku 1. Pokud by bylo
  nekde potreba emulovat jiny ZX joystick (Fuller, Protek), neni problem
  emulaci udelat.

* nastaveni preruseni IM2 a prace s registrem I

    Vse je na Sharpu emulovano tak, aby to fungovalo pro Spectrum transparentne
  a program nic nepoznal.

* zvukovy vystup ZX Spectra 48k a okraj obrazovky
  
    Hudby ve hrach ze ZX 48k se vyznacuji velice jemnym casovanim, proto je mozne,
  ze vysledna hudba na Sharpu bude horsi (misto proste instrukce OUT je nutne
  vykonat docela casove narocne RST + emulaci).

* zvukovy vystup ZX Spectra 128k

    Zvukovy obvod AY 3-891x je plne emulovan. Sharpovy zvukovy obvod ale neposkytuje
  stejny rozsah oktav, proto jsou nizke tony posunuty o oktavu vys. Vetsinou je hudba
  v poradku, i kdyz nekdy ne uplne ta prava orechova ;-((


  Ktere hry/programy nejdou vubec nebo jdou zatim tezko predelavat
  ----------------------------------------------------------------

* Vse, co se odkazuje do ZX ROM

    Z ROMky Spectra je v pameti pritomna pouze znakova sada na adresach 3d00-3fff.
  Pokud predelavany program vola podprogramy v ZX ROM, nebude fungovat.

* Vse, co pouziva IM1

    Vzhledem k tomu, ze IM1 preruseni obsluhuje basic ZX Spectra, bylo by nutne ho tam mit.
  Kazdopadne - standardne je preruseni Sharpa zapnute, takze pokud hra pouziva IM1 pouze
  pro casovani, mela by bezet. Pokud vsak nejakym zpusobem pouziva IM1 i jinak, nema moc sanci.

* Vse, co pouziva zasobnik pro psani na obrazovku

    Nektere hry pouzivaji zasobnikovou instrukci Z80 (PUSH) pro psani na obrazovku. Vzhledem
  k tomu, ze pri emulaci zapisu na obrazovku je na emulovanem miste pouzita instrukce RST,
  ktera umistuje navratovou adresu na zasobnik, zpusobilo by jeji vyvolani nehezke zapisy
  do VRAM ZX a nasledne mozna i do VRAM Sharpa.
    Instrukce PUSH (Z80 kody C5, D5, E5, F5, DD E5, FD E5) nejsou zatim vubec emulovane.

* Vse, co strankuje pamet ZX Spectra 128k

    Sharp ma *zatim* pouze 64k RAM, proto neni jednoduse mozne udelat plnohodnotnou emulaci
  ZX Spectra 128k (coz je velika skoda - vetsina 128k her ma i hezkou hudbu, bohuzel vetsinou
  ve vedlejsi strance pameti).
    Pokud by se nasel nekdo, kdo by pro Sharpa dokazal navrhnout a udelat strankovani pameti,
  bylo by mozne udelat emulaci ZX Spectra 128k.
    Spectrum strankuje pouze pametovy prostor C000-FFFF (16k), k dispozici je cca 5 stranek.
  Samozrejme by se Sharp na toto nemusel omezit, pricemz ale strankovani po 16k blocich je
  nezbytnou podminkou pro moznost behu her ze ZX. Optimalni by bylo strankovani cele pameti
  nezavisle ve 4 blocich (0000-3FFF, 4000-7FFF, 8000-BFFF a C000-FFFF), pripojitelna pamet
  by nemusela byt mala, napr. 1MB (jako max. RAM Disk).
    Tak, hardwarovi odbornici, dejte hlavy dohromady. Je ale dost mozne, ze to neni vubec
  realizovatelne - nevim, ja hardwarovy odbornik nejsem.

    V soucasnosti je ze Spectrum 128k portu FD emulovan pouze zvukovy cip AY. Hry, ktere
  nemaji hudbu pro AY v extra strance pameti, budou hrat.


  Jake problemy se mohou vyskytnout pri konverzich
  ------------------------------------------------

* hra zapisuje pomoci instrukce, ktera neni emulovana
  - jedinou moznosti je takovou instrukci vyradit z XML a pak vyzkouset, o co jsme
    na Sharpu prisli.

* hra se vyskytuje v TAP souboru v komprimovanem tvaru
  - takovou hru je nejprve nutne dekomprimovat, tj. odkrokovat dekomprimacni rutiny
    a vysledek ulozit do nejakeho souboru (binarne, typ BIN na prikazove radce).

* hra dela ruzne kejkle pred spustenim (presuny v pameti apod.)
  - vzhledem k tomu, ze emulacni rutiny vyzaduji, aby byla hra pred konverzi
    na spravnem miste, je nutne hru odkrokovat a ulozit az po techto presunech.

* hra je ve formatu Z80
  - jedna se o snapshot aktualniho behu ZX Spectra. Tento format zatim neni podporovan.

  Ukazkova konverze hry Pyjamarama
  --------------------------------

1) zahrajeme hru v emulatoru a ziskame jeji vystup:

-------------------------- log start ---------------------------

Load request: id = 00, addr = 5ce2, length =    17, block = 00
Load request: id = ff, addr = 5ccb, length =    94, block = 01
Load request: id = 00, addr = 5d40, length =    17, block = 02
Load request: id = ff, addr = 4000, length =  6950, block = 03
Load request: id = 00, addr = 5d40, length =    17, block = 04
Load request: id = ff, addr = 64ff, length = 39680, block = 05
Detected upper memory entry at 8110
Instr  8101: nop
Instr  8102: nop
Instr  8103: nop
Instr  8104: nop
Instr  8105: nop
Instr  8106: nop
Instr  8107: nop
Instr  8108: nop
Instr  8109: nop
Instr  810a: nop
Instr  810b: nop
Instr  810c: nop
Instr  810d: nop
Instr  810e: nop
Instr  810f: nop
Instr *8110: nop
Instr  8111: nop
Instr  8112: nop
Instr  8113: nop
Instr  8114: nop
Instr  8115: nop
Instr  8116: nop
Instr  8117: nop
Instr  8118: nop
Instr  8119: nop
Instr  811a: nop
Instr  811b: nop
Instr  811c: nop
Instr  811d: nop
Instr  811e: nop
Instr  811f: nop
Instr  8120: nop
Instr  8121: nop
Instr  8122: nop
Instr  8123: nop
Instr  8124: nop
Instr  8125: nop
Instr  8126: nop
Instr  8127: nop
Instr  8128: nop
Instr  8129: nop
Instr  812a: nop
Instr  812b: nop
Instr  812c: nop
Instr  812d: nop
Instr  812e: nop
Instr  812f: nop
Instr  8130: nop
Instr  8131: nop
Instr  8132: nop
Report: Read from VideoRAM 4001 at address 8209
Report: Write to VideoRAM 4001 at address B2D0
Report: Write to VideoRAM 50E4 at address C12C
Report: Read from port 00FE at address B2DC
Report: Write to port 17FE at address F6EB
Report: Write to port 07FE at address F6F2
Report: Read from port 00FE at address B2EB
Report: Write to port 00FE at address B2F4
Report: Write to VideoRAM 4001 at address AFAA
Report: Read from VideoRAM 4001 at address AFAA
Report: Write to VideoRAM 4003 at address C0D7
Report: Write to VideoRAM 4103 at address C0E8
Report: Read from port 7FFE at address B35C
Report: Read from port 7FFE at address B36E
Report: Write to port 00FE at address B49B
Report: Write to port 10FE at address B4A3
Report: Read from VideoRAM 50AA at address AB38
Report: Write to VideoRAM 50AA at address AB3A
Report: Read from VideoRAM 50A9 at address AB3C
Report: Write to VideoRAM 50A9 at address AB3E
Report: Write to VideoRAM 4011 at address E4C3
Report: Write to VideoRAM 400D at address 83DB
Report: Write to VideoRAM 400E at address 83DD
Report: Write to VideoRAM 400F at address 83DF
Report: Read from port 7FFE at address ABD3
Report: Read from port DFFE at address ABF5
Report: Read from port DFFE at address AC1C
Report: Write to port 10FE at address AFD0
Report: Write to port 00FE at address AFD8
Report: Read from port FEFE at address B1B7
Report: Read from port 7FFE at address B1BC
Report: Read from VideoRAM 40C3 at address AB34
Report: Write to VideoRAM 40C3 at address AB36
Report: Read from VideoRAM 40A0 at address E23C
Report: Write to VideoRAM 40A0 at address E23C
Report: Read from VideoRAM 41A0 at address E24C
Report: Write to VideoRAM 41A0 at address E24C
Report: Write to VideoRAM 400D at address 841F
Report: Write to VideoRAM 400E at address 8421
Report: Write to VideoRAM 400F at address 8423
Report: Read from VideoRAM 51FF at address EAF4
Report: Read from VideoRAM 51E0 at address EB00
Report: Write to VideoRAM 51E0 at address EB00
Report: Write to VideoRAM 4F47 at address C175
Report: Write to port 10FE at address AFEE
Report: Write to port 00FE at address AFF8
Report: Read from port 00FE at address B1A3
Report: Read from port 00FE at address B1AC
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE report PUBLIC "//HWREPORT.EMU//DTD 1.0" "http://www.dolejsi.cz/spec/emu/hwreport.dtd">
<report architecture="spec48">
  <access kind="vram" operation="write" count="18428"   address="b2d0"> ed b0 </access>
  <access kind="vram" operation="write" count="63983"   address="c12c"> 12    </access>
  <access kind="vram" operation="write" count="61429"   address="afaa"> ed b0 </access>
  <access kind="vram" operation="write" count="7213"    address="c0d7"> ed a0 </access>
  <access kind="vram" operation="write" count="7215"    address="c0e8"> ed a0 </access>
  <access kind="vram" operation="write" count="778671"  address="ab3a"> 77    </access>
  <access kind="vram" operation="write" count="778671"  address="ab3e"> 77    </access>
  <access kind="vram" operation="write" count="13919"   address="e4c3"> 36 00 </access>
  <access kind="vram" operation="write" count="287"     address="83db"> ed a0 </access>
  <access kind="vram" operation="write" count="287"     address="83dd"> ed a0 </access>
  <access kind="vram" operation="write" count="287"     address="83df"> ed a0 </access>
  <access kind="vram" operation="write" count="581887"  address="ab36"> 77    </access>
  <access kind="vram" operation="write" count="486399"  address="e23c"> cb 16 </access>
  <access kind="vram" operation="write" count="486399"  address="e24c"> cb 1e </access>
  <access kind="vram" operation="write" count="232"     address="841f"> ed a0 </access>
  <access kind="vram" operation="write" count="232"     address="8421"> ed a0 </access>
  <access kind="vram" operation="write" count="232"     address="8423"> ed a0 </access>
  <access kind="vram" operation="write" count="5567"    address="eb00"> cb 1e </access>
  <access kind="vram" operation="write" count="1663"    address="c175"> 12    </access>
  <access kind="vram" operation="read"  count="6142"    address="8209"> ed b0 </access>
  <access kind="vram" operation="read"  count="61429"   address="afaa"> ed b0 </access>
  <access kind="vram" operation="read"  count="778671"  address="ab38"> 7e    </access>
  <access kind="vram" operation="read"  count="778671"  address="ab3c"> 7e    </access>
  <access kind="vram" operation="read"  count="581887"  address="ab34"> 46    </access>
  <access kind="vram" operation="read"  count="486399"  address="e23c"> cb 16 </access>
  <access kind="vram" operation="read"  count="486399"  address="e24c"> cb 1e </access>
  <access kind="vram" operation="read"  count="173"     address="eaf4"> 7e    </access>
  <access kind="vram" operation="read"  count="5567"    address="eb00"> cb 1e </access>
  <access kind="port" operation="write" count="26573"   address="f6eb"> d3 fe </access>
  <access kind="port" operation="write" count="26572"   address="f6f2"> d3 fe </access>
  <access kind="port" operation="write" count="1"       address="b2f4"> d3 fe </access>
  <access kind="port" operation="write" count="199"     address="b49b"> d3 fe </access>
  <access kind="port" operation="write" count="199"     address="b4a3"> d3 fe </access>
  <access kind="port" operation="write" count="19056"   address="afd0"> d3 fe </access>
  <access kind="port" operation="write" count="19056"   address="afd8"> d3 fe </access>
  <access kind="port" operation="write" count="2399"    address="afee"> d3 fe </access>
  <access kind="port" operation="write" count="2399"    address="aff8"> d3 fe </access>
  <access kind="port" operation="read"  count="8078"    address="b2dc"> db fe </access>
  <access kind="port" operation="read"  count="575"     address="b2eb"> db fe </access>
  <access kind="port" operation="read"  count="1205"    address="b35c"> db fe </access>
  <access kind="port" operation="read"  count="3537671" address="b36e"> db fe </access>
  <access kind="port" operation="read"  count="4023"    address="abd3"> db fe </access>
  <access kind="port" operation="read"  count="3985"    address="abf5"> db fe </access>
  <access kind="port" operation="read"  count="1851"    address="ac1c"> db fe </access>
  <access kind="port" operation="read"  count="3386"    address="b1b7"> db fe </access>
  <access kind="port" operation="read"  count="3386"    address="b1bc"> db fe </access>
  <access kind="port" operation="read"  count="10740"   address="b1a3"> db fe </access>
  <access kind="port" operation="read"  count="476204"  address="b1ac"> db fe </access>
  <load block="00" id="00" addr="5ce2" length="0011"/>
  <load block="01" id="ff" addr="5ccb" length="005e"/>
  <load block="02" id="00" addr="5d40" length="0011"/>
  <load block="03" id="ff" addr="4000" length="1b26"/>
  <load block="04" id="00" addr="5d40" length="0011"/>
  <load block="05" id="ff" addr="64ff" length="9b00"/>
</report>

-------------------------- log end ---------------------------

2) Z log souboru vezmeme XML a vytvorime soubor py.xml.

3) podivame se na bloky, ktere hra narava. Je videt, ze nejprve je nahravan
   basicovy program (bloky 0,1), potom obrazek (2,3) a nakonec kod hry (4,5).
   Vzhledem k tomu, ze Pyjamarama vezme pri startu uvodni obrazek z obrazovky
   a pozdeji ho tam zase vraci, budeme potrebovat jak kod (blok 5), tak
   i obrazek (blok 3). Proto si zapamatujeme jak jejich cisla, tak i adresy,
   kam se nahravaly.

4) podivame se, na jake adrese se hra spousti. Z logu je videt, ze poprve kod
   vystoupil z ROM (adresy 0000-4000) na adresu 8110. Zkusime proto tuto adresu
   pouzit jako startovaci.

5) provedeme konverzi pomoci zx2mz, prikazova radka bude:

zx2mz py.xml etc/emu.mzf py.mzf MeJmeno RLE 8110 tap py.tap 3 4000 tap py.tap 5 64ff

   Pro konverzi jsme pouzili XML report a emulacni rutiny.
   Dale jsme specifikovali sve jmeno (bude se objevovat na spodu obrazovky) a typ
   komprese (podporovana je bud zadna (Dummy) nebo Run-length-encoded (RLE)).
   Soucasti radky je i vystupni soubor, spousteci adresa (8110) a popis, odkud
   vzit zdrojova data (TAP soubor, lze i cisty binarni BIN) a kam je dat do pameti.

   Vysledny soubor nesmi byt delsi nez 48640 (BE00) bytu (Sharp by ho neumel nahrat),
   proto je v pripade Pyjamaramy nutne pouzit kompresi (v soucasnosti pouze RLE,
   casem muze byt i jina).

6) Vytvoreny py.mzf vyzkousime na Sharpu.