| General Info | |
|
Interface: UserModManager Files: usermodmanager.h Last change: 25/06/2005 Author: Luiz Henrique Shigunov |
Description
Structures Configuration |
| System Functions | |
|
0x00 - Exit - End a module execution 0x01 - Register - Register a library |
0x02 - Unregister - Unregister a library |
| User Functions | |
|
0x04 - UCatchException - Register an exception handler 0x05 - UExit - End an user module execution 0x06 - UGetFunction - Get a pointer to a function from a registered library or system module 0x07 - UGetLibFunction - Get a function from a loaded library 0x08 - UGetShutdownFunctionI - Get shutdown function pointer of a library |
0x09 - UGetStackSize - Get stack size 0x0a - UGetStartFunction - Get start function pointer of a library 0x0b - UGetStartFunctionI - Get start function pointer of a library 0x0c - ULoad - Load a library 0x0d - UUnload - Unload a library |
This page describes the UserModManager interface which provides functions to manage and use executable and library modules.
Two types of user modules exists: executable module (can be executed as a program) and library module (only provides functions for executable and library modules).
Registering a library module makes its functions available for other user modules.
A library module must implement at least one interface, each implementation with at least one function. Each implementation implements only one interface.
Interfaces and implementations are identified by a name but functions by a number.
A library module is formed by function code, read only data, initialized data and uninitialized data (they are initialized with zero).
An executable module is formed by code, read only data, initialized data and uninitialized data (they are initialized with zero).
Every library used by an executable module, staticaly or dynamicaly, must be initialized before it can be used and must be terminated before the program is terminated.
The functions UGetStartFunctionI and UGetShutdownFunctionI were made to initialize/terminate staticaly used libraries.
And the function UGetStartFunction was made to initialize dynamicaly used libraries.
The dynamicaly used libraries are terminated using function UGetShutdownFunctionI to avoid that it be terminated while still in use.
So, it's possible that the same start function be called more than once. Each library must control this.
Each system function that can be used by user modules has a number saying how many words (4 bytes) it must receive from user modules. This words are copyed from user stack into system stack when the function is called. This is the same type of parameters passing used in FreeBSD and Microsoft Windows NT.
typedef union {
InterManager_Event iEvent;
UserModManager_Events uEvent;
} UserModManager_Event;
This union is used to avoid gcc type-punned warnings. For the functions of the Intermanager interface we use iEvent but for the functions of this interface we use uEvent.
typedef struct {
unsigned int type;
union {
UserModManager_ChildEvent child;
UserModManager_TermEvent term;
};
} UserModManager_Events;
type is the event type and can be:
typedef struct {
unsigned int code;
int pid;
int exitCode
unsigned int res[4];
} UserModManager_ChildEvent;
code has the event cause:
pid is the child task ID, exitCode is the exit code of the child task if code is UserModManager_CHILD_EXITED or has these values if code is UserModManager_CHILD_DUMPED:
typedef struct {
unsigned int res[7];
} UserModManager_TermEvent;
This interface defines the following groups and keys available using the CfgManager interface:
| /system/UserModManager/modules | ||
|
Library modules permanently registered are stored in this group. Each module has a group inside this group which has these keys:
Some examples:
Group /system/UserModManager/modules/memmanager, keys:
| ||
These functions are exclusive for system modules.
int UserModManager_Exit(TaskManager_Task *task, int exitCode);
This function ends execution of the program task.
If task is NULL, ends execution of caller task.
task must be undestroyable.
Remember that a task running system code is already undestroyable. So, if task is NULL you donīt need to call UndestroyableThread and if task is not NULL it was set undestroyable or you couldnīt use task.
exitCode is the return code.
int UserModManager_Register(const char *pathname, int prop);
This function registers library pathname.
prop must be 0 or:
int UserModManager_Unregister(const char *pathname, int prop);
This function unregisters library pathname.
prop must be 0 or:
Only an unused library can be unregistered.
These functions were designed for user modules.
int UserModManager_UCatchException(void *function);
User modules
This function registers function to handle exceptions that occurs on the task.
When an exception occurs control returns to function, that is, the return EIP becomes function.
On return to function the stack will have: specific exception's data, if they exist, the address where the exception occurred and an exception code, that is, ESP points to the exception code.
This are the exceptions supported:
| Code | Meaming |
|---|---|
| 0x00 | A divide by zero occurred. |
| 0x01 | INTO instruction (overflow) was executed. |
| 0x02 | BOUND instruction detected that an array's bound was exceeded. |
| 0x03 | Invalid instruction. |
| 0x04 | Unaligned data access. |
| 0x05 | Memory access violation.
This exception put this values in the stack: the address that caused the access violation and an int saying if it was a write attempt (different from 0) or a read attempt (0). |
It's the program responsability to fix the stack to continue executing.
If a handler isn't set, program terminates.
To remove the handler just call the function with NULL.
void UserModManager_UExit(int exitCode);
User modules
This function terminates execution of caller user module and sets return code to exitCode.
void *UserModManager_UGetFunction(const char *interface, const char *imp, unsigned int function, int type);
User modules
This function gets a pointer to function from implementation imp from interface of a registered library module or system module.
type must be:
The function from the system module must be a user function.
Use the macros IS_PTR_ERROR and PTR_TO_ERROR to know whether an error occurred and to get the error.
void *UserModManager_UGetLibFunction(UserModManager_Library *lib, const char *interface, const char *imp, unsigned int function);
User modules
This function gets a pointer to function from implementation imp from interface from lib.
lib is a library loaded by Load function.
Use the macros IS_PTR_ERROR and PTR_TO_ERROR to know whether an error occurred and to get the error.
void *UserModManager_UGetShutdownFunctionI(unsigned int index);
User modules
This function gets shutdown function pointer from a library.
index should be zero in the first call and incremented each time the function is called.
If the library doesn't has a shutdown function, this function returns 0xffffffff.
Before a program ends shutdown function of every staticaly used library must be called. For instance:
i = 0;
while ((shutdown = UserModManager_UGetShutdownFunctionI(i++))) {
if ((unsigned int)shutdown != 0xffffffff)
shutdown();
}
The function pointer or NULL in case of error.
unsigned int UserModManager_UGetStackSize(void);
User modules
This functions gets the size of the stack in bytes that is allocated when the first thread of the task is created.
The return value is a power of 2.
The size of the stack in bytes.
void *UserModManager_UGetStartFunction(void *function);
User modules
This function gets start function pointer from the library that implements function.
If the library doesn't has a start function, this function returns NULL.
Before a dynamicaly used library can be used the start function must be called. For instance:
start = UserModManager_UGetStartFunction(MyLibrary_Func1);
if (start)
start();
This function must be used to initialize library modules that were dynamicaly used.
The function pointer or NULL in case of error.
void *UserModManager_UGetStartFunctionI(unsigned int index);
User modules
This function gets start function pointer from a library.
index should be zero in the first call and incremented each time the function is called.
If the library doesn't has a start function, this function returns 0xffffffff.
Before a staticaly used library can be used the start function must be called. For instance:
i = 0;
while ((start = UserModManager_UGetStartFunctionI(i++))) {
if ((unsigned int)start != 0xffffffff)
start();
}
The function pointer or NULL in case of error.
int UserModManager_ULoad(const char *pathname, UserModManager_Library **lib);
User modules
This function loads library pathname.
Initialization, if needed, must be done by who use it.
If all goes ok, lib will contain the library ID.
int UserModManager_UUnload(UserModManager_Library *lib);
User modules
This function unloads library lib.