新增了教程和注释以及文档,增加了一键编译并打开ozone调试的脚本

bsp/adc/bsp_adc.md

@@ -1,3 +1,5 @@
 待添加adc的bsp支持,应该提供阻塞/IT/DMA的量测接口
 
-是否需要bsp_adc?由于功能非常简单,似乎可以直接使用HAL的接口,没有必要多此一举进行封装?
+是否需要bsp_adc?由于功能非常简单,似乎可以直接使用HAL的接口,没有必要多此一举进行封装?
+
+回调函数.

bsp/bsp.md

@@ -3,12 +3,9 @@ BSP
 这是BSP层的说明文档。
 
 > TODO:
-> 1. 增加SPI和I2C支持
-> 2. 增加外部中断支持
-> 3. 增加软件中断支持
-> 4. 增加硬件CRC支持
-> 5. 增加USB和虚拟串口支持
+> 1. 增加软件中断支持
+> 2. 增加硬件CRC支持
 
 bsp的功能是提供对片上外设的封装，即单片机芯片内部拥有的功能的封装。在开发板pcb上集成的模块应该放在module层而不是这里。
 
-bsp应该提供几种接口。包括初始化接口，一般命名为`XXXRegister()`；调用此模块实现的必要功能，如通信型外设（CubeMX下的connectivity）提供接收和发送的接口，以及接收完成的数据回调函数。
+bsp应该提供几种接口。包括初始化接口，一般命名为`XXXRegister()`(对于只有一个instance的可以叫`XXXInit()`,但建议统一风格都叫register)；调用此模块实现的必要功能，如通信型外设（CubeMX下的connectivity）提供接收和发送的接口，以及接收完成的数据回调函数。

bsp/bsp_init.c

