RKH
State machines

Files

file  rkh.h
 RKH framwwork platform - independent interface.
 
file  rkhsm.h
 Specifies the interface of the state-machine manager.
 

Data Structures

struct  RKH_SM_T
 Describes the state machine. More...
 

Macros

#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_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_CREATE_BRANCH_TABLE(name)
 
#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...
 

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

Macro Definition Documentation

#define RKH_CREATE_COMP_REGION_STATE (   name,
  en,
  ex,
  parent,
  defchild,
  initialTrn,
  kindOfHistory,
  hDftTrnGuard,
  hDftTrnAction,
  hDftTarget,
  hRamMem 
)
Value:
\
MKFINAL_INCOMP(name); \
MKHIST_INCOMP(name, kindOfHistory, hDftTrnGuard, hDftTrnAction, \
hDftTarget, hRamMem); \
\
extern RKHROM RKH_TR_T name##_trtbl[]; \
RKHROM RKH_SCMP_T name = \
{ \
{MKBASE(RKH_COMPOSITE, name), MKST(en, ex, parent)}, \
MKCOMP(name, defchild, initialTrn, &name##Hist) \
}
Describes a composite state.
Definition: rkhsm.h:2152
Describes the state transition.
Definition: rkhsm.h:2030

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.

The names of history pseudostate and final state are internally conformed as "<nameOfCompositeState>Hist" and "<nameOfCompositeState>Final" respectively. Thus, use these names as target vertex in a transition.

Shallow history means that history applies to the current nesting context only – states nested more deeply are not affected by the presence of a history pseudostates in a higher context. Deep history applies downwards to all levels of nesting.

Parameters
[in]namestate name. Represents a composite state structure.
[in]enpointer to state entry action. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML.
[in]expointer to state exit action. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML.
[in]parentpointer to parent state.
[in]defchildpointer to default child state or pseudostate.
[in]initialTrnpointer to initial transition action of the composite state's region. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by UML.
[in]kindOfHistoryKind of history pseudostate. It could be defined either shallow history (RKH_SHISTORY), deep history (RKH_DHISTORY) or without history (RKH_NO_HISTORY). When it is defined as RKH_NO_HISTORY each of parameters related to history default transition are ignored.
[in]hDftTrnGuardpointer to guard function. This argument is optional, thus it could be declared as NULL.
[in]hDftTrnActionpointer to action function. This argument is optional, thus it could be declared as NULL.
[in]hDftTargetpointer to target state. If a default history Transition is defined (the target parameter is not NULL) originating from the History Pseudostate, it will be taken. Otherwise, default State entry is applied.
[in]hRamMempointer to a RAM location which maintains the last visited state of this region. If composite state don't include the history pseudostate then this parameter should be passed as NULL. Please, use RKH_CREATE_HISTORY_STORAGE() macro to create the history RAM location.
See also
RKH_SCMP_T structure definition for more information.

Definition at line 144 of file rkhsm.h.

#define RKH_CREATE_COMP_STATE (   name,
  en,
  ex,
  parent,
  defchild,
  history 
)
Value:
\
extern RKHROM RKH_TR_T name##_trtbl[]; \
RKHROM RKH_SCMP_T name = \
{ \
{MKBASE(RKH_COMPOSITE, name), MKST(en, ex, parent)}, \
MKCOMP(name, defchild, NULL, history) \
}
Describes a composite state.
Definition: rkhsm.h:2152
Describes the state transition.
Definition: rkhsm.h:2030

This macro creates a composite state.

Parameters
[in]namestate name. Represents a composite state structure.
[in]enpointer to state entry action. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML.
[in]expointer to state exit action. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML.
[in]parentpointer to parent state.
[in]defchildpointer to default child state or pseudostate.
[in]historypointer history pseudostate. This argument is optional, thus it could be declared as NULL.
See also
RKH_SCMP_T structure definition for more information.

Definition at line 183 of file rkhsm.h.

