RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
rkh.h File Reference

RKH framwwork platform - independent interface. More...

#include "rkhitl.h"
#include "rkhrq.h"
#include "rkhmp.h"
#include "rkhtim.h"
#include "rkhassert.h"
#include "rkhtrc.h"

Go to the source code of this file.

Macros

#define RKH_MODULE_VERSION(__fname, __version)   static RKHROM char *const m_version = # __version;
 This macro appears at the top of each C/C++ source file defining the version string for that file (module). More...
 
#define RKH_MODULE_GET_VERSION()   ((const char *)m_version);
 Get the module version.
 
#define RKH_MODULE_DESC(__fname, __desc)   static RKHROM char *const m_desc = __desc;
 This macro appears at the top of each C/C++ source file defining the description string for that file (module). More...
 
#define RKH_MODULE_GET_DESC()   ((const char *)m_desc)
 Get the module description.
 
#define RKH_UPCAST(BaseType_, me_)   ((BaseType_ *)me_)
 Convert a pointer to a base-class. More...
 
#define RKH_DOWNCAST(DerivedType_, me_)   ((DerivedType_ *)me_)
 Converts a base-class pointer to a derived-class pointer.
 
#define ELSE   rkh_else
 Each condition connector can have one special branch with a guard labeled ELSE, which is taken if all the guards on the other branches are false. More...
 
#define RKH_CREATE_COMP_REGION_STATE(name, en, ex, parent, defchild, initialTrn, kindOfHistory, hDftTrnGuard, hDftTrnAction, hDftTarget, hRamMem)
 This macro creates a composite state with a single region, including its own initial pseudostate, history (shallow and deep type) pseudostate, as well as its own final state. More...
 
#define RKH_CREATE_COMP_STATE(name, en, ex, parent, defchild, history)
 This macro creates a composite state. More...
 
#define RKH_CREATE_FINAL_STATE(name, parent)
 This macro creates a final state. More...
 
#define RKH_CREATE_BASIC_STATE(name, en, ex, parent, prepro)
 This macro creates a basic state. More...
 
#define RKH_CREATE_COND_STATE(name)
 This macro creates a conditional pseudostate (a.k.a. junction). More...
 
#define RKH_CREATE_CHOICE_STATE(name)
 This macro creates a choice pseudostate. More...
 
#define RKH_CREATE_DEEP_HISTORY_STATE(name, parent, dftTrnGuard, dftTrnAction, dftTarget)
 
#define RKH_CREATE_SHALLOW_HISTORY_STATE(name, parent, dftTrnGuard, dftTrnAction, dftTarget)
 
#define RKH_CREATE_SUBMACHINE_STATE(name, en, ex, parent, sbm)
 This macro creates a submachine state. More...
 
#define RKH_CREATE_EX_CNNPNT_TABLE(name)
 This macro creates a exit point connection point reference table. More...
 
#define RKH_EX_CNNPNT(name, expnt, act, ts)   {(RKH_TRN_ACT_T)act, (RKHROM struct RKH_ST_T *)ts}
 This macro creates an exit point connection point reference. More...
 
#define RKH_END_EX_CNNPNT_TABLE   };
 This macro is used to terminate a exit point connection reference table. More...
 
#define RKH_EN_CNNPNT(name, enpnt, subm)
 This macro creates an entry point connection point reference. More...
 
#define RKH_CREATE_REF_SUBMACHINE(name, defchild, iact)
 This macro creates a submachine state machine, which is to be inserted in place of the (submachine) state. More...
 
#define RKH_CREATE_REF_EXPNT(name, ix, subm)
 This macro creates an exit point. More...
 
#define RKH_CREATE_REF_ENPNT(name, act, ts, subm)
 This macro creates a entry point. More...
 
#define RKH_CREATE_TRANS_TABLE(name)
 This macro creates a state transition table. More...
 
#define RKH_TRREG(evt_, guard_, effect_, target_)   MKTRN(evt_, guard_, effect_, target_)
 This macro defines a regular state transition. More...
 
#define RKH_TRINT(e, g, a)   {e, (RKH_GUARD_T)g, (RKH_TRN_ACT_T)a, NULL}
 This macro defines an internal state transition. Internal transitions are simple reactions to events that never lead to change of state and consequently never cause execution of exit actions, entry actions, or initial transitions. More...
 
#define RKH_TRCOMPLETION(guard_, effect_, target_)
 This macro defines a completion transition. More...
 
#define RKH_END_TRANS_TABLE   {RKH_ANY, NULL, NULL, NULL}};
 This macro is used to terminate a state transition table. This table have the general structure shown below: More...
 
#define RKH_CREATE_BRANCH_TABLE(name)
 
#define RKH_BRANCH(guard_, effect_, target_)   MKTRN(0, guard_, effect_, target_)
 This macro defines a branch in the branch table. More...
 
#define RKH_CREATE_HISTORY_STORAGE(compStateName)   static RKHROM RKH_ST_T *ramHist_##compStateName
 Define a RAM storage to mantain the last visited state of a composite state (history pseudostate). More...
 
#define RKH_GET_HISTORY_STORAGE(compStateName)   &ramHist_##compStateName
 Return the history storage address of a composite state. More...
 
#define RKH_END_BRANCH_TABLE   RKH_EBTBL};
 This macro is used to terminate a state transition table. This table have the general structure shown below: More...
 
#define RKH_ROOT   RKH_NULL
 This macro indicates the root state of a state machine.
 
#define RKH_SMA_DCLR(me_)   RKH_DCLR_PTR_TYPE(RKH_SMA_T, me_)
 This macro declares a opaque pointer to previously created state machine application (SMA aka active object) to be used as a global object. More...
 
#define RKH_SMA_DCLR_TYPE(type_, me_)   RKH_DCLR_PTR_TYPE(type_, me_)
 This macro declares a typed pointer to previously created state machine application (SMA aka active object) to be used as a global and public object. More...
 
#define RKH_SM_DCLR(me_)   RKH_DCLR_PTR_TYPE(RKH_SM_T, me_)
 This macro declares an opaque pointer to previously created state machine to be used as a global object. More...
 
#define RKH_SM_DCLR_TYPE(type_, me_)   RKH_DCLR_PTR_TYPE(type_, me_)
 This macro declares a typed pointer to previously created state machine to be used as a global and public object. More...
 
#define RKH_ARRAY_SMA_DCLR(_arr, _num)   extern RKH_SMA_T * const *_arr[_num]
 Declares a opaque pointer to previously created array of state machine applications SMA (a.k.a Active Object) to be used as a global object. More...
 
#define RKH_ARRAY_SMA_DCLR_TYPE(type_, array_, num_)   extern type_ * const * array_[num_]
 Declares a typed pointer to previously created array of state machine applications SMA (a.k.a Active Object) to be used as a global object. More...
 
#define RKH_ARRAY_SMA_CREATE(_arr, _num)   RKH_SMA_T * const *_arr[_num] =
 Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T. More...
 
#define RKH_ARRAY_SMA_CREATE_TYPE(type_, array_, num_)   type_ * const * array_[num_] =
 Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T. More...
 
#define RKH_ARRAY_SMA(_arr, _ix)   *_arr[_ix]
 Retrieves the pointer to active object from a SMA's array. More...
 
#define RKH_DCLR_SM_GLOBAL(sma_t, sm, gob)   sma_t * const gob = &s_##sm;
 Declares a previously created SMA to be used as a global object. More...
 
#define RKH_DECLARE_TR_TBL(name)   extern RKHROM RKH_TR_T name##_trtbl[]
 Declares a state transition table. More...
 
#define RKH_INIT_BASIC_STATE(name, en, ex, parent, prepro)
 Initializes the parameters (attibutes) of a basic state object. More...
 
#define RKH_INIT_COMPOSITE_STATE(name, en, ex, parent, defchild, history)
 Initializes the parameters (attibutes) of a composite state object. More...
 
#define RKH_GFALSE   RKH_FALSE
 This values are retrived by guard functions. More...
 
#define RKH_GTRUE   RKH_TRUE
 
#define RKH_TIM_TICK(_sender)   rkh_tmr_tick(_sender)
 Invoke the system clock tick processing rkh_tmr_tick(). More...
 
