OCEOSmp/blank

Logging directives

Introduction

Log Area Features (for details of other areas see oceos_areas.h)

The system log area holds the system log and the records of the present and previous values of the system state variable.

It is set up initially as an array of 32-bit words that starts at a 32-bit aligned address provided by the application developer.

It is recommended that this address be in non-volatile RAM memory if this is available to allow information be preserved across power-up cycles.

OCEOS preserves log area information across resets as far as possible.

The system log itself is a circular buffer of struct log entry. Older entries are overwritten by new entries once all entries are in use.

The application developer can specify a function to be called when 3/4 of log entries are in use. This function is called again only after 3/4 of log entries have been read and the log has again become 3/4 full.

The read and write indices are stored in the log area and if equal indicate that the log is empty.

As with other OCEOS data areas, the log area starts with a header

• a 32-bit word holding a constant OCEOS_VERSION
• a 32-bit word holding the log area size in 32-bit words
• a 32-bit word, the system status variable
• a 32-bit word, the system status mask
• a 32-bit word, the accumulated system status
• a 32-bit word, the previous system status mask
• a 32-bit word, the log control, that gives whether the log full function was called
• the read index
• the write index
• an array of struct log_entry making up the system log itself
• ending with a 32-bit constant END_SENTINEL

The system fixed meta structure at sysMetaPtr provides

• system_log_ptr the start address of the log area
• logEntries the number of log entries
• logCreated flag indicating log was created successfully
• logFullFunction user defined function, called when the log becomes 3/4 full (or NULL if not used)

Log Entry Types and Structure

/*****************************************************************************
 * LOG ENTRY TYPES
 *
 * A log entry type is an 8-bit number.
 * Values from 0 to 127 can be defined by the application.
 * Values from 128 to 255 are used by OCEOS as below.
 *
 *
 * NOTE: Add new log types at the end for backward compatibility
 */
enum LOG_ENTRY_TYPE{
  LOG_SYS_OK = 0x80U,
  LOG_OCEOS_ABORT,				// when exiting from oceos_start
  LOG_LOG_NOT_VALID_ENTRY,		// used to initialise log and when log empty
  LOG_INIT_TASK_START_FAIL,		// initial task passed to oceos_start failed
  LOG_DEADLINE_MISSED,			// task deadline missed
  LOG_JOB_NOT_ACTIVE,			// cpu_terminate but job not active, absurd
  LOG_JOB_NOT_FREE,				// job guarded but not free
  LOG_JOBS_INC_FAILED, 			// pending jobs increment failed
  LOG_JOB_NOT_GUARDED,			// paranoia
  LOG_CS_LOG_SPIN_FAIL,			// oceos_CPU_sleep, trying to update CS log
  LOG_MUTEX_ALREADY_HELD,		// oceos_mutex_wait, code returned, not needed
  LOG_MUTEX_INCORRECT_ORDER,	// oceos_mutex_wait
  LOG_MUTEX_EXIT_HOLDING,		// task exits holding one or more mutexes
  LOG_MUTEX_EXIT_NONE,			// __oceos_tasks_remove_mutexes called but no mutex held
  LOG_SEMAPHORE_PENDING_REMOVE_FAIL,	// timed_action.c
  LOG_SEMAPHORE_PENDING_QUEUE_FULL,		// __oceos_semaphore_add_pend
  LOG_SEMAPHORE_SPIN_FAILED,			// trying to access semaphore
  LOG_DATAQ_PENDING_QUEUE_FULL,
  LOG_DATAQ_PENDING_REMOVE_FAIL,
  LOG_DATAQ_SPIN_FAILED,
  LOG_TIMED_ACTION_TIMER_NULL,
  LOG_TIMED_ACTION_INVALID,
  LOG_TIMED_ACTION_BAD_INDEX,
  LOG_TIMED_ACTION_MISSED,
  LOG_TIMED_ACTION_Q_EMPTY,
  LOG_TIMED_ACTION_REMOVE_FAIL,
  LOG_TIMED_ACTION_BAD_JOB_ID,
  LOG_TIMED_Q_SPIN_FAIL,
  LOG_SYSTEM_ERROR,
  LOG_ATOMICINC_FAILED,
  LOG_PENDING_PRI_UPDATE_FAILED,
  LOG_KILL_TASK_INVALID_ID,      // Tried to kill task with invalid ID
  LOG_OCEOS_EXIT_REQUEST,         // oceos_exit command was called
  LOG_RWMUTEX_NOT_RETURNED,
  LOG_RWMUTEX_NOT_HIGHEST
};

/*****************************************************************************
 * Structures
 */
/**
 * Log entry structure
 */
struct log_entry{
  U64_t             time64;

  unsigned int      entry_cpu          :8;
  unsigned int      entry_type         :8;
  unsigned int      entry_note         :16;	// not used at present

  U32_t             entry_comment;
}__attribute__ ((aligned (8)));

oceos_log_add_entry()

Header File
system_log.h

Description
This function adds an entry to the log. The entry overwrites the oldest unread entry if the log is full. Custom log entries can be added to enum LOG_ENTRY from 0 to 128. The indices are incremented in a circular fashion. If the write index reaches the read_index the read index is moved on, as read and write indices equal would indicate an empty log.

Prototype

