GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > EMSG / V0-0-1

Constituent: emsg_st     Tag: linux-gcc

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » FES » source » EMSG » V0-0-1 » EMSG

EMSG_pubdefs.h File Reference

Public include file defining the interface to the EMSG facility. More...

#include "time.h"

Include dependency graph for EMSG_pubdefs.h:

This graph shows which files directly or indirectly include this file:


Data Structures

struct  _EMSG_InitPrm
 Structure to hold parameters needed by EMSG initialization routine. More...
struct  _EMSG_Message
 Structure to hold an instance of a message. More...
struct  _EMSG_Counts
 Structure for instrumentation counts. More...

Defines

#define EMSG_K_FMTBITS   2
 N-bits needed to type a substitution.
#define EMSG_M_FMTBITS   ((1 << EMSG_K_FMTBITS) - 1)
 Mask for above.
#define EMSG_L_FMTMAX   (32 / EMSG_K_FMTBITS)
 Maximum number of substitutions.
#define EMSG_K_FMTSTRING   0
 Conversion type - pointer to string.
#define EMSG_K_FMT4BINT   1
 Conversion type - 4-byte integer.
#define EMSG_K_FMT8BINT   2
 Conversion type - 8-byte integer.
#define EMSG_K_FMTDOUBLE   3
 Conversion type - double (any float).
#define EMSG_L_FMTLENGTH   256
 Maximum length of a formatting string.
#define EMSG_K_SEVERITY   2
 Number of bits used for severity field.
#define EMSG_K_MESSAGE   21
 Number of bits used for message field.
#define EMSG_K_FACILITY   8
 Number of bits used for facility field.
#define EMSG_K_REPORT   1
 Number of bits used for 'reported' field.
#define EMSG_V_SEVERITY   0
 Bit offset to severity field.
#define EMSG_V_MESSAGE   (EMSG_V_SEVERITY + EMSG_K_SEVERITY)
 Bit offset to message field.
#define EMSG_V_FACILITY   (EMSG_V_MESSAGE + EMSG_K_MESSAGE)
 Bit offset to facility field.
#define EMSG_V_REPORT   (EMSG_V_FACILITY + EMSG_K_FACILITY)
 Bit offset to 'reported' field.
#define EMSG_M_SEVERITY   (((1 << EMSG_K_SEVERITY) - 1) << EMSG_V_SEVERITY)
 Mask for the severity field.
#define EMSG_M_MESSAGE   (((1 << EMSG_K_MESSAGE) - 1) << EMSG_V_MESSAGE)
 Mask for the message field.
#define EMSG_M_FACILITY   (((1 << EMSG_K_FACILITY ) - 1) << EMSG_V_FACILITY)
 Mask for the facility field.
#define EMSG_M_REPORT   (((1 << EMSG_K_REPORT) - 1) << EMSG_V_REPORT)
 Mask for the 'reported' field.
#define EMSG_M_MATCH   (EMSG_M_FACILITY | EMSG_M_MESSAGE)
 Mask of facility and message fields combined.
#define EMSG_M_TEXT   0x00000001
 Print message text.
#define EMSG_M_NAME   0x00000002
 Print message name.
#define EMSG_M_ROUTINE   0x00000004
 Print routine name.
#define EMSG_M_TASK   0x00000008
 Print task name.
#define EMSG_M_NSEC   0x00000010
 Print message time nanoseconds.
#define EMSG_M_MSEC   0x00000020
 Print message time milliseconds.
#define EMSG_M_TIME   0x00000040
 Print message time (local).
#define EMSG_M_DATE   0x00000080
 Print message date (local).
#define EMSG_M_DUMP   0x00000100
 Multi-line dump of everything (dbg).
#define emsg_success(x)   (((x) & 1) == 0)
 Test a message for success.
#define emsg_failure(x)   (((x) & 1) != 0)
 Test a message for failure.
#define emsg_match(x, y)   (((x) & EMSG_M_MATCH) == ((y) & EMSG_M_MATCH))
 Match a message against a known message.
#define emsg_strip(x)   ((x) & ~EMSG_M_REPORT)
 Remove the 'signaled' bit from a code.
#define emsg_report(code, nprm, args...)   EMSG_report(code, __func__, nprm, ## args)
 Inserts routine name to EMSG_report() call.

Typedefs

typedef _EMSG_OutputRtn EMSG_OutputRtn
 Handle for output routine identification.
typedef enum _EMSG_Level EMSG_Level
 Enumerate message severity levels.
typedef enum _EMSG_OutputModes EMSG_OutputModes
 Enumeration of modes in which output processors can be called.
typedef _EMSG_InitPrm EMSG_InitPrm
 Structure to hold parameters needed by EMSG initialization routine.
typedef _EMSG_Message EMSG_Message
 Structure to hold an instance of a message.
typedef _EMSG_Counts EMSG_Counts
 Structure for instrumentation counts.
typedef void EMSG_CbOutputRtn (EMSG_OutputModes mode, void *prm, const EMSG_Message *msg)
 Signature for a EMSG processing callback routine.

Enumerations

enum  _EMSG_Level {
  EMSG_LVL_SUCCESS = 0,
  EMSG_LVL_INFORMATION = 1,
  EMSG_LVL_WARNING = 2,
  EMSG_LVL_ERROR = 3
}
 Enumerate message severity levels. More...
enum  _EMSG_OutputModes {
  EMSG_OUT_INIT = 0,
  EMSG_OUT_NORMAL = 1,
  EMSG_OUT_EXIT = 2
}
 Enumeration of modes in which output processors can be called. More...

Functions

unsigned int EMSG_attachOutputRtn (EMSG_OutputRtn **handle, EMSG_CbOutputRtn *rtn, void *prm)
 Attach a message output callback routine.
unsigned int EMSG_countsSinceReset (EMSG_Counts *cnt, unsigned int rst)
 Return instrumentation counts since last reset.
unsigned int EMSG_countsSinceStart (EMSG_Counts *cnt)
 Return instrumentation counts since message task started.
void EMSG_deleteOptions (void)
 Delete task options.
unsigned int EMSG_detachOutputRtn (EMSG_OutputRtn *handle)
 Detach a message callback routine.
unsigned int EMSG_initialize (const EMSG_InitPrm *prm)
 Initialize the message system.
EMSG_Level EMSG_getLevel (void)
 Get the current reporting level.
const char * EMSG_getTask (void)
 Return pointer to task name.
unsigned short EMSG_getTrace (void)
 Get the current trace buffer number.
void EMSG_print (EMSG_OutputModes mode, void *prm, const EMSG_Message *msg)
 Output processor callback routine to simply print messages.
unsigned int EMSG_printOptions (unsigned int mask, unsigned int valu)
 Selective set and clear of print processor options.
unsigned int EMSG_report (unsigned int code, const char *rtn, unsigned int nprm,...)
 Process a message reporting request.
EMSG_Level EMSG_setLevel (EMSG_Level level)
 Set the current reporting level.
EMSG_Level EMSG_setLevel4Task (int tid, EMSG_Level level)
 Set the reporting level for a task.
unsigned int EMSG_setTask (const char *task)
 Set the task name.
unsigned short EMSG_setTrace (unsigned short trace)
 Set the current trace buffer number.
unsigned int EMSG_shutdown (void)
 Shut down the message system.
unsigned int EMSG_startTask (void)
 Start the message task.
unsigned int EMSG_stopTask (void)
 Stop the message task.

Detailed Description

Public include file defining the interface to the EMSG facility.

Author:
Owen H Saxton
Id
EMSG_pubdefs.h,v 1.2 2006/02/28 20:52:22 saxton Exp

Typedef Documentation

typedef enum _EMSG_Level EMSG_Level
 

Enumerate message severity levels.

Messages can have one of four severity levels defined by the creator of the message. The names are (I hope) self explanatory.

typedef enum _EMSG_OutputModes EMSG_OutputModes
 

Enumeration of modes in which output processors can be called.

Output processors can be called in one of three modes. Note that the pointer to the message structure is only valid during a call in mode EMSG_OUT_NORMAL.

Enumeration Type Documentation

enum _EMSG_Level
 

Enumerate message severity levels.

Messages can have one of four severity levels defined by the creator of the message. The names are (I hope) self explanatory.

Enumerator:
EMSG_LVL_SUCCESS  Success.
EMSG_LVL_INFORMATION  Information.
EMSG_LVL_WARNING  Warning.
EMSG_LVL_ERROR  Error.

enum _EMSG_OutputModes
 

Enumeration of modes in which output processors can be called.

Output processors can be called in one of three modes. Note that the pointer to the message structure is only valid during a call in mode EMSG_OUT_NORMAL.

Enumerator:
EMSG_OUT_INIT  Initialization call.
EMSG_OUT_NORMAL  Regular output call.
EMSG_OUT_EXIT  Exit call.

Function Documentation

unsigned int EMSG_attachOutputRtn (  EMSG_OutputRtn **  handle,
EMSG_CbOutputRtn *  rtn,
void *  prm
) 
 

Attach a message output callback routine.

This routine attaches a message output processing routine. Each routine attached is called once when the message system is starting, once per call to EMSG_report(), and once when the message system is stopping.

In the single-threaded version of MSG, the attached routines are called directly by the EMSG_report() routine. In the multi-threaded version of MSG the routines are called by the message processing task.

Output processing routines may only be attached/detached when the message system is in state EMSG_S_INITIALIZED. This is true:

