Programmere WHDLoad

### Schematisk execution flow

Den følgende tabel viser program forløbet når et WHDLoad installeret program bliver eksekveret. Jeg håber det hjælper til at forstå hvordan WHDLoad fungerer og hvordan WHDLoad, Slaven og det installerede program samarbejder.

BRUGEREN

- Starter demoen eller spillet ved at klikke på et ikon eller ved at starte WHDLoad via kommogo linien.

Operativ Systemet

- loader den eksekverbare WHDLoad og starter den

WHDLoad

- kontrollerer software og hardware miljøet
- loader og kontrollerer Slaven
- allokerer den nødvendige hukommelse for det installerede program
- hvis Preload/S er slået til loader den disk image'erne og filer ind i RAM'en (så længe der er ledig hukommelse)
- lukker OS'et ned (slår mutitasking og interrupts fra, degraderer graphik hardware til OCS, initialiserer al hardware med definerede værdier)
- hopper ind i Slaven

Slaven

- loader det installerede programs hoved programmeved at kalde en WHDLoad funktion (f.eks. resload_DiskLoad eller resload_LoadFile)
- patcher hovedprogrammet (så programmet vil loade dets data via Slaven, for at fikse kompatibilitets problemer, for at klargøre programmets afslutning)
- kalder hovedprogrammet

Installerede programmer

- vil gøre følgende
- når det loader data fra disken vil det kalde Slaven (fordi Slaven tidligere har patchet det sådan), og Slaven vil kalde WHDLoad, og WHDLoad vil delvist slå OS'et til at loade data (kun hvis data ikke er Preload'ed), så returner, returner og det installerede program fortsætter

Brugeren

- afslutter programmet ved at trykke QuitKey

Slave

- returner til WHDLoad ved at kalde resload_Abort

WHDLoad

- slår OS'et til igen (genskaber hardware registre, display og hukommelse)
- frigiver alle allokerede ressourcer
- returnerer til OS'et

### Sådan installeres en simpel en disks trackloader

Dette er en meget kort step by step guide til hvordan man laver en install ved hjælp af WHDLoad. Guiden reflekterer et simpelt eksempel. I den virkelige verden vil sådan et eksempel højst sogsynligt aldrig opstå. For specialle eksempler og problemer læs kapitlerne efter dette.

1. Forberedelse
   - Lav en folder der skal indeholde alle filerne.
   - Generer et disk image ved hjælp af DIC i denne folder.
   - Generer en #?.info fil med "WHDLoad" som <Default Tool> og en Tooltype "SLAVE=#?" der indeholder navnet på slaven. (eller kopier blot ikonet fra et install eksempel, og slå alle tooltypes fra undtagen "SLAVE=").
2. Slaven
   For at skrive slaven skal vi bruge følgende information:
   1. Hvor på disken ligger hoved applikationen?
   2. Hvor i hoved applikationen ligger disk loaderen ?
   For at få denne information må vi først analysere bootblocken. For det meste vil hoved applikationen blive loaded herfra via exec.DoIO(). Nogle gange vil der være en speciel trackloader i bootblocken. Vi skriver nu en Slave der vil simulere bootblocken og loade hoved applikationen fra disk imaget. Nu ripper vi hoved applikationen fra imaget eller et memory dump. Efter dette er vi nødt til at finde loaderen i hoved applikationen. En hurtig måde at gøre dette på er at søge efter mønsteret `$AAAAAAAA` (bruges af MFM decoding) med en hex-editor. Klip det fundne området ud (+/- `$1000` bytes), disassemble det, og søg efter starten af rutinen. Forstå parameterlisten. Nu skal vi lave koden til den Slave som vil patche denne loader rutine på en måde så alle kald redirigeres til Slaven. Slaven vil så indstille alle parametre og kalde WHDLoad funktionen resload_DiskLoad.
