***************************************************************
*                                                             *
*        Gestion de mmoire virtuelle pour DOOM Falcon        *
*                         version 0.4                         *
*                  Par Xavier Joubert (Xaz)                   *
*                                                             *
***************************************************************

DOCUMENTATION


 Conseil d'ami :
 
	Imprimer ce fichier pour pouvoir le garder sous les yeux en
programmant ne serait certainement pas une mauvaise ide.


 Limitations :
 
	Version compatible 030 seulement (adieu jolies Barracuda et
Afterburner, snif). JE VEUX UNE DOC POUR LE 040 !!!

	Cette version supporte la mmoire virtuelle en LECTURE/ECRITURE mais
je ne l'ai ni test, ni debugg ! Prudence, donc...


 Utilisation :
 
1 - Mettre la variable XAZTEST  0. (Elle se trouve au dbut du source)
2 - Inclure le fichier DOOMSWAP.S au dbut du source.
3 - Appeler XazLib (c'est une macro)  un endroit tranquille (aprs l'appel
	 Pterm par ex.).
4 - Utiliser les fonctions comme indiqu dans leurs descriptions.

	Toutes les fonctions doivent tre appeles en mode >Superviseur<

	Ces fonctions ne corrompent que d0 (pour le retour) et pas d0-2/a0-2
comme le Gemdos.

	Les paramtres doivent tre passs par la pile.

	L'appel se fait par un bsr ou un jsr si la routine se trouve  plus
de 32 ko de distance. (quoique bsr.l soit valide depuis le 020, donc c'est
selon les gots de chacun. Je conseillerais personnellement plutt
l'utilisation du bsr.l, vu que cela vite la phase de relocation.
PC-relative rulez !)

	Toutes les constantes se trouvant dans les descriptions des
fonctions sont dfinies dans le source.

	Toutes les tiquettes utilises commencent par "Xaz", "XAZ" ou
"FinXaz". Cela devrait permettre d'viter tout conflit de noms.

	ATTENTION : ces fonctions sont fortement inspires de leurs
quivalents Gemdos. Cependant il existe des diffrences. Notamment :
XazFopen() renvoie un pointeur, XazFclose prend un pointeur comme paramtre,
XazMalloc ne renvoie pas 0 quand il n'y a pas assez de mmoire disponible,
etc. Consulter la description des fonctions pour plus de dtails.

	Pour les Problmes, j'attends bien entendu les "bugs report".
