模块的封装（五）：状态机模板

出处：状态机模板

说在前面的话

---

      好久没有整理代码了，最近一直在做ARMv8-M系统安全设计相关的研究，虽然忙，但不代表我对
自己无聊的爱好——整理一些好玩的代码模板，或者说语法糖——失去了兴趣。人总是会变的，一段
时间过去以后，发现过去写的代码真心看着“心累”——宏一律大写看着辣眼睛，比如以前写的状态机
脚本，所有做“状态机脚本语法辅助”的宏都是大写，看着果然还是不舒服。这次，我修正了一下自己的
编码风格：
    “所有宏和枚举都是大写除非对应的宏或者枚举用于辅助脚本语法”，比如后面你们看到的那个例子。
所有的状态机关键字都小写了，是不是舒服很多？

    如果只是换个格式，那未免也显得太没诚意了，这次的新模板具有以下特性：

    - 针对ARM架构进行效率上的优化
    - 为每一个状态机提供一个控制块，用于参数封装，并且每个控制块在内部都用掩码结构体进行私
      有化保护
    - 状态机模板可以独立存在，实现上更简洁
 

---

首先，我们来说说这次的模板在效率上作了什么优化？是什么原理？
    
    ARM的Thumb指令集有一个特点：所有的寻址都是间接寻址，尤其是对变量的访问，通常都要借助
一个寄存器来保存变量的地址，例如下面的语句：