3. I det ideelle eksempel er installeren nu færdig.
   Det sidste der mangler at blive gjort nu er at lave et flot ikon. Rip to billeder ved hjælp af WHDLoads snoop feature og SP eller en freezer eller U.A.E. og byg ikonet. Det anbefales at bruge 16 farvers paletten RomIcon.

### Mulige problemer og specielle eksempler

#### ikke stogard trackloader

Nogle programmer bruger deres eget disk format. Dette betyder at DIC ikke er istog til at lave disk images. For at lave filer eller images fra sådanne diske anbefales det at bruge RawDIC. Se dokumentatione for RawDIC for mere information.

#### Flere disks

Hvis programmet bruger mere end én disk må Slaven redirigere disk adgangen til den rigtige image fil. Dette er ikke altid lige nemt. Nogle programmer understøtter mere end et drev så du kan bruge drev nummeret til at vælge disken. De fleste programmer bruger et ID på hver disk til at adskille dem. I dette tilfælde kan du bruge en variabel der holder disk nummeret og ved hver tilgang til disk ID'et (find sådan en adgang ved at analysere parametrene for disk loaderen) øg variablen (hvis den sidste disk nås så træk fra). Så vil loaderen forhåbentlig læse ID'et igen og igen indtil den korrekte disk bliver sat i. Måske er der et anmodning til brugeren om at indsætte den rigtige disk, slå den fra.

#### Gemme highscores

Der er ikke meget at sige her. Brug resload_SaveFile til at skrive til det rigtige hukommelses område på disken. Hvis du vil kan du encrypte det så lamers ikke så nemt kan patche det. Det anbefales ikke at skrive direkte ind i et disk image (ved brug af resload_SaveFileOffset), for hvis noget går galt (f.eks. et crash) er det muligt at imaget vil blive beskadiget.

#### Savegames

Håndtering af savegames sker på samme måde som highscores.

#### Adgang til Operativ systemet

På det tidspunkt hvor Slaven og det instalerede program bliver eksekveret eksisterer der absolut intet OS, ingen tilgang til OS eller giver nogen mening at tilgå OS'et! Derfor må al tilgang som det installerede program forsøger slås fra. Hvis der ikke er mange af dem eller de ikke giver nogen mening i WHDLoad miljøet (som f.eks. exec.Disable() eller exec.SuperState()) kan du bare NOP (`$4e71`) dem. Hvis adgangen har en vigtig funktion (som exec.DoIO()), så rediriger dem til Slaven og emulér dem. Hvis der er mange af dem så lav et simpelt exec.library i en ubrugt del af hukommelsen (initialisér longword i adressen `$4`). Du kan kontrollere kilden for Oscar.slaven, som emulerer exec.AllocMem(). For at detektere adgang til OS'et bliver den initialiserende execbase sat til `$f0000001` med henblik på at alle rutiner som kan lide at bruge execbasen vil lave en "Address Error" exception.
Hvis OS funktioner bruges intensivt så brug en af kickemu pakkerne som kan findes i whdload-dev pakken. Der er en pakke til Kick 1.3 ('src/sources/whdload/kick13.s') og en for Kick 3.1 ('src/sources/whdload/kick31.s'). Disse pakker kræver et originalt kickstart image og vil lave et komplet OS miljø inde i WHDLoad området. Læs også de tilhørende readme dokumenter for yderligere information.

### Generelle kompatibilitets problemer

#### Begrænset addresse plads på 68000/68010/68ec020

På disse processorer er adresse området begrænset til 16 MB (`$000000...$ffffff`) fordi disse CPU'er kun har 24 adresse linier. Et resultat heraf er at al adgang til højere adresser bliver udført på de første 16 MB ve at ignorere de mest betydende 8 bits. Nogle programmer bruger disse bits til at gemme data, eller glemmer simpelthen at slette dem. På en processor med fuldt 4 GB adresse område såsom 68020/680ec30/68030/68040/68060 vil dette ikke virke, fordi den fulde 32-bit adresse vil blive tilgået.
For at løse dette må du patche disse tilgange og redirigere dem til den rigtige adresse.
Nogle gange kan grunden til tilgang til mærkelige adresser være en pointer der ikke er initialiseret. I dette tilfælde kan det hjælpe at slette `$400` - ws_BaseMemSize.

