[MiNT] XDD expansion proposal

["Adam Klobukowski" <atari@gabo.pl>]

Ok, I designed a special thing to add to XDD interface (two sleeples 
nights of thinking ;)

With this interface XDD will be able to register some functions in 
some apis. Eache XDD can register the same function  in the same api 
at the same time. Apis can also contain values to read.

Kernel would store a table of lists for each API. Each place in a 
table represents a function or a value. That places points to lists 
of function or value, ie a structure:

struct {
 long flags
 *void P
 long XDD;
}

flags is bitfield of: READ_ONLY, NO_MULTIPLE, VALUE
P is a pointer to a function or value, values are NO_MULTIPLE by 
default.
XDD - XDD that registered that function/value (can be KERNEL).

If a function is called and there are few XDD hooked to is, kernel 
callls them one by one as soon as one handles it.

Now, some functions:

RegisterAPI(long API_ID, long N, *void P)

Registers API function

API_ID - id of an api that function we register
N - function id
P - pointer to a function or a value.
This function must be like this:

long func(long *retval, *void p)

retval is a place where function stores it returning code, valid only 
if function return value is equal to HANDLED 
p is a pointer passed to a function. Where it points depends on 
api/function definition. Function must check for null pointers here.
func Return value: HANDLED, UNHANDLED, ...

Return value: E_OK, E_NO_MULTIPLE, E_READ_ONLY, E_WRONG_API, 
EWRONG_N, ...

UnregisterAPI(long API_ID, long N)

Unregisters api functions

API_ID - id of an api where we unregister,
N - function id

Return value: E_OK, E_NOT_REGISTERED, E_READ_ONLY, E_WRONG_API, 
E_WRONG_N, ...

CallAPI(long API_ID, long N, *void p, long *retval)

Calls API function

API_ID  - id of an api we call
p - pointer passed to a function
N - function id
retval - pointer to a return value of a function, valid only if 
return value is HANDLED

Return value HANDLED, UNHANDLED, E_WRONG_N, ...

ReadAPI(long API_ID, long N, long *retval)

Reads API value

API_ID - id of an api we read
N - value number we read
retval - pointer where to store value we read

Return value: E_OK, E_WRONG_N, E_NOT_VALUE, ...

This is how it works:

For example we do Shutdown(POWEROFF).

Shutdown code does everything it should (kill process, ...)

Then Shutdown code does CallAPI(APM_API, APM_POWEROFF, null, null)

And if it returns (becouse _this_one_ shouldnt), it means that no 
XDD registered it, so it prints "System Halted".

So we can write for example ARANYM.XDD that will register that 
function, and voila, we got poweroff under Aranym. I inted to rewrite 
CT60 code that way.

Rules of designing of good api:

First api member should be READ_ONLY VALUE that represents api 
version number, so XDD can check it and is newer or equal that XDD 
uses it can proceed, other case depends on api and XDD. Therefore as 
a GENERAL RULE: APIS SHOULD BE BACKWARDS COMPATIBILE.

--
Semper Fidelis

Adam Klobukowski
atari@gabo.pl