                      MemMan version 2.2

              Copyright (1991) MSX Software Team

                      Programming Manual


This document describes the environment and functions which 
MemMan version 2.2 provides to transient programs on MSX2 
computers.


Introduction - evt verhuizen naar MM2INTRO.TXT
============

The MemMan 2.2 package includes the MemMan memory managing 
program, the TSR utilities TsrLoad, TsrView and TsrKill and 
both user and programming manuals. Free use and distribution 
of this package is permitted and encouraged. No fee is 
requested or expected for the use and distribution of MemMan.

The MemMan interface to TSR programs is documented in the 
`MemMan 2 TSR development kit'. This package contains full 
documentation on programming TSR programs and some TSR 
development tools. As opposed to the MemMan 2.2 package 
itself, the TSR development tools and documention are not in 
the Public Domain. The TSR development kit can be ordered from 
the MSX Software Team. For more information about this package 
refer to the coming issues of the MSX Computer Magazine.

Questions, comments, suggestions, bug reports and commercial 
inquiries will be welcomed.


MEMMAN version 2.2 - specifications
===================================


Modifications with regard to MemMan version 2.0:
-----------------------------------------------

Het verschijnen van de MSX Turbo R machine in Nederland heeft 
nogal wat stof doen opwaaien, bij de MemMan programmeurs. Net 
na het uitbrengen van MemMan 2.0 bleek het gebruik van MemMan 
op de Turbo-R nogal wat problemen op te leveren, vooral bij 
gebruik van de Kanji schermmodes.

Deze problemen zijn deels door ontstaan doordat de Kanji 
routines in de Turbo-R de extended BIOS hook op adres &HFFCA 
afbuigen op een manier die niet door de MemMan programmeurs 
was voorzien. De Turbo-R verwacht namelijk dat iedere 
applicatie die zich aan de extended BIOS hook bevindt, door 
middel van een zogenaamde `interslot call' aangeroepen wordt, 
terwijl MemMan juist via de veel snellere "jump" instruktie 
werkte. Dit had tot gevolg dat de Turbo-R de extended BIOS 
hook - waaraan MemMan gekoppeld is - niet goed afboog en 
vastliep. Nadat dit was opgelost bleek er nog een structurele 
fout te zijn gemaakt.

