| General Info | |
|
Interface: SysModManager Files: sysmodmanager.h Last change: 17/01/2004 Author: Luiz Henrique Shigunov |
Description
Configuration Structures |
| Functions | |
|
0x00 - Broadcast - Call a function from every module that implements an interface 0x02 - DebugMsg - Print a debug message 0x01 - DelModInfo - Remove data in the module structure 0x05 - GetFunction - Get a function pointer 0x07 - GetFunctionInfoIndex - Get informations about a function 0x0c - GetImpID - Get an implementation ID 0x0d - GetImpInfo - Get informations about an implementation 0x0e - GetImpInfoIndex - Get informations about an implementation 0x13 - GetInterID - Get an interface ID 0x0f - GetInterInfo - Get informations about an interface |
0x10 - GetInterInfoIndex - Get informations about an interface 0x06 - GetModInfo - Get data in the module structure 0x11 - GetModuleInfo - Get informations about a module 0x12 - GetModuleInfoIndex - Get informations about a module 0x03 - PutImpID - Put an implementation ID 0x08 - Register - Register a module 0x09 - SetModInfo - Store data in the module structure 0x0a - StartModule - Start a module 0x0b - Unregister - Unregister a module |
This page describes the SysModManager interface which centralizes everything about system modules: registering, loading, starting, interfaces, implementations and functions of an interface, etc.
Interfaces and their implementations have names and is using these names that a module says it wants to use this or that interface/implementation. These names can only have characteres from the ASCII table, that is, no accents, ç, etc.
The chose for names and not numbers was because it dificults conflicts and makes unnecessary to register interfaces and implementations numbers like, for instance, with PCI device numbers that must be registered to avoid conflicts.
But functions of an interface are used by their numbers because there's no risk of conflicts and because modules that use them must know their numbers anyway.
Every name of an interface and implementation is available in a register that is used every time an interface/implementation is requested to be used and that's why system modules must be registered: to make available for others modules all functions from its implemented interfaces.
Each module must implement one or more interfaces and each interface can have more than one implementation in the same module. That is, a module can have, for instance, two implementations of the AVLTree_In interface: Implementation1 and Implementation2.
Each function of an interface can be an user or system function. User functions are accessible only by user modules and system functions are accessible only by system modules. This difference exists because usually user functions make some checks that aren't necessary when called from system modules.
To have a bigger modularity, the initialization of a module can be done in two phases: phase 0 and phase 1. In phase 0 the processor is with disabled interrupts and in phase 1 the interrupts are enabled.
Because there's two phases, each function of an interface can be available at phase 0 and others only at phase 1. If a function is available only at phase 1, it cannot be used by functions that are used at phase 0 neither by a phase 0 start function of a module.
Boths start functions must have the following syntax:
int PhaseXStart(SysModManager_Module *modID);
Where modID is the identification of the module that is beeing started. If the initialization is successful the function must return 0.
Every module that isn't dynamicly used, that is, the GetFunction function isn't used, must be started with the StartModule function before it can be used. Because it's not possible to know in which module an interface implementation is, the StartModule function receives a pointer to a function as argument. This argument must be the pointer to a function of an implementation used by the module.
The initialization of these modules must be done in the start functions because modules used by phase 0 functions must be started while in phase 0 and modules used by phase 1 functions must be started while in phase 1, that is, a module that is used by phase 0 functions must be started twice.
Some modules must be initialized even if they aren't used by a module. That's why a module can be automatic started and in this case it's initialized when the system starts.
Before a module is removed from memory, the shutdown function, if it exists, is executed. This function must free all resources used by the module and must have this syntax:
int Shutdown(void);
If the shutdown is successful, this function must return 0.
Many modules need to store informations about each module. One way to solve this would be to maintain a structure to store this data. But there's some problems with this approach, such as: more memory needed (besides the data itself a data structure is needed - linked list, tree, etc); bigger access time (you need to look for the data) and synchronization problems.
To solve this, we use a different approach: data about a module is stored in its own data structure. This way we use less memory, access time is faster and synchronization is minimized.
Some times it's necessary to signal modules that something happened. For instance: that system memory is low, that a module was shutdown, that a task was destroyed, etc.
With this information, modules could act accordly (free cache memory, close open files, etc).
To implement this idea the Broadcast function was created. This function has some interresting characteristics, such as: who sends a message doesn't know to who the message is going to; who receives doesn't know from who it comes; who receives it doesn't need to register itself. These characteristics makes this function better than register each module to receive an event.
typedef struct {
unsigned int code;
int prop;
unsigned int words;
} SysModManager_FunctionInfo;
Where code it's the start of the function code.
prop can be:
words it's the number of words of 4 bytes each that the function receives if it's a user function.
typedef struct {
SysModManager_Imp *imp;
SysModManager_Module *module;
SysModManager_Interface *interface;
char *name;
} SysModManager_ImpInfo;
Where imp it's the implementation ID, module it's the module ID, interface it's the interface ID and name it's the name of the implementation.
typedef struct {
SysModManager_Interface *interface;
unsigned int nFunctions;
char *name;
} SysModManager_InterInfo;
Where interface it's the interface ID, nFunction it's the number of functions in this interface and name the name of the interface.
typedef struct {
SysModManager_Module *module;
int prop;
unsigned int memStart;
unsigned int memSize;
unsigned int refCounter;
char *path;
unsigned int phase0Function;
unsigned int phase1Function;
unsigned int shutdownFunction;
char md5[16];
} SysModManager_ModuleInfo;
Where module it's the module ID and prop can be:
memStart and memSize it's the start and the size of the memory used by the module (code and initialized and not initialized data). Will be zero if not loaded.
refCounter it's the utilization counter of the module.
path it's the pathname of the module.
phase0Function, phase1Function and shutdownFunction are the phase 0 and phase 1 start function and the shutdown function. Will be zero if not used.
md5 it's the MD5 of the module.
This interface defines the following groups and keys available using the CfgManager interface:
| /system/SysModManager/modules | ||
|
System modules permanently registered are stored in this group. Each module has a group inside this group which has these keys:
Module's properties should be 0x0 or the sum of:
Some examples:
Group /system/SysModManager/modules/cfgmanager, keys:
| ||
void SysModManager_Broadcast(const char *interface, unsigned int function, void *param1, void *param2);
This function calls function with param1 and param2 as parameters from all modules that are already started and that implement interface.
param1 and param2 are optional, that is, they can be NULL.
void SysModManager_DebugMsg(const char *format, ...);
This function prints format in the error device, currently the device that implements VideoController interface.
format and remainder arguments are formated with function PrintFArgs from StringMan interface.
Final message length cannot be greater than 1024 bytes.
void *SysModManager_DelModInfo(SysModManager_Module *module, SysModManager_Module *which);
This function removes information about which from module structure.
A pointer to the information or NULL in case of error.
void *SysModManager_GetFunction(SysModManager_Imp *imp, unsigned int function, int prop, int *words);
This function is responsible for dynamic bind. It gets a pointer to function from imp.
The function pointer can be used while imp is not freed with PutImpID.
prop has this format:
In case of success and if function is an user function, words, if different than NULL, will have the number of words of 4 bytes that must be copied from user stack to system stack.
Use the macros IS_PTR_ERROR and PTR_TO_ERROR to know whether an error occurred and to get the error.
int SysModManager_GetFunctionInfoIndex(SysModManager_Imp *imp, unsigned int index, SysModManager_FunctionInfo *info, void *data, unsigned int size);
This function gets informations about the function index of the implementation imp.
index starts with zero and should be incremented at each function call.
The implementation imp must have been got using GetImpID.
The fields with variable size (like the name, for instance) are stored in data with has the size size. Not more than size bytes will be stored in data.
In case of success, info will have the informations.
SysModManager_Imp *SysModManager_GetImpID(const char *interface, const char *imp);
This function gets the ID of imp from interface.
While an implementation isn't freed by PutImpID function it can be used. For each GetImpID function call, one call to PutImpID must be done.
interface cannot be NULL.
But imp can be NULL and, in this case, the first implementation is used.
Use the macros IS_PTR_ERROR and PTR_TO_ERROR to know whether an error occurred and to get the error.
int SysModManager_GetImpInfo(SysModManager_Imp *imp, SysModManager_ImpInfo *info, void *data, unsigned int size);
This function gets informations about the implementation imp.
The implementation imp must have been got using GetImpID.
The fields with variable size (like the name, for instance) are stored in data with has the size size. Not more than size bytes will be stored in data.
In case of success, info will have the informations.
int SysModManager_GetImpInfoIndex(SysModManager_Interface *interface, unsigned int index, SysModManager_ImpInfo *info, void *data, unsigned int size);
This function gets informations about the implementation index of interface.
index starts with zero and should be incremented at each function call.
The fields with variable size (like the name, for instance) are stored in data with has the size size. Not more than size bytes will be stored in data.
In case of success, info will have the informations.
SysModManager_Interface *SysModManager_GetInterID(const char *interface);
This function gets the ID of interface.
interface cannot be NULL.
Use the macros IS_PTR_ERROR and PTR_TO_ERROR to know whether an error occurred and to get the error.
int SysModManager_GetInterInfo(SysModManager_Interface *interface, SysModManager_InterInfo *info, void *data, unsigned int size);
This function gets informations about interface.
The fields with variable size (like the name, for instance) are stored in data with has the size size. Not more than size bytes will be stored in data.
In case of success, info will have the informations.
int SysModManager_GetInterInfoIndex(unsigned int index, SysModManager_InterInfo *info, void *data, unsigned int size);
This function gets informations about the interface index.
index starts with zero and should be incremented at each function call.
The fields with variable size (like the name, for instance) are stored in data with has the size size. Not more than size bytes will be stored in data.
In case of success, info will have the informations.
void *SysModManager_GetModInfo(SysModManager_Module *module, SysModManager_Module *which);
This function gets a pointer to which data from module structure.
A pointer to the data or NULL in case of error.
int SysModManager_GetModuleInfo(SysModManager_Module *module, SysModManager_ModuleInfo *info, void *data, unsigned int size);
This function gets informations about module.
The fields with variable size (like the name, for instance) are stored in data with has the size size. Not more than size bytes will be stored in data.
In case of success, info will have the informations.
int SysModManager_GetModuleInfoIndex(unsigned int index, SysModManager_ModuleInfo *info, void *data, unsigned int size);
This function gets informations about the module index.
index starts with zero and should be incremented at each function call.
The fields with variable size (like the name, for instance) are stored in data with has the size size. Not more than size bytes will be stored in data.
In case of success, info will have the informations.
int SysModManager_GetImpID(SysModManager_Imp *imp);
This function puts imp ID, that is, says it won't be used anymore.
For each GetImpID function call, one call to PutImpID must be done.
int SysModManager_Register(const char *path, int prop);
This function registers module path.
prop has this format:
int SysModManager_SetModInfo(SysModManager_Module *module, SysModManager_Module *which, void *info, int prop, void **prev);
This function stores info from which into module structure.
prop says what to do if there's already data in the module structure:
If which already has data in the module structure and prop is 0, data will be overwrited and prev will point to the old data.
int SysModManager_StartModule(unsigned int function);
This function starts the module that implements function if it isn't already started.
For instance, to start IOPortManager_Alloc module do this:
StartModule((unsigned int)IOPortManager_Alloc);
int SysModManager_Unregister(const char *path, int prop);
This function unregister module path. Only modules that aren't in use can be unregistered.
prop has this format: