update readme

2020-03-22 20:48:43 +08:00
parent 8388872d8e
commit 13a597b600
4 changed files with 370 additions and 7 deletions
@@ -8,9 +8,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [Unreleased]

 ## [0.1.0] - 2020-03-18
+
 ### Added
+
 - add changelog and release support
+
 ### Changed
+
 - clean code, and move all tests to test directory

+## [0.2.0] - 2020-03-22

+### Added
+
+- add hal_api for uart/nvram/ctrls/sens
@@ -1,11 +1,366 @@

-## simulink library for Hardware Abstract Layer(HAL) and code-gen support
+# slhal 硬件无关层（HAL）设计与实现

-[![pipeline status](http://sh.matthewgong.com/matt/slhal/badges/master/pipeline.svg)](http://sh.matthewgong.com/matt/slhal/commits/master)
+[![pipeline status](https://sh.matthewgong.com/matt/slhal/badges/master/pipeline.svg)](https://sh.matthewgong.com/matt/slhal/commits/master)

-本Simulink库提供了用于与飞控硬件接口的代码生成模块。只需要以template目录下的*_wrapper.c文件为模板编写接口文件，即可实现飞控代码的移植。
+本Simulink库对飞控连接的各种设备进行抽象，提出一套硬件无关层标准化接口，使得上层simulink飞控开发者无需关心具体硬件。
+
+## 设计思想概述
+
+### 使用S-function Builder协助生成接口模板
+
+HAL的接口模块都是masked S-function。为了免去手工编写.c/.tlc代码引入错误，项目使用了S-function Builder协助生成接口模板。
+
+每个HAL接口库文件都有对应的`*_bld.slx`库，其用于存放对应的s-function builder的模块。
+所有s-function模块的的PW、输入、输出、参数等接口定义都由图形化定义生成，大大简化了编写s-function的过程，自动生成了标准的mex接口代码、TLC代码完全无需修改，只需要关注产生的包裹函数模板_wrapper.c。
+
+### 硬件移植的一般过程
+
+HAL接口是通过s-function实现与飞控硬件接口的调用。只需要将template目录复制到新目录下，并在*_wrapper.c模板文件的基础上根据硬件配置实现其具体功能，最终在飞控代码生成中指向新目录（addpath），即可生成包含此飞控系统接口代码的完整程序。
+
+### wrapper函数需要实现的功能
+
+`*_Start_wrapper()`函数用于设备初始化、可配置参数的注册与绑定。
+
+`*_Outputs_wrapper()`函数一般用于程序正常运行时的调用。还可以细分为三种被调用情况：
+
+ 调用情况 | 说明
+ ------- | ----------------------
+ 周期调用 | 通常情况，按固定周期被调用。常用于输入与输出。
+在Function-Call中被调用 | 通常是被StateFlow状态机调用。常用于事件处理（Event）。
+在initialize function中被调用 | 在所有`*_Start_wrapper()`后，也就是初始完成后，正式启动前被调用，因此也可称为后初始化（post_init）。<br>这种用法的特殊在于此时可以保证所有其他模块都初始化可用，另一个好处是该调用有输入inputs，而`*_Start_wrapper()`没有输入只有参数传入。
+
+生成代码的执行流程见下图。
+
+```mermaid
+graph TD;
+    inits --> period-call
+    starts -.-> |call| call_start["*_Start_wrapper()"]
+    inits -.-> |call| call_outputs["*_Outputs_wrapper()"]
+    period-call -.-> |call| call_outputs
+    func-call -.-> |call| call_outputs
+    subgraph "initialize"
+    starts["init"] --> inits["post-init"]
+    end
+
+    subgraph "step"
+    func-call
+    period-call --> period-call
+    end
+```
+
+## hal_api_uart库
+
+hal_api_uart.slx实现了对串行流的抽象操作，分别是初始化配置（hal_uart_init）、读(hal_uart_in)与写(hal_uart_out)。
+
+模块 | 功能 | 备注
+---- | ---- | -----
+hal_uart_init | 初始化配置 | 可以配置串口波特率、读写FIFO长度等参数。<br>如果某FIFO长度为零，则表示这不是一个双向读写设备。<br>其内部是一个initialize function。 也就是说它的Outputs函数只会在整个系统Start后Step前调用。
+hal_uart_in | 读取串行流 | 从串行流中尽量读取数据到Data缓存，读取长度len不会超出Data的长度。<br>如果出错，ErrorCode返回非零值。
+hal_uart_out | 输出到串行流 | Data是输出的缓存，可用长度为len。当seq号变化时表示有新数据需要从缓存输出。
+
+模块依赖关系如下图。
+
+```mermaid
+    graph LR;
+    hal_api_uart(hal_api_uart.slx) --> hal_uart_init
+    hal_api_uart(hal_api_uart.slx) --> hal_uart_in
+    hal_api_uart(hal_api_uart.slx) --> hal_uart_out
+    hal_uart_init -- startup --> hal_uart_init_Start_wrapper --> initialize_uart_device
+    hal_uart_init -- initialize --> hal_uart_init_Outputs_wrapper
+    hal_uart_in -- startup --> hal_uart_in_Start_wrapper --> initialize_uart_device
+    hal_uart_in -- step --> hal_uart_in_Outputs_wrapper
+    hal_uart_out -- startup --> hal_uart_out_Start_wrapper --> initialize_uart_device
+    hal_uart_out -- step --> hal_uart_out_Outputs_wrapper
+```
+
+### hal_uart_init模块实现
+
+hal_uart_init模块的功能在hal_uart_init_wrapper.c中实现。其中，hal_uart_init_Start_wrapper将在初始化时被调用，它会去调用一个单例函数initialize_uart_device。无论被调用几次（每个hal_api_uart库中模块初始化(start)都会去调用它），单例函数initialize_uart_device只应当初始化对应UART设备一次。
+
+initialize_uart_device函数应该对设备初始化，但无需配置（进行默认配置也可以）。
+它还应当实现对设备属性的绑定注册功能（利用slparm的param_mgr.h绑定设置/读取波特率、字长、中止位、校验位等的函数），这样稍后就可以让地面站配置其波特率；或者从NVRAM中读取参数配置其波特率等属性。
+
+hal_uart_init_wrapper.c中的hal_uart_init_Outputs_wrapper函数被设计成在所有模块start后被初始化调用，这个函数应用于实现配置UART设备的默认波特率及FIFO空间大小。
+
+### hal_uart_in模块实现
+
+hal_uart_in模块的功能应在hal_uart_in_wrapper.c中实现。
+hal_uart_in_Start_wrapper用于调用单例初始化函数initialize_uart_device。
+
+hal_uart_in_Outputs_wrapper用于实现从uart_id设备中读取数据到Data中，并返回本次读取的数据长度Data_len（读取数据长度最多不超过y_width）。
+当未被正常初始化或其他读取异常状态时，返回非零值。
+
+### hal_uart_out模块实现
+
+hal_uart_out模块的功能应在hal_uart_out_wrapper.c中实现。
+hal_uart_out_Start_wrapper用于调用单例初始化函数initialize_uart_device。
+
+hal_uart_out_Outputs_wrapper用于实现uart_id设备对应seq变化时，写入长度len(不超过u_width)数据到buff中。
+当未被正常初始化或其他写入异常状态时，返回非零值。
+
+## hal_api_nvram库
+
+hal_api_nvram.slx实现了对非易失存储设备(如FRAM/EEPRM/FLASH/SDMMC设备)的抽象操作，分别是读(hal_nvram_read)、写(hal_nvram_write)与取消(hal_nvram_cancel)。三模块都最终封装为function-call形式，因此应当使用StateFlow对其进行调用操作。
+
+模块 | 功能 | 备注
+---- | ---- | -----
+hal_nvram_read | 从nvram_id设备的StartAddress地址开始读取Length到Buffer中 | ErrorCode返回负值为出错，返回正值为还有多少字节未读，返回零表示完成。
+hal_nvram_write | 从nvram_id设备的StartAddress地址开始从Buffer写Length字节 | ErrorCode返回负值为出错，返回正值为还有多少字节未写，返回零表示完成。
+hal_nvram_cancel | 取消nvram_id设备的StartAddress地址开始的读写任务 | 必须nvram_id与StartAddress都匹配的作业才能取消
+
+模块依赖关系如下图。
+
+```mermaid
+    graph LR;
+    hal_api_nvram(hal_api_nvram.slx) --> hal_nvram_read
+    hal_api_nvram --> hal_nvram_write
+    hal_api_nvram --> hal_nvram_cancel
+    hal_nvram_read -- startup --> hal_nvram_read_Start_wrapper --> initialize_nvram_device
+    hal_nvram_read -- call --> hal_nvram_read_Outputs_wrapper
+    hal_nvram_write -- startup --> hal_nvram_write_in_Start_wrapper --> initialize_nvram_device
+    hal_nvram_write -- call --> hal_nvram_write_Outputs_wrapper
+    hal_nvram_cancel -- startup --> hal_nvram_cancel_Start_wrapper --> initialize_nvram_device
+    hal_nvram_cancel -- call --> hal_nvram_cancel_Outputs_wrapper
+```
+
+### 接口设计思路
+
+其中initialize_nvram_device是单例函数，实现对nvram_id号的设备进行单次的初始化。
+nvram_id号从0开始，可以表示单个FRAM/EEPRM/FLASH/SDMMC设备。
+但更本质上，nvram_id号是某对NVRAM设备独立操作进程的序号。比如可以同时2个进程对SDMMC进行读写，那么即使只有1个SDMMC设备，也应该有两个nvram_id号，用于独立处理。
+
+这组接口在实现上需要有一定技巧。
+一般NVRAM的读写操作都需要一定时间，但该接口要求即时返回，不能长时间占用。
+因此设计上应当是每个nvram_id号与一个NVRAM处理进程相关联，接口只用于触发读写任务、监控当前任务状态。
+当前任务可以用nvram_id与start_address的组合进行标识。如果读写操作未完成，而新调用的start_address改变了，则应当认为返回-2（Ocuppied）拒绝新读写调用。
+
+ErrorCode返回值 | 含义 | NVRAM处理进程状态
+ ------------- | ---- | -------------
+  -3 | Canncelled | 当前任务已经被取消，可以开始下次任务
+  -2 | Ocuppied | 其他任务正在执行中，无法开始任务
+  -1 | Genral Err | 一般性错误，未完成初始化等
+   0 | Completed | 当前任务已完成，可以开始下次任务
+   $`>0`$ | Working | 当前任务正在传输，请等待
+
+此外，NVRAM设备一般是按块（页）读写的，而本接口设计上为了使用方便属于按段读写。因此应当在处理进程中设计缓存Buffer/Cache。
+当写操作时，如果在同一块内写，则先写入块buffer中，到超时或开始写其他块时才真正开始写入。
+当读操作时，先读取整个块到cache中，如果读取都在cache中则命中，否则再读对应块。
+
+### hal_nvram_read模块实现
+
+hal_nvram_read模块的功能应在hal_nvram_read_wrapper.c中实现。
+hal_nvram_read_Start_wrapper用于调用单例初始化函数initialize_nvram_device。
+
+hal_nvram_read_Outputs_wrapper用于实现启动/监测nvram_id进程从start address开始读取长度len(不超过y_width)数据到buffer中。返回值是当前未读入字节数，零表示写入完成，小于零值表示错误。
+
+### hal_nvram_write模块实现
+
+hal_nvram_write模块的功能应在hal_nvram_write_wrapper.c中实现。
+hal_nvram_write_Start_wrapper用于调用单例初始化函数initialize_nvram_device。
+
+hal_nvram_write_Outputs_wrapper用于实现启动/监测nvram_id进程从start address开始从buffer写长度len(不超过u_width)数据。返回值是当前未写入字节数，零表示写入完成，小于零值表示错误。
+
+### hal_nvram_cancel模块实现
+
+hal_nvram_cancel模块的功能应在hal_nvram_cancel_wrapper.c中实现。
+hal_nvram_cancel_Start_wrapper用于调用单例初始化函数initialize_nvram_device。
+
+hal_nvram_cancel_Outputs_wrapper用于实现取消nvram_id进程从start address开始的读写作业。返回值是零表示完成取消，非零值表示错误。
+
+## hal_api_ctrls库
+
+hal_api_ctrls.slx实现了对输入输出设备的抽象操作。
+模块简介如下：
+
+模块         | 功能     | 备注
+----------- | -------- | -----------------
+hal_pwm_out | PWM输出   | 单位us，类型uint16
+hal_pwm_in  | PWM输入   | 同上
+hal_do      | 离散量输出 | 类型bool
+hal_di      | 离散量输入 | 同上
+hal_ao      | 离散量输出 | 单位V，类型single
+hal_ai      | 离散量输入 | 同上
+hal_led_set | 三色LED输出 | 类型Bus: LedColorMsg, rgb:0-255 uint8
+hal_sbus_in | Sbus接收机输入 | 类型Bus: SbusInMsg
+
+模块依赖关系如下图。
+
+```mermaid
+    graph LR;
+    hal_api_ctrls(hal_api_ctrls.slx) --> hal_pwm_out
+    hal_api_ctrls --> hal_pwm_in
+    hal_api_ctrls --> hal_do
+    hal_api_ctrls --> hal_di
+    hal_api_ctrls --> hal_ao
+    hal_api_ctrls --> hal_ai
+    hal_api_ctrls --> hal_led_set
+    hal_api_ctrls --> hal_sbus_in
+    hal_pwm_out --> hal_pwm_out_wrapper[hal_pwm_out_wrapper.c]
+    hal_pwm_in --> hal_pwm_in_wrapper[hal_pwm_in_wrapper.c]
+    hal_do --> hal_do_wrapper[hal_do_wrapper.c]
+    hal_di --> hal_di_wrapper[hal_di_wrapper.c]
+    hal_ao --> hal_ao_wrapper[hal_ao_wrapper.c]
+    hal_ai --> hal_ai_wrapper[hal_ai_wrapper.c]
+    hal_led_set --> hal_led_set_wrapper[hal_led_set_wrapper.c]
+    hal_sbus_in --> hal_sbus_in_wrapper[hal_sbus_in_wrapper.c]
+    hal_led_set_wrapper --> hal_led_set_bus[hal_led_set_bus.h]
+    hal_sbus_in_wrapper --> hal_sbus_in_bus[hal_sbus_in_bus.h]
+    hal_led_set_bus --> hal_api_busdef[hal_api_busdef.mat]
+    hal_led_set_bus --> hal_api_busdef
+```
+
+### hal_api_ctrls接口设计思路
+
+对于PWM、DIO、AIO这些输入输出接口，不管是几个设备拼成的，每一类的通道需要统一编址。
+如PWM输出可能一个时钟控制4个通道，另一个时钟控制2个通道，我们无需给每组编制一个设备号，而是统一从零开始编号（0、1、2、3、4、5、……）。
+而访问这些通道的时候，可以从start_idx开始连续读写。
+读写的长度取决于给定的输入输出缓存空间width与真实通道的长度（两者取短）。
+如果真实能够的读写的长度小于缓存空间，应返回非零的ErrorCode。
+
+### hal_pwm_out模块实现
+
+hal_pwm_out模块的功能应在hal_pwm_out_wrapper.c中实现。
+hal_pwm_out_Start_wrapper用于调用单例初始化函数pwm_out_init。
+pwm_out_init可以初始化PWM输出设置并绑定PWM周期设定与读取参数。
+
+hal_pwm_out_Outputs_wrapper用于实现输出PWM指令到编号从start_idx到start_idx+u_width-1的通道。
+ErrorCode返回值非零表示错误，一般是对应通道不存在。
+
+### hal_pwm_in模块实现
+
+hal_pwm_in模块的功能应在hal_pwm_in_wrapper.c中实现。
+hal_pwm_in_Start_wrapper用于调用单例初始化函数pwm_in_init。
+pwm_in_init可以初始化PWM输入设置并绑定相关参数。
+
+hal_pwm_in_Outputs_wrapper用于实现从编号start_idx到start_idx+u_width-1的通道读取PWM输入脉宽值。
+ErrorCode返回值非零表示错误，一般是对应通道不存在。
+
+### hal_do模块实现
+
+hal_do模块的功能应在hal_do_wrapper.c中实现。
+hal_do_Start_wrapper用于调用单例初始化函数discrete_output_init。
+discrete_output_init可以初始化离散量输出设置并绑定相关参数。
+
+hal_do_Outputs_wrapper用于实现输出离散指令到编号从start_idx到start_idx+u_width-1的数字通道。
+ErrorCode返回值非零表示错误，一般是对应通道不存在。
+
+### hal_di模块实现
+
+hal_di_in模块的功能应在hal_di_wrapper.c中实现。
+hal_di_Start_wrapper用于调用单例初始化函数discrete_input_init。
+discrete_input_init可以初始化离散输入设置并绑定相关参数。
+
+hal_di_Outputs_wrapper用于实现从编号start_idx到start_idx+u_width-1的通道读取离散量输入值。
+ErrorCode返回值非零表示错误，一般是对应通道不存在。
+
+### hal_ao模块实现
+
+hal_ao模块的功能应在hal_ao_wrapper.c中实现。
+hal_ao_Start_wrapper用于调用单例初始化函数analog_output_init。
+analog_output_init可以初始化模拟量输出设置并绑定相关参数。
+
+hal_ao_Outputs_wrapper用于实现输出模拟指令到编号从start_idx到start_idx+u_width-1的DAC通道。
+ErrorCode返回值非零表示错误，一般是对应通道不存在，或者超量程。
+
+### hal_ai模块实现
+
+hal_ai_in模块的功能应在hal_ai_wrapper.c中实现。
+hal_ai_Start_wrapper用于调用单例初始化函数analog_input_init。
+analog_input_init可以初始化ADC输入设置并绑定相关参数。
+
+hal_ai_Outputs_wrapper用于实现从编号start_idx到start_idx+u_width-1的通道读取ADC采样值。
+ErrorCode返回值非零表示错误，一般是对应通道不存在。
+
+### hal_sbus_in
+
+hal_sbus_in模块的功能应在hal_sbus_in_wrapper.c中实现。
+hal_sbus_in_Start_wrapper用于调用单例初始化函数sbus_input_init。
+sbus_input_init可以初始化sbus输入设置并绑定相关参数。
+
+hal_sbus_in_Outputs_wrapper用于实现根据id编号读取sbus信号。信号包括18通道的输入（uint16）、seq循环计数（收到新包就加一）、ErrorCode返回值非零表示未收到遥控器信号（对应遥控器接收机红灯）。
+
+### hal_led_set
+
+hal_led_set是一个function-call模块，用于StateFlow设置三色LED，
+其功能应在hal_led_set_wrapper.c中实现。
+hal_led_set_Start_wrapper用于调用单例初始化函数led_set_init。
+led_set_init根据设备号id初始化相应设备并绑定参数。
+
+hal_led_set_Outputs_wrapper用于根据id设置LED颜色。ErrorCode返回值非零表示错误，一般是对应设备不存在。
+
+对于带pwm控制的三色LED，rgb通道取值范围在0-255；如果只是三色，则取值零与非零；如果是单色，则是any(rgb)。
+
+LED长短闪烁颜色等功能可以在stateflow中实现。
+
+## hal_api_sens库
+
+hal_api_sens.slx实现了对传感器设备(如IMU/INS/Baro/Radar)的抽象。抽象接口有两大类，一般性接口与特化接口。其中一般性接口设计借鉴了simulink中ROS接口设计思路。
+
+### hal_sen_read接口设计与实现
+
+hal_sen_read模块用于根据信号名称获取值。
+信号名称可以从交互界面中的下拉列表中查找。
+而这个列表可以通过*hal_sen_popup_update.m*脚本进行更新。
+信号可以是标量或向量，但当前的限制是类型必须是single。
+
+hal_sen_read模块通过hal_sen_read_wrapper.c文件实现其功能。
+hal_sen_read_Start_wrapper函数用于根据name名称建立关联信号量，并将关联信息储存在模块的pW中。
+
+pW定义 | 类型 | 说明
+------ | --- | -------
+`pw[0]` | int  | 是否关联好。0-未关联；1-关联。
+`pw[1]` | PROP_TYPE  | 信号量类型
+`pw[2]` | int  | 信号量长度。
+`pw[3]` | void*  | 指向信号对应的地址指针或函数指针
+`pw[4]` | void* | 传给函数指针对应函数第二个自定义参数
+
+PROP_TYPE定义如下。ARRAY表示指向地址，FUNC表示指向函数。
+
+ PROP_TYPE | enum序号
+  --------- | --------
+   PROP_ARRAY_UINT8 | 1
+   PROP_ARRAY_INT8 | 2
+   PROP_ARRAY_UINT16 | 3
+   PROP_ARRAY_INT16 | 4
+   PROP_ARRAY_UINT32 | 5
+   PROP_ARRAY_INT32 | 6
+   PROP_ARRAY_REAL32 | 7
+   PROP_FUNC_UINT8 | 8
+   PROP_FUNC_INT8 | 9
+   PROP_FUNC_UINT16 | 10
+   PROP_FUNC_INT16 | 11
+   PROP_FUNC_UINT32 | 12
+   PROP_FUNC_INT32 | 13
+   PROP_FUNC_REAL32 | 14
+
+`pw[3]`作为函数指针是类似`float (*get_prop_f_func_ptr)(int index, void *paramter)`形式，用于提取第index个信号分量。完整声明如下：
+
+```
+typedef int8_t (*get_prop_b_func_ptr)(int index, void *paramter);
+typedef uint8_t (*get_prop_B_func_ptr)(int index, void *paramter);
+typedef int16_t (*get_prop_h_func_ptr)(int index, void *paramter);
+typedef uint16_t (*get_prop_H_func_ptr)(int index, void *paramter);
+typedef int32_t (*get_prop_i_func_ptr)(int index, void *paramter);
+typedef uint32_t (*get_prop_I_func_ptr)(int index, void *paramter);
+typedef float (*get_prop_f_func_ptr)(int index, void *paramter);
+```
+
+`pw[4]`或者说是`void *paramter`是传入调用函数的自定义参数，可以表示为一个32位数字，也可以是函数、对象的指针。可类似于C++中的this指针使用。
+
+此外，还可以在hal_sen_read_Start_wrapper中注册属性。
+属性与信号都是名称与数值的关联，但用法上有明显的区别：
+
+* 属性表示的是设备的状态，而信号是设备源源不断产生的；
+* 属性是可以读可以写（设置）的，而信号量是只读的（可写的信号量是hal_api_ctrls里的输出模块）；
+* 属性是标量（向量则变成标量组），而信号量可以是向量；
+* 属性量可以是整型或浮点类型（union），而信号量当前只能是浮点类型；
+
+hal_sen_read_Outputs_wrapper函数用于提取信号向量，如果hal_sen_read_Start_wrapper中关联pW成功，则一般无需改动。其实现就是依次从地址或函数调用中提取信号诸元素并返回。
+
+## 测试
+
+工程使用Gitlab-CI实现自动化测试。当前测试项目`test/scriptTest.m`是通过代码生成与编译`hal_template.slx`模型，检查接口设计正确性。

 _______
- Copyright (C) 2020 GONG Zheng(matt@matthewgong.com) http://www.matthewgong.com/
-
-
+ Copyright (C) 2020 GONG Zheng(matt@matthewgong.com) <http://www.matthewgong.com/>