Wanneer MemMan 2.0 wordt geladen en daarna de Kanji driver 
middels een `CALL KANJI' instruktie geactiveerd wordt, wordt 
na een aanroep van de extended BIOS hook de Kanji-ROM 
aangeschakeld in geheugenpagina 1. Wanneer de aanroep voor 
MemMan bestemd blijkt te zijn, wordt vervolgens MemMan 
aangeroepen. Op dat moment is de Kanji-ROM nog steeds aktief 
in pagina 1. Wanneer de MemMan gereed is, zal de 
interslot-call routine de slots terugschakelen in de stand die 
bekend was ten tijde van de hook-aanroep.

In sommige gevallen is dat herstellen van de slotstand echter 
niet gewenst. De MemMan `use' funkties zijn namelijk speciaal 
bedoeld om de slot-stand te kunnen veranderen. Het effect van 
de `use' funkties wordt echter direct weer ongedaan gemaakt 
door het terugschakelen van de slotstand door de 
interslot-call routine.

De `use' funkties van MemMan kunnen dus beter niet via de 
extended BIOS hook aangeroepen kunnen worden. Ook `restore 
slot' (funktie 41) lijdt aan hetzelfde euvel en kan beter niet 
gebruikt worden. Om compatibiliteit met voorgaande MemMan 
versies te behouden zijn voornoemde funkties nog wel aanwezig. 
Ter vervanging van de `use' en `(re)store slot' funkties wordt 
het gebruik van de `fastUse' en eventueel de `fastCurSeg' 
funkties sterk aangeraden. Het adres waarop deze funkties 
aangeroepen kunnen worden kan worden opgevraagd door middel 
van funktie 50 `info'.


Verdere wijzigingen in MemMan 2.1 ten opzichte van versie 2.0:

- funkties 60 en 61 zijn vervallen wegens een structuurfout.
  Deze funkties gebruikten register IX als doorvoer parameter, 
  dit register wordt gewijzigd door de interslot-call routine 
  waarmee MemMan 2.1 aan de extended BIOS hook gekoppeld is.
- funkties GetTsrID (62) en TsrCall (63) vervangen nu de 
  funkties 60 en 61. Het TSR-ID wordt bij deze funkties 
  doorgegeven in register BC in plaats van in register IX.


Terms
-----

Segment - Memory block of 16 kB. MemMan supports two segment 
          types: Page specific Segments (PSEG) and Flexible 
          Segments (FSEG). A PSEG can only be used in a 
          specific memory page. Three PSEG types are 
          supported: PSEG0000, PSEG4000 and PSEG8000, which 
          can be switched into page 0, 1 and 2 respectively.
          FSEG's can be used in any of the three pages 
          mentioned above.

          When the Mapper Support Routines of MSX-DOS2 are 
          active during the installation of MemMan, only the 
          currently available user segments will be allocated 
          by MemMan. Memory already allocated by a MSX-DOS2 
          system appliction like a RAMdisk will therefore 
          never be available for MemMan applications.
          However, if a MSX-DOS2 RAMdisk is installed when 
          MemMan is already active, the segments used by the 
          RAMdisk will become available for MemMan 
          applications as soon as the RAMdisk has been 
          removed.

TSR     - Terminate and Stay Resident. Programs of this type 
          remain permanently in memory and are mostly 
          operating through the hooks provided by the MSX 
          standard. MemMan 2 standardizes the installation and 
          the removal of TSR programs and handles the calls to 
          the TSR's.

TPA     - Transient Program Area. The TPA is the basic 64 kB 
          of memory in which MSX-DOS programs are loaded.
          The term `transient program' is used for programs 
          running either under the MSX-DOS or the MSX-Disk 
          Basic environment.

Heap    - Memory area in page 3 (somewhere between &HC000 and 
          &HFFFF). Heap memory can be allocated and used by 
          any MemMan application, but it is especially useful 
          for TSR programs, for example to allocate a stack 
          area.

FastUse - `Fast' MemMan functions operate faster and in 
          certain cases safer than MemMan function calls at 
          the Extended BIOS hook. The fast functions can be 
          called directly at an entry address in page 3.

unCrash - UnCrash is a routine which frees segments which were 
          not deallocated by badly behaving or crashed 
          programs. UnCrash is automatically executed when the 
          IniChk function (30) is called. Segments having the 
          reserved status will not be deallocated by the 
          UnCrash routine. A segment can be given the reserved 
          status by using the SetRes function (11). The 
          reserved status should only be set when the segment 
          has to remain allocated after the program has ended. 
          This will mostly be the case when the segment is 
          used by a TSR program.


The MemMan environment
----------------------

MemMan handles the available memory in segments of 16 kB each. 
A MemMan application program must allocate each segment before 
it may be used. It must be deallocated before the program 
ends. There are two basic segment types: page specific 
segments, PSEG's, and flexible segments, FSEG's.

PSEG's can be allocated for use at one specific memory page. 
For example, a PSEG8000 can only be used in page 2, at the 
address space from &H8000 to &HBFFF. PSEG's are part of 
conventional memory without the memory-mapping option. 
Formally, system ROM's like the BIOS and BASIC ROM's are also 
PSEG, but of course they cannot be allocated to an application 
program.

FSEG's can be switched into any memory page. Therefore, FSEG's 
are part of a memory-mapper. Both FSEG's and PSEG's are 
represented by a 16-bit `segment code', which will be returned 
when the segment is being allocated.

When an application program uses a segment in one memory page 
only, a PSEG shou