#define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_)
 Invoke the active object activation function rkh_sma_activate(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the active object to activate. More...
 
#define RKH_SM_CREATE(type, name, prio, ppty, initialState, initialAction, initialEvt)
 Use it to allocate a state machine regardless of an active object. More...
 
#define RKH_SM_INIT(me_, nameSMConst_, prio_, ppty_, initialState_, initialAction_, initialEvt_)
 Initialize (at runtime) a previously created state machine object. More...
 
#define RKH_SMA_CREATE(type, name, prio, ppty, initialState, initialAction, initialEvt)
 Declare and allocate a SMA (active object) derived from RKH_SMA_T. Also, initializes and assigns a state machine to previously declared SMA. More...
 
#define RKH_SM_CONST_CREATE(name, prio, ppty, initialState, initialAction, initialEvt)
 Allocates and then initializes the constant part (in ROM) of the state machine. More...
 
#define RKH_SM_GET_CONST(sm)   ((RKH_SM_T *)sm)->romrkh
 Return the address of the constant part from a previously created and initializated state machine. More...
 
#define RKH_SM_GET_CONST_OBJ(sm)   &RKH_SM_CONST_NAME(sm)
 Return the address of the constant part of a state machine. More...
 
#define RKH_SM_DEF_PTR(sm)   RKH_SM_T *const sm = (RKH_SM_T *)&RKH_SM_NAME(sm)
 Declare an opaque pointer pointing to a previously created state machine. More...
 
#define RKH_SM_DEF_PTR_TYPE(type, sm)   type *const sm = (type *)&RKH_SM_NAME(sm)
 Declare a pointer of specified type pointing to a previously created state machine. More...
 
#define RKH_SMA_DEF_PTR(me_)   RKH_SMA_T *const me_ = (RKH_SMA_T *)&RKH_SMA_NAME(me_)
 Declare a opaque pointer pointing to an previously created active object. More...
 
#define RKH_SMA_DEF_PTR_TYPE(type, me_)   type *const me_ = (type *)&RKH_SMA_NAME(me_)
 Declare a pointer of specified type pointing to an previously created active object. More...
 
#define RKH_SMA_POST_FIFO(me_, e_, sender_)   rkh_sma_post_fifo((me_), (e_), (sender_))
 Invoke the direct event posting facility rkh_sma_post_fifo(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the target active object. More...
 
#define RKH_SMA_POST_LIFO(me_, e_, sender_)   rkh_sma_post_lifo((me_), (e_), (sender_))
 Invoke the direct event posting facility rkh_sma_post_lifo(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the target active object. More...
 
#define RKH_ALLOC_EVT(et, e)   (et *)rkh_fwk_ae((RKH_ES_T)sizeof(et),(RKH_SIG_T)(e))
 This macro dynamically creates a new event of type et with its signal. More...
 
#define RKH_FWK_GC(e)   rkh_fwk_gc(e)
 Recycle a dynamic event. More...
 
#define RKH_FWK_RSV(e)   rkh_fwk_reserve(e)
 Reserve the dynamic event to be recycled. More...
 
#define RKH_SET_STATIC_EVENT(ev_obj, ev_sig)   MK_SET_EVT(ev_obj, ev_sig)
 This macro initialize an event e with es signal and establishes it as one static event. More...
 
#define RKH_STATIC_EVENT(ev_obj, ev_sig)   MK_EVT(ev_obj, ev_sig)
 This macro declares and initializes the event structure ev_ob with ev_sig signal number and establishes it as one static event. More...
 
#define RKH_ROM_STATIC_EVENT(ev_obj, ev_sig)   MK_ROM_EVT(ev_obj, ev_sig)
 This macro declares and initializes the event structure ev_ob with ev_sig signal number and establishes it as one static event. More...
 
#define RKH_INIT_STATIC_EVT(ev_sig)   MK_EVT_STRUCT(ev_sig)
 Initializes the attibutes of a RKH's event object structure. More...
 
#define RKH_GET_CSTATE_ID(me)   ((RKH_BASE_T *)(((RKH_SM_T *)me)->state))->id
 This macro retrieves the state ID of SMA. More...
 
#define RKH_GET_AO_NAME(ao)   RKH_SMA_ACCESS_CONST(ao, name)
 This macro retrieves the name of an registered active object. More...
 
#define RKH_GET_VERTEX_NAME(vx)   ((struct RKH_BASE_T *)(vx))->name
 This macro retrieves the name of a vertex. More...
 
#define RKH_GET_SMA(_prio)   rkh_sptbl[(rui8_t)(_prio)]
 Retrieves the address of an registered active object (SMA) according to its priority. More...
 
#define RKH_GET_PRIO(_ao)   (rui8_t)(RKH_SMA_ACCESS_CONST(_ao, prio))
 Retrieves the priority number of an registered active object (SMA). More...
 
#define RKH_EVT_CAST(_e)   ((RKH_EVT_T *)(_e))
 Perform cast to pointer to RKH event structure (RKH_EVT_T*).
 
#define RKH_CAST(_type, _obj)   ((_type *)(_obj))
 Perform downcast of a reference of a base class to one of its derived classes. More...
 
#define RKH_TRC_OPEN()   rkh_trc_open()
 Open the tracing session. More...
 
#define RKH_TRC_CLOSE()   rkh_trc_close()
 Close the tracing session. More...
 
#define RKH_TRC_FLUSH()   rkh_trc_flush()
 Platform-dependent macro flushing the trace stream. More...
 
#define RKH_TRC_SEND_CFG(ts_hz)   RKH_TR_FWK_TCFG(ts_hz)
 Send the trace facility configuration to host application software Trazer. More...
 
#define RKH_DCLR_COMP_STATE   extern RKHROM RKH_SCMP_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_BASIC_STATE   extern RKHROM RKH_SBSC_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_FINAL_STATE   extern RKHROM RKH_FINAL_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_COND_STATE   extern RKHROM RKH_SCOND_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_CHOICE_STATE   extern RKHROM RKH_SCHOICE_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_DHIST_STATE   extern RKHROM RKH_SHIST_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_SHIST_STATE   extern RKHROM RKH_SHIST_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_SUBM_STATE   extern RKHROM RKH_SSBM_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_REF_SUBM   extern RKHROM RKH_RSM_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_ENPNT   extern RKHROM RKH_SENP_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_REF_EXPNT   extern RKHROM RKH_SEXP_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 
#define RKH_DCLR_REF_ENPNT   extern RKHROM RKH_ENPCN_T
 Declares a previously created state/pseudostate to be used as a global object. More...
 

Enumerations

enum  RKH_RCODE_T {
  RKH_EVT_PROC,
  RKH_EVT_NFOUND,
  RKH_CND_NFOUND,
  RKH_GRD_FALSE,
  RKH_UNKN_STATE,
  RKH_EX_HLEVEL,
  RKH_EX_TSEG
}
 Return codes from rkh_sm_dispatch() function. More...
 
enum  RKH_HPPTY_T {
  HCAL,
  FLAT,
  RKH_NUM_HPPTY
}
 State machine properties. More...
 

Functions

void rkh_fwk_init (void)
 Initializes the RKH framework. More...
 
void rkh_fwk_enter (void)
 RKH framework is started. More...
 
void rkh_fwk_exit (void)
 Exit the RKH framework. More...
 
void rkh_sma_terminate (RKH_SMA_T *me)
 Terminate a state machine application (SMA) as known as active object. More...
 
void rkh_tmr_tick (const void *const sender)
 Keep tracks and updates the started timers. More...
 
void rkh_sma_activate (RKH_SMA_T *me, const RKH_EVT_T **qSto, RKH_RQNE_T qSize, void *stkSto, rui32_t stkSize)
 Initializes and activates a previously created state machine application (SMA) as known as active object. More...
 
void rkh_sma_post_fifo (RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
 Send an event to a state machine application (SMA) as known as active object through a queue using the FIFO policy. A message is a pointer size variable and its use is application specific. More...
 
void rkh_sma_post_lifo (RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
 Send an event to a state machine application (SMA) as known as active object through a queue using the LIFO policy. A message is a pointer size variable and its use is application specific. More...
 
RKH_EVT_Trkh_sma_get (RKH_SMA_T *me)
 Get an event from the event queue of an state machine application (SMA) as known as active object. The events received are pointer size variables and their use is application specific. More...
 
void rkh_sma_get_info (RKH_SMA_T *me, RKH_SMAI_T *psi)
 Retrieves performance information for a particular state machine application (SMA) as known as active object. More...
 
void rkh_sma_clear_info (RKH_SMA_T *me)
 Clear performance information for a particular state machine application (SMA) as known as active object. More...
 
void rkh_sma_register (RKH_SMA_T *me)
 Registers a state machine application (SMA) as known as active object into the framework, which implies to store a pointer to the SMA in the priority table. More...
 
void rkh_sma_unregister (RKH_SMA_T *me)
 Removes the SMA as known as active object from the priority table, and thus from the framework, by simply replacing the link to the SMA being deleted with a NULL pointer. More...
 
void rkh_sma_ctor (RKH_SMA_T *me, const RKHSmaVtbl *vtbl)
 Initializes the virtual table of the active object instance and calls the constructor operation of its base class. More...
 
void rkh_fwk_defer (RKH_RQ_T *q, const RKH_EVT_T *e)
 Defer an event to a given separate event queue. More...
 
RKH_EVT_Trkh_fwk_recall (RKH_SMA_T *me, RKH_RQ_T *q)
 Recall a deferred event from a given event queue. More...
 
void rkh_fwk_epool_register (void *sstart, rui32_t ssize, RKH_ES_T esize)
 Registers a new event pool into the event pool list. More...
 
RKH_EVT_Trkh_fwk_ae (RKH_ES_T esize, RKH_SIG_T e)
 Allocates an event from the previously created event pool. More...
 
void rkh_fwk_gc (RKH_EVT_T *e)
 Recycle a dynamic event. More...
 
void rkh_fwk_reserve (RKH_EVT_T *e)
 Reserve the dynamic event to be recycled. More...
 
void rkh_hook_dispatch (RKH_SMA_T *me, RKH_EVT_T *e)
 When dispatching an event to a SMA the dispatch hook function will be executed. More...
 
void rkh_hook_signal (RKH_EVT_T *e)
 When the producer of an event directly posts the event to the event queue of the consumer SMA the rkh_hook_signal() will optionally called. More...
 
void rkh_hook_timeout (const void *t)
 If a timer expires the rkh_hook_timeout() function is called just before the assigned event is directly posted into the state machine application queue. More...
 
void rkh_hook_start (void)
 This hook function is called just before the RKH takes over control of the application. More...
 
void rkh_hook_exit (void)
 This hook function is called just before the RKH returns to the underlying OS/RTOS. Usually, the rkh_hook_exit() is useful when executing clean-up code upon SMA terminate or framework exit. More...
 
void rkh_hook_idle (void)
 An idle hook function will only get executed (with interrupts LOCKED) when there are no SMAs of higher priority that are ready to run. More...
 
void rkh_hook_timetick (void)
 This function is called by rkh_tmr_tick(), which is assumed to be called from an ISR. rkh_hook_timetick() is called at the very beginning of rkh_tmr_tick(), to give priority to user or port-specific code when the tick interrupt occurs. More...
 
void rkh_hook_putTrcEvt (void)
 This function is called from rkh_trc_end() function, at the end of that, to allow to the application to extend the functionality of RKH, giving the port developer the opportunity to add code that will be called when is put a trace event into the stream buffer.
 
void rkh_sm_init (RKH_SM_T *me)
 Inits a previously created state machine calling its initializing action. More...
 
ruint rkh_sm_dispatch (RKH_SM_T *me, RKH_EVT_T *e)
 Executes a state machine in a run-to-completation (RTC) model. More...
 
void rkh_sm_ctor (RKH_SM_T *me)
 Initializes the attributes of the state machine instance. More...
 
void rkh_sm_clear_history (RKHROM RKH_SHIST_T *h)
 Erase the history of a state. It can be a shallow or deep history. More...
 
void rkh_trc_open (void)
 Open the tracing session.
 
void rkh_trc_close (void)
 Close the tracing session.
 
void rkh_trc_flush (void)
 Platform-dependent macro flushing the trace stream.
 
RKH_TS_T rkh_trc_getts (void)
 Retrieves a timestamp to be placed in a trace event. More...
 

Variables

RKH_SMA_Trkh_sptbl [RKH_CFG_FWK_MAX_SMA]
 Priority arranged table of registered SMA. More...
 
RKHROM rui8_t rkh_maptbl [8]
 rkh_maptbl[] is a table in ROM, used to equate an index from 0 to 7 to a bit mask.
 
RKHROM rui8_t rkh_unmaptbl [256]
 rkh_unmaptbl[] is a table in ROM, used to return the bit position of the highest priority bit set - a number between 0 and 7.
 
RKHROM char rkh_version []
 String describing the RKH version.
 
RKHROM char noname []
 String representing the name of undefined object name.
 
RKH_DYNE_TYPE rkh_eplist [RKH_CFG_FWK_MAX_EVT_POOL]
 Event pool list.
 

Detailed Description

RKH framwwork platform - independent interface.

Definition in file rkh.h.

Macro Definition Documentation

#define RKH_MODULE_VERSION (   __fname,
  __version 
)    static RKHROM char *const m_version = # __version;

This macro appears at the top of each C/C++ source file defining the version string for that file (module).

Parameters
[in]__fnamefile (module) name.
[in]__versionfile (module) version.

Definition at line 125 of file rkh.h.

#define RKH_MODULE_DESC (   __fname,
  __desc 
)    static RKHROM char *const m_desc = __desc;

This macro appears at the top of each C/C++ source file defining the description string for that file (module).

Parameters
[in]__fnamefile (module) name.
[in]__descfile (module) description.

Definition at line 143 of file rkh.h.

#define ELSE   rkh_else

Each condition connector can have one special branch with a guard labeled ELSE, which is taken if all the guards on the other branches are false.

A guard function takes the state machine pointer and the event pointer as arguments. These arguments are optional, thus they could be eliminated in compile-time by means of RKH_EN_GRD_EVT_ARG and RKH_EN_GRD_HSM_ARG preprocessor directives.

Definition at line 327 of file rkh.h.

#define RKH_EX_CNNPNT (   name,
  expnt,
  act,
  ts 
)    {(RKH_TRN_ACT_T)act, (RKHROM struct RKH_ST_T *)ts}

This macro creates an exit point connection point reference.

Connection point references are sources/targets of transitions implying exits out of/entries into the submachine state machine referenced by a submachine state.

An exit point connection point reference as the source of a transition implies that the source of the transition is the exit point pseudostate as defined in the submachine of the submachine state that has the exit point connection point defined.

A connection point reference to an exit point has the same notation as an exit point pseudostate.

Parameters
[in]nameexit point connection point reference name.
[in]expntreferenced exit point.
[in]actpointer to transition action function. This argument is optional, thus it could be declared as NULL.
[in]tspointer to target state.
See also
RKH_EXPCN_T structure definition for more information.
Usage
// --- exit point pseudostates of SB submachine ---
0, // index of exit point connection table
&SB );
1, // index of exit point connection table
&SB );
...
// --- exit point connection references of S12 submachine state ---
RKH_CREATE_EX_CNNPNT_TABLE( S12 )
RKH_EX_CNNPNT( EX1S12, &EXPNT1, ... ), // table index = 0 (EXPNT1)
RKH_EX_CNNPNT( EX2S12, &EXPNT2, ... ), // table index = 1 (EXPNT2)

