TSR bestanden: Achtergrond
--------------------------

Bij het ontwikkelen van MemMan 2 en de TSR bestands-structuur 
is het standpunt ingenomen, dat de TSR's zowel eenvoudig 
ontwikkeld als eenvoudig gebruikt moesten kunnen worden. 
Iedereen die machtinetaal programma's voor de MSX kan 
ontwikkelen, zou ook TSR's moeten kunnen schrijven en iedereen 
die MSX programma's kan gebruiken zou ook TSR's moeten kunnen 
installeren. We zijn van mening dat MemMan 2 redelijk aan deze 
uitgangspunten voldoet. Maar desondanks verschilt een TSR op 
diverse punten van een gewoon machinetaal programma.


REL-Tabel

De TSR's kunnen door TsrLoad op iedere willekeurige plaats in 
pagina 1 (adresgebied van &H4000 tot &H7FFF) worden geplaatst. 
Daartoe gebruikt de TSR-Loader een tabel met alle 
programma-relatieve adressen. Deze tabel wordt door het 
programma LinkTsr automatisch in de TSR-file geplaatst.

De informatie die nodig is om machinecode op een willekeurig 
adres te kunnen laden wordt afgeleid uit een zogenaamde 
relocatable file. TSR's moeten daarom geprogrammeerd worden met 
een assembler die `relocatable' files kan maken, kortweg `.REL' 
bestanden. Voorbeelden hiervan zulke assemblers zijn GEN80 uit 
het DEVPAC2 pakket van HiSoft en M80 uit de MSX-DOS tools van 
Ascii.

Een linker wordt normaliter gebruikt om verschillende REL-files 
samen te voegen tot een COM-file die op een vast adres moet 
worden opgestart. Alle informatie omtrend de benodigde 
aanpassingen in de code wordt op dat moment door de linker 
gebruikt en is niet meer aanwezig in de COM file.

Om nu toch die informatie te kunnen behouden heeft het MST de 
reeds genoemde TSR-linker ontwikkeld: LinkTsr oftewel LT.COM. 
Deze linker koppelt de verschillende REL-files aan elkaar, net 
zoals een gewone linker dit zou doen. De TSR-Linker bewaart 
echter alle programma-relatieve adressen en plaatst deze apart 
in een tabel in de uiteindelijke TSR-file. Het aanmaken van de 
REL-tabel gebeurt geheel automatisch, voor de programmeur is de 
precieze opbouw en de positie van de REL-tabel niet van belang.


Initialistatie code

Ieder programma heeft wel een stuk initialisatie code, zo ook 
de meeste TSR's. Deze code wordt maar een keer gebruikt en is 
daarna ook overbodig. Om de initialisatie code na gebruik 
eenvoudig te kunnen verwijderen gebruikt de TSR-Loader een 
truukje. De initialisatie code wordt altijd aan het einde van 
het TSR programma geplaatst. Vlak voordat de TsrLoader de TSR 
op de hooks aansluit, wordt de initialisatie code aangeroepen. 
Na het uitvoeren van die code wordt het geheugen dat bezet werd 
door de initialisatie code weer vrijgegeven voor gebruik door 
andere TSR programma's. De hoeveelheid benodigd geheugen wordt 
zo tot een absoluut minimum beperkt.


Hook-tabel

De TSR's kunnen worden gekoppeld aan de hooks in het 
systeem-geheugen. In de TSR-File moet een tabel worden 
opgenomen waarin vermeld wordt welke hooks door de TSR gebruikt 
worden en naar welke routine moet worden gesprongen als ‚‚n van 
die hooks wordt aangeroepen. Net als de REL-Tabel wordt de 
hook-tabel tijdens de installatie van de TSR door de Loader 
gebruikt. Deze tabellen worden niet opgenomen in de 
uiteindelijke programma-code van de TSR en kosten dus geen 
werkgeheugen in het TSR programma segment. Het is niet mogelijk 
om na de installatie van de TSR nog extra hooks af te buigen.

De hook-tabel begint met twee bytes die de lengte van de tabel 
aangeven. Bij het bepalen van de tabellengte worden deze twee 
lengte-bytes meegeteld. Na het lengte woord staan de 
hook-afbuig gegevens. Ieder element in de hook-tabel is vier 
bytes lang. De eerste twee bytes van het element geven het 
adres aan van de af te buigen hook. De volgende twee bytes 
geven het adres aan van de routine die door MemMan moet worden 
aangeroepen wanneer de hook aangeroepen wordt.


Header tabel

Iedere TSR begint met een speciale tabel: de zogenaamde 
file-header. Aan de hand van deze header kan de TsrLoader de 
positie bepalen van de programmacode van de TSR en de tabellen 
in de file.

Iedere TSR-listing dient dus te beginnen met de header tabel. 
De indeling van deze tabel is als volgt:

	defb 'MST TSR',13,10    ;TSR file ID
	defb 'MSTs TSRname'     ;TSR naam
	defb 26 		;Einde tekst markering
	defw 0002		;Versie nummer voor TsrLoad
	defw tsrStart		;Base-adres
	defw init		;Start initialiatiecode
	defw kill		;Destructie routine
	defw talk		;Interactie routine
	defw tsrLen		;Lengte van TSR-Code
	defw iniLen		;Lengte van init-Code


