Programant WHDLoad

### Flux esquemàtic d'execució

La següent taula mostra el flux del programa quan un programa instal·lat amb WHDLoad és executat. Espero que ajudi a comprendre com treballa WHDLoad i com cooperen WHDLoad, l'Esclau i el programa instal·lat.

L'USUARI

- Arrenca la demo o el joc fent doble click en una icona o arrencant WHDLoad des de la línia de comandes

El Sistema Operatiu

- Carrega l'executable de WHDLoad i inicia la execució

WHDLoad

- Comprova l'entorn de programari (software) i maquinari (hardware)
- Carrega i comprova l'Esclau
- Assigna la memòria que requereix el programa instal.lat
- Si Preload/S està activat, carrega les imatges de disc i els fitxers en RAM (mentre hi hagi memòria lliure disponible)
- Commuta el S.O. cap a "apagat" (desactiva la multitasca i les interrupcions, degrada el maquinari de gràfics a OCS, inicialitza tot el maquinari amb els valors definits)
- Transfereix l'execució a l'Esclau

Esclau

- Carrega l'executable principal del programa instal.lat cridant una funció de WHDLoad (com resload_DiskLoad o resload_LoadFile)
- Aplica un patch a l'executable principal (per a que el programa carregui les seves dades utilitzant l'Esclau, per a solucionar problemes de compatibilitat i habilitar la funció de sortida des del programa)
- Transfereix l'execució al programa principal.

Programa Instal.lat

- Farà allò que li toqui fer
- En carregar dades des de disc, cridarà l'Esclau (donat que l' Esclau li ha aplicat un patch per a que ho faci prèviament), i l'Esclau cridarà WHDLoad que habilitarà parcialment l'S.O. per a carregar les dades (solament si la informació no ha estat Precarregada [Preload]), després retorna i el programa instal.lat continua.

L'USUARI

- Surt del programa prement la tecla de (Sortida)

Esclau

- retorna a WHDLoad cridant la funció resload_Abort

WHDLoad

- Reactiva el S.O. (restaura els registres de hardware, visualització i memòria)
- Llibera tots els recursos assignats
- Retorna al S.O.

### Com instal.lar un lector de pistes simple per a un disc

Aquesta és una petita guia pas a pas sobre com crear un instal·lador usant WHDLoad. La guia reflecteix un cas ideal simple. En el món real un cas com aquest probablement no es doni mai. Per a casos especials i problemes, llegeixi els capítols que segueixen a aquest.

1. Treball Previ
   - Crei un directori que contingui tots el fitxers.
   - Crei una imatge de disc emprant DIC en aquest directori.
   - Crei un arxiu #?.info amb "WHDLoad" com a <Default Tool> i una Tooltype "SLAVE=#?" que contingui el nom de l'Esclau. (O simplement copiï la icona des d'una Instal.lació d'Exemple, i desactivi tots els Tooltypes excepte "SLAVE=").
2. L'Esclau
   Per a escriure l'esclau necessitem la següent informació:
   1. On està ubicat l'executable principal dins del disc?
   2. On es troba el programa de càrrega des de disc dins de l'executable principal?
   Per a obtenir aquesta informació primer analitzarem el sector d'arrencada. La major part de les vegades l'executable principal serà carregat des d'allí usant exec.DoIO(). Algunes vegades un lector de pistes especial estarà al sector d'arrencada. Ara escriurem un Esclau que simuli el sector d'arrencada i carregui l'executable principal des de la imatge de disc. Després extraurem l'executable des de la imatge o un volcat de memòria (memory dump). Després d'això haurem de trobar el lector dins de l'executable principal. Una forma ràpida es buscar el patró `$AAAAAAAA` (que empra el decodificador MFM) amb un editor hexadecimal. Talli l'àrea trobada (+/- `$1000` bytes), realitzi un dessensamblatge i busqui l'inici de la rutina. Asseguri's de comprendre la llista de paràmetres. Ara crearem el codi per a l'Esclau que parxarà aquesta rutina de càrrega de tal forma que totes les crides al lector siguin redireccionades a l'Esclau. L'esclau ajustarà els paràmetres i cridarà la funció de WHDLoad resload_DiskLoad.
