Difference between revisions of "OCEOSmp/blank"

From wiki
Jump to navigation Jump to search
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Next Section ==
== Next Section ==


== Logging directives ==
===<span style="color:#0000ff">blank_function()</span>===
 
===<span style="color:#0000ff">Introduction</span>===
<blockquote style="border-left-style: none;">
 
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)
 
 
<span style="color:#1b7ac2">'''Log Entry Types and Structure'''</span><br>
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));
 
</syntaxhighlight>
 
===<span style="color:#0000ff">oceos_log_add_entry()</span>===
<blockquote style="border-left-style: none;">
 
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
 
<span style="color:#1b7ac2">'''Description'''</span><br>
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.
 
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
 
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | U32_t with the log information
|}
 
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
! 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
|-
|}
 
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
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);
 
</syntaxhighlight>
</blockquote>
 
===<span style="color:#0000ff">oceos_log_get_indexed_entry()</span>===
<blockquote style="border-left-style: none;">
 
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
 
<span style="color:#1b7ac2">'''Description'''</span><br>
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.
 
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
 
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter || Description
|-
| index || U32_t with position in the log
|-
| outputPtr || pointer to struct log_entry to hold the returned entry
|}
 
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| 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
|}
 
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
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);
 
</syntaxhighlight>
</blockquote>
 
===<span style="color:#0000ff">oceos_log_remove_entry()</span>===
<blockquote style="border-left-style: none;">
 
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
 
<span style="color:#1b7ac2">'''Description'''</span><br>
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.
 
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
 
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter || Description
|-
| outputPtr || pointer to struct log_entry
|}
 
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
! 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
|-
|}
 
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
struct log_entry *outputPtr;
...
// Read log_entry into outputPtr and remove the oldest unread log entry
status = oceos_log_remove_entry(outputPtr);
 
</syntaxhighlight>
</blockquote>
 
===<span style="color:#0000ff">oceos_log_reset()</span>===
<blockquote style="border-left-style: none;">
 
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
 
<span style="color:#1b7ac2">'''Description'''</span><br>
This function sets all log entries to LOG_LOG_NOT_VALID_ENTRY and the log to empty, with the read and write indices set to 0.
The log is empty if the index of the next write is the same as the index of the next read. It does not affect the system status variable. It does not affect the context switch log.
 
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* oceos_log_reset()
*
* Set all log entries to LOG_LOG_NOT_VALID_ENTRY and the log to empty, with the
* read and write indices set to 0. and function called flag 0
*
* The log is empty if the index of the next write
* is the same as the index of the next read.
*
* Does not affect the system status variable
* Does not affect the context switch log
*
* N.B The fixed data area may no longer be writable
*
* @return  OCEOS_SUCCESS
*          ERR_SYS_FIXED_CORRUPT      System Fixed area corrupt
*          ERR_SYS_LOG_CORRUPT        System Log area corrupt; reset failed
*          ERR_WRONG_PHASE            Log directive called in wrong phase; can be used after oceos_init() called
*          ERR_SYS_BUSY                Failed to acquire log guard
*/
S32_t oceos_log_reset(void);
</syntaxhighlight>
 
<span style="color:#1b7ac2">'''Parameters'''</span><br>
There are no input parameters to this function.
 
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
! Error bit  !! Description
|-
| ERR_SYS_FIXED_CORRUPT      || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT        || System Log area corrupt; reset failed
|-
| ERR_WRONG_PHASE            || Log directive called in wrong phase; can be used after oceos_init() called
|-
| ERR_SYS_BUSY                || Failed to acquire log guard
|}
 
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
...
 
// Clear down the system log
status = oceos_log_reset();
 
</syntaxhighlight>
</blockquote>
 
===<span style="color:#0000ff">oceos_log_get_size()</span>===
<blockquote style="border-left-style: none;">
 
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
 
<span style="color:#1b7ac2">'''Description'''</span><br>
This function returns the number of entries in the log according to the current values of the read and write indices.
The value will be zero if the current values of the read and write indices are the same. There may still be useful information in the log, e.g. after system reset, this can be accessed using oceos_log_get_indexed_entry().
 
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Return the number of entries in the log
* according to the current values of the read and write indices.
*
* The value will be zero if the current values of the read and write indices
* are the same.
*
* There may still be useful information in the log, e.g. after system reset,
* this can be accessed using oceos_log_get_indexed_entry()
*
* @param l_size        pointer to log size holder
*
* @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_DATA_PTR_BAD        Pointer to log size holder is NULL
*          ERR_LOG_INDEX_WRONG        Read/write log index is wrong
*/
S32_t oceos_log_get_size(
    U32_t *l_size
);
</syntaxhighlight>
 
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter || Description
|-
| l_size|| U32_t pointer where size will be written.
|}
 
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| 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_DATA_PTR_BAD        || Pointer to log size holder is NULL
|-
| ERR_LOG_INDEX_WRONG        || Read/write log index is wrong
|}
 
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, size;
...
 
