GenAlib v0.20 for Ti-89 and Ti-92plus
Copyright 2001 TimeToTeam. All right reserved
http://www.timetoteam.fr.st
Contact: ppelissi@caramail.com



I. Introduction

PpHd:	GenAlib is an asm/C library. Great ! No ?
YOU:	Sucks... What does it do ?
PpHd:	Well, it allocates, desallocates memory blocks,
	it creates lists, sorts lists, ...
YOU:	Fantastic ! Ti-Os does it for more than 5 years.
	It is useless !
PpHd:	Not at all ! As you may know, memory allocation
	is a very hard sport. When you want to create
	such a routine, you have to set up exactly the contex.
	And the contex of genalib is very different from the one
	of tios routines !
YOU:	Well... Maybe, but what is the contex of GenAlib ?
PpHd:	GenAlib's routines were designed to be fast and static.
	They don't do any garbage, and after a very long time
	you may have many small blocks.
	So you can't use them for creating files, or most of the
	things you use with Ti-Os ones.
	They are dynamics routines (i.e. you use them very often)
	contrary to tios ones (You use them at the beginning of
	your program and that's all.)
YOU:	Well... Ok, theses routines are different from HeapAlloc of tios.
	But can you give some examples ?
PpHd:	The best example is to create dynamics lists.
	You can look at the bench, and using GenAlib is 30x faster
	than tios ! For example, in a shoot-them_up, you can now use lists !
	List of ships, lists of fires, ...
YOU:	Hey ! It isn't a nostub	library ! It is a kernel dynamic library.
PpHd:	Yes.
YOU:	I don't like kernel programs !
	I don't understand the need of using a kernel when TiOs offers
	the ability of using AMS programs directly. It is a lose of memory !
	Why don't you create a static library for tigcc ?
PpHd:	Well, the main feature of the kernel is the libraries.
	I don't want to create a static library since no program is
	perfect, and there are always bugs. So I want to fix the bugs
	without recompiling your programs.
YOU:	But you can create a nostub library.
PpHd:	Well. I think is is harder to use nostub libraries.
	You should inialize them, and you can't create crossed libraries.
YOU:	But you can !
PpHd:	Ok, but I don't want.
	Most of the programs I use are kernel programs, so I have always
	a kernel on my calc, so I don't see the need of creating nostub
	programs. If you really prefer nostub library, mail me.
YOU:	I will !
PpHd:	Now, let's start the features !
	
II. Features

	+ You can create more than 5000 elements contrary to 2000 for Tios
	+ Even more with linked area of memory (Not available !)
	+ Fast !
	+ Static !
	+ Lists !
	
III. How to use.

	Very easy.
	In your program, you include "gla.h" (You don't need Genlub !)
	Then, you alloc some memory from Tios routines (or from the stack).
	Then you call : gla_init with the right arguments.
	That's all !
	Then you use gla_alloc and gla_free instead of alloc and free.
	
	Lists:
	The format of the list is :
		struct list {
			struct list *next;
			char	data[];
			}
		Or in assembly 
		LIST + 00.l : Adress of the next element or NULL if the end.
		LIST + 04.? : Your data.


IV. Functions:

void	gla_init(void *start, void *end);
genalib::init:
	In: a0.l = Start / a1.l = End
	Out: Nothing
	Destroy: Nothing

	Init the genlib internal variables so that this block
	of memory from 'start' to 'end' will be used to alloc
	and free memory.

void	*gla_alloc(unsigned long size);
genalib::alloc:
	In: d0.l = Size
	Out: a0.l = Ptr to memory or NULL
	Destroy: a0
	
	Alloc a memory block of size bytes.
	Return NULL if there isn't enought contiguous memory
	left.
	You cannot alloc less than GLA_ALLOC_MIN_SIZE.
	If you call the function with less bytes, it will
	enlarge the block allocated.
	
void	*gla_realloc(void *address, unsigned long size);
genalib::realloc:
	In: d0.l = New Size / a0.l = adress
	Out: a0.l = Ptr to memory or NULL
	Destroy: a0

	ReAlloc a memory block of size bytes.
	Copy the original block to a new block.
	The new size should be bigger than the old one.
	Sorry, I forget to add this feature :(
	Return NULL if there isn't enought contiguous memory
	left.
	You cannot alloc less than GLA_ALLOC_MIN_SIZE.
	If you call the function with less bytes, it will
	enlarge the block allocated.

void	gla_free(void *address);
genalib::free:
	In: a0.l = adress
	Out: Nothing
	Destroy: Nothing

	Free the memory block.
	

LISTS:
	'an' means adress register
	an<list> means the adress list register
	In the macros versions (Asm only), you should not use the register d0/a0
	(They are used internally by the macros).

LIST	*gla_list_new()
genalib::list_new	an
	Create a new empty list

void	gla_list_del(LIST *l)
genalib::list_free	<ea>
	Free the list.
	
void	*gla_list_top(LIST *l)
genalib::list_top	an<list>, an<data>
	Get the data of the top of the list.
	
LIST	*gla_list_tail(LIST *)
genalib::list_tail	an<list>,an<tail>
	Get the tail of the list.
	
BOOL	gla_list_empty(LIST *)
genalib::list_empty	an<list>, instruction, label
	Is an empty list ?
	
LIST	*gla_list_add(LIST *list, unsigned short size)
genalib::list_add	an<list>,sizetoallocate,label_if_error
	Add a new struct of size bytes to the list.
	
LIST	*gla_list_sub(LIST *l)
genalib::list_sub	an<list>
	Remove the second element of the list.

LIST	*gla_list_sort(LIST *list);
genalib::list_sort:
	In: a0 -> List
	Out: a0 -> Sorted List
	Destroy: a0

	Sort the list.
	It uses the fusion sort, which is quite fast.
	It won't alloc any new struct, it will just update
	the links between the nodes.

void	gla_list_set(short size, short offset, short way);
genalib::list_set
	In:
	 d0.w = Size (0: Byte, 1: Word, 2: Long)
	 d1.w = Offset from the beginning of a element of the list (excluding the 'next adress')
	 d2.w = Way of sorting (GLA_INC_U, GLA_DEC_U, GLA_INC_S, GLA_DEC_S)
	Out: Nothing
	Destroy: Nothing

	Set the way of sorting of sort-list.
	The size of the cmp (Byte, word or long).
	If it is unsigned or signed (_U or _S).
	The way of sorting (INC or DEC).
	And the offset from the beginning of the structure.
	



V. Bench

	Here are the results of the program tstalloc.c.
	This program allocs N blocks, and free them in a random
	number.

		Tios		GenAlib
N=1500		4042=45s	132=1.5s
N=1000		1856=20.6s	68=0.75s
N=500		548=6.10s	22=0.25s

Note:	In the program tstalloc.c, we use gla_list_add which
	isn't at all an optimised function !
	In my opinion, it slows down the program a few.
	
VI. Known Problems

	Nothing.
	
VII. To do

	+ Include other functions.
	+ Optimize Realloc
	+ Optimize Free a little more (Choose the best direction).