@@ -11,9 +11,10 @@ void BSPInit()
 {
     DWT_Init(168);
     BSPLogInit();
-    USBInit(); // 务必在进入操作系统之前执行USB初始化
+    USBInit(); // 务必在进入操作系统之前执行USBInit
 
-    // legacy support，待删除,将在实现了led/tempctrl/buzzer的module之后移动到app层
+
+    // legacy support，待删除,将在实现了led/tempctrl/buzzer的module之后移动到app层进行XXXRegister()
     LEDInit();
     IMUTempInit();
     BuzzerInit();

bsp/bsp_legacy_support/legacy.md

@@ -1,3 +1,5 @@
 # legacy bsp
 
-这些bsp实现将在v0.1删除,因为他们实际上都是用pwm实现的,应当放在module层,以彻底隔离bsp和CubeMX的初始化代码.之后在修改CubeMX的初始化配置之后就不再需要修改bsp的内容了,所有的修改都会通过app层的初始化配置`xxx_Init_Config_s`来实现.
+这些bsp实现将在v0.1删除,因为他们实际上都是用pwm实现的,应当放在module层,以彻底隔离bsp和CubeMX的初始化代码.现已提供了bsp_pwm的实现.
+
+之后在修改CubeMX的初始化配置之后就不再需要修改bsp的内容了,所有的修改都会通过app层的初始化配置`xxx_Init_Config_s`来实现.

bsp/can/bsp_can.c

@@ -140,7 +140,7 @@ static void CANFIFOxCallback(CAN_HandleTypeDef *_hcan, uint32_t fifox)
 
 /**
  * @brief 注意,STM32的两个CAN设备共享两个FIFO
- * 下面两个函数是HAL库中的回调函数,他们声明为__weak,这里对他们进行重载(重写)
+ * 下面两个函数是HAL库中的回调函数,他们被HAL声明为__weak,这里对他们进行重载(重写)
  * 当FIFO0或FIFO1溢出时会调用这两个函数
  */
 // 下面的函数会调用CANFIFOxCallback()来进一步处理来自特定CAN设备的消息

bsp/can/bsp_can.h

@@ -8,6 +8,7 @@
 #define CAN_MX_REGISTER_CNT 16     // 这个数量取决于CAN总线的负载
 #define MX_CAN_FILTER_CNT (2 * 14) // 最多可以使用的CAN过滤器数量,目前远不会用到这么多
 #define DEVICE_CAN_CNT 2           // 根据板子设定,F407IG有CAN1,CAN2,因此为2;F334只有一个,则设为1
+// 如果只有1个CAN,还需要把bsp_can.c中所有的hcan2变量改为hcan1(别担心,主要是总线和FIFO的负载均衡,不影响功能)
 
 /* can instance typedef, every module registered to CAN should have this variable */
 #pragma pack(1)

bsp/dwt/bsp_dwt.c

@@ -6,18 +6,15 @@
  * @version V1.1.0
  * @date    2022/3/8
  * @brief
- ******************************************************************************
- * @attention
- *
- ******************************************************************************
  */
+
 #include "bsp_dwt.h"
 
-DWT_Time_t SysTime;
+static DWT_Time_t SysTime;
 static uint32_t CPU_FREQ_Hz, CPU_FREQ_Hz_ms, CPU_FREQ_Hz_us;
 static uint32_t CYCCNT_RountCount;
 static uint32_t CYCCNT_LAST;
-uint64_t CYCCNT64;
+static uint64_t CYCCNT64;
 
 /**
  * @brief 私有函数,用于检查DWT CYCCNT寄存器是否溢出,并更新CYCCNT_RountCount

bsp/dwt/bsp_dwt.h

@@ -23,7 +23,6 @@ typedef struct
     uint16_t us;
 } DWT_Time_t;
 
-extern DWT_Time_t SysTime;
 
 /**
  * @brief 初始化DWT,传入参数为CPU频率,单位MHz

bsp/dwt/bsp_dwt.md

@@ -1,3 +1,3 @@
 # bsp_dwt
 
-DWT是stm32内部的一个"隐藏资源",他的用途是给下载器提供准确的定时,从而为调试信息加上时间戳.
+DWT是stm32内部的一个"隐藏资源",他的用途是给下载器提供准确的定时,从而为调试信息加上时间戳.并在固定的时间间隔将调试数据发送到你的xxlink上.

bsp/gpio/bsp_gpio.md

@@ -6,9 +6,11 @@
 ![img](../../assets/00937839b59a4c039ee8ecb8a5136e3c.png)
 
 
+
 使用示例
 
 ```c
+//在app层只需要设置前三个,callback由module自动设置
 
 GPIO_Init_Config_s gpio_init = {
     .exti_mode = GPIO_EXTI_MODE_FALLING, // 注意和CUBEMX的配置一致
@@ -19,4 +21,5 @@ GPIO_Init_Config_s gpio_init = {
 
 GPIOInstance* test_example = GPIORegister(&gpio_init);
 GPIOSet(test_example);
+// GPIOxxx(test_exmaple, ...);
 ```

bsp/iic/bsp_iic.c

@@ -70,7 +70,7 @@ void IICReceive(IICInstance *iic, uint8_t *data, uint16_t size, IIC_Seq_Mode_e s
 {
     if (seq_mode != IIC_RELEASE && seq_mode != IIC_HOLD_ON)
         while (1)
-            ; // 未知传输模式, 程序停止
+            ; // 未知传输模式, 程序停止,请检查指针越界
 
     // 初始化接收缓冲区地址以及接受长度, 用于中断回调函数
     iic->rx_buffer = data;
@@ -140,7 +140,7 @@ void HAL_I2C_MasterRxCpltCallback(I2C_HandleTypeDef *hi2c)
 }
 
 /**
- * @brief 仅做形式上的封装,仍然使用HAL_I2C_MasterRxCpltCallback
+ * @brief 内存访问回调函数,仅做形式上的封装,仍然使用HAL_I2C_MasterRxCpltCallback
  *
  * @param hi2c handle
  */

bsp/iic/bsp_iic.md

@@ -4,4 +4,7 @@
 
 https://blog.csdn.net/NeoZng/article/details/128496694
 
-https://blog.csdn.net/NeoZng/article/details/128486366
+https://blog.csdn.net/NeoZng/article/details/128486366
+
+
+使用序列通信则在单次通信后不会释放总线,继续占用直到调用传输函数时传入`IIC_RELEASE`参数. 这个功能只在一条总线上挂载多个主机的时候有用.

bsp/pwm/bsp_pwm.c

@@ -6,6 +6,11 @@
 static uint8_t idx;
 static PWMInstance *pwm_instance[PWM_DEVICE_CNT] = {NULL}; // 所有的pwm instance保存于此,用于callback时判断中断来源
 
+/**
+ * @brief pwm dma传输完成回调函数
+ * 
+ * @param htim 发生中断的定时器句柄
+ */
 void HAL_TIM_PWM_PulseFinishedCallback(TIM_HandleTypeDef *htim)
 {
     for (uint8_t i = 0; i < idx; i++)

bsp/pwm/bsp_pwm.h

@@ -1,3 +1,15 @@
+/**
+ * @file bsp_pwm.h
+ * @author your name (you@domain.com)
+ * @brief 
+ * @version 0.1
+ * @date 2023-02-14
+ * @todo 目前的实现有比较大的问题,是否允许module修改tim的分频器和自动重装载寄存器?
+ * 
+ * @copyright Copyright (c) 2023
+ * 
+ */
+
 #ifndef BSP_PWM_H
 #define BSP_PWM_H
 
@@ -52,7 +64,8 @@ void PWMStart(PWMInstance *pwm);
  */
 void PWMStop(PWMInstance *pwm);
 
-// @todo 这三个函数还需要进一步封装,协调好三者之间的关系
+
+// @todo 这三个函数还需要进一步封装,务必协调好三者之间的关系
 /**
  * @brief 设置pwm脉宽
  *

bsp/spi/bsp_spi.h

@@ -32,6 +32,7 @@ typedef struct spi_ins_temp
 /* 接收回调函数定义,包含SPI的module按照此格式构建回调函数 */
 typedef void (*spi_rx_callback)(SPIInstance *);
 
+// @todo: 这里可以将GPIO_TypeDef *GPIO_cs; uint16_t cs_pin合并为bsp_gpio以简化代码实现
 /* SPI初始化配置,其实基本和SPIIstance一模一样,为了代码风格统一因此再次定义 */
 typedef struct
 {

bsp/usart/bsp_usart.h

@@ -17,7 +17,8 @@ typedef enum
     USART_TRANSFER_RX,
 } USART_TRANSFER_MODE;
 
-// 串口实例结构体,每个module都要包含一个实例
+// 串口实例结构体,每个module都要包含一个实例.
+// 由于串口是独占的点对点通信,所以不需要考虑多个module同时使用一个串口的情况,因此不用加入id;当然也可以选择加入,这样在bsp层可以访问到module的其他信息
 typedef struct
 {
     uint8_t recv_buff[USART_RXBUFF_LIMIT]; // 预先定义的最大buff大小,如果太小请修改USART_RXBUFF_LIMIT
@@ -44,7 +45,9 @@ USARTInstance *USARTRegister(USART_Init_Config_s *init_config);
 /**
  * @brief 通过调用该函数可以发送一帧数据,需要传入一个usart实例,发送buff以及这一帧的长度
  *        当前默认为DMA发送,后续会增加中断发送和阻塞发送模式的选择
- *
+ * @todo 目前只支持DMA发送,后续会增加中断发送和阻塞发送模式的选择
+ *       在短时间内连续调用此接口会导致上一次的发送未完成而新的发送取消,后续会增加一个发送状态的判断以及消息队列以解决这个问题
+ * 
  * @param _instance 串口实例
  * @param send_buf 待发送数据的buffer
  * @param send_size how many bytes to send

bsp/usart/bsp_usart.md

@@ -2,7 +2,8 @@
 
 <p align='right'>neozng1@hnu.edu.cn</p>
 
-> TODO:为初始化定义一个结构体`usart_init_config`用于保存初始化所需的参数从而避免单独赋值，使得整体风格统一。
+> TODO: 增加发送队列以解决短时间内调用`USARTSend()`发生丢包的问题,并提供阻塞和IT模式以供选择
+> 可以直接在发送函数的参数列表添加发送模式选择,或增加instance成员变量,并提供设置模式接口,两者各有优劣
 
 ## 使用说明
 

bsp/usb/bsp_usb.h

@@ -3,7 +3,7 @@
  * @author your name (you@domain.com)
  * @brief 提供对usb vpc(virtal com port)的操作接口,hid和msf考虑后续添加
  * @todo 与usart的接口统一完成兼容
- * @attention 这一版修改了usbd_cdc_if.c中的CDC_Receive_FS函数,cube生成后会被覆盖.后续需要由usbcdciftemplate创建一套自己的模板
+ * @attention 这一版usb修改了usbd_cdc_if.c中的CDC_Receive_FS函数,若使用cube生成后会被覆盖.后续需要由usbcdciftemplate创建一套自己的模板
  * @version 0.1
  * @date 2023-02-09
  *