\#include "mm.h"
void
MM_init(char * pApplicationEntityInstanceName);
ReturnCode
MM_registerModule(char * pModuleName,
void ** phModule);
ReturnCode
MM_registerManagableEntity(void * hModule,
MM_ManagableEntityType managableEntityType,
char * pManagableEntityName,
char * pIdentificationMessage,
OS_Uint16 initialNotifyMask,
void ** phManagableEntity);
ReturnCode
MM_setThreshold(void * hManagableEntity,
MM_ThresholdType thresholdType,
OS_Sint32 value);
ReturnCode
MM_incrementValue(void * hManagableEntity,
OS_Sint32 incrementBy);
ReturnCode
MM_startTimer(void * hManagableEntity,
OS_Uint32 milliseconds);
ReturnCode
MM_stopTimer(void * hManagableEntity);
ReturnCode
MM_logMessage(void * hManagableEntity,
char * pFormat,
...);
ReturnCode
MM_registerDestination(ReturnCode (* pfAlert)(char * pApplicationEntityInstanceName,
char * pModuleName,
char * pIdentificationMessage,
MM_EventType eventType,
...),
OS_Uint16 initialNotifyMask,
void ** phDestination);
ReturnCode
MM_modifyDestination(void * hDestination,
OS_Uint16 newNotifyMask);
ReturnCode
MM_processEvents(OS_Boolean * pbFoundOne);
ReturnCode
MM_getValueByHandle(void * hManagableEntity,
void * pValue);
ReturnCode
MM_getValueByName(char * pModuleName,
char * pManagableEntityName,
void * pValue);
ReturnCode
MM_setValueByHandle(void * hManagableEntity,
void * pValue);
ReturnCode
MM_setValueByName(char * pModuleName,
char * pManagableEntityName,
void * pValue);
Note that there are no "modify", "delete", or "create" operations. Creation must occur at the Module Management Entity level. Deletion can be accomplished by setting the Notification Mask to zero. Modify is accomplished via the "set" operation.
The Module Management Module uses the following data types:
typedef enum MM_ManagableEntityType
{
MM_ManagableEntityType_CounterSigned, /* Value Type: OS_Sint32 */
MM_ManagableEntityType_CounterUnsigned, /* Value Type: OS_Uint32 */
MM_ManagableEntityType_GuageSigned, /* Value Type: OS_Sint32 */
MM_ManagableEntityType_GuageUnsigned, /* Value Type: OS_Uint32 */
MM_ManagableEntityType_String, /* Value Type: STR_String */
MM_ManagableEntityType_Timer, /* No maintained value */
MM_ManagableEntityType_Log /* No maintained value */
} MM_ManagableEntityType;
These are the currently supported types of entities which we can manage.
typedef enum MM_NotificationType
{
/* Counter events */
MM_NotificationType_HighPriCounter = (1 << 13)
MM_NotificationType_MidPriCounter = (1 << 7)
MM_NotificationType_LowPriCounter = (1 << 1)
/* Event requires immediate notification */
MM_NotificationType_Urgent = (1 << 15)
/* Event is only informational and may not require any action */
MM_NotificationType_Info = (1 << 0)
/* Generic values for all possible bits */
MM_NotificationType_15 = (1 << 15) /* also Urgent */
MM_NotificationType_14 = (1 << 14)
MM_NotificationType_13 = (1 << 13) /* also HighPriCounter */
MM_NotificationType_12 = (1 << 12)
MM_NotificationType_11 = (1 << 11)
MM_NotificationType_10 = (1 << 10)
MM_NotificationType_9 = (1 << 9)
MM_NotificationType_8 = (1 << 8)
MM_NotificationType_7 = (1 << 7) /* also MidPriCounter */
MM_NotificationType_6 = (1 << 6)
MM_NotificationType_5 = (1 << 5)
MM_NotificationType_4 = (1 << 4)
MM_NotificationType_3 = (1 << 3)
MM_NotificationType_2 = (1 << 2)
MM_NotificationType_1 = (1 << 1) /* also LowPriCounter */
MM_NotificationType_0 = (1 << 0) /* also Info */
} MM_NotificationType;
Each managable entity may be assigned one or more notification types which are to be generated when an event on that managable entity is raised. The module itself may specify an initial set of notification types for the managable entity, but the manager entity may modify that set.
A general rule to follow in deciding what notification type to use, is that the higher-order bits should indicate more urgent events while lower-order bits should indicate less urgent events.
NOTE: The maximum number of bits allowed here is 16, as enum types are 16-bits when using some compilers.
typedef enum MM_EventType
{
MM_EventType_MaxThresholdExceededSigned,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* Two optional parameters are passed:
*
* - the threshold value, as an "OS_Sint32"
* - the value which caused the event by exceeding the
* threshold, as an "OS_Sint32"
*
*/
MM_EventType_MaxThresholdExceededUnsigned,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* Two optional parameters are passed:
*
* - the threshold value, as an "OS_Uint32"
* - the value which caused the event by exceeding the
* threshold, as an "OS_Uint32"
*
*/
MM_EventType_MinThresholdExceededSigned,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* Two optional parameters are passed:
*
* - the threshold value, as an "OS_Sint32"
* - the value which caused the event by exceeding the
* threshold, as an "OS_Sint32"
*
*/
MM_EventType_MinThresholdExceededUnsigned,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* Two optional parameters are passed:
*
* - the threshold value, as an "OS_Uint32"
* - the value which caused the event by exceeding the
* threshold, as an "OS_Uint32"
*
*/
MM_EventType_TimerExpired,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* No optional parameters are passed.
*/
MM_EventType_LogMessage
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* One optional parameter is passed:
*
* - the log message string, as a "char *"
*/
} MM_EventType;
This is the current set of events which may be generated by a module's management entity.
IMPORTANT NOTE:
If additional event types are added, be sure to add comments specifying what optional parameters are passed to the Alert function (see MM_registerDestination()) when an event of this type is raised.
This function is to be called by all applications making use of any of the Module Management facilities.
void MM_init(char * pApplicationEntityInstanceName);
Initialize the Module Management Entity module.
Parameters:
pApplicationEntityInstanceName --
The name of the application entity instance in which the module
is located. Note that if the same application is running in
more then one instance, the instance name must be unique in
each one.
These functions are to be called by each module which wishes to use module management facilities.
ReturnCode
MM_registerModule(char * pModuleName,
void ** phModule);
Allocate management resources for a code module or protocol layer.
Parameters:
pModuleName --
The name of the module for which managable entities are to be
registered.
phModule --
Pointer to a handle. The handle is generated by this function.
Future requests to register a managable entity will use this
handle.
ReturnCode
MM_registerManagableEntity(void * hModule,
MM_ManagableEntityType managableEntityType,
char * pManagableEntityName,
char * pIdentificationMessage,
OS_Uint16 initialNotifyMask,
void ** phManagableEntity);
Register a managable entity for use by the specified module.
Parameters:
hModule --
A module handle previously returned by MM_registerModule().
managableEntityType --
The type of managable entity being registered.
pManagableEntityName --
The name of the managable entity being registered. This name must be
unique within the scope of this module.
pIdentificationMessage --
An identification string which will be passed to the module management
agent when an event is raised.
initialNotifyMask --
Bits identifying the urgency of an event rasied for this managable
entity. Multiple bits may be specified, but this use is discouraged.
phManagableEntity --
Pointer to a handle. The handle is generated by this function. Future
requests to set thresholds, modify values, etc. will require use of
this handle.
subsubsectionSet Threshold
ReturnCode
MM_setThreshold(void * hManagableEntity,
MM_ThresholdType thresholdType,
OS_Sint32 value);
Set the maximum or minimum threshold value for a managable entity.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
thresholdType --
Indication of whether the threshold to be set is a Maximum threshold or
a Minimum threshold.
value --
Value to which the threshold should be set.
Note:
Thresholds are only applicable to certain managable entity types, such as
Counters and Guages.
ReturnCode
MM_incrementValue(void * hManagableEntity,
OS_Sint32 incrementBy);
Increment the numeric value of the specified managable entity (probably either a counter or a guage) by the specified value.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
incrementBy --
Amount by which the managable entity's value should be incremented.
The increment value may be negative to decrement the value.
ReturnCode
MM_startTimer(void * hManagableEntity,
OS_Uint32 milliseconds);
Start a timer. When it expires, an event will be raised.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
milliseconds --
Number of milliseconds before the timer should expire.
ReturnCode MM_stopTimer(void * hManagableEntity);
Stop a previously started timer.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
ReturnCode
MM_logMessage(void * hManagableEntity,
char * pFormat,
...);
Generate a message for logging, using a printf-style format.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
pFormat --
Printf-style format string specifying the format for the remainder of
the parameters.
... --
Additional parameters, as specified by pFormat.
Each MMA talks to multiple Module Management Entities (MME's).
ReturnCode
MM_registerDestination(ReturnCode (* pfAlert)(char * pApplicationEntityInstanceName,
char * pModuleName,
char * pIdentificationMessage,
MM_EventType eventType,
...),
OS_Uint16 initialNotifyMask,
void ** phDestination);
Register a new destination to which events may be sent. A destination is a place where an event is sent. All Module Management Agents should register at least one destination - the Module Management Manager. Additional destinations may be registered, such as to a log file, to send email, etc.
Parameters:
pfAlert --
Pointer to a function which will be called when events are
destined to this registered destination.
If "pfAlert" is NULL, a default function is used, which sends events
for this destination to a non-standard-based Module Management Manager,
using a non-standard-based data format.
When the function pointed to by this parameter is ultimately
called, it will be passed a set of zero or more optional
parameters which are specific to the type of event which has
been raised. See the comments associated with the definition
of MM_EventType.
initialNotifyMask --
Bits specifying that events of notification types include in this mask
are to be sent to this destination (in addition, possibly, to other
destinations).
phDestination
Pointer to a handle. The handle is generated by this function. Future
requests to modify the notification mask for this destination will
require use of this handle.
ReturnCode
MM_modifyDestination(void * hDestination,
OS_Uint16 newNotifyMask);
Modify the set of notification types which should be sent to this destination.
Parameters:
hDestination --
Handle, previously provided by MM_registerDestination().
newNotifyMask --
New bit mask indicating which notification levels are to be sent to
this destination.
ReturnCode MM_processEvents(OS_Boolean * pbFoundOne);
Event notification does not happen asynchronously. The reason for this is that the event could be raised during interrupt routines, critical sections, etc. We therefore enqueue the event notification for action when this function is called.
This function should be called on a regular basis, either in a main loop, or via a timer expiration.
Parameters:
pbFoundOne --
Pointer to a boolean variable, which is set to TRUE by this function if
an event was found to process. This variable is _not_ modified if no
event was found to process, enabling a pointer to the same variable to
be passed to multiple functions to see if any of them had anything to
do.
This pointer may be NULL if an indication of whether an event was
processed is not required.
ReturnCode
MM_getValueByHandle(void * hManagableEntity,
void * pValue);
Get the current value of a managable entity.
Parameters:
hManagableEntity --
Handle to a managable entity, previously provided by
MM_registerManagableEntity().
pValue --
Pointer to the location where the current value of the specified
managable entity is to be placed. It is up to the caller to provide a
pointer to the correct type of variable into which the value will be
placed.
ReturnCode
MM_getValueByName(char * pModuleName,
char * pManagableEntityName,
void * pValue);
Get the current value of a managable entity.
Parameters:
pModuleName --
Name of the module in which the manangable entity resides.
pManagableEntityName --
Name of the managable entity for which the value is desired.
pValue --
Pointer to the location where the current value of the specified
managable entity is to be placed. It is up to the caller to provide a
pointer to the correct type of variable into which the value will be
placed.
ReturnCode
MM_setValueByHandle(void * hManagableEntity,
void * pValue);
Set the current value of a managable entity.
Parameters:
hManagableEntity --
Handle to a managable entity, previously provided by
MM_registerManagableEntity(), for which the value is to be
modified.
pValue --
Pointer to the new value for this managable entity. It is up
to the caller to provide a pointer to the correct type of
variable into which the value will be placed.
ReturnCode
MM_setValueByName(char * pModuleName,
char * pManagableEntityName,
void * pValue);
Get the current value of a managable entity.
Parameters:
pModuleName --
Name of the module in which the manangable entity resides.
pManagableEntityName --
Name of the managable entity for which the value is to be
modified.
pValue --
Pointer to the new value for this managable entity. It is up
to the caller to provide a pointer to the correct type of
variable into which the value will be placed.