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 ... ]
C synopsis target-domain sourced in xdc/runtime/Registry.xdc
#include <xdc/runtime/Registry.h>
Functions
Bool 
CString 
Bool 
Functions common to all target modules
Typedefs
typedef Types_RegDesc 
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:
  1. a fixed configuration environment where modules are registered via Registry_addModule(), or
  2. 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

C synopsis target-domain
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

C synopsis target-domain
typedef Types_RegDesc Registry_Desc;
 
 
Registry_addModule()  // module-wide

Add a runtime module to the registry with the specified name

C synopsis target-domain
Registry_Result Registry_addModule(Registry_Desc *desc, CString modName);
 
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

C synopsis target-domain
Registry_Desc *Registry_findById(Types_ModuleId mid);
 
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

C synopsis target-domain
Registry_Desc *Registry_findByName(CString modName);
 
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

C synopsis target-domain
Bool Registry_getMask(CString name, Types_DiagsMask *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

C synopsis target-domain
Types_ModuleId Registry_getModuleId(Registry_Desc *desc);
 
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

C synopsis target-domain
CString Registry_getModuleName(Registry_Desc *desc);
 
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

C synopsis target-domain
Registry_Desc *Registry_getNextModule(Registry_Desc *desc);
 
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

C synopsis target-domain
Bool Registry_isMember(Types_ModuleId mid);
 
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

C synopsis target-domain
Types_ModuleId Registry_Module_id();
// Get this module's unique id
 
Bool Registry_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Registry_Module_heap();
// 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
 
Configuration settings sourced in xdc/runtime/Registry.xdc
var Registry = xdc.useModule('xdc.runtime.Registry');
module-wide constants & types
    values of type Registry.Result// Status codes
        const Registry.ALLOC_FAILED// reserved;
module-wide config parameters
 
 
enum Registry.Result

Status codes

Configuration settings
values of type Registry.Result
    const Registry.SUCCESS;
    // The module was added successfully
    const Registry.ALLOC_FAILED;
    // reserved
    const Registry.ALREADY_ADDED;
    // The module has already been added or another module with the same name is present
    const Registry.ALL_IDS_USED;
    // No more module ids available for new modules
 
C SYNOPSIS
 
metaonly config Registry.common$  // module-wide

Common module configuration parameters

Configuration settings
Registry.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Thu, 23 May 2019 00:24:46 GMT