Programovanie WHDLoad

### Schematické zobrazenie postupu po spustení programu WHDLoad

Nasledujúca tabuľka ukazuje, ako pracuje program WHDLoad, keď je spustený nainštalovaný program. Dúfam, že to pomôže pri pochopení, ako WHDLoad pracuje a ako WHDLoad, Slave a nainštalovaný program spolupracujú.

Užívateľ

- spustí demo alebo hru kliknutím na ikonu alebo spustením WHDLoad cez príkazový riadok

Operačný Systém

- nahrá executable programu WHDLoad a spustí ho

WHDLoad

- testuje softverové a hardverové prostredie
- nahrá a testuje Slave
- alokuje požadovanú pamäť pre program
- ak je zapnutý Preload/S, nahráva obraz disku alebo súbory do RAM (ak je pre ne dostatok voľnej pamäte)
- vypína OS (zastaví multitasking a prerušenia, degraduje grafický hardvér na OCS, inicializuje všetok hardvér s definovanými hodnotami)
- skočí do kódu Slave

Slave

- nahrá hlavný executable nainštalovaného programu volaním WHDLoad funkcie (napr. resload_DiskLoad,alebo resload_LoadFile)
- upraví hlavný executable (takže program bude nahrávať svoje dáta cez Slave, odstránia sa problémy s nekompatibilitou a je umožnené vyskočenie z programu), prípadne nastaví exit key - klávesu, prostredníctvom ktorej sa môžeme vrátiť do OS)
- skočí do hlavného executable hry alebo dema

Nainštalovaný program

- robí to, na čo bol programovaný ;-)
- pri nahrávaní dát z disku volá Slave (pretože Slave ho predtým tak upravil) a Slave volá WHDLoad a WHDLoad čiastočne zapne OS, aby nahral dáta z disku (ak dáta neboli nahrané predtým pomocou voľby Preload), potom sa vráti z OS, vráti sa z WHDLoad, vráti sa zo Slave a nainštalovaný program pokračuje ďalej

Užívateľ

- ukončí program pomocou klávesy QuitKey

Slave

- vracia sa do WHDLoad volaním resload_Abort

WHDLoad

- odblokuje OS (vráti hodnoty hardvér registru, displeja a pamäte)
- uvolní všetky alokované zdroje
- vracia sa do OS

### Ako vytvoriť jednoduchý trackloader jedno-disketovej hry

Toto je len veľmi malý a krátky názorný príklad, ako vytvoriť inštalačku pomocou programu WHDLoad. Ukážka popisuje najjednoduchšiu situáciu, s ktorou sa však v skutočnosti (pravdepodobne) nikdy nestretnete, takže pre špeciálne prípady a problémy, ktoré môžu nastať, čítajte ďalšie kapitoly.

