Programmere WHDLoad

### Skjematisk kjøreflyt

Den følgende tabellen viser programflyten når et WHDLoad-installert program kjøres. Jeg håper den hjelper til med å skjønne hvordan WHDLoad virker, og hvordan WHDLoad, Slaven og det installerte programmet samarbeider.

BRUKEREN

- starter demoen eller spillet ved å klikke et Ikon eller ved å starte WHDLoad via kommandolinjen

Operativsystemet

- laster WHDLoads kjørefil og starter den

WHDLoad

- kontrollerer programvaren og maskinvare-miljøet
- laster og kontrollerer Slaven
- tildeler nødvendig minne til det installerte programmet
- hvis Preload/S er satt på, lastes diskbilder og filer inn i RAM (så langt ledig minne rekker)
- slår av OS (stenger for multitasking og avbrudd, degraderer grafisk maskinvare til OCS, setter all maskinvare til definerte verdier)
- hopper til Slaven

Slave

- laster hoved-kjørefilen til det installerte programmet ved å kalle en WHDLoad-funksjon (f.eks resload_DiskLoad eller resload_LoadFile)
- oppdaterer kjørefilen (slik at programmet laster data via Slaven, fikser kompatibilitetsproblemer, muliggjør avslutning av programmet)
- kjører hovedkjørefilen

Installert program

- gjør sine ting
- ved lasting av data fra disk vil den kalle Slaven (fordi Slaven har oppdatert den for dette), og Slaven vil kalle opp WHDLoad, og WHDLoad vil delvis tillate OS å laste dataene (hvis ikke dataene er Preload-et), så retur, retur og det installerte programmet fortsetter

BRUKEREN

- avslutter programmet ved å trykke QuitKey

Slaven

- returnerer til WHDLoad ved å kalle resload_Abort

WHDLoad

- slår på OS igjen (tilbakestiller maskinvare-registre, skjerm og minne)
- frigjør alle tildelte ressurser
- returnerer til OS'et

### Hvordan installere en enkel en-disketts sporlaster

Dette er en veldig liten og kort steg for steg guide for hvordan lage en installerer med WHDLoad. Guiden reflekterer et ideelt, enkelt tilfelle. I den virkelige verden vil sannsynligvis et slikt tilfelle ikke forekomme. For spesielle tilfeller og problemer, les de påfølgende kapitlene.

1. Forarbeid
   - Lag en skuff som skal inneholde alle filer.
   - Lag et disbilde med DIC ii denne skuffen.
   - Lag en #?.info-fil med "WHDLoad" som <Default Tool> og en Tooltype "SLAVE=#?" som inneholder navnet på Slaven. (eller rett og slett kopier ikonet fra en Eksempelinstallering, og slå av alle tooltyper unntatt "SLAVE=").
2. Slaven
   For å skrive slaven trenger vi følgende informasjon:
   1. Hvor på disken finnes hovedkjørefilen?
   2. Hvor i hovedkjørefilen finnes disklasteren?
   For å få denne informasjonen må vi først analysere startblokken. Stort sett vil hovedkjørefilen lastes herfra via exec.DoIO(). Noen ganger ligger det en spesiell sporlaster i startblokken. Nå skriver vi en Slave som simulerer startblokken og laster hovedkjørefilen fra diskbildet. Så trekker vi ut hovedkjørefilen fra bildet eller en memory dump. Etter dette må vi finne lasteren i kjørefilen. En rask metode er å søke etter mønsteret `$AAAAAAAA` (brukt av MFM dekoding) med en hex-redigerer. Så klippes området ut (+/- `$1000` byte), disassembler den, og søker etter starten av rutinen. Forstå parameterlisten. Nå lager vi en kode for Slaven som oppdaterer denne lasterutinen slik at alle kall til lasteren blir omdirigert til Slaven. Slaven vil så tilpasse parameterene og kalle opp WHDLoad-funksjonen resload_DiskLoad.
