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 | |
| |
CString | |
| |
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
diagnostics mask for the runtime control of logging across all legacy C
code. The
Registry module allows legacy C code to have the same granular
control over logging as statically defined RTSC modules.
To use the Registry module, 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
module 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:
- a fixed configuration environment where modules are registered
via Registry_addModule(), or
- a "normal" configurable environment in which this code is
assumed to be part of the Main module.
The
Registry_Desc structure must then be registered by calling
Registry_addModule(). 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 mainDesc
#include <xdc/runtime/Registry.h>
//Declare the Registry_Desc object, the name is unimportant
Registry_Desc mainDesc;
Int main(Int argc, String argv[]) {
//Register this file as a module "main"
Registry_addModule(&mainDesc, "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 diagnostic mask. The bits of this mask can be set using
Diags_setMask.
Continuing the previous example:
//Initialize the legacy code's diags mask to enable USER1.
Diags_setMask("main=1");
}
All events logged by registered modules will be sent to the logger
configured for the Registry module. For example, to configure the
logger for use by all modules managed by Registry:
Registry.common$.logger = LoggerBuf.create();
Since the registered modules are not known until runtime, it is not
possible to statically configure the diagnostics masks for individual
registered modules. However, it is possible to configure diagnostics
categories to be permanently off or on for ALL registered modules. This
is done by configuring the diagnostic mask for the
Registry module.
Diagnostic categories set to
Diags.ALWAYS_OFF
will be permanently off for all
Registry modules. Categories set to
Diags.ALWAYS_ON will be permanently on for all
modules managed by
Registry.
In order to enable runtime configuration of individual
Registry module
masks, all relevant diagnostic categories must be set to
Diags.RUNTIME_OFF or
Diags.RUNTIME_ON in the
Registry module's
mask.
enum Registry_Result |
|
Status codes
typedef enum Registry_Result {
Registry_SUCCESS,
// The module was added successfully
Registry_ALLOC_FAILED,
// reserved
Registry_ALREADY_ADDED,
// The module has already been added or another
module with the same name is present
Registry_ALL_IDS_USED
// No more module ids available for new modules
} Registry_Result;
typedef Registry_Desc |
|
Registry module descriptor
Registry_addModule() // module-wide |
|
Add a runtime module to the registry with the specified name
ARGUMENTS
desc
non-NULL pointer to a {#Desc Registry_Desc}
structure.
modName
non-NULL string name of the module being registered.
DETAILS
The desc parameter and the modName string provided must both be
permanent since the Registry will maintain references to both of
these.
RETURNS
Registry_addModule returns one of the following
Result status values indicating success or the
cause of failure:
Registry_findById() // module-wide |
|
Find registered module's descriptor from its module ID
ARGUMENTS
mid
any module id
RETURNS
If the ID
mid is registered via
Registry_addModule(), this function
returns the pointer to the registered
Registry_Desc structure;
otherwise it returns
NULL.
Registry_findByName() // module-wide |
|
Find the registered module with the given name
ARGUMENTS
modName
non-NULL string name of a registered module
RETURNS
If the name
modName is registered via
Registry_addModule(), this function
returns the pointer to the registered
Registry_Desc structure;
otherwise it returns
NULL.
Registry_getMask() // module-wide |
|
Get the specified module's diagnostic mask
ARGUMENTS
modName
non-NULL string name of a registered module
mask
non-NULL pointer to a mask to be initialized
to the the current state of the diagnostics mask
associated with modName
RETURNS
The function returns TRUE if name identifies a registered module;
otherwise, it return FALSE.
Registry_getModuleId() // module-wide |
|
Get the module id associated with a specified module descriptor
ARGUMENTS
desc
non-NULL pointer to a {#Desc Registry_Desc}
structure.
RETURNS
If the specified module descriptor has been initialized via a
successful call to
Registry_addModule(), this
function returns the module id assigned by
Registry_addModule();
otherwise, its return value is indeterminate.
Registry_getModuleName() // module-wide |
|
Get the module name associated with a specified module descriptor
ARGUMENTS
desc
non-NULL pointer to a {#Desc Registry_Desc}
structure.
RETURNS
If the specified module descriptor has been initialized via a
successful call to
Registry_addModule(), this
function returns the module name passed
Registry_addModule();
otherwise, its return value is indeterminate.
Registry_getNextModule() // module-wide |
|
Scan the current list of registered modules
ARGUMENTS
desc
optionally NULL pointer to a Registry_Desc
structure. If desc is NULL, a pointer to the
first structure is returned. If desc is non-NULL
and equal to a previous return value of this function,
a pointer to the "next" Registry_Desc structure
is returned.
DETAILS
This function used to scan the list of all Registry_Desc structures
currently being managed by the Registry module.
RETURNS
This function returns a non-NULL pointer to one of the
Registry_Desc structures added via Registry_Desc structures or
NULL in the case that
- there are no more module's in the list after desc, or
- there are no modules registered
Registry_isMember() // module-wide |
|
Determines if the specified module ID belongs to a registered module
ARGUMENTS
mid
any module id
RETURNS
This function returns TRUE if and only if the specified module id
is a valid Registry module id. It does not search registered
module ids, 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 Thu, 23 May 2019 00:24:46 GMT