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

Specifies the interface of the state-machine manager. More...

#include "rkhitl.h"
Include dependency graph for rkhsm.h:

Go to the source code of this file.

Data Structures

struct  RKH_ROM_T
 Constant parameters of state machine. More...
 
struct  RKH_SM_T
 Describes the state machine. More...
 
struct  RKH_BASE_T
 Maintains the basic information of a state. More...
 
struct  RKH_TR_T
 Describes the state transition. More...
 
struct  RKH_ST_T
 Describes the common properties of regular states (basic, composite, and submachine). More...
 
struct  RKH_SBSC_T
 Describes a basic state. More...
 
struct  RKH_SCMP_T
 Describes a composite state. More...
 
struct  RKH_FINAL_T
 Describes a final state. More...
 
struct  RKH_EXPCN_T
 Describes the exit point connection. More...
 
struct  RKH_ENPCN_T
 Describes the entry point connection. More...
 
struct  RKH_SSBM_T
 Describes a submachine state. More...
 
struct  RKH_RSM_T
 Describes a (referenced) submachine state machine. More...
 
struct  RKH_SENP_T
 Describes the entry point pseudostate. More...
 
struct  RKH_SEXP_T
 Describes the exit point pseudostate. More...
 
struct  RKH_SCOND_T
 Describes the conditional pseudostate. More...
 
struct  RKH_SCHOICE_T
 Describes the choice pseudostate. More...
 
struct  RKH_SHIST_T
 Describes the history pseudostate. More...
 

Macros

#define ELSE   rkh_sm_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_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_DECLARE_TR_TBL(name)   extern RKHROM RKH_TR_T name##_trtbl[]
 Declares a state transition table. 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_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_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_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_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_VERTEX_NAME(vx)   ((struct RKH_BASE_T *)(vx))->name
 This macro retrieves the name of a vertex. 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...
 

Typedefs

typedef void(* RKH_INIT_ACT_T )(const RKH_SM_T *me, const struct RKH_EVT_T *e)
 Initialization action. More...
 
typedef void(* RKH_ENT_ACT_T )(const RKH_SM_T *me)
 Entry action. More...
 
typedef void(* RKH_EXT_ACT_T )(const RKH_SM_T *me)
 Exit action. More...
 
typedef RKH_SIG_T(* RKH_PPRO_T )(const RKH_SM_T *sma, RKH_EVT_T *pe)
 Event preprocessor. More...
 
typedef void(* RKH_TRN_ACT_T )(const RKH_SM_T *me, RKH_EVT_T *pe)
 Transition action. More...
 
typedef rbool_t(* RKH_GUARD_T )(const RKH_SM_T *me, RKH_EVT_T *pe)
 Guard. 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_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...
 

Detailed Description

Specifies the interface of the state-machine manager.

Definition in file rkhsm.h.

Macro Definition Documentation

#define ELSE   rkh_sm_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 79 of file rkhsm.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 567 of file rkhsm.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 591 of file rkhsm.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: rkhsm.h:2420

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 615 of file rkhsm.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 803 of file rkhsm.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 827 of file rkhsm.h.

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

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 862 of file rkhsm.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 886 of file rkhsm.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_sm_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 948 of file rkhsm.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 978 of file rkhsm.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 1005 of file rkhsm.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 1040 of file rkhsm.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 1065 of file rkhsm.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 1077 of file rkhsm.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 1078 of file rkhsm.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 1079 of file rkhsm.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 1080 of file rkhsm.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 1081 of file rkhsm.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 1082 of file rkhsm.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 1083 of file rkhsm.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 1084 of file rkhsm.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 1085 of file rkhsm.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 1086 of file rkhsm.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 1087 of file rkhsm.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 1088 of file rkhsm.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 1097 of file rkhsm.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 1122 of file rkhsm.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 1249 of file rkhsm.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 1272 of file rkhsm.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 1290 of file rkhsm.h.

#define RKH_GTRUE   RKH_TRUE

True condition

Definition at line 1291 of file rkhsm.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: rkhsm.h:1415

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 1326 of file rkhsm.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)
Constant parameters of state machine.
Definition: rkhsm.h:1636
Describes the state machine.
Definition: rkhsm.h:1712
#define RKH_SM_GET_CONST_OBJ(sm)
Return the address of the constant part of a state machine.
Definition: rkhsm.h:1451
Describes the common properties of regular states (basic, composite, and submachine).
Definition: rkhsm.h:2062

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 1370 of file rkhsm.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: rkhsm.h:1636

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 1415 of file rkhsm.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 1437 of file rkhsm.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 1451 of file rkhsm.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 1474 of file rkhsm.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 1491 of file rkhsm.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 1503 of file rkhsm.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 1516 of file rkhsm.h.