Parameters:
handle (out) Handle for identifying the callback (used to detach)
rtn (in) Routine entry point
prm (in) Routine parameter
Return values:
EMSG_SUCCESS Success
EMSG_BADSTATE Cannot attach output processors in the current message state
EMSG_ALOCFAIL Cannot allocate memory for the output routine description

unsigned int EMSG_countsSinceReset (  EMSG_Counts *  cnt,
unsigned int  rst
) 
 

Return instrumentation counts since last reset.

Parameters:
cnt Counts block into which to put the results
rst Reset flag (0 => don't reset, otherwise reset)
Return values:
EMSG_BADSTATE Message system not initialized
EMSG_SUCCESS Success
This routine returns an instrumentation block giving (bread and butter case) message counts and high and low water marks for packet usage since the last reset. This makes sense while the message task is running. The following table gives details of what's returned when the message task is not running.

MSG state MSG task has run at least once Return code Contents of instrumentation block
EMSG_S_UNINITIALIZED n/a EMSG_BADSTATE All zero
EMSG_S_INITIALIZED no EMSG_SUCCESS Fake statistics for a zero length run of the msg task
EMSG_S_INITIALIZED yes EMSG_SUCCESS Statistics from most recent reset to time msg task stopped

unsigned int EMSG_countsSinceStart (  EMSG_Counts *  cnt  ) 
 

Return instrumentation counts since message task started.

Parameters:
cnt Counts block into which to put the results
Return values:
EMSG_BADSTATE Message system not initialized
EMSG_SUCCESS Success
This routine returns an instrumentation block giving (bread and butter case), message counts and high and low water marks for packet usage since the message task was started. This makes sense while the message task is running. The following table gives details of what's returned when the message task is not running.

MSG state MSG task has run at least once Return code Contents of instrumentation block
EMSG_S_UNINITIALIZED n/a EMSG_BADSTATE All zero
EMSG_S_INITIALIZED no EMSG_SUCCESS Fake statistics for a zero length run of the msg task
EMSG_S_INITIALIZED yes EMSG_SUCCESS Statistics for the most recent run of the msg task

void EMSG_deleteOptions (  void   ) 
 

Delete task options.

This routine deletes the options block associated with the current task. For the single-threaded case, this is a no-op.

unsigned int EMSG_detachOutputRtn (  EMSG_OutputRtn *  handle  ) 
 

Detach a message callback routine.

This routine detaches an message output processing routine.

Output processing routines may only be attached/detached when the message system is in state EMSG_S_INITIALIZED. This is true:

Parameters:
handle (in) Handle for identifying the callback (from attach call)
Return values:
EMSG_SUCCESS Success
EMSG_BADSTATE Cannot detach output processors in the current message state
EMSG_OUTNTFND Cannot find this output processor on the list

EMSG_Level EMSG_getLevel (  void   ) 
 

Get the current reporting level.

This routine returns the level at which messages are reported. Messages whose severity is greater than or equal to the level set are reported.

Returns:
The severity level for reporting

const char* EMSG_getTask (  void   ) 
 

Return pointer to task name.

This routine returns a pointer to the task name. This is the host side version where the task name is an arbitrary string under user control.

Returns:
Pointer to the string containing the task name

unsigned short EMSG_getTrace (  void   ) 
 

Get the current trace buffer number.

This routine returns the trace buffer number currently in effect. This is a 16-bit number associated with a message. All messages record the current value of the trace buffer number. This is a simple mechanism to group messages.

Returns:
The trace buffer number for reporting

unsigned int EMSG_initialize (  const EMSG_InitPrm *  prm  ) 
 

Initialize the message system.

This routine initializes the message system according to the parameters provided in the parameterization block.

Parameters:
prm (in) Parameter block contining initialization information (note 1)
Note:
  1. If prm is NULL, EMSG_initialize() will provide a default (currently 32 message packets of 256 bytes each). If prm is not NULL, the caller need not make the storage for the EMSG_InitPrm structure persistent.
Return values:
EMSG_ALOCFAIL Fixed packet allocator (FPA) buffer allocation failed
EMSG_BADSTATE Cannot initialize in the current MSG state
EMSG_FINDFAIL Cannot look up up alternate messages in database
EMSG_FPAIFAIL Fixed packet allocator (FPA) initialization failed
EMSG_MUALOCFL Cannot allocate a mutex
EMSG_PKT2FEW Packet count parameter too small
EMSG_PKT2SMAL Packet length parameter too small
EMSG_SUCCESS Success

void EMSG_print (  EMSG_OutputModes  mode,
void *  prm,
const EMSG_Message *  msg
) 
 

Output processor callback routine to simply print messages.

This routine prints a message using printf following options provided by the user.

Parameters:
mode (in) Output processor calling mode
prm (in) User parameter
msg (in) Message structure

unsigned int EMSG_printOptions (  unsigned int  mask,
unsigned int  valu
) 
 

Selective set and clear of print processor options.

This routine does a selective set and clear on the print options word.

Parameters:
mask (in) Mask of options to touch
valu (in) Values to set (in masked bits only)
Returns:
Previous value of the options word

unsigned int EMSG_report (  unsigned int  code,
const char *  rtn,
unsigned int  nprm,
  ...
) 
 

Process a message reporting request.

This routine reports a message. It allocates a message packet and populates it with a block of standard information (timestamp, CPU, task name, etc.) and the variable information in the variadic arguments following nprm.

The packet is sent to an message task (in the multi-threaded case) where the message is formatted using the formatting string associated with the message code. The message task then calls all output processors in turn to do whatever it is they want to do with the information.

In the single-threaded case, the message processing occurs inline with the routine call.

Parameters:
code (in) Message code to be reported
rtn (in) Name of calling routine (note 1)
nprm (in) Number of parameters that follow
Return values:
code Reflection of the first input argument, probably with "reported" bit set
Note:
  1. String must be persistent. Recommended method for the caller to provide this argument: don't call this routine directly, but use the emsg_report() macro, which will provide this argument automatically. If there is some necessity to call EMSG_report() directly, please use the compiler provided __func__ macro to fill in the routine name.
Warning:
Under normal circumstances, no-one should be calling this routine directly. It's far more convenient (and usually more accurate) to use the emsg_report() macro provided by the EMSG package. See note 1 above for the reason.

EMSG_Level EMSG_setLevel (  EMSG_Level  newval  ) 
 

Set the current reporting level.

This routine sets the level at which messages are reported. A message whose severity is greater than or equal to the level set is reported. The routine returns the reporting level prior to the call (to allow simple reversion).

Parameters:
newval (in) Reporting level to be set
Returns:
Reporting level prior to the call

EMSG_Level EMSG_setLevel4Task (  int  tid,
EMSG_Level  newval
) 
 

Set the reporting level for a task.

This routine is meaningless in the single-threaded context and is only provided to provide compatibility between the single-threaded and multi-threaded modules.

Parameters:
tid (in) Arbitrary task's ID
newval (in) Reporting level to be set
Returns:
The reporting level for the only existing task/thread

unsigned int EMSG_setTask (  const char *  task  ) 
 

Set the task name.

This routine sets a task name. This is only valid in the single- threaded environment where the task name is an arbitrary string under user control.

Parameters:
task (in) Pointer to task name
Return values:
EMSG_ALOCFAIL Could not allocate storage for task name string
EMSG_TNM2LONG Task name too long
EMSG_SUCCESS Success

unsigned short EMSG_setTrace (  unsigned short  newval  ) 
 

Set the current trace buffer number.

This routine sets the trace buffer number currently in effect. This is a 16-bit number associated with a message. All messages record the current value of the trace buffer number. This is a simple mechanism to group messages. The routine returns the trace buffer in effect prior to the call to make reversion simple.

Parameters:
newval (in) Trace buffer number to set
Returns:
The trace buffer prior to the change

unsigned int EMSG_shutdown (  void   ) 
 

Shut down the message system.

This routine detaches all attached output processors and frees all resources associated with the message system.

Return values:
EMSG_BADSTATE Cannot shut down in the current state
EMSG_SUCCESS Success

unsigned int EMSG_startTask (  void   ) 
 

Start the message task.

In multi-threaded mode, this routine spawns a task (with the attributes defined in the task attributes block passed into this routine) to receive and process messages.

In single-threaded mode, it does not spawn a task, and all message processing is done inline with the report call. The task attributes block is ignored.

In both modes (and before the task spawn in multi-threaded mode), this routine calls each of the output processing routines in turn with a flag to indicate an inialization call.

Warning:
Message believes it owns its own task name and will overwrite a task name provided by the caller.
Return values:
EMSG_BADSTATE Cannot start in the current message state
EMSG_SPWNFAIL Message task spawn failed
EMSG_SUCCESS Success

unsigned int EMSG_stopTask (  void   ) 
 

Stop the message task.

In multi-threaded mode, EMSG_stopTask() runs down the task spawned in EMSG_startTask() and releases the resources associated with it.

In single-threaded mode, there is no spawned task to run down.

In both modes (and after the spawned task has run down in multi- threaded mode), EMSG_stopTask() calls each of the output processing routines in turn with a flag to indicate a cleanup call.

Return values:
EMSG_BADSTATE Cannot stop in the current message state
EMSG_SUCCESS Success

Generated on Tue Feb 28 20:24:07 2006 by  doxygen 1.4.4