Definition at line 815 of file rkh.h.

#define RKH_END_EX_CNNPNT_TABLE   };

This macro is used to terminate a exit point connection reference table.

Note
This macro is not terminated with the semicolon.
Usage
This table have the general structure shown below:
RKH_EX_CNNPNT( EX1S2, &EXPNT1, NULL, &S1 ),
RKH_EX_CNNPNT( EX2S2, &EXPNT2, NULL, &S3 ),
Each exit point table always begins with the macro RKH_CREATE_EX_CNNPNT_TABLE() and ends with the macro RKH_END_EX_CNNPNT_TABLE(). As noted above, sandwiched between these macros are the exit point macros, RKH_EX_CNNPNT().

Definition at line 839 of file rkh.h.

#define RKH_EN_CNNPNT (   name,
  enpnt,
  subm 
)
Value:
\
RKHROM RKH_SENP_T name = \
{ \
MKBASE(RKH_ENPOINT, name), \
MKENP(enpnt,subm) \
}
Describes the entry point pseudostate.
Definition: rkhitl.h:3691

This macro creates an entry point connection point reference.

Connection point references are sources/targets of transitions implying exits out of/entries into the submachine state machine referenced by a submachine state.

An entry point connection point reference as the target of a transition implies that the target of the transition is the entry point pseudostate as defined in the submachine of the submachine state.

A connection point reference to an entry point has the same notation as an entry point pseudostate.

Parameters
[in]nameentry point connection point reference name.
[in]enpntreferenced entry point.
[in]submpointer to submachine state.
See also
RKH_SENP_T structure definition for more information.