Typedef Documentation

typedef void(* RKH_INIT_ACT_T)(const RKH_SM_T *me, const struct RKH_EVT_T *e)

Initialization action.

Frequently, the state transition originating at the black ball is called the initial transition. Such transition designates the first active state after the state machine object is created. An initial transition can have associated actions, which in the UML notation are enlisted after the forward slash (/). In RKH framework, the application code must trigger the initial transition explicitly by invoking rkh_sma_activate() function.

Definition at line 1612 of file rkhsm.h.

typedef void(* RKH_ENT_ACT_T)(const RKH_SM_T *me)

Entry action.

The actions that are always executed when a state is entered should be specified as entry actions. UML statecharts provide optional entry and exit actions, which are associated with states rather than transitions, as in a Moore automaton. An entry function takes the state machine pointer as argument. This argument is optional, thus it could be eliminated in compile-time by means of RKH_CFG_SMA_ENT_ARG_SMA_EN.

The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML. Specifically, the implemented transition sequence is as follows:

  • Execute exit actions of the source state.
  • Execute the transition actions.
  • Execute entry actions of the target state.
Note
This callback is referenced from RKH_CREATE_COMP_STATE() and RKH_CREATE_BASIC_STATE() macros. RKH_CFG_SMA_ENT_ARG_SMA_EN macro.

Definition at line 1828 of file rkhsm.h.

typedef void(* RKH_EXT_ACT_T)(const RKH_SM_T *me)

Exit action.

The actions that are always execute when a state is exited should be exit actions. UML statecharts provide optional entry and exit actions, which are associated with states rather than transitions, as in a Moore automaton. An exit function takes the state machine pointer as argument. This argument is optional, thus it could be eliminated in compile-time by means of RKH_CFG_SMA_EXT_ARG_SMA_EN.

The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML. Specifically, the implemented transition sequence is as follows:

  • Execute exit actions of the source state.
  • Execute the transition actions.
  • Execute entry actions of the target state.
Note
This callback is referenced from RKH_CREATE_COMP_STATE() and RKH_CREATE_BASIC_STATE() macros.

Definition at line 1868 of file rkhsm.h.

typedef RKH_SIG_T(* RKH_PPRO_T)(const RKH_SM_T *sma, RKH_EVT_T *pe)

Event preprocessor.

Before sending the arrived event to state machine, it can be previously processed using the event preprocessor function. The RKH framework provides optional event preprocessor action, which are associated with states rather than transitions, as in a Moore automaton. This action takes the state machine pointer and the event pointer as arguments. This argument is optional, thus it could be eliminated in compile-time by means of RKH_CFG_SMA_PPRO_ARG_SMA_EN.

Note
This callback is referenced from RKH_CREATE_COMP_STATE() and RKH_CREATE_BASIC_STATE() macros.

Definition at line 1897 of file rkhsm.h.

typedef void(* RKH_TRN_ACT_T)(const RKH_SM_T *me, RKH_EVT_T *pe)

Transition action.

Transition actions are small atomic behaviors executed at specified points in a state machine. This actions are assumed to take an insignificant amount of time to execute and are noninterruptible. UML statecharts are extended state machines with characteristics of both Mealy and Moore automata. In statecharts, actions generally depend on both the state of the system and the triggering event, as in a Mealy automaton. Additionally, UML statecharts provide optional entry and exit actions, which are associated with states rather than transitions, as in a Moore automaton. An action 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_CFG_SMA_ACT_ARG_EVT_EN and RKH_CFG_SMA_ACT_ARG_SMA_EN.

The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML. Specifically, the implemented transition sequence is as follows:

  • Execute exit actions of the source state.
  • Execute the transition actions.
  • Execute entry actions of the target state.
Note
This callback is referenced from RKH_TRREG() and RKH_TRINT()macro.

Definition at line 1936 of file rkhsm.h.

typedef rbool_t(* RKH_GUARD_T)(const RKH_SM_T *me, RKH_EVT_T *pe)

Guard.

A guard is a boolean condition that returns a true (RKH_GTRUE) or false (RKH_GFALSE) value that controls whether or not a transition is taken following the receipt of a triggering event. A transition with a guard is only take if the triggering event occurs and the guard evaluates to true. As long as the guard evaluated to false, the triggering event would be discarded and the transition would not be taken. Each condition connector can have one special branch with a guard labeled rkh_sm_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_CFG_SMA_GRD_ARG_EVT_EN and RKH_CFG_SMA_GRD_ARG_SMA_EN.

Note
This callback is referenced from RKH_BRANCH() macro.

Definition at line 1975 of file rkhsm.h.