3. En el cas ideal que l'instal.lador estigui complert.
   L'únic que fa falta es crear una bonica icona. Pot extraure un parell d'imatges emprant la funcionalitat snoop de WHDLoad i SP o un capturador de pantalles o U.A.E. per a construir la icono. Es recomana la paleta RomIcon de 16 colors.

### Possibles problemes i casos especials

#### Lector de pistes no estàndar

Alguns programes utilitzen els seus propis formats de disc. Això significa que DIC no serà capaç de crear les imatges de disc. Per a crear arxius o o imatges des d'aquests discos es recomana l'ús de RawDIC. Vegi la documentació de RawDIC per a més informació.

#### Múltiples discos

Si el programa utilitza més d'un disc l'esclau ha de redireccionar els accessos a disc a l'arxiu d'imatge apropiat. Algunes vegades això no és senzill. Alguns programes suporten mes d'una unitat de discos, de tal forma que ha d'usar-se el número d'unitat per a seleccionar el disc. La majoria dels programes utilitzen un ID (identificador) en cada disc per a distingir-los. En aquest cas, utilitzi una variable que mantingui el número de disc, i en cada accés a l'ID de disc (determini tals accessos analitzant els paràmetres del lector de disc) incrementi la variable (si s'ha arribat a l'últim disc, decrementi-la). D'aquesta forma esperem que el lector llegirà l'ID una vegada i una altra fins que el disc correcte sigui inserit. Tal vegada hi hagi un quadre de diàleg del programa demanant el disc correcte, en aquest cas desactivi'l.

#### Guardant la taula de màximes puntuacions (highscores)

No hi ha massa a dir. Utilitzi resload_SaveFile per a escriure l'àrea de memòria apropiada al disc. Si ho desitja, encripti-la un poc perquè els perdedors no puguin modificar-la massa fàcilment. No es recomana escriure directament a les imatges de disc (emprant resload_SaveFileOffset) , atès que si alguna cosa surt malament (per ex. que es pengi el sistema) és possible que les imatges es facin malbé.

#### Guardant el joc en curs

S'ha de tractar de forma anàloga a la taula de màximes puntuacions.

#### Accessos al sistema operatiu

Des del moment que l'esclau i el programa instal·lat s'executen, no existirà absolutament cap S.O., ni serà accessible, ni tindrà cap sentit intentar accedir al mateix! Per tant, tot accés que intenti el programa instal·lat ha d'ésser desactivat. Si no hi ha molts accessos i els mateixos manquen de sentit en l'entorn de WHDLoad (tals com exec.Disable() o exec.SuperState()) simplement canviï'ls per NOP (`$4e71`). Si els accessos tenen una funció important (tal com exec.DoIO()), redireccioni'ls a l'Esclau i emuli'ls. Si hi ha molts accessos, creï una llibreria exec.library simple en un àrea de memòria que no s'utilitzi (inicialitzi la paraula llarga a l'adreça `$4`). Pot consultar el codi font de Oscar.slave, el qual emula exec.AllocMem(). Per a detectar accessos al S.O., la execbase inicial es configura en `$f0000001` amb la intenció que totes les rutines que fan servir execbase creïn una excepció d'error d'adreça ("Address Error" exception).
Si hi ha un ús intensiu de les funcions del S.O., empri un dels paquets kickemu que poden trobar-se al paquet whdload-dev. Hi ha un paquet per a Kick 1.3 ('src/sources/whdload/kick13.s') i un per a Kick 3.1 ('src/sources/whdload/kick31.s'). Aquests paquets requereixen una imatge de la kickstart original i pereten crear un entorn de S.O. complert dintre de l'espai de WHDLoad. Consulti també l'arxiu readme apropiat que es proveeix per a major informació.

### Problemes comuns de compatibilitat

#### Espai d'adreces limitat en els 68000/68010/68ec020

En aquests processadors l'espai d'adreces està limitat a 16 MB (`$000000...$ffffff`) degut al fet que aquestes CPU's tenen solament 24 línies d'adreces. Com resultat, tots els accessos a adreces més altes es realitzen en els primers 16 MB ignorant els 8 bits més significatius. Alguns programes usen aquests bits per a emmagatzemar dades, o simplement obliden esborrar-los. En un processador amb l'espai d'adreces complet de 4 GB tals com 68020/680ec30/68030/68040/68060 això no funcionarà degut al fet que s'accediran les adreces completes de 32-bits.
Per a solucionar això és necessari parxar aquests accessos i redireccionar-los a l'adreça apropiada. Algunes vegades la raó d'accessos a adreces estranyes pot ser un punter sense inicialitzar. Si aquest és el cas, pot ajudar netejar `$400` - ws_BaseMemSize.

