Declaring the basic states

Prev: Instantiating the composite states
Next: Declaring the pseudostates

A basic state (also called substate) is defined with the RKH_CREATE_BASIC_STATE() macro and declared with the RKH_DCLR_BASIC_STATE() macro. Frequently, each state machine and its states (superstates and substates) are encapsulated inside a dedicated source file (.c file), from which the RKH_CREATE_BASIC_STATE() macro is used. As will demostrates the use of RKH_CREATE_BASIC_STATE() macro and its arguments is very similar to RKH_CREATE_COMP_STATE() macro.

The Figure 7 highlights the basic states "S2". Also, shows its implementation using the RKH framework.

Figure 7 - basic state "S2"

Defining the basic state "S2"

(1) //  my.c: state-machine's module

(2) RKH_CREATE_BASIC_STATE( S2, 
(4)                         NULL, 
(5)                         NULL, 
(6)                         RKH_ROOT, 
(7)                         NULL);

Declaring the basic state "S2"

//  my.h: state-machine's header file

RKH_DCLR_BASIC_STATE(S2);

Explanation

• (1) Frequently, each state machine and its states are encapsulated inside a dedicated source file (.c file), from which the RKH_CREATE_BASIC_STATE() macro is used.
• (2) S2 is the state name. Represents a substate structure.
• (4) the entry action is unused, therefore it is declared as NULL.
• (5) the exit action is unused, therefore it is declared as NULL.
• (6) RKH_ROOT is the parent state of S2. If a state has no explicit superstate means that it is implicitly nested in the "top" state, and the parent state is defined by means of RKH_ROOT macro. The "top" state is a UML concept that denotes the ultimate root of the state hierarchy in a hierarchical state machine.
• (7) the event preprocessor action is unused, therefore it is declared as NULL. Before sending the arrived event to state machine, it can be previously processed using the event preprocessor function. An action function takes the state machine pointer and the event pointer as arguments. The first parameter is optional in compile-time according to RKH_CFG_SMA_PPRO_ARG_SMA_EN macro. Example:

  static RKH_SIG_T
  in_keyb(RKH_EVT_T *pe)
  {
      if (pe->e >= 0 && pe->e <= 9)
      {
          return DECIMAL;
      }
      if (pe->e == '.')
      {
          return POINT;
      }
      else
      {
          return pe->e;
      }
  }

• (7) Aditionally, by means of single inheritance in C it could be used as state's abstract data. Aditionally, 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.

This argument is optional, thus it could be declared as NULL.

Example:

static
RKH_SIG_T
preprocessor(RKH_EVT_T *pe)
{
   ...
}

typedef struct
{
   RKH_PPRO_T prepro;  // extend the RKH_PPRO_T class
   unsigned min:4;
   unsigned max:4;
   char *buff;
} SDATA_T;

static const SDATA_T option = {preprocessor, 4, 8, token1};

RKH_CREATE_BASIC_STATE(S111, set_x_1,
                      NULL, &S11, preprocessor);
RKH_CREATE_BASIC_STATE(S22, set_x_4,
                      NULL, &S2, (RKH_PPRO_T*)&option);

The following figures, Figure 8, Figure 9, and Figure 10 highlights the basic states "S111", "S112", "S31", "S32", and "S12" respectively. Also, shows its implementation using the RKH framework.

Figure 8 - basic states "S111", and "S112"

Figure 9 - basic state "S12"

Figure 10 - basic states "S31", and "S32"

Prev: Instantiating the composite states
Next: Declaring the pseudostates