module xdc.runtime.Registry |
|
|
|
Register modules that are not statically configured
This module provides a mechanism by which legacy C code can have its own
module logging support, including having a name and its own diags mask.
[
more ... ]
#include <xdc/runtime/Registry.h>
Functions |
| |
| |
| |
Bool | |
| |
Char * | |
| |
Bool | |
Functions common to all target modules |
|
|
Typedefs |
| |
typedef enum | |
DETAILS
This module provides a mechanism by which legacy C code can have its own
module logging support, including having a name and its own diags mask.
Without the Registry, all logging done by legacy C code is handled by the
xdc.runtime.Main module. This means that all log events will be marked as
coming from "xdc.runtime.Main", and there is only a single diags mask for
controlling logging across all legacy C code. The Registry module addresses
this and allows legacy C code to have the same granular control over
logging as statically defined RTSC modules.
To use the Registry, legacy code must define the symbol Registry_CURDESC
to be the name of an externally declared Registery_Desc structure.
This symbol must be defined before the inclusion of any xdc/runtime header
files. If any xdc/runtime header files are included before the definition
of this symbol, the Registry may not function properly.
Note: by defining this symbol on the compile line, rather than in the
file, one can easily compile code to be used in one of two environments:
1. a fixed configuration environment where moudles are registered
via Registry_addModule(), or
2. a "normal" configurable environment in which this code is
assumed to be part of the xdc.runtime.Main module.
The
Registry_Desc structure must then register by calling the
'
addModule' API. The structure is typically registered and
initialized within
main().
For example:
//Define the required symbol, Registry_CURDESC, to this file's
//Registry_Desc object
#define Registry_CURDESC main_desc
#include <xdc/runtime/Registry.h>
//Declare the Registry_Desc object, the name is unimportant
Registry_Desc main_desc;
Int main(Int argc, String argv[]) {
//Register this file as a module "main"
Registry_addModule(&main_desc, "main");
Once registered, the legacy code may call log APIs without any other change
and the formatted log events will show as coming from the registered
modules. Also, the logging by the legacy code is now filtered by its own
diags mask. The bits of this mask can be set using the Diags_setMask API.
Continuing the previous example:
//Initialize the legacy code's diags mask to enable USER1.
Diags_setMask("main=1");
All events logged registered modules will be sent to the logger configured
for the Registry module. For example, to configure the logger for use by
all modules in the Registry:
Registry.common$.logger = LoggerBuf.create();
There is no way to statically configure the diags masks for individual
registered modules, since the registered modules are not known until
runtime. However, it is possible to configure diags categories to be
permanently off or on for ALL registered modules. This is done by
configuring the diags mask for the xdc.runtime.Registry module. Diags
categories set to ALWAYS_OFF will be permanently off for all Registry
modules. Categories set to ALWAYS_ON will be permanently on for all
Registry modules.
In order to enable runtime configuration of individual Registry module
masks, all relevant diags categories must be set to RUNTIME_OFF or
RUNTIME_ON in the Registry module's mask.
enum Registry_Result |
|
Status code returned from addModule
typedef enum Registry_Result {
Registry_SUCCESS,
Registry_ALLOC_FAILED,
Registry_ALREADY_ADDED,
Registry_ALL_IDS_USED
} Registry_Result;
DETAILS
SUCCESS - The module was added successfully.
ALLOC_FAILED - Unused.
ALREADY_ADDED - The module has already been added or another module
with the same name is present. The Registry will not
be modified.
ALL_IDS_USED - There are no more module ids available for new modules.
There are a total of 16,384 - 1 module ids available for
use by the Registry.
typedef Registry_Desc |
|
Registry module descriptor
Registry_addModule() // module-wide |
|
Add a runtime module to the registry with the specified name
DETAILS
The 'desc' parameter and the 'modName' string provided must both be
permanent since the Registry will maintain references to both of these.
Returns a status code indicating success or the cause of failure. See
Result for details.
Registry_findById() // module-wide |
|
Find registered module's descriptor from it's module ID
Registry_findByName() // module-wide |
|
Find the registered module with the given name
Registry_getMask() // module-wide |
|
Get the named registered module's diagnostic mask
Registry_getModuleId() // module-wide |
|
Get the module id associated with this module descriptor
Registry_getModuleName() // module-wide |
|
Get the module name associated with this module descriptor
Registry_getNextModule() // module-wide |
|
API for walking the list of modules in the Registry
DETAILS
This API retrieves the next module in the Registry's module list. To
get the head of the list, pass NULL. This API returns NULL when there
are no more module's in the list.
Registry_isMember() // module-wide |
|
Determines if the specified module ID belongs to a registered module
DETAILS
This function returns TRUE if and only if the specified module id
is a valid Registry module id. It does not search the Registry for the
module id, but simply checks if the id is within the range of valid
Registry module ids.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Registry_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Registry_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Registry_Module_getMask();
// Returns the diagnostics mask for this module
Void Registry_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
var Registry = xdc.useModule('xdc.runtime.Registry');
module-wide constants & types
module-wide config parameters
generated on Fri, 25 Jun 2010 22:40:34 GMT