Definition at line 863 of file rkh.h.

#define RKH_TRREG (   evt_,
  guard_,
  effect_,
  target_ 
)    MKTRN(evt_, guard_, effect_, target_)

This macro defines a regular state transition.

The general syntax of an expression labelling a transition in a statechart is "i[c]/a" where i is the input that triggers the transition, c is a condition that guards the transition from being taken unless it is true when i occurs, and a is an action that is carried out if and when the transition is taken. All of these parts are optional.

Parameters
[in]evt_triggering event.
[in]guard_pointer to guard function. This argument is optional, thus it could be declared as NULL.
[in]effect_pointer to action function. This argument is optional, thus it could be declared as NULL.
[in]target_pointer to target state.
See also
RKH_TR_T structure definition for more information.
Usage
RKH_TRREG( TOUT0, // triggering event
is_full, // guard function
drop_frame, // action function
&WAIT_SYNC ) // next state

Definition at line 1051 of file rkh.h.

#define RKH_TRINT (   e,
  g,
 
)    {e, (RKH_GUARD_T)g, (RKH_TRN_ACT_T)a, NULL}

This macro defines an internal state transition. Internal transitions are simple reactions to events that never lead to change of state and consequently never cause execution of exit actions, entry actions, or initial transitions.

Parameters
[in]etriggering event.
[in]gpointer to guard function.
[in]apointer to action function.
See also
RKH_TR_T structure definition for more information.
Usage
RKH_TRINT( RCV_DATA, // triggering event
is_sync, // guard function
store_data ) // action function

Definition at line 1075 of file rkh.h.

#define RKH_TRCOMPLETION (   guard_,
  effect_,
  target_ 
)
Value:
(RKH_GUARD_T)guard_, (RKH_TRN_ACT_T)effect_, target_}
void(* RKH_TRN_ACT_T)(const RKH_SM_T *me, RKH_EVT_T *pe)
Transition action.
Definition: rkhitl.h:3207
#define RKH_COMPLETION_EVENT
This macro is used to indicate the completion event.
Definition: rkhitl.h:153
rbool_t(* RKH_GUARD_T)(const RKH_SM_T *me, RKH_EVT_T *pe)
Guard.
Definition: rkhitl.h:3246

This macro defines a completion transition.

A special kind of transition is a completion transition, which has an implicit trigger. The event that enables this trigger is called a completion event and it signifies that all behaviors associated with the source state of the completion transition have completed execution. In case of simple states, a completion event is generated when the associated entry behavior have completed executing. If no such behaviors are defined, the completion event is generated upon entry into the state. For composite state, a completion event is generated under the following circumstances:

  • All internal activities (e.g., entry behavior) have completed execution, and
  • its region have reached a finalState.
Parameters
[in]guard_pointer to guard function. This argument is optional, thus it could be declared as NULL.
[in]effect_pointer to effect function. This argument is optional, thus it could be declared as NULL.
[in]target_pointer to target vertex (state or pseudostate).
See also
RKH_TR_T structure definition for more information.
Usage
RKH_TRCOMPLETION(isFull, // guard function
dropFrame, // effect function
&waitSync), // next state

Definition at line 1110 of file rkh.h.

#define RKH_END_TRANS_TABLE   {RKH_ANY, NULL, NULL, NULL}};

This macro is used to terminate a state transition table. This table have the general structure shown below:

RKH_CREATE_TRANS_TABLE( state_name ) // transition table begin
RKH_TRxx( ... ) // transition
RKH_TRxx( ... ) // transition
...
RKH_END_TRANS_TABLE // transition table end

Each transition table always begins with the macro RKH_CREATE_TRANS_TABLE() and ends with the macro RKH_END_TRANS_TABLE(). As noted above, sandwiched between these macros are the transitions macros that actually represent behavior of state.

Note
This macro is not terminated with the semicolon.

Definition at line 1134 of file rkh.h.

#define RKH_BRANCH (   guard_,
  effect_,
  target_ 
)    MKTRN(0, guard_, effect_, target_)

This macro defines a branch in the branch table.

Each condition connector can have one special branch with a guard labeled rkh_else, which is taken if all the guards on the other branches are false. The general syntax of an expression labelling a branch in a statechart is "[c]/a" where c is a condition that guards the transition from being taken unless it is true, and a is an action that is carried out if and when the transition is taken. All of these parts are optional.

Parameters
[in]guard_branch guard function. Branches are labeled with guards that determine which one is to be actually taken. Use ELSE macro when if all the guards on the other branches are false.
[in]effect_pointer to transition action. This argument is optional, thus it could be declared as NULL.
[in]target_pointer to target state.
See also
RKH_TR_T structure definition for more information.
Usage
RKH_BRANCH( is_power_ok, enable_process, &power ),
RKH_BRANCH( is_switch_off, turnoff, &wait ),
RKH_BRANCH( ELSE, abort, &aborted ),

Definition at line 1196 of file rkh.h.

#define RKH_GET_HISTORY_STORAGE (   compStateName)    &ramHist_##compStateName

Return the history storage address of a composite state.

Frequently, it's used in the hRamMem parameter of RKH_CREATE_COMP_REGION_STATE() macro to define the dynamic storage of a history pseudostate.

Parameters
[in]compStateNamepointer to the composite state that contains this history pseudostate.

Definition at line 1226 of file rkh.h.

#define RKH_END_BRANCH_TABLE   RKH_EBTBL};

This macro is used to terminate a state transition table. This table have the general structure shown below:

RKH_BRANCH( is_power_ok, enable_process, &power ),
RKH_BRANCH( is_switch_off, turnoff, &wait ),
RKH_BRANCH( ELSE, abort, &aborted ),

Each branch table always begins with the macro RKH_CREATE_BRANCH_TABLE() and ends with the macro RKH_END_BRANCH_TABLE().

See also
This macro is not terminated with the semicolon.

Definition at line 1253 of file rkh.h.

#define RKH_SMA_DCLR (   me_)    RKH_DCLR_PTR_TYPE(RKH_SMA_T, me_)

This macro declares a opaque pointer to previously created state machine application (SMA aka active object) to be used as a global object.

This global pointer represent the active object in the application. These pointers are "opaque" because they cannot access the whole active object structure, but only the part inherited from the RKH_SMA_T structure. The power of an "opaque" pointer is that it allows to completely hide the definition of the active object structure and make it inaccessible to the rest of the application, thus strengthening the encapsulation concept.

Parameters
[in]me_pointer to previously created state machine application.
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE().
Usage
// my.h: state-machine application's header file

Definition at line 1288 of file rkh.h.

#define RKH_SMA_DCLR_TYPE (   type_,
  me_ 
)    RKH_DCLR_PTR_TYPE(type_, me_)

This macro declares a typed pointer to previously created state machine application (SMA aka active object) to be used as a global and public object.

Parameters
[in]type_Data type of the state machine application. Could be derived from RKH_SMA_T. The pointer could be used to publish the internals of the class of the state machine.
[in]me_pointer to previously created state machine application.
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE(), RKH_SMA_DCLR().
Usage
// my.h: state-machine application's header file
RKH_SMA_DCLR_TYPE(Blinky, blinky);

Definition at line 1317 of file rkh.h.

#define RKH_SM_DCLR (   me_)    RKH_DCLR_PTR_TYPE(RKH_SM_T, me_)

This macro declares an opaque pointer to previously created state machine to be used as a global object.

This global pointer represent the state machine in the application. The state machine pointers are "opaque" because they cannot access the whole state machine structure, but only the part inherited from the RKH_SM_T structure. The power of an "opaque" pointer is that it allows to completely hide the definition of the state machine structure and make it inaccessible to the rest of the application.

Parameters
[in]me_Pointer to previously created state machine.
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE(), RKH_SM_CREATE().
Usage
// ColorRegion.h: state machine's header file
RKH_SM_DCLR_TYPE(ColorRegion, color);

Definition at line 1347 of file rkh.h.

#define RKH_SM_DCLR_TYPE (   type_,
  me_ 
)    RKH_DCLR_PTR_TYPE(type_, me_)

This macro declares a typed pointer to previously created state machine to be used as a global and public object.

Parameters
[in]type_Data type of the state machine, derived from RKH_SM_T.
[in]me_Pointer to previously created state machine.
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE(), RKH_SM_CREATE().
Usage
// ColorRegion.h: state machine's header file
RKH_SM_DCLR_TYPE(ColorRegion, color);

Definition at line 1372 of file rkh.h.

#define RKH_DCLR_COMP_STATE   extern RKHROM RKH_SCMP_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1384 of file rkh.h.

#define RKH_DCLR_BASIC_STATE   extern RKHROM RKH_SBSC_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1385 of file rkh.h.

#define RKH_DCLR_FINAL_STATE   extern RKHROM RKH_FINAL_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1386 of file rkh.h.

#define RKH_DCLR_COND_STATE   extern RKHROM RKH_SCOND_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1387 of file rkh.h.

#define RKH_DCLR_CHOICE_STATE   extern RKHROM RKH_SCHOICE_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1388 of file rkh.h.

#define RKH_DCLR_DHIST_STATE   extern RKHROM RKH_SHIST_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1389 of file rkh.h.

#define RKH_DCLR_SHIST_STATE   extern RKHROM RKH_SHIST_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1390 of file rkh.h.

#define RKH_DCLR_SUBM_STATE   extern RKHROM RKH_SSBM_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1391 of file rkh.h.

#define RKH_DCLR_REF_SUBM   extern RKHROM RKH_RSM_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1392 of file rkh.h.

#define RKH_DCLR_ENPNT   extern RKHROM RKH_SENP_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1393 of file rkh.h.

#define RKH_DCLR_REF_EXPNT   extern RKHROM RKH_SEXP_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1394 of file rkh.h.

#define RKH_DCLR_REF_ENPNT   extern RKHROM RKH_ENPCN_T

Declares a previously created state/pseudostate to be used as a global object.

Note
Generally, this macro is used in the state-machine's header file.

Definition at line 1395 of file rkh.h.

#define RKH_ARRAY_SMA_DCLR (   _arr,
  _num 
)    extern RKH_SMA_T * const *_arr[_num]

Declares a opaque pointer to previously created array of state machine applications SMA (a.k.a Active Object) to be used as a global object.

Parameters
[in]_arrpointer to previously created array of state machine applications. To do that is recommended to use the macro RKH_ARRAY_SMA_CREATE().
[in]_numsize of array [in active objects].
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE().
Usage
// cli.h: state-machine application's header file
#define NUM_CLIENTS 4
typedef struct
{
RKH_SMA_T me; // base structure
RKH_TMR_T cli_utmr; // usage time
RKH_TMR_T cli_rtmr; // waiting request time
} CLI_T; // Active Object derived from RKH_SMA_T structure
RKH_ARRAY_SMA_DCLR( clis, NUM_CLIENTS );

Definition at line 1429 of file rkh.h.

#define RKH_ARRAY_SMA_DCLR_TYPE (   type_,
  array_,
  num_ 
)    extern type_ * const * array_[num_]

Declares a typed pointer to previously created array of state machine applications SMA (a.k.a Active Object) to be used as a global object.

Parameters
[in]type_data type of active object.
[in]array_pointer to previously created array of state machine applications. To do that is recommended to use the macro RKH_ARRAY_SMA_CREATE_TYPE().
[in]num_size of array [in active objects].
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE().
Usage
// cli.h: state-machine application's header file
#define NUM_CLIENTS 4
typedef struct
{
RKH_SMA_T me; // base structure
RKH_TMR_T cli_utmr; // usage time
RKH_TMR_T cli_rtmr; // waiting request time
} CLI_T; // Active Object derived from RKH_SMA_T structure
RKH_ARRAY_SMA_DCLR_TYPE(CLI_T, clis, NUM_CLIENTS);

Definition at line 1464 of file rkh.h.

#define RKH_ARRAY_SMA_CREATE (   _arr,
  _num 
)    RKH_SMA_T * const *_arr[_num] =

Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T.

Parameters
[in]_arrname of SMA's array.
[in]_numsize of array [in active objects].
Usage
// Defines SMAs (a.k.a Active Objects)
RKH_SMA_CREATE( CLI_T, cli0, 1, HCAL, &cli_idle, cli_init, NULL );
RKH_SMA_CREATE( CLI_T, cli1, 2, HCAL, &cli_idle, cli_init, NULL );
RKH_SMA_CREATE( CLI_T, cli2, 3, HCAL, &cli_idle, cli_init, NULL );
RKH_SMA_CREATE( CLI_T, cli3, 4, HCAL, &cli_idle, cli_init, NULL );
RKH_ARRAY_SMA_CREATE( clis, NUM_CLIENTS )
{
&cli0, &cli1, &cli2, &cli3
};

Definition at line 1490 of file rkh.h.

#define RKH_ARRAY_SMA_CREATE_TYPE (   type_,
  array_,
  num_ 
)    type_ * const * array_[num_] =

Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T.

Parameters
[in]type_data type of active object.
[in]array_name of SMA's array.
[in]num_size of array [in active objects].
Usage
// Defines SMAs (a.k.a Active Objects)
RKH_SMA_CREATE(CLI_T, cli0, 1, HCAL, &cli_idle, cli_init, NULL);
RKH_SMA_CREATE(CLI_T, cli1, 2, HCAL, &cli_idle, cli_init, NULL);
RKH_SMA_CREATE(CLI_T, cli2, 3, HCAL, &cli_idle, cli_init, NULL);
RKH_SMA_CREATE(CLI_T, cli3, 4, HCAL, &cli_idle, cli_init, NULL);
RKH_ARRAY_SMA_CREATE(CLI_T, clis, NUM_CLIENTS)
{
&cli0, &cli1, &cli2, &cli3
};

Definition at line 1517 of file rkh.h.

#define RKH_ARRAY_SMA (   _arr,
  _ix 
)    *_arr[_ix]

Retrieves the pointer to active object from a SMA's array.

Parameters
[in]_arrname of SMA's array.
[in]_ixindex (position in the array).
Usage
#define NUM_CLIENTS 4
#define CLI( _clino ) RKH_ARRAY_SMA( clis, _clino )
#define CLI0 CLI(0)
#define CLI1 CLI(1)
#define CLI2 CLI(2)
#define CLI3 CLI(3)
typedef struct
{
RKH_SMA_T me; // base structure
RKH_TMR_T cli_utmr; // usage time
RKH_TMR_T cli_rtmr; // waiting request time
} CLI_T; // Active Object derived from RKH_SMA_T structure
RKH_ARRAY_SMA_DCLR( clis, NUM_CLIENTS );

Definition at line 1547 of file rkh.h.

#define RKH_DCLR_SM_GLOBAL (   sma_t,
  sm,
  gob 
)    sma_t * const gob = &s_##sm;

Declares a previously created SMA to be used as a global object.

Parameters
[in]sma_tdata type of SMA.
[in]smname of previously created SMA.
[in]gobname of global object.
Note
Generally, this macro is used in the state-machine's module.
See also
RKH_SMA_T structure definition for more information. Also, single inheritance in C , and another example .
Usage
// g_my: global pointer to SMA "my".
RKH_DCLR_SM_GLOBAL( MYSM_T, my, g_my );

Definition at line 1571 of file rkh.h.

#define RKH_DECLARE_TR_TBL (   name)    extern RKHROM RKH_TR_T name##_trtbl[]

Declares a state transition table.

Parameters
[in]namename of state (basic or composite) object.

Definition at line 1580 of file rkh.h.

#define RKH_INIT_BASIC_STATE (   name,
  en,
  ex,
  parent,
  prepro 
)
Value:
{ \
{ \
MKBASE(RKH_BASIC, name), /* RKH_BASE_T */ \
MKST(en, ex, parent) \
}, /* RKH_ST_T */ \
MKBASIC(name, prepro) \
} /* RKH_SBSC_T */ \

Initializes the parameters (attibutes) of a basic state object.

By means of single inheritance in C it could be used to associate data to a basic state. Moreover, implementing the single inheritance in C is very simply by literally embedding the base type, RKH_SBSC_T in this case, as the first member of the derived structure. The following listing shows an example:

See also
See RKH_CREATE_BASIC_STATE() macro for more information.
Usage
(1) typedef struct MENU_ST_T
{
(2) RKHROM RKH_SBSC_T base;
(3) const char *title;
} MENU_ST_T;
...
(4) #define MENU_BASIC_STATE( type_t, name, en, ex, parent, title ) \
(5) RKH_DECLARE_TR_TBL( name ); \
\
(6) RKHROM type_t name = \
{ \
(7) RKH_INIT_BASIC_STATE( name, en, ex, parent, NULL ), \
(8) title \
}
(9) MENU_BASIC_STATE( MENU_ST_T, menu_cfg, NULL, NULL, RKH_ROOT,
"Menu 1" );
RKH_TRREG( TIMEOUT, NULL, mc_title, &menu_cfg_resume ),
...
...
(10) void
mc_title( const struct RKH_SMA_T *me )
{
...
lcd_print("%s\n",
((MENU_ST_T *)(((RKH_SM_T *)me)->state))->title);
}

