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]	name	exit point connection point reference name.
[in]	expnt	referenced exit point.
[in]	act	pointer to transition action function. This argument is optional, thus it could be declared as NULL.
[in]	ts	pointer to target state.

See also

RKH_EXPCN_T structure definition for more information.

Usage

// --- exit point pseudostates of SB submachine ---
RKH_CREATE_REF_EXPNT(   EXPNT1,
                        0,      // index of exit point connection table
                        &SB );
RKH_CREATE_REF_EXPNT(   EXPNT2,
                        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)
RKH_END_EX_CNNPNT_TABLE

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_CREATE_EX_CNNPNT_TABLE( S2 )
    RKH_EX_CNNPNT( EX1S2, &EXPNT1, NULL, &S1 ),
    RKH_EX_CNNPNT( EX2S2, &EXPNT2, NULL, &S3 ),
RKH_END_EX_CNNPNT_TABLE

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) \
    }

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]	name	entry point connection point reference name.
[in]	enpnt	referenced entry point.
[in]	subm	pointer 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,
			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.

Parameters

[in]	e	triggering event.
[in]	g	pointer to guard function.
[in]	a	pointer 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_COMPLETION_EVENT, \
     (RKH_GUARD_T)guard_, (RKH_TRN_ACT_T)effect_, target_}

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_CREATE_BRANCH_TABLE( C2 )
    RKH_BRANCH( is_power_ok,    enable_process, &power      ),
    RKH_BRANCH( is_switch_off,  turnoff,        &wait       ),
    RKH_BRANCH( ELSE,           abort,          &aborted    ),
RKH_END_BRANCH_TABLE

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]

compStateName

pointer 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_CREATE_BRANCH_TABLE( C2 )
    RKH_BRANCH( is_power_ok,    enable_process, &power      ),
    RKH_BRANCH( is_switch_off,  turnoff,        &wait       ),
    RKH_BRANCH( ELSE,           abort,          &aborted    ),
RKH_END_BRANCH_TABLE

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]

name

name 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_t	data type of SMA.
[in]	sm	name of previously created SMA.
[in]	gob	name 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_CREATE_TRANS_TABLE( menu_cfg )
        RKH_TRREG( TIMEOUT, NULL, mc_title, &menu_cfg_resume ),
        ...
    RKH_END_TRANS_TABLE

...


(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 ) \
                RKH_DECLARE_TR_TBL( name ); \
                \
                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)}

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

Parameters

[in]	type	Data type of the SMA. Could be derived from RKH_SMA_T.
[in]	name	Name of state machine application. Also, it represents the top state of state diagram.
[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.

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)

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)

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

Parameters

[in]	name	Name of state machine application. Also, it represents the top state of state diagram.
[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 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]

sm

Name 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]

sm

Name 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]

sm

Name 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]	type	Data type of the state machine. Could be derived from RKH_SM_T.
[in]	sm	Name 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]

me

pointer 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]

vx

pointer 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.