De betekenis van de elementen in de header tabel is als volgt:

- MST TSR file ID, 9 bytes.
  Aan deze identificatietekst herkent TsrLoad of het bestand al 
  dan niet een TSR bestand is.

- TSR naam, 12 bytes
  Een zo uniek mogelijke ID-tekst gekozen door de programmeur. 
  Toepassingen kunnen door middel van deze naam met de TSR 
  communiceren. Ongebruikte posities opvullen met spaties.

- Einde tekst markering, 1 byte
  Afsluitend staat altijd Control-Z (^Z), voor het geval TYPE 
  commando losgelaten wordt op de TSR programmacode.

- Vereiste versie nummer van de TSR-Loader, 2 bytes.
  De loader controleert dit nummer, om te voorkomen dat een 
  `verouderde' loader een TSR file in wil lezen die een 
  niet-compatible struktuur heeft. De TSR-loader is 
  upward-compatible, zodat ook eventuele TSR's van een vorige 
  MemMan versie ge‹nstalleerd kunnen worden. Gebruikers kunnen 
  dan volstaan met het vervangen van de loader en kunnen 
  dezelfde TSR's blijven gebruiken.
  Het versienummer is 0001 indien door de TSR alleen MemMan 2.1 
  functies aangeroepen worden. Indien ook van de specifieke 
  MemMan 2.2 functies gebruik wordt gemaakt, dient het 
  versienummer 0002 in de header te worden geplaatst.

- Base-adres van de TSR programmacode, 2 bytes.
  Dit is het adres van het eerste byte van de TSR programma 
  code. Dit is altijd het eerste byte na de header in de TSR 
  file. Deze waarde wordt door de loader gebruikt om de 
  programma relatieve adressen aan te passen.

- Initialisatie adres, 2 bytes.
  Wordt aangeroepen tijdens de installatie van de TSR. De 
  Init-routine MOET helemaal achteraan het TSR-programma staan, 
  zodat de loader de ruimte van de INIT routine weer eenvoudig 
  kan vrijgeven nadat de TSR ge‹nstalleerd is.

  Na de aanroep moet de initroutine in register A een vlag 
  teruggeven. De definitie van dit vlaggenregister is als 
  volgt:

	reg | bit | functie
	----+-----+------------------------------
	 A  |  0  | 0 = Initialisatie gelukt
	    |	  | 1 = Initialisatie mislukt
	    |  1  | 0 = Geen intro-tekst
	    |	  | 1 = Pointer naar intro-tekst in [DE]
	    | 2-7 | 0 = Gereserveerd

  Indien de TSR initialisatie routine met bit 0 van het A 
  register aangeeft dat de installatie niet gelukt is, 
  verwijdert de TSR-Loader de gehele TSR weer. Als de TSR met 
  bit 1 aangeeft dat er een intro tekst afgedrukt is, dan wordt 
  deze door de TSR-Loader afgedrukt. TSR's mogen nooit zelf 
  teksten op het scherm afdrukken. Hierdoor is mogelijk om in 
  de toekomst ook in grafische omgevingen de intro tekst af te 
  kunnen drukken. Ook het onderdrukken van de intro teksten is 
  dan eenvoudiger. De intro-tekst wordt afgesloten een met 
  0-byte.

  De hooks worden pas na de aanroep van de initialisatie 
  routine ge‹nstalleerd.

- Destruktie adres, 2 bytes.
  Wordt aangeroepen bij het verwijderen van de TSR.

- Interactie adres, 2 bytes.
  Wordt aangeroepen door toepassingsprogramma's, via de TsrCall 
  functie van MemMan.

- Lengte van de TSR-code, 2 bytes.
  Deze lengte betreft de TSR-programmacode, zonder de 
  initialisatie routine.

- Lengte van de initialisatie routine, 2 bytes.
  De initialisatie routine staat helemaal achteraan de TSR, en 
  wordt bij de initialisatie van de TSR in hetzelfde segment 
  gezet als de TSR code zelf. De ruimte die de initialisatie 
  routine in beslag neemt wordt na de aanroep ervan weer vrij 
  gegeven.


File structuur

Ieder TSR programma bestaat uit onderdelen die elk op een vaste 
positie in het bronbestand moeten staan. Deze programma 
onderdelen zijn:

- Header tabel
- TSR programmacode
- TSR initialisatiecode
- Hook tabel

Deze volgorde dient strikt in acht te worden genomen. In de 
meeste gevallen zal de gehele TSR uit slechts ‚‚n REL-file 
bestaan die in ‚‚n keer wordt gelinkt. De programmeur hoeft er 
dan alleen op te letten dat de elementen in de juiste volgorde 
in de bron-listing staan. Indien de TSR uit meerdere REL-files 
is opgebouwd worden in de files in de opgegeven volgorde 
ingeladen en achter elkaar geplaatst, de TSR-linker voert 
hierop geen controles uit.

Het bestand TSRFRAME.GEN op de TSR development-disk bevat het 
raamwerk van een TSR-listing. Door van dit raamwerk uit te gaan 
bij het schrijven van een nieuw TSR programma is het eenvoudig 
de juiste structuur aan te houden.
