Gauntlet/docs/Syscall_ABI
Created by Adam Wiggins: 07/09/1999
Last Modified by Adam Wiggins: 21/10/1999
Current Syscall Application Binary Interface

**********
* Common *
**********

- Syscall Numbers are passed in r0.
- Unless otherwise stated all registers less the user_sp are undefined on return

**************
* Data Types *
**************

Unique Ids:
	-thread id:    version (14), task (10), thread (8)
	-task id:      version (14), task (10), 0's (8)
	-interrupt id: 1's (24), interrupt (8)
	-nil id:       0's (32)
        -invalid id:   1's (32)
	*Task 1023 is reserved for the kernel

*******
* IPC *
*******

Register Allocation:
             0 | r0             r0 | ~                 / ~
          dest | r1             r1 | ~                 / ~
snd descriptor | r2             r2 | source            / ~
rcv descriptor | r3 --- SWI --> r3 | msg.dope + cc     / cc
      timeouts | r4             r4 | ~                 / ~
           msg | r5 - r12 r5 - r12 | msg               / ~
   ~ / virtual | user_lr   user_lr | ~

Parameters:
	snd descriptor:
		- "nil" (0xFFFFFFFF), No Send.
		- "mem" (snd msg/4, 30 bits. m bit. p bit), Memory Send
		- "reg" (0, 31 bits. p bit), Short Send
		* m = 0, Long Send. m = 1 Fpage Mapping
		* p = 0, No Propagate. p = 1 propagate, user_r14 is propagatee
	rcv descriptor:
		- "nil" (0xFFFFFFFF), No Receive
		- "mem" (rcv msg/4, 30 bit. 0 bit. o bit), Long Receive
		- "reg" (0, 31 bits. o bit), Short Receive
		- "rmap" (fcv fpage), Fpage Receive or Short Receive (diff?)
		* o = 0, Closed wait. o = 1, open wait
	virtual :
		- Virtual Senders TID if deceiving
	dest id:
		- !=nil, dest thread 
		- =nil, send generates error. receive sleeps for timeout
	source id:
		- If msg received contains id of sender
	msg:
		- "snd" First 8 words of msg to be sent
		- "rcv" First 8 words of received msg
	msg.dope + cc:
		- cc is standard, clear up rest with Jochen!

**************
* id_nearest *
**************
Register Allocation:
             1 | r0             r0 | ~
       dest id | r1 --- SWI --> r1 | type
             ~ | r2             r2 | nearest id

Parameters:
	dest id:
		- =nil, get threads own id
		- !=nil, get id of thread ipc would send to
	type:
		=0 dest in same clan
		=C dest in inner clan
		=4 dest in outer clan
	neaarest id:
		- Actual id of dest id 

	NOTE: Currently returns INVALID_TID if not the get_my_id case

***************
* fpage_unmap *
***************
Register Allocation:
             2 | r0             r0 | ~
         fpage | r1 --- SWI --> r1 | ~
      map mask | r2             r2 | ~

Parameters:
	fpage:
		- fpage to be unmapped
	map mask:
		- (f bit. 0, 29 bits. w bit. 0 bit)
		* w = 0, partial (read only unmap). w = 1 total unmap
		* f = 0, unmap mappee's only. f = 1 unmap caller/mappee's

*****************
* thread_switch *
*****************
Register Allocation:
             3 | r0             r0 | ~
       dest id | r1 --- SWI --> r1 | ~

Parameters:
	dest id:
		- =nil, Schedule next thread
		- !=nil, if dest id ready donate remainning timeslice,
		otherwise as =nil

*******************
* thread_schedule *
*******************
Register Allocation:
             4 | r0             r0 | ~
       dest id | r1             r1 | time high
    param word | r2 --- SWI --> r2 | time low
             ~ | r3		r3 | old param word
             ~ | r4             r4 | partner 		

Parameters:
	dest id:
		- Must be a valid thread and running at a priority less then 
                or equal to calling thread otherwise dest thread is unaffected
                and all results invalid except for old param word
	param word:
		- New scheduling perameters
		- (mt, 8 bits. et, 4 bits. 0, 12 bits. prio 8 bits)
		  * mt/et (timeslice)
		  * prio = Priority
	old param word:
		- Old scheduling perameters
		- (mt, 8 bits. et, 4 bits. ts, 4 bits. 0, 12 bits. prio 8 bits)
		  * ts = thread state
	partner:
		- Partner thread is currently in IPC operation with (if in IPC)
		0xFFFFFFFF recieved if thread in open wait IPC state
	time:
		- Work out later

         
******************
* lthread_ex_reg *
******************
Register Allocation:
             5 | r0             r0 | ~
    lthread no | r1             r1 | old SP
            SP | r2             r2 | old PC
            PC | r3 --- SWI --> r3 | old pager tid
     pager tid | r4             r4 | old excpt tid
     excpt tid | r5             r5 | old CPSR

Parameters:
	lthread no:
		- (0, 24 bits. lthread, 8 bits), thread of current task
	SP:
		- "invalid", SP not modified
		- "valid", New SP
	PC:
		- "invalid", PC not modified
		- "valid", New PC
	pager tid:
		- "invalid", pager unchanged
		- "valid", New pager tid
	excpt tid:
		- "invalid", excpt tid unchanged
		- "valid", New excpt tid
	old CPSR:
		- Flags of thread. (Can find out if thread was in the kernel or
not)
	old ... :
		- old values of these parameters

	Note: Non-destructive lthread_ex_regs on threads in the kernel leaves 
	      them executing in the kernel. Descructive lthread_ex_regs aborts
              an IPC (other kernel calls must reach a consistant state) and 
              returns the relavent error code. Descructive lthread_ex_regs is
              one that effects the SP or PC.

************
* task_new *
************
Register Allocation:
             6 | r0             r0 | ~
     dest task | r1             r1 | new task id
 mcp/new chief | r2             r2 | ~
            SP | r3 --- SWI --> r3 | ~
            PC | r4             r4 | ~
     pager tid | r5             r5 | ~
     excpt tid | r6             r6 | ~ 

Parameters:
	dest task:
		- Task id of 'creatable' task
	pager tid:
		- =nil, inactive task (task deleted if active, new cheif set)
		- !=nil, pager tid of activated task (deleted first if active)
	excpt tid:
		- =nil, ?
		- !=nil, excpt tid of activated task
	SP:
		- SP of lthread 0
	PC:
		- PC of lthread 0 
	mcp:
		- mcp of task
	new cheif:
		- new cheif of task
	new task id:
		- !=nil, task id of new task (succeded)
		- =nil, syscall failed