#### Forskellige stackframes på hver processor

De stackframes der laves ved interrupts og exceptions er forskellige for medlemmer af 68k familien. På 68000'ren er en stackframe 6 bytes, undtagen på Bus og Address Errors. Stackframes indeholder den gemte SR på (a7) og den gemte PC på (2,a7). På alle ogre processorer (68010+) er den minimale stackframe 8 bytes og indeholder yderligere vektor nummeret som et word ved (6,a7). Dette Four-Word stackframe format `$0` bliver genereret for Trap #xx" og Interrupts på 68010-68060. Ved ogre exceptions er stackframsene forskellige på hver processor. RTE instruktionerne fungerer forskelligt på 68000'eren mod 68010+. På en 68000 genskabes SR og PC ganske enkelt og fortsætter program eksekveringen på den interrupted addresse. På 68010+'eren vil den yderlige frigøre den stackframe der afhænger af stackframe formatet.
Nogle programmer pusher en adresse (PC) og en SR og eksekverer så en RTE instruktion. Dette fungerer kun på en 68000. På 68010+ vil dette resultere i udefinerbare resultater.
Hvis et program gør dette bliver du nødt til at rette dette. Nogle gange vil det være nok at erstatte RTE'en med en RTR.

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

Der er en forskel hvis registret der bruges i predecrement mode (RL) også bruges i listen. For 68020, 68030 og 68040'ren er værdien der skrives til hukkommelsen den initielle register værdi minus størrelsen på operationen. 68000 og 68010'ren skriver den initielle register værdi (uden at trække noget fra).
Fordi sådan en konstruktion ikke er særlig brugbar kendes der ikke til nogen software der har problemer med dette.

### Generelle guidelines for at skrive installationer

- Modificer ikke CPU registrene i højere processor såsom VBR eller CACR. VBR'en er altid 0 fra Slave programmørens syn, selv hvis den flyttes pga. Auto Vectors (og Traps hvis Flaget WHDL_EmulTrap er sat) er emuleret. Bitsene in CACRen er forskellige for hver processor. Der er kun en måde ændre cachene, brug resload_SetCACR/SetCPU og bitdef'sene fra 'exec/execbase.i' og 'whdload.i'. Derudover må alt i programmet der skal installeres der bruges til at tilgå disse registre slås fra eller skippes. Ellers kan WHDLoad ikke fungere korrekt!
- Modificer aldrig disk images. Dette har den fordel at hvis nogen skulle ønske at starte programmet fra en floppy disk skal han kun skrive imagesne tilbage til en disk (forudsat at programmet kører uden mange fixes, helt klart ikke det mest forekommende).
- Brug aldrig originale ting fra programmet direkte i Slaven (copyright problem).
- Slå kun Caches til hvis du er sikker på at det virker på alle processorer.
- Brug så lidt hukommelse som muligt til ws_BaseMemSize. Nogle mennesker har faste tags i slutningen af Chip hukommelsen, så det hjælper kun at bruge `$1f0000` istedet for `$200000` og WHDLoad kan bruge absolut allokeret hukommelse.

### Tips & tricks

#### Er det bedst at bruge disk images eller files ?

Nogle gange vil du have mulighed for at bruge disk images eller rigtige filer. Begge dele har sine fordele. Brugen af disk images er oftest det nemmeste og den hurtigste vej til at lave Slaven. Men rigtige filer er nemmere at cache (hvis der er meget lidt hukommelse eller hukommelsen er fragmenteret). Pladsen der behøves på hardisken bliver også mindre med rigtige filer end med disk images. Du bør kun bruge disk images hvis der er mange filer (flere end 30).