WHDLoadin ohjelmointi

### Suorituksen virtauskaavio

Seuraavassa taulukossa esitetään ohjelman kulku, kun WHDLoadilla asennettu ohjelma suoritetaan. Toivon, että se auttaa ymmärtämään, miten WHDLoad toimii ja kuinka WHDLoad, Slave ja asennettu ohjelma toimivat yhdessä.

KÄYTTÄJÄ

- käynnistää demon tai pelin napsauttamalla kuvaketta tai käynnistämällä WHDLoadin komentoriviltä

Käyttöjärjestelmä

- lataa WHDLoad-ohjelman ja käynnistää sen

WHDLoad

- tarkistaa ohjelmisto- ja laitteistoympäristön
- lataa ja tarkistaa Slaven
- varaa asennetulle ohjelmalle vaaditun muistimäärän
- jos Preload/S on käytössä, lataa levynkuvia ja tiedostoja RAM-muistiin (niin kauan kuin vapaata muistia riittää)
- kytkee käyttöjärjestelmän pois (sammuttaa moniajon ja keskeytykset, alentaa grafiikkalaitteiston OCS-tasolle, alustaa kaiken laitteiston määritetyillä arvoilla)
- siirtyy Slaveen

Slave

- lataa asennetun ohjelman suoritettavan osan kutsumalla WHDLoad-funktiota (esim. resload_DiskLoad tai resload_LoadFile)
- päivittää suoritettavan osan (jotta ohjelma lataa tiedot Slaven kautta, korjaa yhteensopivuusongelmat, mahdollistaa poistumisen ohjelmasta)
- kutsuu suoritettavaa osaa

Asennettu ohjelma

- tekee mitä tekee
- ladatessaan tietoa levyltä se kutsuu Slavea (koska Slave on päivittänyt sen näin aiemmin) ja Slave kutsuu WHDLoadia, jolloin WHDLoad ottaa osan käyttöjärjestelmää käyttöön tiedon lataamiseksi (vain jos Preload ei ole käytössä) ja palaa takaisin, jolloin asennettu ohjelma jatkuu

KÄYTTÄJÄ

- poistuu ohjelmasta QuitKey -näppäimellä

Slave

- palaa WHDLoadiin kutsumalla funktiota resload_Abort

WHDLoad

- ottaa käyttöjärjestelmän uudelleen käyttöön (palauttaa laitteistorekisterit, näytön ja muistin)
- vapauttaa varatut resurssit
- palaa käyttöjärjestelmään

### Miten asennetaan yksinkertainen, yhden levyn trackloader

Tämä on hyvin pieni ja lyhyt vaiheittainen opas asennusohjelman luontiin WHDLoadilla. Opas kuvaa ihanteellista, yksinkertaista tapausta. Tosielämässä tällaista tapausta tuskin koskaan esiintyy. Erityistapaustan ja ongelmien varalta lue tätä seuraavat kappaleet.

1. Esityö
   - Tee kansio, johon kaikki tiedostot tallennetaan.
   - Luo tähän kansioon levynkuva DIC -ohjelmalla.
   - Luo #?.info-tiedosto, jonka <Default Tool> on "WHDLoad" ja Tooltype "SLAVE=#?" sisältää slave-tiedoston nimen. (tai kopioi kuvake esimerkistä ja poista kaikki tooltypet paitsi "SLAVE=").
2. Slave
   Slave-tiedoston kirjoittamiseen tarvitaan seuraavat tiedot:
   1. Missä suoritettava ohjelma on levyllä?
   2. Missä kohtaa suoritettavaa ohjelmaa levylataaja on?
   Tämän tiedon saamiseksi analysoimme ensin käynnistyslohkoa. Useimmiten suoritettava ohjelma ladataan täältä käskyllä exec.DoIO(). Joskus käynnistyslohkolla on erityinen trackloader. Kirjoitamme Slaven, joka simuloi käynnistyslohkoa ja lataa suoritettavan ohjelman levynkuvasta. Tallennamme suoritettavan ohjelman levynkuvasta tai muistidumpista. Tämän jälkeen on löydettävä latausrutiini. Nopea tapa on etsiä merkkijonoa `$AAAAAAAA` (jota käytetään MFM-dekoodaukseen) heksaeditorilla. Leikkaa sitten löydetty alue (+/- `$1000` tavut) pura se ja etsi rutiinin alku. Ymmärrä parametrien luettelo. Nyt luomme Slavelle koodin, joka päivittää latausrutiinin niin, että latausrutiinin kutsut ohjataan uudelleen Slavelle. Slave säätää parametrit ja kutsuu WHDLoad-funktiota resload_DiskLoad.
