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

Description

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.

Structures

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.

Configuration

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:

  • path - full pathname to the module file
  • prop - module's properties

Module's properties should be 0x0 or the sum of:

  • 0x02 - Module of type automatic start

Some examples:
Group /system/SysModManager/modules/sysmodmanager, keys:

  • path = /system/modules/sysmodmanager.mod
  • prop = 0x02

Group /system/SysModManager/modules/cfgmanager, keys:
  • path = /system/modules/cfgmanager.mod
  • prop = 0x0

0x00 - Broadcast

Syntax

void SysModManager_Broadcast(const char *interface, unsigned int function, void *param1, void *param2);

Properties

Description

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.

Return value

Nothing.

0x02 - DebugMsg

Syntax

void SysModManager_DebugMsg(const char *format, ...);

Properties

Description

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.

Return value

Nothing.

0x01 - DelModInfo

Syntax

void *SysModManager_DelModInfo(SysModManager_Module *module, SysModManager_Module *which);

Properties

Description

This function removes information about which from module structure.

Return value

A pointer to the information or NULL in case of error.

0x05 - GetFunction

Syntax

void *SysModManager_GetFunction(SysModManager_Imp *imp, unsigned int function, int prop, int *words);

Properties

Description

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.

Return value

Use the macros IS_PTR_ERROR and PTR_TO_ERROR to know whether an error occurred and to get the error.

0x07 - GetFunctionInfoIndex

Syntax

int SysModManager_GetFunctionInfoIndex(SysModManager_Imp *imp, unsigned int index, SysModManager_FunctionInfo *info, void *data, unsigned int size);

Properties

Description

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.

Return value

0x0c - GetImpID

Syntax

SysModManager_Imp *SysModManager_GetImpID(const char *interface, const char *imp);

Properties

Description

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.

Return value

Use the macros IS_PTR_ERROR and PTR_TO_ERROR to know whether an error occurred and to get the error.

0x0d - GetImpInfo

Syntax

int SysModManager_GetImpInfo(SysModManager_Imp *imp, SysModManager_ImpInfo *info, void *data, unsigned int size);

Properties

Description

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.

Return value

0x0e - GetImpInfoIndex

Syntax

int SysModManager_GetImpInfoIndex(SysModManager_Interface *interface, unsigned int index, SysModManager_ImpInfo *info, void *data, unsigned int size);

Properties

Description

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.

Return value

0x13 - GetInterID

Syntax

SysModManager_Interface *SysModManager_GetInterID(const char *interface);

Properties

Description

This function gets the ID of interface.

interface cannot be NULL.

Return value

Use the macros IS_PTR_ERROR and PTR_TO_ERROR to know whether an error occurred and to get the error.

0x0f - GetInterInfo

Syntax

int SysModManager_GetInterInfo(SysModManager_Interface *interface, SysModManager_InterInfo *info, void *data, unsigned int size);

Properties

Description

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.

Return value

0x10 - GetInterInfoIndex

Syntax

int SysModManager_GetInterInfoIndex(unsigned int index, SysModManager_InterInfo *info, void *data, unsigned int size);

Properties

Description

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.

Return value

0x06 - GetModInfo

Syntax

void *SysModManager_GetModInfo(SysModManager_Module *module, SysModManager_Module *which);

Properties

Description

This function gets a pointer to which data from module structure.

Return value

A pointer to the data or NULL in case of error.

0x11 - GetModuleInfo

Syntax

int SysModManager_GetModuleInfo(SysModManager_Module *module, SysModManager_ModuleInfo *info, void *data, unsigned int size);

Properties

Description

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.

Return value

0x12 - GetModuleInfoIndex

Syntax

int SysModManager_GetModuleInfoIndex(unsigned int index, SysModManager_ModuleInfo *info, void *data, unsigned int size);

Properties

Description

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.

Return value

0x03 - PutImpID

Syntax

int SysModManager_GetImpID(SysModManager_Imp *imp);

Properties

Description

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.

Return value

0x08 - Register

Syntax

int SysModManager_Register(const char *path, int prop);

Properties

Description

This function registers module path.

prop has this format:

Return value

0x09 - SetModInfo

Syntax

int SysModManager_SetModInfo(SysModManager_Module *module, SysModManager_Module *which, void *info, int prop, void **prev);

Properties

Description

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.

Return value

0x0a - StartModule

Syntax

int SysModManager_StartModule(unsigned int function);

Properties

Description

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);

Return value

0x0b - Unregister

Syntax

int SysModManager_Unregister(const char *path, int prop);

Properties

Description

This function unregister module path. Only modules that aren't in use can be unregistered.

prop has this format:

Return value