// Clear down the system log
status = oceos_log_get_size(&size);
 
</syntaxhighlight>
</blockquote>
 
===<span style="color:#0000ff">System State Variable and System State Mask</span>===
<blockquote style="border-left-style: none;">
 
The System State variable provides a record of anomalies or problems detected by OCEOSmp's automatic consistency checks. An application handler for these can be set to be called automatically.
 
An anomaly or problem results in a flag bit being set in the 32-bit word used to store the system state variable. The flags are identified below.
 
All flags are reset to zero by oceos_init() when OCEOSmp is initialised, and may also be reset by the application using the directive provided.
 
To provide a record across OCEOSmp restarts a copy is updated automatically whenever the state variable is updated. This is not cleared by oceos_init() but may be cleared by the application using a directive.
 
Application software can define a problem handling function to be called automatically when specified system state flags are set. The flags are specified by setting the corresponding bits in the system state mask. The function and the state mask are defined in the system configuration.
 
Changing a state flag from clear to set results in the function being called (if defined). Subsequent settings of that flag have no effect until after it has been cleared using the directive provided.
 
N.B. In many cases when OCEOSmp sets a System State flag it also makes an entry in the system log that provides further information.
 
SYSTEM STATE VARIABLE FLAGS
 
These flags are updated by OCEOSmp using inclusive 'OR' when a consistency check detects a problem or anomaly. A copy of the system state variable is updated also and accumulates a record of flag settings that is preserved across restarts of OCEOSmp. OCEOSmp restarts reset the system state variable but not the copy.
 
Resetting the state variables is the responsibility of the application (except for the state variable reset done when OCEOSmp is restarted).
 
<span style="color:#1b7ac2">'''System Status Bits'''</span><br>
<syntaxhighlight lang="C">
 
#define  STATUS_NORMAL                    0u    // No flag set                              YES
#define  STATUS_INVALID          0xffffffffu    // System status is invalid                YES BUT NO DETAIL!!!
 
#define  STATUS_MASK_NORMAL      0xffffffffu    // Always call user def fn                  YES
 
/* Task related problems */
#define  STATUS_DISABLED_TASK_START    0x1U    // An attempt to start a disabled task
#define  STATUS_TASK_JOB_LIMIT_OVER    0x2U    // An attempt to execute a task when its jobs limit is already reached.
#define  STATUS_JOB_OVER_TIME          0x4U    // Job time from creation to completion exceeds allowed maximum for task. YES
#define  STATUS_JOB_INTERVAL_SHORT    0x8U    // Minimum time between job creations is less than the allowed minimum for task
#define  STATUS_READYQ_FULL          0x10U    // Ready queue unable to accept job as result of being full
#define  STATUS_READYQ_NO_REMOVE      0x20U    // Remove job from ready queue failed
 
/* Mutex related problems */
#define  STATUS_MUTEX_ALREADY_HELD    0x40U    // Mutex wait() when mutex already held
#define  STATUS_MUTEX_NOT_HELD        0x80U    // Mutex signal() when not already held
#define  STATUS_MUTEX_NOT_RETURNED  0x100U    // Mutex not returned before job terminates
#define  STATUS_MUTEX_NOT_NESTED    0x200U    // Use of multiple mutexes not nested
 
/* Counting semaphore and data queue related problems */
#define  STATUS_SEMAPHORE_JOBS_FULL  0x400U    // Attempt to add job to semaphore pending list when list full
#define  STATUS_DATAQ_JOBS_FULL      0x800U    // Attempt to add job to data queue pending list when list full
#define  STATUS_DATAQ_FULL          0x1000U    // Data queue write when queue already full
 
/* Timed actions related problems */
#define  STATUS_TIMED_JOBS_FULL    0x2000U    // Timed actions queue already full for timed task start
#define  STATUS_TIMED_OUTPUT_FULL  0x4000U    // Timed actions queue already full for timed output
#define  STATUS_TIMED_ACTION_LATE  0x8000U    // Timed action late                          YES
 
/* Default trap handler should have been replaced
* NOT USED AT THE MOMENT*/
#define  STATUS_SYSTEM_ERROR      0x10000U    // ERROR was handled by default trap handler  YES
 