3. Ihannetapauksessa asennusohjelma on nyt valmis.
   Jäljellä on vain mukavan kuvakkeen tekeminen. Nappaa kaksi kuvaa WHDLoadin snoop-toiminnolla ja SP:llä tai jäädytysohjelmalla tai UAE:llä ja luo kuvake. Suositus on 16 värin RomIcon-paletti.

### Mahdolliset ongelmat ja erikoistapaukset

#### Epästandardi trackloader

Jotkin ohjelmat käyttävät aivan omaa levyformaattiaan. Tämä tarkoittaa, ettäDIC ei voi luoda levynkuvia. Tiedostojen tai levynkuvien luontiin suositellaan RawDIC-ohjelmaa. Lisätietoja on RawDIC-ohjeessa.

#### Useat levyt

Jos ohjelmassa on useampi levyke, slaven tulee ohjata levynkäyttö oikeaan levynkuvatiedostoon. Tämä ei ole aina helppoa. Jotkin ohjelmat tukevat useampaa levyasemaa, jolloin voit käyttää levyn valintaan aseman numeroa. Useimmat ohjelmat käyttävät kullakin levyllä tunnusta, jolla ne erotetaan. Tässä tapauksessa käytä muuttujaa, jossa on levyn numero, ja joka kerta kun levyn tunnusta käytetään (määritä se analysoimalla latausrutiinin parametreja) lisää muuttujan arvoa (viimeisellä levyllä vähennä sitä). Näin latausohjelma toivottavasti lukee tunnusta uudestaan ja uudestaan kunnes oikea levy syötetään. Mikäli ohjelmassa on käyttäjälle pyyntö syöttää oikea levy, kytke se pois.

#### Tulosten tallennus

Tästä ei ole paljon sanottavaa. Kirjoita oikea muistialue levylle resload_SaveFile-funktiolla. Halutessasi voit salakirjoittaa sitä hieman, jolloin lamerit eivät pääse liian helposti muuttelemaan sitä. Ei kannata kirjoittaa suoraan levynkuviin (funktiolla resload_SaveFileOffset), koska jos jokin menee pieleen (esim. kaatuminen), levynkuvat voivat vioittua.

#### Pelitallennukset

Pelitallennuksia käsitellään kuten tuloksia.

#### Käyttöjärjestelmäkutsut

Slaven ja asennetun ohjelman suorituksen aikana käyttöjärjestelmää ei ole, eikä sitä voi käyttää, eikä sen käytössä ole mitään järkeä! Siksi kaikki asennetun ohjelman kutsut tulee estää. Jos niitä ei ole monia, eikä niissä ole järkeä WHDLoad-ympäristössä (kuten exec.Disable() tai exec.SuperState()), korvaa ne vain NOP:lla (`$4e71`). Jos kutsuilla on tärkeä toiminto (kuten exec.DoIO()), ohjaa ne Slaveen ja emuloi ne. Jos niitä on paljon, luo yksinkertainen exec.library käyttämättömälle muistialueelle (alusta longword osoitteessa `$4`). Voit katsoa Oscar.slave:n lähdekoodia, jossa emuloidaan exec.AllocMem(). Käyttöjärjestelmäkutsujen tunnistamiseksi execbasen arvo on aluksi `$f0000001`, minkä tarkoitus on, että kaikki execbasea käyttävät ru tiinit synnyttävät "Address Error" -poikkeuksen.
Jos käyttöjärjestelmäfunktioita käytetään runsaasti, käytä kickemu-paketteja jotka ovat whdload-dev -paketissa. Omat pakettinsa on Kick 1.3:lle ('src/sources/whdload/kick13.s') ja Kick 3.1:lle ('src/sources/whdload/kick31.s'). Nämä paketit vaativat alkuperäisen kickstart-muistinkuvan ja luovat täydellisen käyttöjärjestelmäympäristön WHDLoadin sisään. Katso lisätietoja myös mukana tulevasta readme-tiedostosta.

### Yleisiä yhteensopivuusongelmia

#### Rajoitettu osoiteavaruus 68000/68010/68ec020:ssa

Näissä suorittimissa osoiteavaruus on rajoitettu 16 megatavuun (`$000000...$ffffff`), koska suorittimissa on vain 24 osoitelinjaa. Tämän tuloksena korkeampien osoitteiden käyttö tehdään alempaan 16 megatavuun ohittamalla merkittävimmät 8 bittiä. Jotkut ohjelmat käyttävät bittejä tallentamaan tietoa tai unohtavat vain tyhjentää ne. Jos prosessorin muistiavaruus on täydet 4 gigatavua, kuten 68020/680ec30/68030/68040/68060:llä, tämä ei toimi, koska täyttä 32-bittistä osoitetta käytetään.
Tämän ratkaisemiseksi nämä kutsut tulee korjata ja ohjata ne sopivaan osoitteeseen.
Joskus outoihin osoitteisiin tehtävien kutsujen syynä voi olla alustamaton osoitin. Tässä tapauksessa saattaa kannattaa tyhjentää `$400` - ws_BaseMemSize.

