Message Logger

The Message Logger (LM) is a module to buffer log messages generated by any other components, called generating components. The log messages can be processed by further components, called processing components, see Figure 1.

Figure: integration of the message logger

A log message consists of a header and a parameter block. The parameter block is optional and can include the values of up to 2 parameters in order to indicate current values or state information on processing-side. The structure of a log message is shown in Figure 14.

Figure: data structure of a log message

The header of the log message contains the following information:

• log-ID: a unique number to report a definite message (4 byte)

• timestamp: indicates the time in ms since the start of the device (8 byte)

• parameter length: length of parameter 1 and parameter 2 in the parameter block in byte (4 byte)

• padding length: number of padding bytes to fill up the log message (2 byte)

The generating components write the header of log messages into the ring buffer by function goal_lmLog(). This function generates the timestamp and adds the padding bytes automatically.

The parameter block contains for each parameter the length (2 bytes) and the parameter value. There are functions to write one parameter depending on the data type of the parameter, e.g. goal_lmLogParamUINT16(). The Message Logger supports parameters of the LM-parameter data types, see chapter 8.2.

The arguments CM-module-ID, text-ID and text of the function goal_lmLog() are implemented for future.

If the ring buffer is full, the next log message, which shall be stored in the ring buffer, overwrites the oldest log messages in the ring buffer. The log messages are stored in a platform dependent byte order.

On processing-side the log-ID shall be known and can be assigned to specific properties, e.g. a logging text and a severity class. The reduction of a unique log-ID allows a fast information transfer with less resources. The Message Logger supports the following severity classes:

• GOAL_LOG_EXCEPTION

• GOAL_LOG_ERROR

• GOAL_LOG_WARNING

• GOAL_LOG_INFO

• GOAL_LOG_DEBUG

The availability of log messages in the ring buffer can be checked by function goal_lmBufferGetCnt(). Log messages can be read from the ring buffer by function goal_lmBufferGet() according to the FIFO-method.

Each processing component has to administrate the read pointer of the ring buffer by itself. This allows that the same log message is interpreted by different processing components.

This module is used by the Device Manager about CM-variables.

• GOAL files:

  • goal_lm.[h,c]

• example:

  • not available

Configuration

Compiler-defines

The following compiler-defines are available to configure the Message Logger:

• GOAL_LM_BUFFER_SIZE:

  • size of the ring buffer for the logging messages in bytes (default: 5120 byte)

CM-variables

For the configuration of the Message Logger the following CM-variables are available:

Table: LM_CM_VAR_READBUFFER

Table: LM_CM_VAR_CNT

Table: LM_CM_VAR_ EXLOG_READBUFFER

Table: LM_CM_VAR_ EXLOG_CNT

Implementation guidelines

Write a log message without parameters to the ring buffer

The log message is generated by the device detection module with the CM-module-ID GOAL_ID_DD. The log message "Error while enabling UDP channel" is classified as GOAL_LOG_ERROR and assigned to log-ID 4 and text-ID 5. Because no parameter shall be transferred, the length of parameter 1 and parameter 2 is 0.

1. write header of the log message:
   

   goal_lmLog(GOAL_ID_DD, 4, 5, 0, 0, GOAL_LOG_ERROR, "Error while enabling UDP channel");

Write a log message with parameters to the ring buffer

The log message is generated by the device detection module with the CM-module-ID GOAL_ID_DD. The log message "Error while opening UDP server channel on port $1" is classified as GOAL_LOG_ERROR and assigned to log-ID 1 and text-ID 2. In error case the port number of the UDP channel shall be reported. The port number has the data type uint32_t. The length of parameter 1 is 4 bytes. The following function sequence is necessary:

1. write header of the log message:
   

   goal_lmLog(GOAL_ID_DD, 1, 2, 4, 0, GOAL_LOG_ERROR, "Error while opening UDP server channel on port $1");

2. write the parameter value:
   

   goal_lmLogParamUINT32((uint32_t) DD_UDP_PORT);

3. finish the entry of the log message in the ring buffer:
   

   goal_lmLogFinish();