3. I det ideelle tilfellet er installeren nå ferdig.
   Det eneste som gjenstår er å lage et pent Ikon. Trekk ut to bilder ved å bruke søkefunksjonen i WHDLoad og SP eller en fryser eller U.A.E. og bygg ikonet. 16-fargers RomIcon-palett anbefales.

### Mulige problemer og spesialtilfeller

#### Ikke-standard spor-laster

Noen programmer har sitt eget diskett-format. Dette betyr at DIC ikke er i stand til å lage diskbildene. For å lage filer eller bilder fra slike disketter anbefales RawDIC. Les dokumentasjonen for RawDIC for mer informasjon.

#### Flere disketter

Hvis programmet bruker mere enn en diskett må slaven omdirigere diskett-tilgangen til det passende diskbildet. Av og til er ikke dette så lett. Noen programmer støtter mere enn en stasjon, så man kan bruke stasjonsnummeret for valg av diskett. De fleste programmer benytter en ID på hver diskett for å skille dem. I dette tilfellet, bruk en variabel som inneholder diskettnummeret, og ved hvertilgang til diskett-ID'en (avgjør en slik tilgang ved å analysere parameterene til disklasteren) øk variabelen (hvis siste diskett er nådd, reduser variabelen). Så håper man at lasteren vil lese diskett-ID'en om og om igjen til den riktige disketten finnes. Kanskje det er en forespørsel fra programmet om at brukeren må sette inn riktig diskett, isåfall slå den av.

#### Highscore-lagring

Ikke så mye å si her. Bruk resload_SaveFile for å skrive det passende minneområdet til disk. Hvis man vil, krypter det litt så lamere ikke tukler for lett med det. Det anbefales ikke å skrive direkte til diskbilder (med resload_SaveFileOffset), for hvis noe går galt (f.eks. en kræsj) er det mulig at bildene blir ødelagt.

#### Lagrede spill (savegames)

Håndter lagring av spill på samme måte som highscore.

#### Tilgang til operativsystemet

Når slaven og det installerte programmet kjøres, eksisterer absolutt ikke noe OS, og det gir absolutt ingen mening å få tilgang til OS'et. Derfor må alle forsøk på tilgang fra det installerte programmet slås av. Hvis det ikke er for mange av dem, og de ikke gir mening i WHDLoad-miljøet (som exec.Disable() eller exec.SuperState()) rett og slett NOP (`$4e71`) dem. Hvis tilgangene har en viktig funksjon (som exec.DoIO()), omdiriger dem til Slaven og emuler dem. Hvis det er mange av dem, lag en enkel exec.library i et ubrukt minneområde emulate them. If there are loads of them, create a simple exec.library in an (initialiser longword ved addresse `$4`). Du kan sjekke kilden til Oscar.slave, som emulerer exec.AllocMem(). For å oppdage tilganger til OS'et, settes den initielle execbase `$f0000001` med den intensjon at alle rutiner som liker å bruke execbase lager er "Address Error"-unntak.
Hvis det er tung bruk av OS-funksjoner, bruk en av kickemu-pakkene som finnes i whdload-dev pakken. Det er en pakke for Kick 1.3 ('src/sources/whdload/kick13.s') og en for Kick 3.1 ('src/sources/whdload/kick31.s'). Disse pakkene krever et originalt kickstart-bilde og vil lage et komplett OS-miljø inne i WHDLoad. Konsulter også de relevante medfølgende readme-filene for mer informasjon.

### Vanlige kompatibilitetsproblemer

#### Begrenset addresseplass på 68000/68010/68ec020

På disse prosessorene er addresseplassen begrenset til 16 MB (`$000000...$ffffff`) siden disse CPU'ene bare har 24 adresselinjer. Et resultat av dette er at all tilgang til høyere adresser skjer på de lavere 16 MB ved å ignorere de mest signifikante 8 bit'er. Noen programmer bruker disse bit'ene til å lagre data, eller glemmer rett og slett å tømme dem. På en prosessor med full 4 GB adresseplass som 68020/680ec30/68030/68040/68060 vil ikke dette virke, fordi de fullstendige 32-bits addressene vil få tilgang.
For å løse dette må man fikse alle disse tilgangene og omdirigere dem til passende adresser.
Noen ganger kan grunnen til tilgang til merkelige adresser være en ikke-initialisert peker. I så tilfelfelle kan det hjelpe å tømme `$400` - ws_BaseMemSize.