(1) Defines MENU_ST_T as a derived structure from the basic state structure. It could be used to associate data to a basic state objects.
(2) Implementing the single inheritance in C is very simply by literally embedding the base type, RKH_SBSC_T in this case, as the first member of the derived structure.
(3) Private members of MENU_ST_T derived structure.
(4) Defines a simple macro to instantiate the derived state object. It is not strictly necessary.
(4) Declares the transtion table by means of RKH_DECLARE_TR_TBL() macro provided by the framework.
(6) Instantiates the derived state structure.
(7) Initializes the base structure, basic state in this case, using the RKH_INIT_BASIC_STATE() macro provided by the framework.
(8) Initializes the private member of derived state.
(9) Invokes the BLINKY_BASIC_STATE() macro to instantiate the derived state object, menu_cfg. Note that the "Menu 1" string is associated to the state machine context, menu_cfg state in this case.
(10) Lastly, on the transtion action mc_title(), or any other action, is used the state data after casting the active object state to derived state object.

The following listing shows another example for derived state structure, which access to RAM from ROM object (state structure).

typedef struct XY_T
{
int x;
int y;
} XY_T;
(1) typedef struct NUM_STATE_T
{
(2) RKHROM RKH_SBSC_T base;
(3) XY_T *p_ram_xy;
} NUM_STATE_T;
(4) #define NUM_BASIC_STATE( name, en, ex, parent, p_xy ) \
\
RKHROM NUM_STATE_T name = \
{ \
RKH_INIT_BASIC_STATE( name, en, ex, parent, NULL ), \
(5) p_xy \
}
static XY_T xy;
(6) NUM_BASIC_STATE( num, NULL, NULL, RKH_ROOT, &xy );
void
num_inc( const struct RKH_SMA_T *me )
{
(7) ((NUM_STATE_T *)(((RKH_SM_T *)me)->state))->p_ram_xy++;
...
}

(1) Defines NUM_STATE_T as a derived structure from the basic state structure.
(2) Implementing the single inheritance in C is very simply by literally embedding the base type, RKH_SBSC_T in this case, as the first member of the derived structure.
(3) Private members of NUM_STATE_T derived structure. It allows to acccess to RAM locations from this object (NUM_STATE_ST) allocated in ROM.
(4) Defines a simple macro to instantiate the derived state object.
(5) Initializes the private member of derived state.
(6,7)Invokes the NUM_BASIC_STATE() macro to instantiate the derived state object, num. Note that the variable xy is allocated in RAM but it is access to read and write from ROM object.

Definition at line 1707 of file rkh.h.

#define RKH_INIT_COMPOSITE_STATE (   name,
  en,
  ex,
  parent,
  defchild,
  history 
)
Value:
{ \
{ \
MKBASE(RKH_COMPOSITE, name), /* RKH_BASE_T */ \
MKST(en, ex, parent) \
}, /* RKH_ST_T */ \
MKCOMP(name, defchild, history) \
} /* RKH_SCMP_T */ \

Initializes the parameters (attibutes) of a composite state object.

By means of single inheritance in C it could be used to associate data to a basic state. Moreover, implementing the single inheritance in C is very simply by literally embedding the base type, RKH_SCMP_T in this case, as the first member of the derived structure.

Note
See RKH_INIT_BASIC_STATE() and RKH_CREATE_COMP_STATE() macros to more information.

Definition at line 1730 of file rkh.h.

#define RKH_GFALSE   RKH_FALSE

This values are retrived by guard functions.

A guard is a boolean condition that returns a true or false value that controls whether or not a transition is taken following the receipt of a triggering event.False condition

Definition at line 1748 of file rkh.h.

#define RKH_GTRUE   RKH_TRUE

True condition

Definition at line 1749 of file rkh.h.

#define RKH_SM_CREATE (   type,
  name,
  prio,
  ppty,
  initialState,
  initialAction,
  initialEvt 
)
Value:
RKH_SM_CONST_CREATE(name, prio, ppty, initialState, initialAction, \
initialEvt); \
static type s_##name = {MKSM(&RKH_SM_CONST_NAME(name), initialState)}
#define RKH_SM_CONST_CREATE(name, prio, ppty, initialState, initialAction, initialEvt)
Allocates and then initializes the constant part (in ROM) of the state machine.
Definition: rkh.h:2094

Use it to allocate a state machine regardless of an active object.

Parameters
[in]typeData type of the SMA. Could be derived from RKH_SMA_T.
[in]nameName of state machine application. Also, it represents the top state of state diagram.
[in]prioState machine application priority. A unique priority number must be assigned to each SMA from 0 to RKH_LOWEST_PRIO. The lower the number, the higher the priority.
[in]pptyState machine properties. The available properties are enumerated in RKH_HPPTY_T enumeration in the rkh.h file.
[in]initialStatePointer to initial state. This state could be defined either composite or basic (not pseudo-state).
[in]initialActionPointer to initialization action (optional). The function prototype is defined as RKH_INIT_ACT_T. This argument is optional, thus it could be declared as NULL.
[in]initialEvtPointer to an event that will be passed to state machine application when it starts. Could be used to pass arguments to the state machine like an argc/argv. This argument is optional, thus it could be declared as NULL or eliminated in compile-time with RKH_CFG_SMA_INIT_EVT_EN = 0.
See also
RKH_SM_CONST_CREATE, RKH_SM_GET_CONST, RKH_SM_GET_CONST

Definition at line 1921 of file rkh.h.

#define RKH_SM_INIT (   me_,
  nameSMConst_,
  prio_,
  ppty_,
  initialState_,
  initialAction_,
  initialEvt_ 
)
Value:
((RKH_SM_T *)me_)->romrkh = \
(RKHROM RKH_ROM_T *)(RKH_SM_GET_CONST_OBJ(nameSMConst_)); \
((RKH_SM_T *)me_)->state = \
(RKHROM struct RKH_ST_T *) \
((RKH_SM_GET_CONST_OBJ(nameSMConst_))->istate)
#define RKH_SM_GET_CONST_OBJ(sm)
Return the address of the constant part of a state machine.
Definition: rkh.h:2130
Constant parameters of state machine.
Definition: rkhitl.h:2730
Describes the state machine.
Definition: rkhitl.h:2806
Describes the common properties of regular states (basic, composite, and submachine).
Definition: rkhitl.h:3333

Initialize (at runtime) a previously created state machine object.

Parameters
[in]me_Name of state machine. Also, it represents the top state of state diagram.
[in]nameSMConst_Describe it
[in]prio_State machine application priority. A unique priority number must be assigned to each SMA from 0 to RKH_LOWEST_PRIO. The lower the number, the higher the priority.
[in]ppty_State machine properties. The available properties are enumerated in RKH_HPPTY_T enumeration in the rkh.h file.
[in]initialState_Pointer to initial state. This state could be defined either composite or basic (not pseudo-state).
[in]initialAction_Pointer to initialization action (optional). The function prototype is defined as RKH_INIT_ACT_T. This argument is optional, thus it could be declared as NULL.
[in]initialEvt_Pointer to an event that will be passed to state machine application when it starts. Could be used to pass arguments to the state machine like an argc/argv. This argument is optional, thus it could be declared as NULL or eliminated in compile-time with RKH_CFG_SMA_INIT_EVT_EN = 0.

Definition at line 1965 of file rkh.h.

#define RKH_SMA_CREATE (   type,
  name,
  prio,
  ppty,
  initialState,
  initialAction,
  initialEvt 
)
Value:
RKH_SM_CONST_CREATE(name, prio, ppty, initialState, initialAction, \
initialEvt); \
static type RKH_SMA_NAME(name) = MKSMA(&RKH_SM_CONST_NAME(name), \
initialState)
#define RKH_SM_CONST_CREATE(name, prio, ppty, initialState, initialAction, initialEvt)
Allocates and then initializes the constant part (in ROM) of the state machine.
Definition: rkh.h:2094

Declare and allocate a SMA (active object) derived from RKH_SMA_T. Also, initializes and assigns a state machine to previously declared SMA.