1. Príprava
   - Vytvorte adresár, kde budú uložené všetky súbory.
   - Vytvorte disk image pomocou DIC a presuňte ho do nášho adresára.
   - Vytvorte ikonu s "WHDLoad" ako <Default Tool> a tooltype "SLAVE=#?" obsahujúcim meno Slave (alebo jednoducho prekopírujte ikonu z ukážkových inštalácií a odstráňte všetky tooltype okrem "SLAVE="
2. Slave
   Na napísanie Slave potrebujeme nasledujúce informácie:
   1. Kde je na disku hlavný executable?
   2. Kde je vo vnútri hlavného executable disk-loader? (tj. nahrávacia rutina)
   Na získanie týchto informácii najskôr analyzujeme bootblock. Väčšinou je executable nahraný pomocou funkcie exec.DoIO(), niekedy je ale v bootblocku špeciálny trackloader. Napíšeme Slave, ktorý simuluje bootblock a nahrá hlavný executable z disk image. Teraz získame (vyripujeme) hlavný executable z image alebo memory dump, Potom musíme nájsť loader v hlavnom executable. Rýchlou cestou je pomocou hex-editoru hľadať reťazec $AAAAAAAA (ktorý je používaný pre MFM dekódovanie). Potom vystrihneme danú oblasť (+/- $1000 bytes), disassemblujeme ju a nájdeme začiatok rutiny. Musíme pochopiť zoznam parametrov. Potom vytvoríme kód pre Slave, ktorý upraví túto loader rutinu tak, že všetky odkazy na loader budú presmerované do Slave. Potom si Slave prispôsobí parametre a zavolá WHDLoad funkciu resload_DiskLoad.
3. V ideálnom prípade je inštalačka hotová.
   Zostáva už len urobiť peknú ikonu. Extrahujte dva obrázky použitím snoop módu a SP alebo freezerom alebo U.A.E. a vytvorte ikonu. Doporučená je šestnásťfarebná RomIcon paleta.

### Možné problémy a zvláštne prípady

#### Neštandardný trackloader

Niektoré programy majú svoj vlastný formát disku. To znamená, že DIC nemôže vytvoriť disk image. Na vytvorenie súboru alebo image z takého disku je potrebné napísať špeciálnu rutinu s použitím RawDIC. Pre viac informácií čítajte dokumentáciu RawDIC.

#### Viacero diskov

Ak program používa viac než jednu disketu, Slave musí presmerovať prístupy k disku na zodpovedajúci disk image súbor. Niekedy je to ťažké. Niektoré programy vedia použiť viac disketových jednotiek, takže môžete použiť číslo jednotky na vybratie správneho image. Väčšina programov používa určité ID na každom disku kvôli rozpoznaniu, v tomto prípade použite premennú, ktorá by obsahovala číslo diskety a pri každom prístupe na ID diskety (odhaľte také prístupy analyzovaním parametrov pre disk loader) zvýšte hodnotu premennej (ak sa dostaneme na poslednú disketu, znížte hodnotu). Tak by mal loader čítať ID znova a znova, až kým nenájde správnu disketu. Ak sa zobrazuje požiadavka na vloženie disku, odstráňte ju.

#### Ukladanie Highscore tabuľky

Použite resload_SaveFile na zapísanie potrebnej oblasti pamäte na disk. Ak chcete, zašifrujte vytvorený súbor, takže lameri ho nebudú schopní tak ľahko editovať. Nie je dobré zapisovať highscore priamo do disk image (použitím resload_SaveFileOffset), pretože ak sa niečo zlé prihodí (napr. program zamrzne), môže sa stať, že image sa poškodí.

#### Uloženie pozície v hre (Savegames)

Ovládanie je rovnaké, ako pri ukladaní highscore.

#### Prístupy do operačného systému

V momente, kedy je Slave a inštalovaný program v chode, neexistuje žiadny OS, takže žiadny prístup k nemu nebude fungovať! Všetky prístupy nainštalovaného programu k OS musia byť odstránené alebo emulované. Ak ich nie je príliš veľa a nemajú pre WHDLoad systému veľký význam (napr. exec.Disable() alebo exec.SuperState()) jednoducho ich odstráňte pomocou NOP ($4e71). Ak má volanie OS dôležitú funkciu (ako exec.DoIO()), presmerujte toto volanie do Slave a emulujte ho. Ak ich je takýchto prístupov mnoho, vytvorte jednoduchú exec.library v nepoužitej oblasti pamäte (iniciujte longword adresu na `$4`). Môžete sa pozrieť napr. na Oscar.slave, ktorý emuluje exec.AllocMem(). Na zistenie prístupov do OS, začiatok execbase je nastavený na $f0000001 kvôli tomu, pretože všetky rutiny, ktoré použijú execbase, spôsobia výnimku "Address Error".
Ak je prístupov do OS až príliš mnoho, použite jeden z KickEmu balíčkov z whdload-dev archívu. Je tam jeden balíček pre Kick 1.3 ('src/sources/whdload/kick13.s') a jeden pre Kick 3.1 ('src/sources/whdload/kick31.s'). Tieto balíčky vyžadujú originálny kickstart ROM súbor a vytvoria kompletné OS prostredie vo vnútri WHDLoad. Pre viac informácií si prečítajte priložené ReadMe.

### Obvyklé problémy s kompatibilitou

#### Obmedzený adresný priestor na 68000/68010/68ec020 procesoroch

Na týchto procesoroch je adresný priestor limitovaný na 16 MB (`$000000...$ffffff`), pretože tieto procesory majú len 24 adresných riadkov. Následkom toho všetky prístupy na vyššie adresy sú vykonané na nižších 16 MB ignorovaním väčšiny signifikantných 8 bitov. Niektoré programy používajú tieto bity na ukladanie dát alebo ich jednoducho zabudnú vyčistiť. Na procesoroch s plným 4 GB adresovaním (68020/680ec30/68030/68040/68060) toto nebude fungovať, pretože je sprístupnené plné 32 bitové adresovanie. Na vyriešenie tohto problému treba upraviť tieto prístupy a presmerovať ich na príslušnú adresu. Niekedy príčina pristupovania na zvláštne adresy môže byť neinicializovaním pointeru. V tomto prípade môže pomôcť vyčistenie `$400` - ws_BaseMemSize.

#### Odlišné stackframes na každom CPU

Stackframes tvorené CPU prerušeniami a výnimkami sa u jednotlivých CPU líšia. Na 68000 je stackframe 6 bajtov, okrem zbernicových a adresových chýb. Stackframe obsahuje hodnotu SR na (a7) a hodnotu PC na (2,a7). Na ostatných CPU je minimálny stackframe 8 bajtov a dodatočne obsahuje číslo vektoru ako word na (6,a7). Tento štvorwordový formát stackframu je vytvorený pre "Trap #xx" a prerušenie na 68010-68060. Stackframes pre ostatné výnimky sú na každom procesore iné. Inštrukcia RTE funguje inak na 68000 a inak na 68010+. Na 68000 vracia hodnotu do SR a potom sa vracia na správnu adresu, zatiaľ čo na 68010+ naviac uvoľní stackframe podľa adekvátneho stackframe formátu.
Niektoré programy posunú adresu a hodnotu SR a potom vykonajú RTE. Takto to ale funguje len na 68000, na iných CPU to má katastrofálne účinky. Ak sa o to program pokúša, musíte to opraviť. Niekedy stačí nahradiť RTE s RTR.

#### MOVEM.x RL,-(An) na 68000/010 a 68020/030/040

Je rozdiel, ak register použitý v predecrement móde je tiež obsiahnutý v zozname registrov. Pre 68020, 68030 a 68040 je hodnota zapísaná do pamäti počiatočnou hodnotou registru znížená o rozsah operácie. 68000 a 68010 zapisujú počiatočnú hodnotu registru (nezníženú).
Keďže takáto konštrukcia nie je veľmi užitočná, nie je známy žiaden súčasný software, ktorý by mal kvôli tomu problémy.

### Hlavné zásady pri vytváraní inštalačiek

- Na novších CPU nemodifikujte CPU registre napr. VBR a CACR. Z programátorského pohľadu je VBR vždy na 0, i keď je presunuté, pretože autovektory (a TRAPs, ak je voľba WHDL_EmulTrap zapnutá) sú emulované. Bity v CACR sa líšia u každého CPU. Je len jeden správny spôsob ako modifikovať caches: použite funkcie resload_SetCACR/SetCPU a bitdef hodnoty z 'exec/execbase.i' a 'whdload.i'. Tiež všetok kód v programe, ktorý mení tieto registre, musí byť odstránený alebo vynechaný.
- Nikdy nemodifikujte disk image, pretože ak by niekto chcel spustiť program z diskety, stačí mu len zapísať image späť na disk (za predpokladu, že program beží z diskety i bez rôznych opráv, čo nie je veľmi častý prípad).
- Nikdy nepoužívajte originálny kód z programu priamo vo Slave (copyright problém).
- Zapnite caches len ak ste si istý, že to bude fungovať na všetkých procesoroch.
- Používajte čo najmenej pamäte pre ws_BaseMemSize. Niektorí ľudia majú rezidentné tagy na konci Chip RAM, takže pomáha ak použijete len $1f0000 namiesto $200000 a WHDLoad môže použiť absolútnu alokovanú pamäť.

### Tipy a triky

#### Čo je lepšie, používanie diskových obrazov alebo súborov?

Niekedy si musíte vybrať, či použiť obraz diskety alebo reálne súbory. Oba spôsoby majú svoje výhody. Použitie obrazu je väčšinou ľahší a rýchlejší spôsob ako vytvoriť Slave. Na druhú stranu, reálne súbory sa ľahšie ukladajú do cache (ak je napr. málo pamäte alebo pamäť je fragmentovaná). Potrebné miesto na harddisku bude menšie pri použití reálnych súborov ako pri použití obrazov. Diskové obrazy by ste mali použiť vtedy, ak zdroj obsahuje väčšie množstvo súborov (viac než 30).