/**
 * Add an entry to the log.
 * this overwrites the oldest unread entry if the log is full.
 * Custom log entries can be added to enum LOG_ENTRY from 0 to 128
 *
 * N.B. The indices are incremented in a circular fashion.
 *      If the write index reaches the read_index the read index is moved on,
 *      as read and write indices equal would indicate an empty log.
 *
 * @param type  enum LOG_ENTRY_TYPE
 * @param info  extra information to be logged
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_LOG_CORRUPT         System Log area corrupt
 *          ERR_WRONG_PHASE             Log directive called in wrong phase; can be used after oceos_init() called
 *          ERR_ID_INVALID              Log type invalid
 *          ERR_SYS_BUSY                Failed to acquire log guard
 *          ERR_LOG_INDEX_WRONG         Read/write log index is wrong
 */
S32_t   oceos_log_add_entry(
    enum LOG_ENTRY_TYPE type,   // 8 bits enum LOG_ENTRY_TYPE
    const U32_t        info     // information
);

Parameters

Parameter	Description
enum LOG_ENTRY_TYPE	Log entry type (see previous section for a list)
U32_t with the log information

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

Error bit	Description
ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_LOG_CORRUPT	System Log area corrupt
ERR_WRONG_PHASE	Log directive called in wrong phase; can be used after oceos_init() called
ERR_ID_INVALID	Log type invalid
ERR_SYS_BUSY	Failed to acquire log guard
ERR_LOG_INDEX_WRONG	Read/write log index is wrong

Example Usage

S32_t status, info;
...
// Log LOG_APP_COMMS__ERROR (defined in enum LOG_ENTRY_TYPE) and info with more details
status = oceos_log_add_entry(LOG_APP_COMMS__ERROR, info);

oceos_log_get_indexed_entry()

Header File
system_log.h

Description
This function returns the entry at the specified position in the log. The entry is not removed and the log and log indices are not changed. One use of this function is to allow the log be examined after a reset.

Prototype

/**
 * Returns the entry at the specified position in the log.
 * The entry is not removed and the log and log indices are not changed.
 * (intended to allow the log be examined for example after reset)
 *
 * @param index         position in the log
 * @param outputPtr     pointer to return log entry
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_LOG_CORRUPT         System Log area corrupt
 *          ERR_WRONG_PHASE             Log directive called in wrong phase; can be used after oceos_init() called
 *          ERR_LOG_INDEX_WRONG         Read log index is wrong
 *          ERR_LOG_DATA_PTR_BAD        Data holder pointer is null
 */
S32_t oceos_log_get_indexed_entry(
    const unsigned int index,
    struct log_entry * const outputPtr
);

Parameters

Parameter	Description
index	U32_t with position in the log
outputPtr	pointer to struct log_entry to hold the returned entry

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_LOG_CORRUPT	System Log area corrupt
ERR_WRONG_PHASE	Log directive called in wrong phase; can be used after oceos_init() called
ERR_LOG_INDEX_WRONG	Read log index is wrong
ERR_LOG_DATA_PTR_BAD	Data holder pointer is null

Example Usage

S32_t status, index;
struct log_entry store_entry;
...

// Read log_entry at specified index into outputPtr
status = oceos_log_get_indexed_entry(index, &store_entry);

oceos_log_remove_entry()

Header File
system_log.h

Description
This function reads and removes the oldest unread log entry. If the log is not empty use the entry at the read index to update the value at the output pointer, returning OCEOS_SUCCESS. If outputPtr is NULL, entry is removed but no returned. If the log is empty, set the value at the output pointer to LOG_LOG_NOT_VALID_ENTRY and return ERR_LOG_EMPTY.

Prototype

/**
 * Read and remove the oldest unread log entry
 *
 * If the log is not empty use the entry at the read index to update the value
 * at the output pointer, returning OCEOS_SUCCESS.
 *
 * If outputPtr is NULL, entry is removed but no returned
 *
 * If the log is empty, set the value at the output pointer to LOG_LOG_NOT_VALID_ENTRY
 * and return ERR_LOG_EMPTY
 *
 * @param outputPtr   pointer to struct log_entry
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_LOG_CORRUPT         System Log area corrupt
 *          ERR_WRONG_PHASE             Log directive called in wrong phase; can be used after oceos_init() called
 *          ERR_SYS_BUSY                Failed to acquire log guard
 *          ERR_LOG_INDEX_WRONG         Read/write log index is wrong
 *          ERR_LOG_EMPTY               Log is empty
 */
S32_t   oceos_log_remove_entry(
    struct log_entry * const outputPtr
);

Parameters

Parameter	Description
outputPtr	pointer to struct log_entry

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

Error bit	Description
ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_LOG_CORRUPT	System Log area corrupt
ERR_WRONG_PHASE	Log directive called in wrong phase; can be used after oceos_init() called
ERR_SYS_BUSY	Failed to acquire log guard
ERR_LOG_INDEX_WRONG	Read/write log index is wrong
ERR_LOG_EMPTY	Log is empty

Example Usage

S32_t status;
struct log_entry *outputPtr;
...
// Read log_entry into outputPtr and remove the oldest unread log entry
status = oceos_log_remove_entry(LOG_APP_COMMS__ERROR, info);

blank_function()

Header File
header.h

Description
This function does xyz...

Prototype

S32_t oceosmp_blank(
    U32_t param
);

Parameters

Parameter	Description
param	parameter to function

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

Error bit	Description
Error_name	description

Example Usage

S32_t status, param;
...
// Do xyz
status = oceosmp_blank(param));