In the UML specification, every state machine has a top state (the abstract root of every state machine hierarchy), which contains all the other elements of the entire state machine. RKH provides the top state using the macro RKH_SMA_CREATE(). Frequently, RKH_SMA_CREATE() is used within state-machine's module (.c file), thus the structure definition is in fact entirely encapsulated in its module and is inaccessible to the rest of the application. However, use RKH_SMA_DEF_PTR() or RKH_SMA_DEF_PTR_TYPE() macros to define a opaque pointer or typed pointer to that state machine application structure, respectively. Also, use the RKH_SMA_DCLR() macro to declare it to be for the rest of application code. RKH_SMA_T is not intended to be instantiated directly, but rather serves as the base structure for derivation of state machines in the application code. The following example illustrates how to derive an state machine from RKH_SMA_T. Please note that the RKH_SMA_T member sm is defined as the FIRST member of the derived structure.

Parameters
[in]typeData type of the SMA. Could be derived from RKH_SMA_T.
[in]nameName of state machine application. Also, it represents the top state of state diagram.
[in]prioState machine application priority. A unique priority number must be assigned to each SMA from 0 to RKH_LOWEST_PRIO. The lower the number, the higher the priority.
[in]pptyState machine properties. The available properties are enumerated in RKH_HPPTY_T enumeration in the rkh.h file.
[in]initialStatePointer to initial state. This state could be defined either composite or basic (not pseudo-state).
[in]initialActionPointer to initialization action (optional). The function prototype is defined as RKH_INIT_ACT_T. This argument is optional, thus it could be declared as NULL.
[in]initialEvtPointer to an event that will be passed to state machine application when it starts. Could be used to pass arguments to the state machine like an argc/argv. This argument is optional, thus it could be declared as NULL or eliminated in compile-time with RKH_CFG_SMA_INIT_EVT_EN = 0.
See also
RKH_SM_CONST_CREATE(), RKH_SM_GET_CONST(), RKH_SM_GET_CONST(), RKH_SMA_DEF_PTR(), RKH_SMA_DEF_PTR_TYPE()
Usage
...within state-machine application's module
typedef struct
{
RKH_SMA_T ao; // base structure
rui8_t x; // private member
rui8_t y; // private member
} MYSM_T;
// static instance of SMA object
RKH_SMA_CREATE(MYSM_T, my, 0, HCAL, &S1, my_iaction, &my_ievent);

Definition at line 2046 of file rkh.h.

#define RKH_SM_CONST_CREATE (   name,
  prio,
  ppty,
  initialState,
  initialAction,
  initialEvt 
)
Value:
static RKHROM RKH_ROM_T RKH_SM_CONST_NAME(name) = \
MKRRKH(name, \
prio, \
ppty, \
initialState, \
initialAction, \
initialEvt)
Constant parameters of state machine.
Definition: rkhitl.h:2730

Allocates and then initializes the constant part (in ROM) of the state machine.

Parameters
[in]nameName of state machine application. Also, it represents the top state of state diagram.
[in]prioState machine application priority. A unique priority number must be assigned to each SMA from 0 to RKH_LOWEST_PRIO. The lower the number, the higher the priority.
[in]pptyState machine properties. The available properties are enumerated in RKH_HPPTY_T enumeration in the rkh.h file.
[in]initialStatePointer to initial state. This state could be defined either composite or basic (not pseudo-state).
[in]initialActionPointer to initialization action (optional). The function prototype is defined as RKH_INIT_ACT_T. This argument is optional, thus it could be declared as NULL.
[in]initialEvtPointer to an event that will be passed to state machine application when it starts. Could be used to pass arguments to the state machine like an argc/argv. This argument is optional, thus it could be declared as NULL or eliminated in compile-time with RKH_CFG_SMA_INIT_EVT_EN = 0.

Definition at line 2094 of file rkh.h.

#define RKH_SM_GET_CONST (   sm)    ((RKH_SM_T *)sm)->romrkh

Return the address of the constant part from a previously created and initializated state machine.

Parameters
[in]smName of state machine.

Definition at line 2116 of file rkh.h.

#define RKH_SM_GET_CONST_OBJ (   sm)    &RKH_SM_CONST_NAME(sm)

Return the address of the constant part of a state machine.

Parameters
[in]smName of state machine.

Definition at line 2130 of file rkh.h.

#define RKH_SM_DEF_PTR (   sm)    RKH_SM_T *const sm = (RKH_SM_T *)&RKH_SM_NAME(sm)

Declare an opaque pointer pointing to a previously created state machine.

Parameters
[in]smName of state machine.
See also
RKH_SMA_DCLR()

Definition at line 2169 of file rkh.h.

#define RKH_SM_DEF_PTR_TYPE (   type,
  sm 
)    type *const sm = (type *)&RKH_SM_NAME(sm)

Declare a pointer of specified type pointing to a previously created state machine.

The pointer could be used to hide (opaque) or to publish the internals of the class of the state machine.

Parameters
[in]typeData type of the state machine. Could be derived from RKH_SM_T.
[in]smName of state machine.
See also
RKH_SMA_DCLR()

Definition at line 2186 of file rkh.h.

#define RKH_SMA_DEF_PTR (   me_)    RKH_SMA_T *const me_ = (RKH_SMA_T *)&RKH_SMA_NAME(me_)

Declare a opaque pointer pointing to an previously created active object.

Parameters
[in]me_Name of state machine application.
See also
RKH_SMA_DCLR()

Definition at line 2198 of file rkh.h.

#define RKH_SMA_DEF_PTR_TYPE (   type,
  me_ 
)    type *const me_ = (type *)&RKH_SMA_NAME(me_)

Declare a pointer of specified type pointing to an previously created active object.

The pointer could be used to hide (opaque) or to publish the internals of the class of the active object.

Parameters
[in]typeData type of the state machine application. Could be derived from RKH_SMA_T.
[in]me_Name of state machine application.
See also
RKH_SMA_DCLR()

Definition at line 2215 of file rkh.h.

#define RKH_GET_CSTATE_ID (   me)    ((RKH_BASE_T *)(((RKH_SM_T *)me)->state))->id

This macro retrieves the state ID of SMA.

Parameters
[in]mepointer to previously created state machine application.
Returns
Id of current state.

Definition at line 2557 of file rkh.h.

#define RKH_GET_AO_NAME (   ao)    RKH_SMA_ACCESS_CONST(ao, name)

This macro retrieves the name of an registered active object.

Parameters
[in]aopointer to previously created active object.
Returns
Name of active object.

Definition at line 2570 of file rkh.h.

#define RKH_GET_VERTEX_NAME (   vx)    ((struct RKH_BASE_T *)(vx))->name

This macro retrieves the name of a vertex.

Parameters
[in]vxpointer to previously created vertex object.
Returns
Name of vertex object.

Definition at line 2581 of file rkh.h.

#define RKH_GET_SMA (   _prio)    rkh_sptbl[(rui8_t)(_prio)]

Retrieves the address of an registered active object (SMA) according to its priority.

Parameters
[in]_prioregistered active object (SMA) priority.
Returns
pointer to previously registered active object (SMA).

Definition at line 2596 of file rkh.h.

#define RKH_GET_PRIO (   _ao)    (rui8_t)(RKH_SMA_ACCESS_CONST(_ao, prio))

Retrieves the priority number of an registered active object (SMA).

Parameters
[in]_aopointer to previously registered active object (SMA).

Definition at line 2605 of file rkh.h.

#define RKH_CAST (   _type,
  _obj 
)    ((_type *)(_obj))

Perform downcast of a reference of a base class to one of its derived classes.

See also
single inheritance in C , and another example .
Usage
void
svr_start( const struct RKH_SMA_T *me, RKH_EVT_T *pe )
{
START_EVT_T *e_start;
e_start = RKH_ALLOC_EVT( START_EVT_T, START );
e_start->clino = RKH_CAST(REQ_EVT_T, pe)->clino;
RKH_SMA_POST_FIFO( RKH_GET_SMA( RKH_CAST(REQ_EVT_T, pe)->clino ),
RKH_EVT_CAST(e_start), me );
}

Definition at line 2639 of file rkh.h.

Function Documentation

void rkh_tmr_tick ( const void *const  sender)

Keep tracks and updates the started timers.