#### Diferents entorns de pila a cada processador

L'entorn de pila creat pel processador durant les interrupcions i excepcions és diferents per a diferents membres de la família 68k. Al 68000 l'entorn de pila és de 6 bytes, excepte per als errors de bus i adreces. L'entorn de pila conté el SR guardat en (a7) i el PC salvat en (2,a7). En tots els altres processadors (68010+) l'entorn de pila mínim és de 8 bytes i addicionalment conté el número de vector com una paraula en (6,a7). Aquest format d'entorn de pila de 4 paraules $0 es crea per a les interrupcions "Trap #xx" en 68010-68060. Els entorns de pila per a altres excepcions són diferents a cada processador. La instrucció RTE treballa de forma diferent en el 68000 comparat amb el 68010+. En un 68000 simplement restaura el SR i el PC i contínua l'execució del programa a l'adreça interrompuda. En el 68010+ addicionalment allibera l'entorn de pila depenent del format del mateix.
Alguns programes fan un push d'una adreça (PC) i un SR i llavors executen una instrucció RTE. Això funciona solament en un 68000; en un 68010+ provocarà resultats no definits.
Si un programa fa això, caldrà solucionar el problema. Algunes vegades hi ha prou amb reemplaçar el RTE per RTR.

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

Existeix una diferència si el registre usat en el mode de pre-decrement (RL) està també contingut a la llista de registres. Per als 68020, 68030 i 68040 el valor escrit a memòria és el valor inicial del registre decrementat per la grandària de l'operació. El 68000 i 68010 escriuen el valor inicial del registre (no decrementat).
Atès que tal construcció no seria molt útil, no es coneix cap programari que actualment tingui problemes a causa de això.

### Línies generals per a escriure instal.ladors

- No modifiqui els registres de CPU presents en els processadors més alts tals com VBR o CACR. VBR sempre és 0 des del punt de vista dels programadors d'Esclaus, àdhuc si és mogut degut al fet que els Vectors Automàtics (i Traps si el modificador WHDL_EmulTrap està configurat) són emulats. Els bits en el CACR són diferents per a cada processador. Solament hi ha una forma vàlida de modificar les cachés, emprant resload_SetCACR/SetCPU i les bitdef's de 'exec/execbase.i' y 'whdload.i'. Totes les parts del codi presents al programa a instal.lar que modifiquin aquests registres han d'ésser desactivades o "esquivades" durant l'execució, d'altra banda WHDLoad no podrà treballar correctament!
- Mai modifiqui les imatges de disc. Això té l'avantatge que si algú vol arrencar el programa des de disc, solament haurà d'escriure les imatges novament al disc (suposant que el programa s'executi sense massa patches, segurament no és el cas més freqüent).
- No utilizi mai el suports originals del programa directament a l'Esclau (problemes de drets de còpia).
- Activi les Cachés solament si està segur que funcionarà amb tots els processadors.
- Empri tan poca memòria com sigui possible per a ws_BaseMemSize. Algunes persones fan servir marcadors (tags) residents al final de la memòria Xip, de forma que és d'ajuda utilitzar solament `$1f0000` en lloc de `$200000` i WHDLoad pot utilitzar memòria assignada de forma absoluta.

### Suggeriments i trucs

#### Què és millor, fer servir imatges de disc o fitxers?

Algunes vegades tindrà l'oportunitat de triar entre utilitzar imatges de disc o fitxers reals. Ambdós tenen els seus avantatges. L'ús d'imatges de disc és usualment la forma més senzilla i ràpida de crear l'Esclau, però els fitxers reals són molt més senzills de mantenir en una caché (si hi ha poca memòria o la memòria està fragmentada). L'espai necessari en disc dur també serà menor amb els fitxers reals que amb imatges de disc. Solament s'hauran d'emprar imatges de disc si hi ha molts fitxers (més de 30).