#define RKH_CREATE_FINAL_STATE (   name,
  parent 
)
Value:
\
static RKHROM RKH_TR_T name##_trtbl[] = \
RKH_TRREG(RKH_ANY, NULL, NULL, NULL); \
RKHROM RKH_FINAL_T name = \
{ \
{MKBASE(RKH_FINAL, name), MKST(NULL, NULL, parent)}, \
MKFINAL(name) \
}
#define RKH_ANY
This macro is used to indicate the end of a transition table.
Definition: rkhitl.h:131
Describes the state transition.
Definition: rkhsm.h:2030
Describes a final state.
Definition: rkhsm.h:2231

This macro creates a final state.

Parameters
[in]namestate name. Represents a composite state structure.
[in]parentpointer to parent state.
See also
RKH_FINAL_T structure definition for more information.

Definition at line 204 of file rkhsm.h.

#define RKH_CREATE_BASIC_STATE (   name,
  en,
  ex,
  parent,
  prepro 
)
Value:
\
extern RKHROM RKH_TR_T name##_trtbl[]; \
\
RKHROM RKH_SBSC_T name = \
{ \
{MKBASE(RKH_BASIC, name), MKST(en,ex,parent)}, \
MKBASIC(name,prepro) \
}
Describes a basic state.
Definition: rkhsm.h:2095
Describes the state transition.
Definition: rkhsm.h:2030

This macro creates a basic state.

Parameters
[in]namestate name. Represents a basic state structure.
[in]enpointer to state entry action. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML.
[in]expointer to state exit action. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML.
[in]parentpointer to parent state.
[in]prepropointer to input preprocessor function. This function could be called "Moore" action. This argument is optional, thus it could be declared as NULL. Aditionally, by means of single inheritance in C it could be used as state's abstract data. Moreover, implementing the single inheritance in C is very simply by literally embedding the base type, RKH_PPRO_T in this case, as the first member of the derived structure. See prepro member of RKH_SBSC_T structure for more information.
Usage
1 static RKH_SIG_T
2 preprocessor( RKH_EVT_T *pe )
3 {
4  ...
5 }
6 
7 typedef struct
8 {
9  RKH_PPRO_T prepro; // extend the RKH_PPRO_T class
10  unsigned min:4;
11  unsigned max:4;
12  char *buff;
13 } SDATA_T;
14 
15 static const SDATA_T option = { preprocessor,4,8,token1 };
16 
17 RKH_CREATE_BASIC_STATE( S111, set_x_1,
18  NULL, &S11, preprocessor );
19 RKH_CREATE_BASIC_STATE( S22, set_x_4,
20  NULL, &S2,
21  (RKH_PPRO_T*)&option );
See also
RKH_SBSC_T structure definition for more information.

Definition at line 269 of file rkhsm.h.

#define RKH_CREATE_COND_STATE (   name)
Value:
\
extern RKHROM RKH_TR_T name##_trtbl[]; \
\
RKHROM RKH_SCOND_T name = \
{ \
MKBASE(RKH_CONDITIONAL, name), \
name##_trtbl \
}
Describes the state transition.
Definition: rkhsm.h:2030
Describes the conditional pseudostate.
Definition: rkhsm.h:2478

This macro creates a conditional pseudostate (a.k.a. junction).

The conditional pseudostates are semantic-free vertices that are used to chain together multiple transitions. They are used to construct compound transition paths between states. For example, a junction can be used to converge multiple incoming transitions into a single outgoing transition representing a shared transition path (this is known as a merge). Conversely, they can be used to split an incoming transition into multiple outgoing transition segments with different guard conditions. This realizes a static conditional branch. (In the latter case, outgoing transitions whose guard conditions evaluate to false are disabled. A predefined guard denoted "ELSE" may be defined for at most one outgoing transition. This transition is enabled if all the guards labeling the other transitions are false.) Static conditional branches are distinct from dynamic conditional branches that are realized by choice vertices.

Parameters
[in]namepseudostate name. Represents a conditional pseudostate structure.
See also
RKH_SCOND_T structure definition for more information.