(J'spre qu'il n'y en aura pas).


 Description des fonctions :
 
*** XazOn() ******************************************************

Prototypage :	LONG XazOn(VOID)

Description :	XazOn() initialise la gestion de mmoire viruelle

Paramtres :	Aucun.

Appel :		bsr	XazOn

Retour :	XAZ_OK		: gestion de mmoire virtuelle en place
		XAZ_ERR_ON	: la gestion tait dj en place
		XAZ_ERR_MEM	: pas assez de mmoire dispo
		XAZ_ERR_PROC	: type de processeur non support
		XAZ_ERR_MMU	: pas de MMU ou MMU dj utilise

Problmes :	XazOn() ne teste pas la prsence d'une MMU sur le systme
		dans cette version tant donn qu'il n'y a actuellement
		aucun moyen document de le faire.

Divers :	XazOn() doit tre appel avant toute autre fonction. Si le
		retour est un code d'erreur, il ne faut pas appeler XazOff.
		Tout  dj t remis en tat correctement.

		Toute tentative d'appel  une autre fonction avant XazOn()
		(ou aprs si on a eu une erreur  l'installation) a 99,99%
		de chances de tout faire planter. You've been warned !


*** XazOff() *****************************************************

Prototypage :	LONG XazOff(VOID)

Description :	XazOff() remet tout dans l'tat initial.

Paramtres :	Aucun.

Appel :		bsr	XazOff

Retour :	XAZ_OK		: tout  t remis dans l'tat initial
		XAZ_ERR_OFF	: la gestion n'tait pas installe

Problmes :	Aucun connu.

Divers :	XazOff() doit tre appele avant de quitter.

		XazOff() libre toute la mmoire alloue et ferme tous les
		fichier encore ouverts (Cool, non ?).


*** XazFopen() ***************************************************

Prototypage :	VOIDP XazFopen(fname,mode)
		char *fname
		WORD mode

Description :	XazFopen() permet d'"ouvrir" un fichier et d'y accder
		ensuite comme  de la mmoire.

Paramtres :	fname doit pointer sur un nom de fichier valide (par exemple
		"DOOM.WAD") ou un nom avec chemin complet (par exemple
		"E:\JEUX\DOOM\WADS\DOOM.WAD"). Bref, c'est strictement la
		mme chose que le Fopen du Gemdos.

		mode peut tre au choix :

		XAZ_READONLY	: Accs en lecture seulement (ROM)
		XAZ_WRITEONLY	: Accs en criture seulement
		XAZ_READWRITE	: Accs en lecture/criture

Appel :		move.w	mode,-(sp)
		pea	fname
		bsr	XazFopen
		addq.l	#6,sp

Retour :	Si le retour est infrieur  XAZ_ERR_MAX, c'est l'adresse 
		laquelle on peut accder au fichier, sinon, sa valeur SIGNE
		reprsente un des codes d'erreur suivants :

		XAZ_ERR_MEM	: pas assez de mmoire dispo
		XAZ_ERR_FICH	: erreur d'accs au fichier
		XAZ_ERR_ADR	: pas de zone d'adressage libre
		XAZ_ERR_INVMODE	: le mode pass n'est pas valide (ou pas
				  support dans cette verion)

		Le test devra tre effectu comme suit :

		cmp.l	#XAZ_ERR_MAX,d0
		blo	OK		;ou encore :	bhs	PasOK

Problmes :	XAZ_WRITEONLY n'est pas support dans cette version et ne le
		sera probablement jamais (Dans le genre inutile, on ne fait
		pas mieux ; en plus la MMU du 030 ne permet pas ce genre de
		fantaisies (Je veux dire de la mmoire en criture seule)).

Divers :	Le nombre de fichier ouverts simultanment n'est limit que
		par le systme (TOS ou MiNT), la mmoire disponible et la
		zone d'adressage libre.

		Ouvrir un fichier consomme ~512 octets par Mo de fichier.

		Je conserve le handle du fichier, le nom peut donc ensuite
		tre modifi sans risques.

		Tenter d'crire dans un fichier accssible en lecture seule
		provoquera une erreur de bus (2 bombes !).


*** XazFclose() **************************************************

Prototypage :	LONG XazFclose(adr)
		char *adr

Description :	XazFclose() "ferme" un fichier ouvert avec XazFopen().

Paramtres :	adr doit tre l'adresse renvoye par XazFopen().

Appel :		move.l	adr,-(sp)
		bsr	XazFclose
		addq.l	#4,sp

Retour :	XAZ_OK		: le fichier est ferm
		XAZ_ERR_NOTFICH	: l'adr donne n'est pas celle d'1 fichier

Problmes :	Aucun connu.

Divers :	Nant.


*** XazMxalloc() *************************************************

Prototypage :	VOIDP XazMxalloc(amount, mode)
		LONG amount
		WORD mode

Description :	XazMxalloc() alloue un bloc selon les prfrences indiques.

Paramtres :	amount doit tre la quantit de mmoire dsire ou -1 pour
		demander la taille du plus grand bloc disponible du type de
		mmoire spcifi.

		mode peut tre au choix :

		XAZ_STRAM	: ST Ram uniquement
		XAZ_TTRAM	: TT Ram uniquement
		XAZ_PREFSTRAM	: ST Ram de prfrence
		XAZ_PREFTTRAM	: TT Ram de prfrence

Appel :		move.w	mode,-(sp)
		move.l	amount,-(sp)
		bsr	XazMxalloc
		addq.l	#6,sp

Retour :	Si le retour est infrieur  XAZ_ERR_MAX, c'est l'adresse du
		bloc allou, sinon, sa valeur SIGNE reprsente un des codes
		d'erreur suivants :

		XAZ_ERR_MEM	: pas assez de mmoire dispo
		XAZ_ERR_INVMODE	: le mode pass n'est pas valide
		XAZ_ERR_LEN	: on ne peut pas allouer un bloc de longueur
				  0 octets.

		Le test devra tre effectu comme suit :

		cmp.l	#XAZ_ERR_MAX,d0
		blo	OK		;ou encore :	bhs	PasOK

Problmes :	Aucun connu.

Divers :	XazMxalloc(0,?) retourne XAZ_ERR_LEN car il est interdit
		(et inutile) d'avoir des blocs de longueur nulle.

		L'adresse de dbut d'un bloc allou avec XazMalloc() est
		toujours align sur 4 ko. Vous pouvez utiliser ce fait sans
		craintes : c'est document !

		Un bloc allou avec XazMxalloc() n'est >PAS REMIS A ZERO<
		avant d'tre retourn  l'utilisateur. Celui ci devra donc
		le faire lui-mme si besoin est.


*** XazMfree() ***************************************************

Prototypage :	LONG XazMfree(startadr)
		VOIDP startadr

Description :	XazMfree() libre un bloc de mmoire allou par
		XazMxalloc().

Paramtres :	startadr doit tre l'adresse retourne par XazMxalloc().

Appel :		pea	startadr
		bsr	XazMfree
		addq.l	#4,sp

Retour :	XAZ_OK		: le bloc  t libr
		XAZ_ERR_NOTBLOC	: l'adr donne n'est pas celle d'1 bloc
				  allou

Problmes :	Aucun connu.

Divers :	Nant.


*** XazMshrink() *************************************************

Prototypage :	LONG XazMshrink(startadr,newsize)
		VOIDP startadr
		LONG newsize

Description :	XazMshrink() permet de rduire la taille d'un bloc mmoire
	allou avec XazMxalloc().

Paramtres :	startadr doit tre l'adresse retourne par XazMxalloc().
	newsize doit tre la nouvelle taille dsire.

Appel :	move.l	newsize,-(sp)
	pea	startadr
	bsr	XazMshrink
	addq.l	#8,sp

Retour :	XAZ_OK	: le bloc  t rduit  la taille demande
	XAZ_ERR_NOTBLOC	: l'adr donne n'est pas celle d'1 bloc
		  allou
	XAZ_ERR_GROWTH	: le bloc n'a pas pu tre agrandi.
	XAZ_ERR_LEN	: un bloc ne peut pas tre rduit  la
				  longueur 0 octets.

Problmes :	XazMshrink ne peut tre utilis que pour DIMINUER la taille
	d'un bloc. Toute tentative d'agrandissement se soldera par
	un XAZ_ERR_GROWTH en retour. Si newsize est gal  la taille
	du bloc, le retour sera XAZ_OK.

Divers :	XazMshrink(x,0) renvoie XAZ_ERR_LEN car il est interdit
	d'avoir un bloc de longueur 0. Utilisez XazMfree(x) pour
	librer la mmoire.