Holy cow! another new doc!  :) see, I know what you are thinking. 

	This one is going to be released as preperation for the next 
one, which will be going further in depth concerning the operation of
the bootstrap loader [BSL], and the various steps it goes through before
the DHOS system is initialized and ready to be used.
	This document is concerning the use of IDs in the DHOS system.
This method will greatly simplify many things that a program can do.
I have decided to use these because they simplify so many things, and 
also because they are similar to the File handles of DOS and unix, and
the unix's process IDs.  Some were from my own invention/adaptation.
	Note: I will update the Function texts to deal with these new
functions and the many others that will be affected by these changes 
as soon as i can.
	Also, please reply to this document so it can be as good as it
can be.

And so, without further ado, let me present to you the proposed ID 
system of the Doomsday Horizons Operating System!!

	There are several ID types.  They are, in no particular order:
Arena IDs (AID)
Process IDs (PID)
Owner IDs (OID)
File IDs (FID)
Device IDs (DID)
Arena Header Block (AHB)  
ID Route paths (IDRP) these wouldnt be implemented until 
			we did a networking extension library
			
Arena IDs (AID)
===============
These deal with the allocation of RAM on the TI-85 system RAM.
It identifies each allocated arena (block) of ram, and is the 1st byte
in its arena header (see topic:Arena Header)
These are created when a block of ram is allocated using the
AllocateArena function.

(note about the function usage forms: they are in high-level style as
given here. but in an actual program, we would use an asm equivalent)

The preliminary form for this function is:

	ArenaID=AllocateArena(SizeRequired)

A -1 is returned if there is not enough memory, otherwise, the new AID
is returned.

	SuccessFail=DeallocateArena(ArenaID)

a 0 is returned if it was a success, a -1 if no such AID was found

Each arena begins with an arena header, which ranges from 4 to 6 bytes
depending on what the arena contains.  Then the arena contents are in 
RAM after the header. Each arena can only be accessed by its owner(see
the OID section). arena's owned by the kernal can only be accessed by 
the kernal, etc.  The only one that seems to break this rule is the 
Free arena (always AID:00) which actually does follow the rule, because
it is owned by the kernal and the kernal is the one that breaks it down
into newly allocated arenas for programs to use.


Process IDs (PID)
=================
These IDs are on the order of Linux/Unix process IDs, each identifying
a program that is currently running.  This has been slightly modified,
but it still is sort of the same thing.
First of all, the program is assigned a process ID when it is relocated
by the kernal.  IT keeps this ID until it is killed. It is the ID
used as the owner ID (see the OID section) when it allocated an arena.
Although DHOS does not multitask, with this, it coudl be a little 
easier to make it do so.
Each arena that can be executed has a process ID included in its arena
header.
Here are the functions associated with PIDs:

	ProcessID=RelocateArena(ArenaID,Permissions)

where Permissions=0 if no access to owner's arenas (see OIDs) or a 1 if
access is going to be allowed to the owner's arenas.  A -1 is returned
if a problem occurs with the relocation.  Or if the program is not in
relocatable format (e.g. not an executable file).

	SuccessFail=KillProcess(ProcessID)

This kills the process, cahnging all the process's owned arenas to the
killer and taking the Process off the runnable process list.
a -1 occurs if the processid is invalid (e.g. that process # is not 
assigned, or you don't have access engough to kill it (like the kernal)
:)



Owner IDs (OID)
===============
These are process IDs that have allocated another arena for there own 
use.  Only the owner can access its allocated arenas. unless special
permissions are set for a spawned process (one that is owned by another
one) in which case, all arena's allocated by the owner are accessible 
by the child process (the spawned one).   On further note, when a 
process is killed, the killer (usually the owner) gets all the killed
processes arena's by default.
They ARE NOT deallocated automatically.  If your program does not 
deallocate its arenas (Execuatable or not) they jsut take up room even
after the process is killed.  So please, be efficient and clean up your
allocated memory when done with it.  Also, when a process is killed,
it is still allocated. It needs to be deallocated also.
Just a short lesson in memory management..... :)) hehe


File IDs (FID)
==============
These are the IDs which are similar to the File Handles used in DOS and
UNIX implementations.  I jsut called them File IDs for a more uniform
naming mechanism throughout the OS.  :)
They are used to point to a given file on a given device, assigned
with an assign command:

	FileID=Assign("FILENAME", DEVICEID)

where a -1 is returned if the file was not found or the device was 
inaccessible.
For a descritpion of the DEVICEIDs , see the DID section, next.

After assigning a FID, it can then be used to transfer files between
the calculator and a device.  
Note: if you wish to create a file, you 
can do so and create a FID to it with the following command:

	FileID=CreateFile("FILENAME", DEVICEID)

This will only work, however, if the file does not alreeady exist and
the device is accessible.  otherwise it returns a -1.

Device IDs (DID)
================
These are IDs assigned to a device so that you can access it with 
communications functions.  These must be assigned before you can use 
them.  The E2 is assigned during kernal initialization, but for mapped
module port use, they msut be assigned.  
	
	DeviceID=AssignDeviceTIOS(TIOSmap#toassign)
	
This assigns a TIOS device (usually a calculator) hooked to the mod
port.  When the mod port is mapped with the mapmodport function, you 
must then use the assigndeviceTIOS fucntion before you can use TIOS
ports on the module port.
similaritly for I2C ports:
	
	DeviceID=AssignDeviceI2C(I2Cmap#toassign,busaddress)

the bus address is the address assigned to the I2C port # you are 
trying to assign.
These functions return -1 if the device is unreachable.  (They are 
pinged before use)


Arena Header Block (AHB)
========================
This is the 4-6 byte block in the beginning of each arena allocated by
the DHOS arena system. it is just the preliminary design, and so may
be modified to support later features.

len	Offs	descript
byte	00	The AID.  Assigned on allocation of arena
word	01	the size of the arena. does not included the AHB
byte	03	the OID1.  if it is a spawned process arena, it is the
		permissions byte:	FF=permissions=0 (not access
		to owner arenas allowed to child)
		FE=permissions=1 (child access to owner arenas allowed)
--------------------End of AHB unless OID1 is FF or FE
byte	04	the PID.  If it is a spawned process arena, this 
		contains the process ID for the arena. otherwise, this
		does not exist
byte 	05	the OID2.  if it is a child process, it is the process'
		owner id.  
--------------------End of AHB if OID1 is FF or FE

Well, thats about it for now.
I will release another document describing further indepth the BSL
[Bootstrap Loader] perhaps tomorrow or the next day.
I will also update the fUnctions document as soon as i can to include
these new functions.  Please check back within a day or two.

also, the OFFICIAL DHOS WEBSITE IS UP!!!!  has been for a few days.
its pretty neat.  check it out at:  http://members.xoom.com/e2os/
note that the webmaster says it will only work with NEtscape and IE.
It may crash if you dont have one of these browsers.
The infosite will continued to release information concerning the DHOS,
but it may be scaled down a bit to make access easier, since the main 
site is now at xoom.
Thank you, 
Jonathan Kaus