Typedefs | Enumerations | Functions
Serval_OpControl.h File Reference

An interface to control the operation of stack.The header file provides functions to pre-initialize the stack components, which means, setting some essential flags to zero in the case this is not done by the boot loader. This must be done exactly once when the devices boots. More...

#include <Serval_Defines.h>
#include <PBasics.h>
#include <Serval_Types.h>
#include <Serval_Exceptions.h>
+ Include dependency graph for Serval_OpControl.h:


typedef void(* EmergencyFunc_T )(retcode_t)
typedef retcode_t(* NVData_Func_T )(NVData_Dir_T dir, NVData_T *data_ptr)
typedef struct NVData_S NVData_T


enum  NVData_Dir_T


retcode_t OpControl_initialize (void)
bool OpControl_isActiv (void)
void OpControl_notify (retcode_t exception)
retcode_t OpControl_preInitialize (void)
void OpControl_registerEmergencyFunc (EmergencyFunc_T func)
void OpControl_registerNVDataFunc (NVData_Func_T func)
retcode_t OpControl_trySleep (void)
retcode_t OpControl_wakeUp (void)

Detailed Description

In some applications, the device needs to periodically switch off and go to a deep-sleep state, where RAM and CPU registers are not retained. The header provides the functions to put the stack to sleep and to wake it up in order to support such a duty-cycling mechanism.

It also allows the application to register the application functions which are needed by the stack. These are the following:

Each application needs to include this header and to invoke the following functions at the initialization phase in order to be able to use the stack correctly.

Typedef Documentation

typedef void(* EmergencyFunc_T)(retcode_t)

This data type represents a function pointer to an emergency function which will be called by the stack to inform application, in case of a fatal error is detected. The application must register such an emergency function.

See also
typedef retcode_t(* NVData_Func_T)(NVData_Dir_T dir, NVData_T *data_ptr)

A data type of a function for accessing the non-volatile data block of the stack.

This data type represents a function which is provided by the application and used by the stack to access the non-volatile data block.

[in]dirThe direction of the access, read or write.
[in]data_ptrpointer to the struct provided by the stack. In the case of a read access, it is used to read the non-volatile data into it. In the case of write access, it contains the data block which should be written to the non-volatile memory.
RC_OK if the data transfer was successful
RC_NV_MEMORY_ACCESS_ERROR if the access to non-volatile memory failed
See also
NVData_Dir_T, OpControl_registerNVDataFunc()
typedef struct NVData_S NVData_T

A type definition for the non-volatile data of the stack.

See also

Enumeration Type Documentation

This is a typedef for access type (read or write) to the non-volatile memory block.


Function Documentation

retcode_t OpControl_initialize ( void  )

This function initializes the operation control and the utility modules including Log, Exception Handling, Resources Monitor, etc. The application needs to explicitly invoke this function only if it needs to use any of the utility feature, such as logging, before initializing any protocols of the stack.

RC_OK if initialization was successful
RC_UTIL_INIT_ERROR if the initialization of the utility module fails.
bool OpControl_isActiv ( void  )

Return state of DutyCycling. If System is in sleep or an OperationControl_trySleep sequence is running, the function will return false. Modules should not operate any activity if OperationControl_isActiv returns false

true -> active, false->sleep or try sleep
void OpControl_notify ( retcode_t  exception)

This function is used to notify the operation control module about exceptions. It should be used when a runtime exception occurs and is being handled. This function will log the exception. In the case of a fatal exception it will also invoke the application emergency function, which has been registered by the application using OpControl_registerEmergencyFunc().

[in]exceptionThe exception code
See also
retcode_t OpControl_preInitialize ( void  )

This function must be invoked on booting the device software. It prepares the stack memory image. It must be called before calling any other functions/modules of the stack, even before the initialization of any modules of the stack. This function must not called more than once when the system starts!

RC_OK on success
void OpControl_registerEmergencyFunc ( EmergencyFunc_T  func)

This function registers an emergency function which is invoked in the case of fatal exceptions. The application must provide such an emergency callback which is able to recover the device from this faulty state. The application may for example reboot the device or to put it in a safe state.

[in]funcReference to a EmergencyFunc_T object which defines a callback which application wants exception handling module to call, in case of a fatal error is detected. It has to be a valid pointer.
void OpControl_registerNVDataFunc ( NVData_Func_T  func)

Using this function the application provides the stack with the function to access the non-volatile memory block.

[in]funcThe function to be used to access the non-volatile memory block. It has to be a valid pointer.
retcode_t OpControl_trySleep ( void  )

Try set the stack into sleep state. If there are no ongoing actions, which cannot be stopped, the function will return RC_OK. After this call no further stack requests are committed. The stack enters state SLEEP. If not successful the stack remains state ACTIVE and application shall call OperationControl_trySleep later.

RC_OK when stack is set to sleep
RC_RETRY_SLEEP_LATER stack not ready for sleep, retry function later
RC_ALREADY_SLEEP when stack is already sleeping
retcode_t OpControl_wakeUp ( void  )

Wake up the stack from sleep mode.

RC_OK when stack is awaken from sleep
RC_DOESNT_SLEEP stack is already active

This documentation file has been automatically generated on Wed May 6 2020 20:45:13 by doxygen 1.8.8