Definition at line 305 of file rkhsm.h.

#define RKH_CREATE_CHOICE_STATE (   name)
Value:
\
extern RKHROM RKH_TR_T name##_trtbl[]; \
\
RKHROM RKH_SCHOICE_T name = \
{ \
MKBASE(RKH_CHOICE, name), \
name##_trtbl \
}
Describes the choice pseudostate.
Definition: rkhsm.h:2499
Describes the state transition.
Definition: rkhsm.h:2030

This macro creates a choice pseudostate.

Choice pseudostate which, when reached, result in the dynamic evaluation of the guards of its outgoing transitions. This realizes a dynamic conditional branch. It allows splitting of transitions into multiple outgoing paths such that the decision on which path to take may be a function of the results of prior actions performed in the same run-to-completion step. If more than one of the guards evaluates to true, an arbitrary one is selected. If none of the guards evaluates to true, then the model is considered ill-formed. To avoid this, it is recommended to define one outgoing transition with the predefined "ELSE" guard for every choice pseudostate. Also, branches cannot contain triggers, but in addition to a guard they may contain actions. A branch can enter another choice connector, thus providing for the nesting of branches.

Parameters
[in]namepseudostate name. Represents a choice pseudostate structure.
See also
RKH_SCHOICE_T structure definition for more information.

Definition at line 341 of file rkhsm.h.

#define RKH_CREATE_DEEP_HISTORY_STATE (   name,
  parent,
  dftTrnGuard,
  dftTrnAction,
  dftTarget 
)
Value:
\
static RKHROM RKH_ST_T *ram##name; \
MKHISTORY(name, parent, RKH_DHISTORY, dftTrnGuard, dftTrnAction, \
dftTarget, &ram##name)
Describes the common properties of regular states (basic, composite, and submachine).
Definition: rkhsm.h:2062
Deprecated:
This macro creates a deep history pseudostate. Instead use: RKH_CREATE_COMP_REGION_STATE() macro.

Deep history applies downwards to all levels of nesting.

Note
At this framework version, it is not recommended to instantiate the same history object more than once using this macro, since it uses a static memory to store the last visited state (memory of history pseudostate).
See also
RKH_SHIST_T structure definition for more information.
Parameters
[in]namepseudostate name. Represents a deep history pseudostate structure.
[in]parentpointer to parent state.
[in]dftTrnGuardpointer to guard function. This argument is optional, thus it could be declared as NULL.
[in]dftTrnActionpointer to action function. This argument is optional, thus it could be declared as NULL.
[in]dftTargetpointer to target state. If a default history Transition is defined (the target parameter is not NULL) originating from the History Pseudostate, it will be taken. Otherwise, default State entry is applied.

Definition at line 385 of file rkhsm.h.

#define RKH_CREATE_SHALLOW_HISTORY_STATE (   name,
  parent,
  dftTrnGuard,
  dftTrnAction,
  dftTarget 
)
Value:
\
static RKHROM RKH_ST_T *ram##name; \
MKHISTORY(name, parent, RKH_SHISTORY, dftTrnGuard, dftTrnAction, \
dftTarget, &ram##name)
Describes the common properties of regular states (basic, composite, and submachine).
Definition: rkhsm.h:2062
Deprecated:
This macro creates a shallow history pseudostate. Instead use: RKH_CREATE_COMP_REGION_STATE() macro.

Shallow history means that history applies to the current nesting context only – states nested more deeply are not affected by the presence of a history pseudostates in a higher context.

Note
At this framework version, it is not recommended to instantiate the same history object more than once using this macro, since it uses a static memory to store the last visited state (memory of history pseudostate).
See also
RKH_SHIST_T structure definition for more information.
Parameters
[in]namepseudostate name. Represents a shallow history pseudostate structure.
[in]parentpointer to parent state.
[in]dftTrnGuardpointer to guard function. This argument is optional, thus it could be declared as NULL.
[in]dftTrnActionpointer to action function. This argument is optional, thus it could be declared as NULL.
[in]dftTargetpointer to target state. If a default history Transition is defined (the target parameter is not NULL) originating from the History Pseudostate, it will be taken. Otherwise, default State entry is applied.

Definition at line 428 of file rkhsm.h.

#define RKH_CREATE_SUBMACHINE_STATE (   name,
  en,
  ex,
  parent,
  sbm 
)
Value:
\
extern RKHROM RKH_EXPCN_T name##_exptbl[]; \
extern RKHROM RKH_TR_T name##_trtbl[]; \
\
RKHROM RKH_SSBM_T name = \
{ \
{MKBASE(RKH_SUBMACHINE, name), MKST(en,ex,parent)}, \
MKSBM(name,sbm) \
}
Describes the exit point connection.
Definition: rkhsm.h:2259
Describes a submachine state.
Definition: rkhsm.h:2351
Describes the state transition.
Definition: rkhsm.h:2030

