module xdc.runtime.Registry

C synopsis
Individual elements
XDCscript usage
Individual elements

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
Registry_Result	Registry_addModule// Add a runtime module to the registry with the specified name(Registry_Desc *desc, String modName);
Registry_Desc *	Registry_findById// Find registered module's descriptor from it's module ID(Types_ModuleId mid);
Registry_Desc *	Registry_findByName// Find the registered module with the given name(String name);
Bool	Registry_getMask// Get the named registered module's diagnostic mask(String name, Types_DiagsMask *mask);
Types_ModuleId	Registry_getModuleId// Get the module id associated with this module descriptor(Registry_Desc *desc);
Char *	Registry_getModuleName// Get the module name associated with this module descriptor(Registry_Desc *desc);
Registry_Desc *	Registry_getNextModule// API for walking the list of modules in the Registry(Registry_Desc *desc);
Bool	Registry_isMember// Determines if the specified module ID belongs to a registered module(Types_ModuleId mid);
Functions common to all target modules
	Registry_Module_getMask// Returns the diagnostics mask for this module, Registry_Module_hasMask// Test whether this module has a diagnostics mask, Registry_Module_heap// The heap from which this module allocates memory, Registry_Module_id// Get this module's unique id, Registry_Module_setMask// Set the diagnostics mask for this module, Registry_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Types_RegDesc	Registry_Desc// Registry module descriptor;
typedef enum	Registry_Result// Status code returned from addModule ...

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

index URL

Status code returned from addModule

C synopsis target-domain

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

index URL

Registry module descriptor

C synopsis target-domain

typedef Types_RegDesc Registry_Desc;

Registry_addModule() // module-wide

index URL

Add a runtime module to the registry with the specified name

C synopsis target-domain

Registry_Result Registry_addModule(Registry_Desc *desc, String modName);

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

index URL

Find registered module's descriptor from it's module ID

C synopsis target-domain

Registry_Desc *Registry_findById(Types_ModuleId mid);

Registry_findByName() // module-wide

index URL

Find the registered module with the given name

C synopsis target-domain

Registry_Desc *Registry_findByName(String name);

Registry_getMask() // module-wide

index URL

Get the named registered module's diagnostic mask

C synopsis target-domain

Bool Registry_getMask(String name, Types_DiagsMask *mask);

Registry_getModuleId() // module-wide

index URL

Get the module id associated with this module descriptor

C synopsis target-domain

Types_ModuleId Registry_getModuleId(Registry_Desc *desc);

Registry_getModuleName() // module-wide

index URL

Get the module name associated with this module descriptor

C synopsis target-domain

Char *Registry_getModuleName(Registry_Desc *desc);

Registry_getNextModule() // module-wide

index URL

API for walking the list of modules in the Registry

C synopsis target-domain

Registry_Desc *Registry_getNextModule(Registry_Desc *desc);

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

index URL

Determines if the specified module ID belongs to a registered module

C synopsis target-domain

Bool Registry_isMember(Types_ModuleId mid);

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

index URL

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

XDCscript usage meta-domain sourced in xdc/runtime/Registry.xdc

var Registry = xdc.useModule('xdc.runtime.Registry');

module-wide constants & types

values of type Registry.Result// Status code returned from addModule

const Registry.SUCCESS;

const Registry.ALLOC_FAILED;

const Registry.ALREADY_ADDED;

const Registry.ALL_IDS_USED;

module-wide config parameters

Registry.common$// Common module configuration parameters = Types.Common$ undefined;

enum Registry.Result

index URL

Status code returned from addModule

XDCscript usage meta-domain

values of type Registry.Result

const Registry.SUCCESS;

const Registry.ALLOC_FAILED;

const Registry.ALREADY_ADDED;

const Registry.ALL_IDS_USED;

DETAILS

C SYNOPSIS

Registry_Result

metaonly config Registry.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

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 Tue, 24 Aug 2010 15:39:41 GMT