/* Flag to indicate problem with Stack Pointer
* NOT USED AT THE MOMENT*/
#define  STATUS_SP_WARNING        0x20000U    // SP not in expected range
/* Log system error */
#define  STATUS_BAD_LOG            0x40000U    // System log problem
#define  STATUS_SPIN_FAILED        0x80000U    // Get SPIN lock failed
/* Not using next few bits */
 
/* Will have to exit */
#define  STATUS_BAD_SENTINEL    0x40000000U    // Area sentinel corrupt
#define  STATUS_BAD_META_PTR    0x80000000U    // Null meta pointer
 
</syntaxhighlight>
 
===<span style="color:#0000ff">oceos_system_state_get()</span>===
<blockquote style="border-left-style: none;">
 
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
 
<span style="color:#1b7ac2">'''Description'''</span><br>
This function returns of the system state variable.
 
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Returns the value of the system state variable
*
* @param state  pointer to state holder
*
* @return  OCEOS_SUCCESS
*          ERR_SYS_FIXED_CORRUPT      System Fixed area corrupt
*          ERR_LOG_DATA_PTR_BAD        Data holder pointer is null
*          ERR_SYS_LOG_CORRUPT        LOG dynamic pointer is null
*/
S32_t oceos_system_state_get(
    U32_t *state // pointer to state holder
);
</syntaxhighlight>
 
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter || Description
|-
| state || U32_t pointer to state holder
|}
 
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| ERR_SYS_FIXED_CORRUPT      || System Fixed area corrupt
|-
| ERR_LOG_DATA_PTR_BAD        || Data holder pointer is null
|-
| ERR_SYS_LOG_CORRUPT        || LOG dynamic pointer is null
|}
 
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, state;
...
 
// Get the system state
status = oceos_system_state_get(&state);
 
</syntaxhighlight>
</blockquote>
 
===<span style="color:#0000ff">oceos_system_state_set()</span>===
<blockquote style="border-left-style: none;">
<blockquote style="border-left-style: none;">


<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function sets system state variable.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Sets system state variable
*
* @param new_state
*
* @return  OCEOS_SUCCESS
*          ERR_SYS_FIXED_CORRUPT      System Fixed area corrupt
*          ERR_SYS_LOG_CORRUPT        LOG dynamic pointer is null
*/
S32_t oceos_system_state_set(
    U32_t new_state  // new value of system state variable
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter || Description
|-
| new_state || U32_t containing new system state
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| ERR_SYS_FIXED_CORRUPT      || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT        || LOG dynamic pointer is null
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, new_state;
...
// Set new system state
status = oceos_system_state_set(new_state);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_system_state_copy_get()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function returns the value of the system state copy variable.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Returns the value of the copy of system state variable
*
* @param state  pointer to state holder
*
* @return  OCEOS_SUCCESS
*          ERR_SYS_FIXED_CORRUPT      System Fixed area corrupt
*          ERR_LOG_DATA_PTR_BAD        Data holder pointer is null
*          ERR_SYS_LOG_CORRUPT        LOG dynamic pointer is null
*/
S32_t oceos_system_state_copy_get(
    U32_t *state // pointer to state copy holder
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter || Description
|-
| state || U32_t pointer to state copy holder
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| ERR_SYS_FIXED_CORRUPT      || System Fixed area corrupt
|-
| ERR_LOG_DATA_PTR_BAD        || Data holder pointer is null
|-
| ERR_SYS_LOG_CORRUPT        || LOG dynamic pointer is null
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, copy_state;
...
// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_system_state_copy_set()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''system_log.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function loads a value to tha system state copy variable.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Sets system state copy variable
*
* @param new_state
*
* @return  OCEOS_SUCCESS
*          ERR_SYS_FIXED_CORRUPT      System Fixed area corrupt
*          ERR_SYS_LOG_CORRUPT        LOG dynamic pointer is null
*/
S32_t oceos_system_state_copy_set(
    U32_t new_state  // new value of system state variable
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter || Description
|-
| new_state || U32_t containing new system state copy
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| ERR_SYS_FIXED_CORRUPT      || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT        || LOG dynamic pointer is null
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, new_state;
...
// Set new system state copy
status = oceos_system_state_copy_set(new_state);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">blank_function()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''header.h'''''<br>
'''''header.h'''''<br>

Latest revision as of 16:56, 3 May 2024

Next Section

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));
Retrieved from ‘https://wiki.ocetechnology.com/mediawiki/index.php?title=OCEOSmp/blank&oldid=1702’