#### Forskjellige stakkrammer (stackframes) på hver prosessor

Stakkrammene som lages av prosessorer ved avbrudd og unntak er forskjellige for medlemmene av 68k-familien. På en 68000 er stakkrammen 6 byte, bortsett ved buss- og adressefeil. Stakkrammen inneholder den lagrede SR ved (a7) og den lagrede PC ved (2,a7). På alle andre prosessorer (68010+) er minste stakkramme 8 byte og inneholder i tillegg vektornummeret som et word ved (6,a7). Dette fire-word stakkrammeformatet `$0` er laget for "Trap #xx" og avbrudd på 68010-68060. Stakkrammene for andre unntak er forskjellige på hver prosessor. RTE-instruksjonen virker forskjellig på 68000 mot 68010+. På en 68000 tilbakekaller den bare SR og PC og fortsetter programkjøringen ved den avbrutte adressen. På en 68010+ vil den i tillegg frigjøre stakkrammen avhengig av stakkrammeformat.
Noen programmer dytter (push) en adresse (PC) og en SR og kjører sp en RTE-instruksjon. Dette virker bare på en 68000, på en 68010+ vil dette ha uforutsigbare resultater.
Hvis et program gjør dette, må man fikse dette. Noen ganger er det nok å erstatte RTE'en med en RTR.

#### MOVEM.x RL,-(An) på 68000/010 og 68020/030/040

Det er en forskjell på om registeret brukt i førreduseringsmodus (RL) også finnes i registerlisten. For 68020, 68030 og 68040 er verdien skrevet i minne den initielle registerverdien redusert med størrelsen på operasjonen. 68000 og 68010 skriver initiell registerverdi (uredusert)
Siden slik konstruksjon ikke er særlig nyttig er det ingen nåværende programvare som er kjent med å ha problemer med dette.

### Generelle retningslinjer for å skrive installerere

- Ikke endre CPU-registre som finnes i høyere prosessorer som VBR eller CACR. VBR er alltid 0 fra Slaveprogrammererens synsvinkel, selv om det er flyttet fordi Autovektorer (og feller (Traps) hvis flagget WHDL_EmulTrap er satt) emuleres. Bit'ene i CACR'en er forskjellige for hver prosessor. Det er bare én gyldig måte å endre bufrene på, bruk resload_SetCACR/SetCPU og bitdef'ene fra 'exec/execbase.i' og 'whdload.i'. I tillegg må alle ting i programmet som installeres som bruker disse registrene slås av eller omgås, ellers vil ikke WHDLoad virke!
- Endre aldri på diskbildene. Dette har den fordelen at hvis noen ønsker å kjøre programmet fra diskett trenger man bare skrive bildet tilbake til disketten (forutsatt at programmet kjører uten diverse oppdateringer, stort sett ikke det vanligste tilfellet...)
- Bruk aldri originale ting fra programmet direkte i Slaven (kopirettighetsproblemer).
- Slå på bufre kun hvis du sikker på at det kjører på alle prosessorer.
- Bruk så lite minne som mulig for ws_BaseMemSize. Noen folk har informasjon (resident tags) på slutten av Chip-minnet, så det hjelper å bare bruke `$1f0000` istedet for `$200000` og WHDLoad kan bruke absolutt tildelt minne.

### Tips & triks

#### Hva er best, bruke diskbilder eller filer?

Noen ganger har man valget om å bruke diskbilder eller ekte filer. Begge valg har sine fordeler. Bruk av diskbilder er som oftest den enkleste og raskeste måten p lage Slaven. Men ekte filer bufres lettere (hvis det er veldig lite minne eller minnet er fragmentert). Nødvendig diskplass er også mindre med ektre filer enne med diskbilder. Man bør bare bruke diskbilder om det er mange filer (mer enn 30).