| General Info | |
|
Interface: UserSpaceManager Files: userspacemanager.h Last change: 08/06/2003 Author: Luiz Henrique Shigunov |
Description
Structures Configuration |
| System Functions | |
|
0x0a - Brk - Set heap break point 0x00 - CopyFromUser - Copy data from user space 0x01 - CopyToUser - Copy data to user space 0x02 - Exit - End a program 0x03 - MapStackPages - Map pages with arguments of a program |
0x04 - RegisterLoader - Register an executable loader 0x05 - Run - Run a program 0x06 - StrLen - Get the size of a string in user space 0x07 - StrNCopy - Copy a string from user space 0x08 - UnregisterLoader - Unregister an executable loader |
| User Functions | |
|
0x0b - UBrk - Set heap break point |
0x09 - URun - Run a program |
This page describes the UserSpaceManager interface which provides functions to interact with user memory space, execute programs and is also responsible for starting the first program.
A module that implements this interface must generate events defined in UserSpaceManagerE interface.
typedef struct {
unsigned int exitType;
unsigned int exitCode;
} UserSpaceManager_ExitInfo;
This structure is used by the TaskDestroyed event of the UserSpaceManagerE interface to tell why the task was destroyed.
exitType can be:
exitCode is the exit code of the task when exitType is UserSpaceManager_TASK_EXITED or has these values if itīs UserSpaceManager_TASK_DUMPED:
typedef struct {
FSManager_Handle *fd;
char fileBuf[128];
unsigned int stackTop;
unsigned int argc;
unsigned int envc;
unsigned int exec;
unsigned int stackSize;
unsigned int startBrk;
} UserSpaceManager_ExecInfo;
This structure is used by modules that implement the ExecLoader interface.
fd is the file descriptor of the executable and fileBuf has the first 128 bytes of the executable to allow it identification.
stackTop has the stack top, argc the number of arguments in the stack and envc the number of environment variables in the stack.
exec points to the pathname of the executable and stackSize has the size in bytes of the stack with the arguments.
startBrk must be set to the start of the task heap and must be multiple of 0x1000.
stackTop and exec only point to the stack in user memory space after the function MapStackPages is called.
This interface defines the following groups and keys available using the CfgManager interface:
| /system/UserSpaceManager/init | ||
|
This group contains information about the first program to be executed and has this keys:
For example: path = /exec/shell.mod | ||
| /system/UserSpaceManager/init/input | ||
|
The implementations of the InputDev interface that should be registered as input devices for the first program are stored in this group. Each implementation has a group inside this group which has these keys:
For example:
| ||
| /system/UserSpaceManager/init/output | ||
|
The implementations of the OutputDev interface that should be registered as output devices for the first program are stored in this group. Each implementation has a group inside this group which has these keys:
For example:
| ||
| /system/UserSpaceManager/loader | ||
|
This group stores information about executable loaders. Each module must have a group with the following keys:
For example:
Group /system/UserSpaceManager/loader/elf, keys:
| ||
These functions are exclusive for system modules.
void *UserSpaceManager_Brk(void *addr);
This function sets heap break point to addr.
This way, the area till addr, not including addr, can be used by the task.
addr is round up to a system page (4096 bytes).
If it isn't possible to change, this function returns the old value.
A pointer to the heap break point.
int UserSpaceManager_CopyFromUser(void *dst, const void *src, unsigned int size);
This function copies size bytes from src into dst.
src must be inside user memory space.
int UserSpaceManager_CopyToUser(void *dst, const void *src, unsigned int size);
This function copies size bytes from src in dst.
dst must be inside user memory space.
int UserSpaceManager_Exit(TaskManager_Task *task, unsigned int exitType, unsigned int exitCode);
This function ends execution of the program task with the exit type exitType and the exit code exitCode see UserSpaceManager_ExitInfo.
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.
int UserSpaceManager_MapStackPages(UserSpaceManager_ExecInfo *exec, char *stack, unsigned int size);
This function maps the pages with arguments of the program into the caller task.
The pages are mapped at stack which has size bytes.
stack must have been allocated using the function AllocUserPages.
This function is used by modules that implement the ExecLoader interface to allow the access to the arguments that will be passed to a program.
stack must be big enough to map all the pages with arguments, that is, must have at least the size specified in the field stackSize of exec.
int UserSpaceManager_RegisterLoader(const char *imp, int prop);
This function registers the executable loader that has the name of the implementation imp of the ExecLoader interface.
prop must be 0 or:
int UserSpaceManager_Run(const char *pathname, char *const argv[], char *const envp[], int prop, TaskManager_Task **task, TaskManager_Thread **thread);
This function executes the program pathname.
argv is an array of argument strings passed to the program. envp is an array of strings, conventionally of the form key=value, which are passed as environment to the program. Both, argv and envp must be different than NULL and must terminated by a null pointer.
prop must be 0 or:
In case of success, task will contain the task handle and thread the thread handle and thread will be undestroyable. The caller is responsable for setting it destroyable.
int UserSpaceManager_StrLen(const char *str, unsigned int *size);
This function gets the size of str and puts in size not including the terminating `\0'.
str must be inside user memory space.
int UserSpaceManager_StrNCopy(char *dst, const char *str, unsigned int n, unsigned int *size);
This function copies no more than n bytes from string str in dst and puts in size the number of bytes copied not including the terminating `\0'.
The copy will end if string end is found.
str must be inside user memory space.
int UserSpaceManager_UnregisterLoader(const char *imp, int prop);
This function unregisters the executable loader that has the name of the implementation imp of the ExecLoader interface.
prop must be 0 or:
Only an unused loader can be unregistered.
These functions were designed for user modules.
void *UserSpaceManager_UBrk(void *addr);
User modules
This function sets heap break point to addr.
This way, the area till addr, not including addr, can be used by the task.
addr is round up to a system page (4096 bytes).
If it isn't possible to change, this function returns the old value.
A pointer to the heap break point.
int UserSpaceManager_URun(const char *pathname, char *const argv[], char *const envp[]);
User modules
This function executes the program pathname.
The program will start execution immediatly.
argv is an array of argument strings passed to the program. envp is an array of strings, conventionally of the form key=value, which are passed as environment to the program. Both, argv and envp must be different than NULL and must terminated by a null pointer.