Time intervals are measured by periodic timer interrupts. Each timer interrupt is called a timer-tick. The actual time between timer-ticks is specified by the application. This function must be placed where will be incrementing the system tick. Normally this function is placed in a timer ISR routine. If one or more timers expires the assigned event is directly posted into the state machine application (SMA) queue and associated hook function is executed (if it's used). The expiration events of timers that expire at the same time are executed in the order they were started.

Note
This function is internal to RKH and the user application should not call it. Instead, use RKH_TIM_TICK() macro.
void rkh_sma_get_info ( RKH_SMA_T me,
RKH_SMAI_T psi 
)

Retrieves performance information for a particular state machine application (SMA) as known as active object.

The user application must allocate an RKH_SMAI_T data structure used to receive data. The performance information is available during run-time for each of the RKH services. This can be useful in determining whether the application is performing properly, as well as helping to optimize the application. This information provides a "snapshot" a particular instant in time, i.e., when the service is invoked.

Parameters
[in]mepointer to previously created state machine application.
[in]psipointer to the buffer into which the performance information will be copied by reference.
Note
See RKH_SMAI_T structure for more information. This function is optional, thus it could be eliminated in compile-time with RKH_CFG_SMA_GET_INFO_EN = 0.
void rkh_sma_clear_info ( RKH_SMA_T me)

Clear performance information for a particular state machine application (SMA) as known as active object.

Parameters
[in]mepointer to previously created state machine application.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_SMA_GET_INFO_EN = 0.
void rkh_sma_register ( RKH_SMA_T me)

Registers a state machine application (SMA) as known as active object into the framework, which implies to store a pointer to the SMA in the priority table.

Parameters
[in]mepointer to previously created state machine application.
void rkh_sma_unregister ( RKH_SMA_T me)

Removes the SMA as known as active object from the priority table, and thus from the framework, by simply replacing the link to the SMA being deleted with a NULL pointer.

Parameters
[in]mepointer to previously created state machine application.
void rkh_sma_ctor ( RKH_SMA_T me,
const RKHSmaVtbl vtbl 
)

Initializes the virtual table of the active object instance and calls the constructor operation of its base class.

Parameters
[in]mepointer to previously created state machine application.
[in]vtblpointer to virtual table. Define it as null to use the default virtual table, rkhSmaVtbl.
Note
The initializer assumes that memory has previously been allocated for the object (either statically or dynamically).
void rkh_fwk_defer ( RKH_RQ_T q,
const RKH_EVT_T e 
)

Defer an event to a given separate event queue.

Event deferral comes in very handy when an event arrives in a particularly inconvenient moment but can be deferred for some later time, when the system is in a much better position to handle the event. RKH supports very efficient event deferring and recalling mechanisms. This function is part of the event deferral mechanism. An SMA uses this function to defer an event e to the event queue q. RKH correctly accounts for another outstanding reference to the event and will not recycle the event at the end of the RTC step. Later, the SMA might recall one event at a time from the event queue by means of rkh_fwk_recall() function.

Parameters
[in]qpointer to previously created queue.
[in]epointer to event.
Note
For memory efficiency and best performance the deferred event queue, STORE ONLY POINTERS to events, not the whole event objects. An SMA can use multiple event queues to defer events of different kinds. The assertion inside it guarantee that operation is valid, so is not necessary to check the value returned from it.
Usage
static RKH_RQ_T qurc;
static RKH_EVT_T *qurc_sto[ MAX_SIZEOF_QURC ];
rkh_rq_init( &qurc, qurc_sto, MAX_SIZEOF_QURC, NULL );
...
void
ring( const struct rkh_t *me, RKH_EVT_T *pe )
{
(void)me; // argument not used
rkh_fwk_defer( &qurc, pe ); // defer event
}
RKH_EVT_T* rkh_fwk_recall ( RKH_SMA_T me,
RKH_RQ_T q 
)

Recall a deferred event from a given event queue.

This function is part of the event deferral support. An SMA uses this function to recall a deferred event from a given event queue. Recalling an event means that it is removed from the deferred event queue q and posted (LIFO) to the event queue of the me state machine application.

Note
For memory efficiency and best performance the destination event queue, STORE ONLY POINTERS to events, not the whole event objects.
Returns
The pointer to the recalled event to the caller, or NULL if no event has been recalled.
Usage
void
exit_rx_manager( const struct rkh_t *me )
{
rkh_fwk_recall( me, &qurc );
}
void rkh_fwk_epool_register ( void *  sstart,
rui32_t  ssize,
RKH_ES_T  esize 
)

Registers a new event pool into the event pool list.

Before using dynamic events (or event with arguments) the application code must register the event pools, which stores the events as a fixed-sized memory block. Each event pool must be registered with the RKH framework, by means of the rkh_fwk_epool_register() function.

This function initializes one event pool at a time and must be called exactly once for each event pool before the pool can be used.

The application code might initialize the event pools by making calls to the rkh_fwk_epool_register() function. However, for the simplicity of the internal implementation, the application code initialize event pools in the ascending order of the event size.

Many RTOSes provide fixed block-size heaps, a.k.a. memory pools that can be adapted for RKH event pools. In case such support is missing, RKH provides a native RKH event pool implementation. The macro RKH_DYNE_TYPE determines the type of event pool used by a particular RKH port. See structure RKH_MP_T for more information.

For adapting RKH event pools to any fixed-size memory block service RTOS provided the application code must define RKH_DYNE_TYPE, RKH_DYNE_INIT(), RKH_DYNE_GET_ESIZE(), RKH_DYNE_GET(), and RKH_DYNE_PUT() macros.

The dynamic allocation of events is optional then if the RKH_CFGPORT_NATIVE_DYN_EVT_EN is set to 1 and the native fixed-size memory block facility is enabled (see RKH_CFG_MP_EN) then RKH will include its own implementation of dynamic memory management. When RKH_CFGPORT_NATIVE_DYN_EVT_EN is enabled RKH also will automatically define RKH_DYNE_TYPE, RKH_DYNE_INIT(), RKH_DYNE_GET_ESIZE(), RKH_DYNE_GET(), and RKH_DYNE_PUT().

Parameters
[in]sstartstorage start. Pointer to memory from which memory blocks are allocated.
[in]ssizestorage size. Size of the memory pool storage in bytes.
[in]esizeevent size. This number determines the size of each memory block in the pool.
Usage
#define SIZEOF_EP0STO 64
#define SIZEOF_EP0_BLOCK sizeof( TOUT_T )
#define SIZEOF_EP1STO 32
#define SIZEOF_EP1_BLOCK sizeof( DIAL_T )
#define SIZEOF_EP2STO 32
#define SIZEOF_EP2_BLOCK sizeof( SETUP_T )
typedef struct
{
RKH_EVT_T evt; // base structure
int timerno; // parameter 'timerno'
} TOUT_T;
typedef struct
{
RKH_EVT_T evt; // base structure
char dial[ MAX_SIZE_DIAL ]; // parameter 'dial'
int qty; // parameter 'qty'
} DIAL_T;
typedef struct
{
RKH_EVT_T evt; // base structure
int volume; // parameter 'volume'
int baud_rate; // parameter 'baud_rate'
char name[ MAX_SIZE_NAME ]; // parameter 'name'
int iloop; // parameter 'iloop'
} SETUP_T;
// declares the storage memory of event pool
static rui8_t ep0sto[ SIZEOF_EP0STO ],
ep1sto[ SIZEOF_EP1STO ],
ep2sto[ SIZEOF_EP2STO ];
...
rkh_fwk_epool_register( ep0sto, SIZEOF_EP0STO, SIZEOF_EP0_BLOCK );
rkh_fwk_epool_register( ep1sto, SIZEOF_EP1STO, SIZEOF_EP1_BLOCK );
rkh_fwk_epool_register( ep2sto, SIZEOF_EP2STO, SIZEOF_EP2_BLOCK );
...
RKH_EVT_T* rkh_fwk_ae ( RKH_ES_T  esize,
RKH_SIG_T  e 
)

Allocates an event from the previously created event pool.

Parameters
[in]esizesize of event [in bytes].
[in]eevent signal.
Note
This function is internal to RKH and the user application should not call it. Instead, use RKH_ALLOC_EVT() macro.
See also
rkh_put_fifo(), rkh_put_lifo(), rkh_alloc_event(), rkh_set_static_event() and rkh_fwk_gc().
void rkh_fwk_gc ( RKH_EVT_T e)

Recycle a dynamic event.

Parameters
[in]eevent signal.
void rkh_fwk_reserve ( RKH_EVT_T e)

Reserve the dynamic event to be recycled.

Parameters
[in]eevent signal.

Variable Documentation

Priority arranged table of registered SMA.

Register a state machine application into the framework implies to store a pointer to the SMA in the priority table. A unique priority number must be assigned to each SMA from 0 to RKH_LOWEST_PRIO. The lower the number, the higher the priority.