1.  
2.     LDR   r0, =<某个数组的基地址>  ; 步骤1： 这是一个汇编伪代码，将某个数组的基地址复制到r0中，汇编器可以识别这种语法
3.     LDR   r1,  [r0]                ; 步骤2：r0里保存的是一个uint32_t变量的地址，我们把它读出来保存到r1里面
4.     LDR   r2,  [r0, #4]          ; 步骤3：读取uint32_t 数组的第二个word

复制代码

   这种方式实际上对面向对结构体的访问非常友好，而且如果你仔细观察你会发现：
    1. 如果你访问的是一个静态变量或者全局变量，那么生成的汇编包含“步骤1”和“步骤2”
    2. 如果你访问的是一个数组，那么一定会包含“步骤1”，然后每个元素的访问都对应一个步骤，也就是“步骤2”、“步骤三”
    3. 你会发现，无论是单个静态变量的访问，还是批量数组或者结构体的访问，“步骤1”——也就是加载基地址的过程都是省不掉的。
        在这种情况下，数组和结构体元素的访问共享同一个步骤一，这就比单个变量的访问要节省很多。

    举一个例子：总有人问，外设寄存器是单独定义成类似全局变量的形式好，还是用结构体访问的形式好？根据上面的描述，答案
    就很清楚了。同样的，普通的switch状态机，横竖要包含一个静态的状态变量，另外还有若干静态的参数，那么

    “为什么不把状态变量和状态机用到的静态变量打包成一个结构体——也就是状态机控制块呢？”
    
    实际上，根据上面的分析，哪怕这个状态机控制块只包含一个状态变量，它也不会比直接使用状态变量的方式增加更多的开销，
    相反，如果这个控制块包含更多其他的变量，我们就赚了！所以，我在模板上加入了以下的内容：
 

1.  
2. #define __simple_fsm(__FSM_TYPE, ...)                               \
3.         DECLARE_CLASS(__FSM_TYPE)                                   \
4.         DEF_CLASS(__FSM_TYPE)                                       \
5.             uint_fast8_t chState;                                   \
6.             __VA_ARGS__                                             \
7.         END_DEF_CLASS(__FSM_TYPE)
8.  
9. #define simple_fsm(__NAME, ...)                                     \
10.         __simple_fsm(fsm(__NAME), __VA_ARGS__)

复制代码

    可以看到，状态机控制块至少包含了一个状态变量 chState，而用状态机要用到的其它变量可以通过 "..." 对应的__VA_ARGS__
    加入到结构体中来。例如，一个用于延时的状态机delay_1s需要一个计数器，我们可以写成如下的形式：
 

1.  
2. simple_fsm( delay_1s,
3.     
4.     /* define all the parameters used in the fsm */ 
5.    uint32_t wCounter;                  //!< a uint32_t counter
6. )

复制代码

    这里，delay_1s 是状态机的名字，uint32_t wCounter; 是我们定义的参数（可以定义更多的参数）。显然，这两个东西放在一起
让人有点不知所措，所以我们增加了一个语法的辅助宏：

1.  
2.     #define def_params(...)         __VA_ARGS__

复制代码

    借助它，我们写出来的代码即便没有注释，也好懂多了：

1.  
2. simple_fsm( delay_1s,
3.     def_params(
4.         uint32_t wCounter;                  
5.     )
6. )

复制代码

    那么，实现状态机的时候，我们如何访问控制块里面的成员变量呢？这就要看看状态机的实现宏了：

1.  
2. #define fsm_implementation(__NAME, ...)                                              \
3.     fsm_rt_t __NAME( fsm(__NAME) *ptFSM __VA_ARGS__ )                           \
4.     {                                                                           \
5.         CLASS(fsm_##__NAME##_t) *ptThis = (CLASS(fsm_##__NAME##_t) *)ptFSM;     \
6.         if (NULL == ptThis) {                                                   \
7.             return fsm_rt_err;                                                  \
8.         }  
9.  
10. #define body(...)                                                               \
11.         switch (ptThis->chState) {                                              \
12.             case 0:                                                             \
13.                 ptThis->chState++;                                              \
14.             __VA_ARGS__                                                         \
15.         }                                                                       \
16.                                                                                 \
17.         return fsm_rt_on_going;                                                 \
18.     }

复制代码

    这里我们可以发现， implement_fsm() 和 body() 是配对使用的。你也许已经猜到了，状态机的具体
    实现代码是写在body的括号里的。具体可以看后面的例子，这里我们继续来讨论状态机控制块成员变量
    的访问。
    implement_fsm() 实际上规定了状态机的函数原形，它包含了一个指向状态机控制块的指针ptFSM，而
    这个指针随后就被还原为原始形式（控制块默认情况下实际上是一个掩码结构体，所以要访问内部成员
    必须要还原为原始形式）：ptThis实际上就指向了我们实际使用的控制块，通过这个结构体指针，我们
    就可以轻松的访问任何的成员变量。但到这里，不要急，为了让代码更好看一点，我们引入了一个专门 
    的辅助宏：

1.  
2. #ifndef this
3. #   define this    (*ptThis)
4. #endif

复制代码

    借助这一语法糖，我们可以毫无代价的在body()内部通过 "this." 的方式访问成员变量，例如：

1.  
2. fsm_implementation (  delay_1s)
3.     def_states(DELAY_1S)               
4.  
5.     body (
6.         state(  DELAY_1S,               
7.             if (0 == this.wCounter) {
8.                 fsm_cpl();              
9.             }
10.             this.wCounter--;
11.             fsm_on_going();             
12.         )
13.     )
14.  

复制代码

    如果我们的状态机要作为一个字模块提供给外部使用怎么办呢？别着急，这里有一个简单的宏，你
    可以放在头文件里面提供给别的.c文件来引用：

1.  
2. #define __extern_simple_fsm(__NAME, __FSM_TYPE, ...)                \
3.         DECLARE_CLASS(__FSM_TYPE)                                   \
4.         EXTERN_CLASS(__FSM_TYPE)                                    \
5.             uint_fast8_t chState;                                   \
6.             __VA_ARGS__                                             \
7.         END_EXTERN_CLASS(__FSM_TYPE)                                \
8.         extern fsm_rt_t __NAME( __FSM_TYPE *ptThis __VA_ARGS__ );
9.  
10. #define extern_simple_fsm(__NAME, ...)                              \
11.         __extern_simple_fsm(__NAME, fsm(__NAME), __VA_ARGS__)  

复制代码

    比如，我们要把delay_1s作为一个字状态机提供出去，我们可以在头文件里这么写：

1.  
2. extern_simple_fsm( delay_1s,
3.     def_params(
4.         uint32_t wCounter;                  
5.     )
6. )

复制代码

    好吧，我承认，其实就是把定义的部分又抄了一遍并加了一个extern_的前缀，简单吧？通过上面的
    宏定义，容易发现，因为使用了掩码结构体的形式，所以使用者是无法直接访问控制块内的成员变量
    的。

    至此，控制块定义、使用和优化的部分我们就解释完毕了。如果你有任何疑问，欢迎跟贴讨论。
 

---

最后谈谈设计思维和哲学

---

    这个状态机模板从发布第一个版本到小范围试用已经过去大半年了，其间，我被问得最多的问题是：
“你这已经不是C语言了”、“你实际上是制作了另外一个状态机脚本语言语法”、“为什么要做一个四不像
的东西呢？”、“这个模板本质上和protoThread一样，你为什么要重复发明轮子呢？” 针对这些大家感兴
趣的问题，如果我不从设计思维的角度给出答案，这个模板是很难让人接受的。下面我就以上问题，
从设计思维上给出一个系统的答案：

       首先，C语言原生态就不支持状态机，用C语言实现的状态机，本质上只是一种模拟。这跟C语言并
不原生态支持面向对象，如果真的要大量使用面向对象进行编程，最好的办法是使用C++，而不使用
OOPC去模拟是一样的——为什么呢？因为程序设计要专注于“应用逻辑的实现”本身，应该尽量避免被
“某种技术”分心——对需要大量使用面向对象技术进行开发的程序来说，应用逻辑是我们应该更多关心的，
而使用C模拟OO则是需要避免的。
        同样的问题发生在状态机上，C语言不仅不支持状态机，甚至我们模拟状态机的技术本身也相当复
杂、混乱。不像面向对象有C++，状态机的开发并没有一种语言与C具有传承关系（别说verlog，谢谢，
有本事你去找个verlog编译器，编译出来的机器码主流MCU都能运行的）。这可怎么办呢？回到我们的
目的本身：

程序设计要专注于“应用逻辑的实现”本身，应该尽量避免被“某种技术”分心

        为了达到这个目的，一个可行的方案就是想方设法构造一种基于C语言的“脚本语言”，使得状态机的
开发者得以关注“状态机应用逻辑的实现”，而不必关心“状态机具体是如何使用C语言进行构造的”。也就是
说，从一开始我们建立这个模板的目的就是要构造一种 状态机专用 的脚本语言，使得这种语言可以极大
的简化状态机的开发和表达。这种脚本语言根本就不用“看起来是C语言”，因为它从一开始就不是C语言。
        另一方面，新的脚本语言在使用时，应该能“无缝”的与其它C语言代码（函数）融合在一起，这表现
于：状态机的调用、参数传递、基本类似C的函数调用。简而言之，新的脚本语言：

设计的时候看起来是状态机，使用的时候看起来就像C语言

这与C++设计的时候是面向对象，使用的时候(可以)看起来就像C语言是类似的。基于上述思想，我们得以
“狡辩说”：现在的状态机模板导致的结果是一个对C很友好的状态机脚本语言，而不是一个用C实现的“四
不像”——当然，这对一部分人来说“其狡辩的本质是不随个人意志转移而改变的”  : p。

        针对和protoThread技术原理类似的问题，其实如果你真的使用过protoThread就会发现，这两个
模板在出发点上就是截然相反的：

- protoThread 试图让人产生“我是在使用RTOS进行线程开发”的错觉，它极力隐藏的是它“状态机的本质”
- simple fsm 从一开始，就让开发人员明确知道“我是在开发状态机”

足可见，虽然技术原理相同，但思维不同，最终使用的设计哲学也大相径庭。

        最后，一个决定性的因素说明 simple fsm 不是一个简单的模板而是一个“新的（基于C的）脚本语
言”，即simple fsm 使用了面向对象技术来封装状态机，这就从根本上决定了它不只是一种设计状态机的
方式，而是一整套面向对象状态机设计的哲学，比如：

    - 一个状态机就是一个类
    - 状态机函数只是这个类的一个方法
    - 状态机所要用到的变量都作为成员变量封装在类中（每个状态机都有自己的上下文）
    - 状态机及其数据被封装在一起，且对外界提供私有化保护（掩码结构体实现的private）
    - 状态机类是可以多实例的
    - 每个状态机从一开始就是一个任务（有自己的上下文——注意，这里的上下文是一个广义的概念，
       并不局限于stack）
    - 支持面向对象开发带来的种种好处
    - 支持面向接口开发（注意，面向接口开发不是面向对象的专利）

        综上所述：使用simple fsm开发的时候，我们只关心状态机如何设计，这也是为什么写出来的
                          代码  从字面上看  更像状态机而不是C语言；而调用状态机的时候，又对C语言很
                          友好——这当然是个优点。另外，如果你并不知道如何设计状态机，也不喜欢，那
                          么推荐你用protoThread或者干脆RTOS，因为你用simple fsm就要清楚你写的就是
                          TMD状态机！

     欢迎大家踊跃讨论，拍砖。
                                                                                          —— 傻孩子   吐槽于 2017-10-14日夜
 

---

如何使用

---

1. 如何定义一个状态机

    语法：

1.  
2. simple_fsm( <状态机名称>,
3.     def_params(
4.         参数列表                
5.     )
6. )

复制代码

    例子：

1.  
2.  
3. /*! fsm used to output specified string */
4. simple_fsm( print_string,
5.     def_params(
6.         const char *pchStr;        //!< point to the target string
7.         uint16_t hwIndex;          //!< current index
8.         uint16_t hwLength;        //!< claimed length of the target string, it is used to prevent buffer overflow 
9.     )
10. )

复制代码

     这里，实际上我们为目标状态机控制块定义了一个专用的类型，可以用fsm()对这个状态机加以引用。需要说明
的是，这个类型本质上是一个掩码结构体，也就是说你无法通过这个类型直接访问控制块的成员变量。这也是它安
全的地方——当然，防君子不防小人。
     语法：

1.  
2.      fsm(<状态机名称>)

复制代码

     例子：

1.  
2.      static fsm( print_string ) s_fsmPrintString;     //! 定义了一个本地的状态机控制块

复制代码

 

---

2. 如何extern一个状态机
         很多时候，我们的状态机会作为一个模块，提供给别的.c文件来使用（直接调用或者作为子状态机被
    调用，那么这种情况下应该如何处理呢？

    语法：

1.  
2. extern_simple_fsm( <状态机名称>,
3.     def_params(
4.         参数列表                
5.     )
6. )

复制代码

    例子：

        在某个头文件中写入如下的内容：

1.  
2. #include "simple_fsm.h"
3.  
4. ...
5.  
6. /*! fsm used to output specified string */
7. extern_simple_fsm( print_string,
8.     def_params(
9.         const char *pchStr;        //!< point to the target string
10.         uint16_t hwIndex;          //!< current index
11.         uint16_t hwLength;        //!< claimed length of the target string, it is used to prevent buffer overflow 
12.     )
13. )

复制代码

 

---

3. 如何实现一个状态机控制块的初始化函数
    很多复杂的状态机其服务本身是需要初始化的，简单说就是它的控制块在状态机使用前，必须进行
初始化，这类初始化是通过用户自定义的初始化函数来实现的，那么如何编写这类初始化函数呢？
 

---

[注意] 无论状态机多简单，初始化函数都不能省略。
    原因很简单，这样写出来的代码兼容性最好。有的说，控制块如果你不初始化，就是自动放到ZI段去了，
    编译器会自动帮你初始化为0。即便如此，这也是不妥的，原因如下：
    a. 不能依赖编译器，因为ANSI-C并没有规定不初始化的变量一定会被自动初始化为0
    b. 如果控制块是来自堆，就没有人帮你初始化状态机控制块了，别忘控制块里至少还有一个状态变量
    c. 作为子状态机使用的时候，为了节省空间，不同时运行的子状态机可以用union共享同一块Memory，
        这种情况下，状态机使用前不初始化问题很严重。

---

    语法：

1.  
2. fsm_initialiser( <状态机名称>,
3.     args(           
4.         <状态机初始化函数的形参列表，参数用逗号隔开，如果真的没有形参，可以省略该部分>
5.         /* 注意，即便没有形参，你也是需要initialiser来初始化状态机的 */
6.     ))
7.  
8.     init_body (
9.         <初始化函数的函数体，用普通C语言语法即可>
10.         /* 如果初始化过程中发生了任何错误需要放弃初始化并立即退出，使用 abort_init() */
11.     )

复制代码

    例子：
 

1.  
2. fsm_initialiser( print_string,
3.     args(           
4.         const char *pchString, uint16_t hwSize
5.     ))
6.  
7.     init_body (
8.         if (NULL == pchString || 0 == hwSize) {
9.             abort_init();                                       //!< illegal parameter
10.         } else if (strlen(pchString) < hwSize) {
11.             abort_init();                                       //!< buffer overflow
12.         }
13.  
14.         this.pchStr = pchString;  
15.         this.hwLength = hwSize;
16.     )

复制代码

 

---

4. 如何extern一个状态机初始化函数
     当一个状态机包含初始化函数时，如果要把该状态机提供给别的.c使用，我们还需要把对应的初
始化函数也extern出去。

    当你使用 extern_fsm_initialiser 的时候，我们的宏木板还会自动定义一个函数原型，这样，你就可以
    用这个函数圆形去定义指向 当前初始化函数 的函数指针。函数原型的名称如下：

   <状态机名称>_init_fn

    语法：

1.  
2. extern_simple_fsm_initialiser( <状态机名称>,
3.     args(           
4.         <状态机初始化函数的形参列表，参数用逗号隔开，如果真的没有形参，可以省略该部分>
5.         /* 注意，即便没有形参，你也是需要initialiser来初始化状态机的 */
6.     ))

复制代码

    例子：
        在某个头文件中写入如下的内容：

1.  
2. #include "simple_fsm.h"
3.  
4. ...
5.  
6. /*! fsm used to output specified string */
7. extern_simple_fsm_initialiser( print_string,
8.     args(           
9.         const char *pchString, uint16_t hwSize
10.     ))
11.  
12. ...
13.  

复制代码

这里，系统顺便定义了一个函数原型，print_string_init_fn，你可以用print_string_init_fn 直接定义函数指针：

1.  
2.     print_string_init_fn *fnInit = &print_string_init;   //!< <状态机名称>_init  就是初始化函数的函数名。

复制代码

 

---

5. 如何初始化一个状态机
    对于一个需要初始化的状态机，我们应该如何对它进行初始化呢？

    语法：

1.  
2. init_fsm(   <状态机名称>, <目标状态机控制块的地址>, 
3.     args( 
4.         <状态机初始化函数的实参列表，参数用逗号隔开，如果没有实参，可以省略该部分> 
5.      ));
6.  
7. 该函数的返回值是地址：
8.      NULL          初始化过程中出错
9.      ! NULL   <目标状态机控制块的地址>
10.  

复制代码

     例子：

1.  
2. //! 定义了一个状态机控制块
3. static fsm(print_string)  s_fsmPrintString;
4.  
5. #define DEMO_STRING   "Hello FSM World!\r\n"
6.  
7.     if (NULL == init_fsm(    print_string, & s_fsmPrintString,
8.         args( 
9.             DEMO_STRING,                      //!< target string    
10.             sizeof(DEMO_STRING) - 1))) {      //!< String Length
11.          /* failed to initialize the FSM, put error handling code here */
12.      }
13.  

复制代码

 

---

6. 如何实现一个状态机

    语法：

1.  
2. fsm_implementation(  <状态机名称>, 
3.         args( <状态机的形参列表，参数用逗号隔开，如果没有形参，可以省略这部分> )
4.     )
5.     def_states( <列举所有状态机状态，用逗号隔开，确保状态机的入口状态列在第一的位置> )               
6.  
7.     <局部变量列表>
8.  
9.     body (
10.          on_start(  
11.              <状态机复位后第一次运行时，运行且只运行一次的代码，通常放一些状态机内部的初始化代码，如果无所事事，可以省略这个部分>
12.          )  
13.       
14.         <状态机所有的状态实现>
15.     )

复制代码

    例子：

1.  
2. fsm_implementation(  print_string )
3.     def_states( CHECK_LENGTH, OUTPUT_CHAR )               
4.  
5.     body (
6.          on_start(  
7.              this.hwIndex = 0;         //!< reset index
8.          )  
9.       
10.         ...
11.     )

复制代码

 

---

7. 如何extern一个状态机函数

    当你使用 extern_fsm_implementation 的时候，我们的宏木板还会自动定义一个函数原型，这样，你就可以
    用这个函数圆形去定义指向 当前初始化函数 的函数指针。函数原型的名称如下：

   <状态机名称>_fn


    语法：

1.  
2. extern_fsm_implementation(  <状态机名称>, 
3.         args( <状态机的形参列表，参数用逗号隔开，如果没有形参，可以省略这部分> )
4.     )

复制代码

    例子：
        在某个头文件中写入如下的内容：

1.  
2. #include "ooc.h"
3. #include "simple_fsm.h"
4.  
5. ...
6.  
7. extern_fsm_implementation(  print_string );
8.  
9. ...
10.  

复制代码

这里，系统顺便定义了一个函数原型，print_string_fn，你可以用print_string_fn 直接定义函数指针：

1.  
2.     print_string_fn *fnFSM = &print_string;   //!< <状态机名称> 就是状态机函数的名称。

复制代码

 

---

8. 如何实现一个状态
     状态必须在body()内实现，具体形式如下：

    语法：

1.  
2.      state( <状态名称>,
3.  
4.          <状态实现代码，C语言实现>
5.  
6.          fsm_on_going();
7.      )

复制代码

    在实现状态的过程中，状态的切换要通过 transfer_to() 来实现，它将立即终止当前状态代码的执行，
并跳转到目标状态中，其语法如下：

1.  
2.      transfer_to( <目标状态的名称> )

复制代码

    有些时候，我们只希望更新状态机的状态，而并不希望立即终止当前状态机的执行，则可以用
update_state_to() 来实现。通常update_state_to() 配合 “省缺状态结尾处的fsm_on_going()” 来
直接 fall-through 到紧随着当前状态的下一个状态来执行，这实际上是利用switch的fall-through特性
来实现某些情况下的状态机性能提升。其语法如下：

1.  
2.      update_state_to( <目标状态的名称> )

复制代码

    实际上 transfer_to() 等效于以下的组合

1.  
2.      update_state_to( <目标状态> )
3.      fsm_on_going();

复制代码

     状态实现的时候，如果需要更新状态机的返回值，则可以使用下列方式：

1.  
2.      fsm_on_going()                         立即终止当前状态，并让状态机返回fsm_rt_on_going;
3.      fsm_cpl()                                  立即终止当前状态，复位状态机，并让状态机返回fsm_rt_cpl;
4.      fsm_reset()                               仅复位状态机，不影响状态机返回值（通常配合fsm_on_going() 
5.                                                     和fsm_report() 使用）
6.      fsm_report( <任意负数> )          立即终止当前状态，并返回错误码（任意小于等于fsm_rt_err）的值

复制代码

     例子：

1.  
2. fsm_implementation(  print_string )
3.     def_states( CHECK_LENGTH, OUTPUT_CHAR )               
4.  
5.     body (
6.          on_start(  
7.              this.hwIndex = 0;         //!< reset index
8.          )  
9.       
10.         state ( CHECK_LENGTH,
11.             if ( this.hwIndex >= this.hwLength ) {
12.                  fsm_cpl();               
13.             }
14.             update_state_to ( OUTPUT_CHAR );              //! deliberately ignore the following fsm_on_going() in order to fall through to next state
15.             // fsm_on_going();        
16.         )
17.  
18.         state ( OUTPUT_CHAR,
19.              if (SERIAL_OUT( this.pchStr[ this.hwIndex ] )) {
20.                    this.hwIndex++;
21.                    transfer_to ( CHECK_LENGTH );
22.              }
23.  
24.              fsm_on_going();
25.         )
26.     )

复制代码

9. 如何调用一个状态机
     状态机（包括子状态机）的调用方式是一样的，假设状态机已经被初始化过了，那么可以使用
下面的方法进行调用（放在超级循环里面，或者放在某个状态里面是一样的）：

    语法：

1.  
2.     call_fsm ( <状态机名称>, <状态机控制块的地址>
3.         args( <状态机的实参列表，参数用逗号隔开。如果没有实参，可以省略该部分> )
4.     )
5.  
6. 该函数的返回值是状态机的运行状态 fsm_rt_t：
7.      fsm_rt_err                状态机出现了意料之外的，且自身无法处理的错误，例如无效的参数
8.      fsm_rt_on_going           状态机正在执行
9.      fsm_rt_cpl                状态机已经完成

复制代码

    例子：

1.  
2.     static fsm(print_string) s_fsmPrintSting;
3.  
4.     void main(void)
5.     {
6.          ...
7.          while(1) {
8.              ...
9.              if (fsm_rt_cpl == call_fsm( print_string, &s_fsmPrintString )) {
10.                   /* fsm is complete, do something here */
11.              }
12.          }
13.     }

复制代码

 

---

10. 如何前置声明一个状态机
         有些时候，在我们正式通过 simple_fsm 宏定义一个状态机之前，当前状态机就要被其它（当前状态机）所依赖的关键类型所引用，
比如，定义指向当前状态机的指针啊，函数指针啊，之类的——简而言之，前置引用的问题如何解决呢？

    语法：

1.  
2. declare_simple_fsm( <状态机名称> )

复制代码

    例子：

        在某个头文件中写入如下的内容：

1.  
2. #include "simple_fsm.h"
3.  
4.  
5. declare_simple_fsm(print_string);
6. extern_fsm_implementation(print_string);
7. extern_simple_fsm_initialiser( print_string,
8.     args(           
9.         const char *pchString, uint16_t hwSize
10.     ));
11.  
12. typedef struct {
13.     fsm(print_string) *ptThis;          //!< a pointer points to fsm obj
14.     print_string_fn *fnTask;             //!< a function pointer, point to fsm function
15.     print_string_init_fn *fnInit;       //!< a function pinter, points to initialisation function
16. } vtable_t;
17.  
18.  
19. /*! fsm used to output specified string */
20. simple_fsm( print_string,
21.     def_params(
22.         vtable_t Methods;
23.         const char *pchStr;        //!< point to the target string
24.         uint16_t hwIndex;          //!< current index
25.         uint16_t hwLength;        //!< claimed length of the target string, it is used to prevent buffer overflow 
26.     )
27. )

复制代码

 

---

一个简单的例子

---

     这里，我们展示了一个简单的状态机例子，用于周期性的通过串口输出“hello”。我们可以看到，
这个例子里定义了两个状态机，print_hello 用于打印字符串，并调用另外一个子状态机delay_1s用于
实现一个差不离的延时（代码里用了一个随便写的常数10000，领会精神就好）。

     print_hello 状态机的结构相当简单，前半部分是字符串的输出——简单粗暴的为每一个字符分配 
一个状态；后半部分演示了子状态机的调用方式：首先对子状态机进行初始化（如果这个子状态机确
实需要这个步骤）；紧接着是通过一个专门的状态来进行子状态机调用。我们通过子状态机的返回值
来了解子状态机的状态——正在进行（on going），完成（cpl ）还是发生了什么错误（返回值为负数）
 

1.  
2.  
3. /***************************************************************************
4. *   Copyright(C)2009-2017 by Gorgon Meducer<[email protected]> *
5. *                                                                         *
6. *   This program is free software; you can redistribute it and/or modify  *
7. *   it under the terms of the GNU Lesser General Public License as        *
8. *   published by the Free Software Foundation; either version 2 of the    *
9. *   License, or (at your option) any later version.                       *
10. *                                                                         *
11. *   This program is distributed in the hope that it will be useful,       *
12. *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
13. *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
14. *   GNU General Public License for more details.                          *
15. *                                                                         *
16. *   You should have received a copy of the GNU Lesser General Public      *
17. *   License along with this program; if not, write to the                 *
18. *   Free Software Foundation, Inc.,                                       *
19. *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
20. ***************************************************************************/
21.  
22. /*============================ INCLUDES ======================================*/
23. #include ".\app_cfg.h"
24.  
25. /*============================ MACROS ========================================*/
26. /*============================ MACROFIED FUNCTIONS ===========================*/   
27.  
28. #ifndef SERIAL_OUT
29. #define SERIAL_OUT(__BYTE)      serial_out(__BYTE)
30. #endif
31.  
32. /*============================ TYPES =========================================*/
33.  
34. /*! \brief you can use simple fsm at any where you want with little cost. 
35.            E.g.
36.             
37. *! \brief function that output a char with none-block manner
38. *! \param chByte target char
39. *! \retval true the target char has been put into the output buffer 
40. *! \retval false service is busy
41. */
42. extern bool serial_out(uint8_t chByte);
43.  
44.  
45.  
46. /*============================ GLOBAL VARIABLES ==============================*/
47. /*============================ LOCAL VARIABLES ===============================*/
48. /*============================ PROTOTYPES ====================================*/
49.  
50. /*! /brief define fsm delay_1s
51. *!        list all the parameters
52. */
53. simple_fsm( delay_1s,
54.     
55.     /* define all the parameters used in the fsm */ 
56.     def_params(
57.         uint32_t wCounter;                  //!< a uint32_t counter
58.     )
59. )
60.  
61. /*! /brief define fsm print_hello
62. *!        list all the parameters
63. */
64. simple_fsm( print_hello,
65.     def_params(
66.         fsm(delay_1s) fsmDelay;             //!< sub fsm delay_1s
67.     )
68. )
69.  
70. /*============================ IMPLEMENTATION ================================*/
71.  
72.  
73.  
74. /*! /brief define the fsm initialiser for FSML delay_1s
75. *! /param wCounter  an uint32_t value for the delay count
76. */
77. fsm_initialiser(delay_1s,               //!< define initialiser for fsm: delay_1s
78.     /*! list all the parameters required by this initialiser */
79.     args(           
80.         uint32_t wCounter               //!< delay count
81.     ))
82.  
83.     /*! the body of this initialiser */
84.     init_body (
85.         this.wCounter = wCounter;       //!< initialiser the fsm paramter
86.     )
87. /* End of the fsm initialiser */
88.  
89.  
90. /*! /brief Implement the fsm: delay_1s
91. *         This fsm only contains one state.
92. */
93. fsm_implementation(  delay_1s)
94.     def_states(DELAY_1S)                //!< list all the states used in the FSM
95.  
96.     /* the body of the FSM: delay_1s */
97.     body (
98.         state(  DELAY_1S,               //!< state: DELAY_1s
99.             if (!this.wCounter) {
100.                 fsm_cpl();              //!< FSM is completed
101.             }
102.             this.wCounter--;
103.             fsm_on_going();             //!< on-going
104.         )
105.     )
106. /* End of fsm implementation */
107.  
108.  
109. fsm_initialiser(print_hello)
110.     init_body ()
111.  
112. /*! /brief Implement the fsm: delay_1s
113. *         This fsm only contains one state.
114. */
115. fsm_implementation(print_hello)
116.  
117.     /*! list all the states used in the FSM */
118.     def_states(PRINT_H, PRINT_E, PRINT_L, PRINT_L_2, PRINT_O, DELAY)
119.  
120.     body(
121. //! the on_start block are called once and only once on the entry point of a FSM
122. //        on_start(
123. //            /* add fsm parameter initialisation code here */
124. //        )
125.  
126.         state(PRINT_H,
127.             if (SERIAL_OUT('H')) {
128.                 transfer_to(PRINT_E);   //!< transfer to state PRINT_E
129.             }
130.             fsm_on_going();             //!< on going
131.         )
132.         
133.         state(PRINT_E,
134.             if (SERIAL_OUT('e')) {
135.                 transfer_to(PRINT_L);
136.             }
137.             fsm_on_going();
138.         )
139.  
140.         state(PRINT_L,
141.             if (SERIAL_OUT('l')) {
142.                 transfer_to(PRINT_L_2);
143.             }
144.             fsm_on_going();
145.         )
146.  
147.         state(PRINT_L_2,
148.             if (SERIAL_OUT('l')) {
149.                 transfer_to(PRINT_O);
150.             }
151.             fsm_on_going();
152.         )
153.  
154.         state(PRINT_O,
155.             if (!SERIAL_OUT('o')) {
156.                 fsm_on_going();
157.             }
158.  
159.             //! initialize the internal sub fsm
160.             init_fsm(   delay_1s,           //!< FSM: delay_1s
161.                         &(this.fsmDelay),   //!< the fsm control block
162.                         args(10000));       //!< pass parameters to the initialiser
163.  
164.             //! update the state to DELAY without yield, so it will fall-through to the following state directly
165.             update_state_to(DELAY);
166.         )
167.  
168.  
169.         state(DELAY,
170.             /*! call the sub fsm */
171.             if (fsm_rt_cpl == call_fsm(delay_1s, &(this.fsmDelay))) {
172.                 fsm_cpl();
173.             }
174.             fsm_on_going();
175.         )
176.     )
177.  
178. /* EOF */

复制代码