#### Eri pinokehykset kullakin suorittimella

Suorittimen luomat pinokehykset keskeytyksissä ja poikkeuksissa ovat erilaiset 68k-perheen jäsenille. 68000:lla pinokehys on 6 tavua, paitsi väylä- ja osoitevirheissä. Pinokehys sisältää tallennetun SR:n osoitteessa (a7) ja tallennetun PC:n osoitteessa (2,a7). Kaikilla muilla suorittimilla (68010+) pinokehyksen minimi on 8 tavua ja se sisältää lisäksi vektorin numeron sanana osoitteessa (6,a7). Tämä neljän sanan pinokehysmuoto `$0` tehdään 68010-680060:lla trapille #xx ja keskeytyksille. Muiden poikkeusten pinokehykset eroavat kullakin prosessorilla. RTE-käsky toimii eri tavoin 68000:lla ja 68010+:lla. 68000:lla se palauttaa SR:n ja PC:n ja jatkaa ohjelman suoritusta keskeytetystä osoitteesta. 68010+:lla se vapauttaa lisäksi pinokehyksen riippuen sen muodosta.
Jotkin ohjelmat pushaavat osoitteen (PC) ja SR:n ja suorittavat sitten RTE-käskyn. Tämä toimii vain 68 000:lla, 68010+:lla tulokset ovat epämääräisiä.
Jos ohjelma tekee näin, se on korjattava. Joskus riittää, kun RTE:n korjaa RTR:llä.

#### MOVEM.x RL,-(An) 68000/010:lla ja 68020/030/040:lla

Tässä on eroa sen mukaan, onko ennen vähennystä käytetty rekisteri (RL) myös rekisteriluettelossa. 68020:llä, 68030:llä ja 68040:llä muistiin kirjoitettu arvo on rekisterin alkuarvo vähennettynä operaation koolla. 68000 ja 68010 kirjoittavat rekisterin alkuarvon (ilman vähennystä).
Koska tällainen rakenne ei ole kovin käyttökelpoinen, ei olemassa olevan ohjelmiston tiedetä sisältävän tästä johtuvia ongelmia.

### Yleisohjeita asennusohjelmien kirjoitukseen

- Älä muokkaa suoritinrekistereitä, jotka ovat käytössä uudemmissa suorittimissa, kuten VBR:ää tai CACR:ää. VBR on Slaven ohjelmoijan näkökulmasta aina 0, vaikka sitä siirrettäisiin autovektorien (ja trapien, jos WHDL_EmulTrap -lippu on asetettu) emuloinnin vuoksi. CACR:n bitit ovat erilaiset jokaiselle suorittimelle. Välimuistien käyttöön on vain yksi kelvollinen tapa. Käytä funktiota resload_SetCACR/SetCPU sekä 'exec/execbase.i':n ja 'whdload.i':n bitdefejä. Myös kaikki ohjelman osat, jotka kuormittavat näitä rekistereitä on kytkettävä pois tai ohitettava, sillä WHDLoad ei voi muuten toimia oikein!
- Älä muokkaa levynkuvia. Tällä on se etu, että jos joku haluaa käynnistää ohjelman levykkeeltä, tulee vain kirjoittaa kuva takaisin levylle (olettaen, että ohjelma toimii ilman korjauksia, mitä tuskin usein tapahtuu).
- Älä käytä ohjelman alkuperäisiä osia suoraan slavessa (tekijänoikeussyistä).
- Ota välimuistit käyttöön vain, jos olet varma, että se toimii kaikilla suorittimilla.
- Käytä mahdollisimman vähän muistia ws_BaseMemSize-arvona. Joillakin on muistinvaraisia koodeja Chip-muistin lopussa, joten kannattaa käyttää vain `$1f0000` `$200000`:n sijaan, ja WHDLoad voi käyttää absoluuttista varattua muistia.

### Vinkkejä ja jippoja

#### Kumpi on parempi, levynkuvien vai tiedostojen käyttö?

Joskus voit käyttää joko levynkuvia tai oikeita tiedostoja. Molemmissa on etunsa. Levynkuvat ovat yleensä helpompi ja nopeampi tapa kirjoittaa Slave. Toisaalta oikeat tiedostot on helpompi kopioida välimuistiin (jos muistia on vähän tai se on pirstoutunut). Kiintolevyltä tarvittava tila on myös pienempi oikeilla tiedostoilla kuin levynkuvilla. Käytä levynkuvia vain, jos tiedostoja on paljon (yli 30).