This macro creates a submachine state.

A submachine state is a kind of a state that actually refers to another defined state machine. A submachine state is logically equivalent to the insertion of the referenced state machine as a composite state in the place of the submachine state. Consequently, every entrance to a submachine state is equivalent to the corresponding entrance to the inserted (referenced) composite state. In particular, it can be entered thruough its initial pseudostate (as any other composite state), or through one of its entry points.

Similary, every exit from a submachine state is equivalent to the corresponding exit from the inserted composite state. It can be exited through one of its exit points. When it is exited through its exit point the effect of the transition targeting the exit point is executed first, followed by the exit behavior of the composite state.

The purpose od defining submachine states is to decompose and localize repetitive parts because the same state machine can be referenced from more than one submachine state.

Parameters
[in]namesubmachine state name. Represents a submachine state structure.
[in]enpointer to state entry action. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML.
[in]expointer to state exit action. This argument is optional, thus it could be declared as NULL. The RKH implementation preserves the transition sequence imposed by Harel's Statechart and UML.
[in]parentpointer to parent state.
[in]sbmpointer to referenced submachine state machine.
See also
RKH_SSBM_T structure definition for more information.
1 RKH_CREATE_SUBMACHINE_STATE( adquire, // state name
2  start_adquire, // entry action
3  stop_adquire, // exit action
4  &processing, // parent state
5  &herror ); // referenced submachine

Definition at line 485 of file rkhsm.h.

#define RKH_CREATE_EX_CNNPNT_TABLE (   name)
Value:
RKHROM RKH_EXPCN_T name##_exptbl[]= \
{
Describes the exit point connection.
Definition: rkhsm.h:2259

This macro creates a exit point connection point reference table.

Parameters
[in]namesubmachine state name
Note
This macro is not terminated with the semicolon.
Usage
This table have the general structure shown below:
1 RKH_CREATE_EX_CNNPNT_TABLE( S2 )
2  RKH_EX_CNNPNT( EX1S2, &EXPNT1, NULL, &S1 ),
3  RKH_EX_CNNPNT( EX2S2, &EXPNT2, NULL, &S3 ),
4 RKH_END_EX_CNNPNT_TABLE
Each exit point connection reference 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 521 of file rkhsm.h.

#define RKH_CREATE_REF_SUBMACHINE (   name,
  defchild,
  iact 
)
Value:
\
static RKHROM RKH_ST_T * rdyp_##name; \
\
RKHROM RKH_RSM_T name = \
{ \
MKBASE(RKH_REF_SUBMACHINE, name), \
MKMCH(defchild,iact,name) \
}
Describes a (referenced) submachine state machine.
Definition: rkhsm.h:2378
Describes the common properties of regular states (basic, composite, and submachine).
Definition: rkhsm.h:2062

This macro creates a submachine state machine, which is to be inserted in place of the (submachine) state.

Parameters
[in]namesubmachine name. Represents a submachine structure.
[in]defchildpointer to default child state.
[in]iactpointer 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.
See also
RKH_RSM_T structure definition for more information.
1 RKH_CREATE_REF_SUBMACHINE( adquire,
2  &wait,
3  init_adquire );

Definition at line 646 of file rkhsm.h.

#define RKH_CREATE_REF_EXPNT (   name,
  ix,
  subm 
)
Value:
\
RKHROM RKH_SEXP_T name = \
{ \
MKBASE(RKH_EXPOINT, name), \
ix, subm \
}
Describes the exit point pseudostate.
Definition: rkhsm.h:2451

This macro creates an exit point.

An exit pseudostate is used to join an internal transition terminating on that exit point to an external transition emanating from that exit point. The main purpose of such entry and exit points is to execute the state entry and exit actions respectively in between the actions that are associated with the joined transitions.

Parameters
[in]nameentry point name.
[in]ixindex of exit point connection table. Note that each row number matches with the index number of the exit point pseudostate that it represent.
[in]submpointer to submachine state machine.
1 RKH_CREATE_REF_EXPNT(handled,
2  0,
3  &handle_error);
See also
RKH_SEXP_T structure definition for more information.
Usage
1 // --- exit point pseudostates of SB submachine ---
2 RKH_CREATE_REF_EXPNT( EXPNT1,
3  0, // index of exit point connection table
4  &SB );
5 RKH_CREATE_REF_EXPNT( EXPNT2,
6  1, // index of exit point connection table
7  &SB );
8  ...
9 // --- exit point connection references of S12 submachine state ---
10 RKH_CREATE_EX_CNNPNT_TABLE( S12 )
11  RKH_EX_CNNPNT( EX1S12, &EXPNT1, ... ), // table index = 0 (EXPNT1)
12  RKH_EX_CNNPNT( EX2S12, &EXPNT2, ... ), // table index = 1 (EXPNT2)
13 RKH_END_EX_CNNPNT_TABLE

Definition at line 700 of file rkhsm.h.

#define RKH_CREATE_REF_ENPNT (   name,
  act,
  ts,
  subm 
)
Value:
\
RKHROM RKH_ENPCN_T name = \
{ \
(RKH_TRN_ACT_T)act, (RKHROM struct RKH_ST_T *)ts \
}
Describes the entry point connection.
Definition: rkhsm.h:2278
Describes the common properties of regular states (basic, composite, and submachine).
Definition: rkhsm.h:2062
void(* RKH_TRN_ACT_T)(const RKH_SM_T *me, RKH_EVT_T *pe)
Transition action.
Definition: rkhsm.h:1936

This macro creates a entry point.

An entry pseudostate is used to join an external transition terminating on that entry point to an internal transition emanating from that entry point. The main purpose of such entry and exit points is to execute the state entry and exit actions respectively in between the actions that are associated with the joined transitions.

Parameters
[in]nameentry point name.
[in]actpointer to transition action function. This argument is optional, thus it could be declared as NULL.
[in]tspointer to target state.
[in]submpointer to submachine state machine.
See also
RKH_ENPCN_T structure definition for more information.
1 RKH_CREATE_REF_ENPNT( show,
2  2,
3  &S2,
4  &handle_error );

Definition at line 737 of file rkhsm.h.

#define RKH_CREATE_TRANS_TABLE (   name)
Value:
\
RKHROM RKH_TR_T name##_trtbl[]= \
{
Describes the state transition.
Definition: rkhsm.h:2030

This macro creates a state transition table.

Parameters
[in]namestate name.
Note
This macro is not terminated with the semicolon.
Usage
This table have the general structure shown below:
1 RKH_CREATE_TRANS_TABLE( state_name ) // transition table begin
2  RKH_TRxx( ... ) // transition
3  RKH_TRxx( ... ) // transition
4  ...
5 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.

Definition at line 769 of file rkhsm.h.

#define RKH_CREATE_BRANCH_TABLE (   name)
Value:
\
RKH_CREATE_TRANS_TABLE(name)

This macro creates a branch table.

Parameters
[in]nameconditional pseudostate name.
See also
This macro is not terminated with the semicolon. Use rkh_sm_else() when if all the guards on the other branches are false.
Usage
This table have the general structure shown below:
1 RKH_CREATE_BRANCH_TABLE( C2 )
2  RKH_BRANCH( is_power_ok, enable_process, &power ),
3  RKH_BRANCH( is_switch_off, turnoff, &wait ),
4  RKH_BRANCH( ELSE, abort, &aborted ),
5 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(). In RKH branches are defined by the macro RKH_BRANCH().

Definition at line 912 of file rkhsm.h.

#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).

Frequently, it's used before 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 964 of file rkhsm.h.

Enumeration Type Documentation

Return codes from rkh_sm_dispatch() function.

Enumerator
RKH_EVT_PROC 

The arrived event was succesfully processed and HSM resides in an allowed state.

RKH_EVT_NFOUND 

The arrived event was't founded in the transition table.

RKH_CND_NFOUND 

The branch function returned a value not founded in the branch table.

RKH_GRD_FALSE 

The transition was cancelled by guard function.

RKH_UNKN_STATE 

Unknown state.

RKH_EX_HLEVEL 

The transition exceeded the allowed hierarchical level.

RKH_EX_TSEG 

The transition exceeded the allowed number of segments within a compound transtion.

Definition at line 1530 of file rkhsm.h.

State machine properties.

Enumerator
HCAL 

Used as state machine property. This macro enables state nesting in a particular state machine.

FLAT 

Used as state machine property. This macro disables state nesting in a particular state machine. When FLAT is used in RKH_SMA_CREATE() macro some important features of RKH are not included: state nesting, composite state, history (shallow and deep) pseudostate, entry action, and exit action.

RKH_NUM_HPPTY 

Number of state machines properties

Definition at line 1578 of file rkhsm.h.

Function Documentation

void rkh_sm_init ( RKH_SM_T me)

Inits a previously created state machine calling its initializing action.

Parameters
[in]mepointer to previously created state machine.
ruint rkh_sm_dispatch ( RKH_SM_T me,
RKH_EVT_T e 
)

Executes a state machine in a run-to-completation (RTC) model.

In this model, before the system handles a new event it can store it until the previous event has completed processing. This model is called run to completion or RTC. Thus, the system processes events in discrete, indivisible RTC steps. An RTC step is the period of time in which events are accepted and acted upon. Processing an event always completes within a single model step, including exiting the source state, executing any associated actions, and entering the target state. 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.

Here now are the details of the main part of this algorithm (rkh_sm_dispatch()), in which an event is processed by the statechart.

  • Determine the compound transition (CT) that will fire in response to the event: traverse the states in the active configuration from lowest states in the hierarchy upwards. A CT is enabled if its trigger is the dispatched event, and the guard evaluates to true. Once an enabled transition is found with a given source state stop traversing the states that are higher than this state in the hierarchy.
  • Perform the CT that we found should fire. For each transition do:
    • Update histories of exited states.
    • Perform the exit actions of the exited states according to the order states are exited, from low state to high state.
    • Perform the actions on the CT sequentially according to the order in which they are written on the transition, from the action closest to source state to the action closest to target state.
    • Perform the entry actions of the entered states according to the order states are entered, from high state to low state.
    • For lowest level states that were entered, which are not basic states, perform default transitions (recursively) until the statechart reaches basic states.
    • Update the active configuration.
  • Wrap up: once a stable configuration is reached, the reaction to the event is completed, control returns to the dispatcher and new events can be dispatched.
Parameters
[in]mepointer to previously created state machine application.
[in]epointer to arrived event. It's used as state-machine's input alphabet.
Returns
Result RKH_RCODE_T code.
void rkh_sm_ctor ( RKH_SM_T me)

Initializes the attributes of the state machine instance.

Parameters
[in]mepointer to previously created state machine.
Note
The initializer assumes that memory has previously been allocated for the object (either statically or dynamically).
void rkh_sm_clear_history ( RKHROM RKH_SHIST_T h)

Erase the history of a state. It can be a shallow or deep history.

Parameters
[in]hpointer to history pseudostate.