[feat] update peripheral api and demo

docs/development_guide/source/api_reference/api_adc.rst

@@ -0,0 +1,15 @@
+ADC 设备
+=========================
+
+简介
+------------------------
+
+
+ADC 设备结构体定义
+------------------------
+
+ADC 设备参数配置表
+------------------------
+
+ADC 设备接口
+------------------------

docs/development_guide/source/api_reference/api_clock.rst

@@ -0,0 +1,60 @@
+时钟树
+=========================
+
+简介
+------------------------
+
+博流系列芯片拥有丰富的时钟源选择，为方便用户配置，提供了时钟树配置表，不需要用户手动调用时钟设置接口，用户只需要关心最终的系统时钟和外设时钟频率即可。时钟配置表位于 ``bsp/board/xxx_board`` 目录下 ``xxx_clock_config.h`` 文件。
+
+
+时钟频率获取接口
+------------------------
+
+**system_clock_get**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``system_clock_get`` 用来获取系统时钟频率。
+
+.. code-block:: C
+
+    uint32_t system_clock_get(enum system_clock_type type);
+
+- type 获取的系统时钟频率类型
+
+``type`` 提供以下几种类型
+
+.. code-block:: C
+
+    enum system_clock_type
+    {
+        SYSTEM_CLOCK_ROOT_CLOCK = 0,
+        SYSTEM_CLOCK_FCLK,
+        SYSTEM_CLOCK_BCLK,
+        SYSTEM_CLOCK_XCLK,
+    };
+
+
+**peripheral_clock_get**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``peripheral_clock_get`` 用来获取外设时钟频率。
+
+.. code-block:: C
+
+    uint32_t peripheral_clock_get(enum peripheral_clock_type type);
+
+- type 获取的外设时钟频率类型
+
+``type`` 提供以下几种类型
+    
+.. code-block:: C
+    
+    enum peripheral_clock_type
+    {
+        PERIPHERAL_CLOCK_UART = 0,
+        PERIPHERAL_CLOCK_SPI,
+        PERIPHERAL_CLOCK_I2C,
+        PERIPHERAL_CLOCK_ADC,
+        PERIPHERAL_CLOCK_DAC,
+        PERIPHERAL_CLOCK_I2S,
+    };

docs/development_guide/source/api_reference/api_dac.rst

@@ -0,0 +1,15 @@
+DAC 设备
+=========================
+
+简介
+------------------------
+
+
+DAC 设备结构体定义
+------------------------
+
+DAC 设备参数配置表
+------------------------
+
+DAC 设备接口
+------------------------

docs/development_guide/source/api_reference/api_dma.rst

@@ -0,0 +1,424 @@
+DMA 设备
+=========================
+
+简介
+------------------------
+
+DMA(Direct Memory Access) 是一种内存存取技术，可以独立地直接读写系统内存，而不需处理器介入处理。在同等
+程度的处理器负担下，DMA 是一种快速的数据传送方式。博流系列 MCU 中 DMA 设备具有以下特性：
+
+- 控制器有 8 组独立专用通道
+- 四种传输方向：内存至内存、内存至外设、外设至内存、外设到外设
+- LLI 链表工作模式。
+
+DMA 设备结构体定义
+------------------------
+
+.. code-block:: C
+
+    typedef struct dma_device
+    {
+        struct device parent;
+        uint8_t id;
+        uint8_t ch;
+        uint8_t direction;
+        uint8_t transfer_mode;
+        uint32_t src_req;
+        uint32_t dst_req;
+        uint8_t src_burst_size;
+        uint8_t dst_burst_size;
+        uint8_t src_width;
+        uint8_t dst_width;
+        dma_lli_ctrl_t *lli_cfg;    
+    } dma_device_t;
+
+- parent        继承父类属性
+- id            DMA id号，默认0，当前只有一个DMA
+- ch            通道号
+- direction     传输方向
+- transfer_mode 传输模式
+- src_req       源请求
+- dst_req       目标请求
+- src_burst_size 源突发字节数
+- dst_burst_size 目标突发字节数
+- src_width     源传输位宽
+- dst_width     目标传输位宽
+- lli_cfg       用来存储dma通道的一些信息，用户不用管
+
+``direction`` 提供以下类型
+
+.. code-block:: C
+
+    typedef enum {
+        DMA_MEMORY_TO_MEMORY = 0,                        /*!< DMA transfer tyep:memory to memory */
+        DMA_MEMORY_TO_PERIPH,                            /*!< DMA transfer tyep:memory to peripheral */
+        DMA_PERIPH_TO_MEMORY,                            /*!< DMA transfer tyep:peripheral to memory */
+        DMA_PERIPH_TO_PERIPH,                            /*!< DMA transfer tyep:peripheral to peripheral */
+    }dma_transfer_dir_type;
+
+``transfer_mode`` 提供以下类型
+
+.. code-block:: C
+
+    #define DMA_LLI_ONCE_MODE     0 
+    #define DMA_LLI_CYCLE_MODE    1
+
+``src_req`` 提供以下类型
+
+.. code-block:: C
+
+    #define DMA_REQUEST_NONE        0x00000000 /*!< DMA request peripheral:None */
+    #define DMA_REQUEST_UART0_RX    0x00000000 /*!< DMA request peripheral:UART0 RX */
+    #define DMA_REQUEST_UART0_TX    0x00000001 /*!< DMA request peripheral:UART0 TX */
+    #define DMA_REQUEST_UART1_RX    0x00000002 /*!< DMA request peripheral:UART1 RX */
+    #define DMA_REQUEST_UART1_TX    0x00000003 /*!< DMA request peripheral:UART1 TX */
+    #define DMA_REQUEST_I2C0_RX     0x00000006 /*!< DMA request peripheral:I2C RX */
+    #define DMA_REQUEST_I2C0_TX     0x00000007 /*!< DMA request peripheral:I2C TX */
+    #define DMA_REQUEST_SPI0_RX     0x0000000A /*!< DMA request peripheral:SPI RX */
+    #define DMA_REQUEST_SPI0_TX     0x0000000B /*!< DMA request peripheral:SPI TX */
+    #define DMA_REQUEST_I2S_RX      0x00000014 /*!< DMA request peripheral:I2S RX */ 
+    #define DMA_REQUEST_I2S_TX      0x00000015 /*!< DMA request peripheral:I2S TX */ 
+    #define DMA_REQUEST_ADC0        0x00000016 /*!< DMA request peripheral:ADC0 */
+    #define DMA_REQUEST_DAC0        0x00000017 /*!< DMA request peripheral:DAC0 */
+    #define DMA_REQUEST_USB_EP0     0x00000018 /*!< DMA request peripheral:USB EP0*/
+    #define DMA_REQUEST_USB_EP1     0x00000019 /*!< DMA request peripheral:USB EP1*/
+    #define DMA_REQUEST_USB_EP2     0x0000001A /*!< DMA request peripheral:USB EP2*/
+    #define DMA_REQUEST_USB_EP3     0x0000001B /*!< DMA request peripheral:USB EP3*/
+    #define DMA_REQUEST_USB_EP4     0x0000001C /*!< DMA request peripheral:USB EP4*/
+    #define DMA_REQUEST_USB_EP5     0x0000001D /*!< DMA request peripheral:USB EP5*/
+    #define DMA_REQUEST_USB_EP6     0x0000001E /*!< DMA request peripheral:USB EP6*/
+    #define DMA_REQUEST_USB_EP7     0x0000001F /*!< DMA request peripheral:USB EP7 */
+
+``dst_req`` 提供以下类型
+
+.. code-block:: C
+
+    #define DMA_REQUEST_NONE        0x00000000 /*!< DMA request peripheral:None */
+    #define DMA_REQUEST_UART0_RX    0x00000000 /*!< DMA request peripheral:UART0 RX */
+    #define DMA_REQUEST_UART0_TX    0x00000001 /*!< DMA request peripheral:UART0 TX */
+    #define DMA_REQUEST_UART1_RX    0x00000002 /*!< DMA request peripheral:UART1 RX */
+    #define DMA_REQUEST_UART1_TX    0x00000003 /*!< DMA request peripheral:UART1 TX */
+    #define DMA_REQUEST_I2C0_RX     0x00000006 /*!< DMA request peripheral:I2C RX */
+    #define DMA_REQUEST_I2C0_TX     0x00000007 /*!< DMA request peripheral:I2C TX */
+    #define DMA_REQUEST_SPI0_RX     0x0000000A /*!< DMA request peripheral:SPI RX */
+    #define DMA_REQUEST_SPI0_TX     0x0000000B /*!< DMA request peripheral:SPI TX */
+    #define DMA_REQUEST_I2S_RX      0x00000014 /*!< DMA request peripheral:I2S RX */ 
+    #define DMA_REQUEST_I2S_TX      0x00000015 /*!< DMA request peripheral:I2S TX */ 
+    #define DMA_REQUEST_ADC0        0x00000016 /*!< DMA request peripheral:ADC0 */
+    #define DMA_REQUEST_DAC0        0x00000017 /*!< DMA request peripheral:DAC0 */
+    #define DMA_REQUEST_USB_EP0     0x00000018 /*!< DMA request peripheral:USB EP0*/
+    #define DMA_REQUEST_USB_EP1     0x00000019 /*!< DMA request peripheral:USB EP1*/
+    #define DMA_REQUEST_USB_EP2     0x0000001A /*!< DMA request peripheral:USB EP2*/
+    #define DMA_REQUEST_USB_EP3     0x0000001B /*!< DMA request peripheral:USB EP3*/
+    #define DMA_REQUEST_USB_EP4     0x0000001C /*!< DMA request peripheral:USB EP4*/
+    #define DMA_REQUEST_USB_EP5     0x0000001D /*!< DMA request peripheral:USB EP5*/
+    #define DMA_REQUEST_USB_EP6     0x0000001E /*!< DMA request peripheral:USB EP6*/
+    #define DMA_REQUEST_USB_EP7     0x0000001F /*!< DMA request peripheral:USB EP7 */
+
+``src_burst_size`` 提供以下类型
+
+.. code-block:: C
+
+    #define DMA_BURST_1BYTE     0
+    #define DMA_BURST_4BYTE     1
+    #define DMA_BURST_8BYTE     2
+    #define DMA_BURST_16BYTE    3
+
+``dst_burst_size`` 提供以下类型
+
+.. code-block:: C
+
+    #define DMA_BURST_1BYTE     0
+    #define DMA_BURST_4BYTE     1
+    #define DMA_BURST_8BYTE     2
+    #define DMA_BURST_16BYTE    3
+
+``src_width`` 提供以下类型
+
+.. code-block:: C
+
+    #define DMA_TRANSFER_WIDTH_8BIT  0
+    #define DMA_TRANSFER_WIDTH_16BIT 1
+    #define DMA_TRANSFER_WIDTH_32BIT 2
+
+``dst_width`` 提供以下类型
+
+.. code-block:: C
+
+    #define DMA_TRANSFER_WIDTH_8BIT  0
+    #define DMA_TRANSFER_WIDTH_16BIT 1
+    #define DMA_TRANSFER_WIDTH_32BIT 2
+
+DMA 设备参数配置表
+------------------------
+
+每一个 DMA 设备都有一个参数配置宏,宏定义位于 ``bsp/board/xxx`` 目录下 ``peripheral_config.h`` 文件,变量定义位于 ``hal_dma.c`` 中，因此无需用户自己定义变量。当用户打开对应设备的宏，该设备的配置才生效。例如打开宏 ``BSP_USING_DMA0_CH0`` ，``DMA0_CH0_CONFIG`` 即生效，同时DMA 通道0设备就可以进行注册和使用了。
+
+.. code-block:: C
+
+    /*参数配置宏*/
+    #if defined(BSP_USING_DMA0_CH0)
+    #ifndef DMA0_CH0_CONFIG
+    #define DMA0_CH0_CONFIG \
+    {   \
+     .id = 0, \
+     .ch = 0,\
+     .direction = DMA_MEMORY_TO_MEMORY,\
+     .transfer_mode = DMA_LLI_ONCE_MODE, \
+     .src_req = DMA_REQUEST_NONE, \
+     .dst_req = DMA_REQUEST_NONE, \
+     .src_width = DMA_TRANSFER_WIDTH_32BIT , \
+     .dst_width = DMA_TRANSFER_WIDTH_32BIT , \
+    }
+    #endif
+    #endif
+    
+
+    /*变量定义*/
+    static dma_device_t dmax_device[DMA_MAX_INDEX] =
+    {
+    #ifdef BSP_USING_DMA0_CH0
+        DMA0_CH0_CONFIG,
+    #endif
+    #ifdef BSP_USING_DMA0_CH1
+        DMA0_CH1_CONFIG,
+    #endif
+    #ifdef BSP_USING_DMA0_CH2
+        DMA0_CH2_CONFIG,
+    #endif
+    #ifdef BSP_USING_DMA0_CH3
+        DMA0_CH3_CONFIG,
+    #endif
+    #ifdef BSP_USING_DMA0_CH4
+        DMA0_CH4_CONFIG,
+    #endif
+    #ifdef BSP_USING_DMA0_CH5
+        DMA0_CH5_CONFIG,
+    #endif
+    #ifdef BSP_USING_DMA0_CH6
+        DMA0_CH6_CONFIG,
+    #endif
+    #ifdef BSP_USING_DMA0_CH7
+        DMA0_CH7_CONFIG,
+    #endif
+    };
+
+.. note:: 上述配置可以通过 ``DMA_DEV(dev)->xxx`` 进行修改，只能在调用 ``device_open`` 之前使用。
+
+DMA 设备接口
+------------------------
+
+DMA 设备接口全部遵循标准设备驱动管理层提供的接口。并且为了方便用户调用，将某些标准接口使用宏来重定义。
+
+**dma_register**
+^^^^^^^^^^^^^^^^^^^^^^^^
+    
+``dma_register`` 用来注册一个 DMA 设备的一个通道，在注册之前需要打开对应 DMA 设备的通道宏定义。例如定义宏 ``BSP_USING_DMA_CH0`` 方可使用 ``DMA`` 设备的 0 通道,注册完成以后才可以使用其他接口，如果没有定义宏，则无法使用 ``DMA`` 设备的 0 通道。
+
+.. code-block:: C
+    
+    int dma_register(enum dma_index_type index, const char *name, uint16_t flag);
+
+- index 要注册的设备索引
+- name 为注册的设备命名
+- flag 默认可读可写属性
+
+``index`` 用来选择 DMA 设备某个通道的配置，一个 index 对应一个 DMA 设备的一个通道配置，比如 ``DMA_CH0_INDEX`` 对应 DMA 通道0 配置，``index`` 有如下可选类型
+
+.. code-block:: C
+    
+    enum dma_index_type
+    {
+    #ifdef BSP_USING_DMA0_CH0
+        DMA0_CH0_INDEX,
+    #endif
+    #ifdef BSP_USING_DMA0_CH1
+        DMA0_CH1_INDEX,
+    #endif
+    #ifdef BSP_USING_DMA0_CH2
+        DMA0_CH2_INDEX,
+    #endif
+    #ifdef BSP_USING_DMA0_CH3
+        DMA0_CH3_INDEX,
+    #endif
+    #ifdef BSP_USING_DMA0_CH4
+        DMA0_CH4_INDEX,
+    #endif
+    #ifdef BSP_USING_DMA0_CH5
+        DMA0_CH5_INDEX,
+    #endif
+    #ifdef BSP_USING_DMA0_CH6
+        DMA0_CH6_INDEX,
+    #endif
+    #ifdef BSP_USING_DMA0_CH7
+        DMA0_CH7_INDEX,
+    #endif
+        DMA_MAX_INDEX
+    };
+
+**device_open**
+^^^^^^^^^^^^^^^^
+
+``device_open`` 用于设备的打开，``oflag`` 表示以何种方式打开。
+
+.. code-block:: C
+
+    int device_open(struct device *dev, uint16_t oflag);   
+
+- dev 设备句柄
+- oflag 设备的打开方式
+- return 错误码，0 表示打开成功，其他表示错误
+
+``oflag`` 可以写入以下参数：
+
+.. code-block:: C
+
+    #define DEVICE_OFLAG_STREAM_TX  0x001 /* 设备以轮训发送模式打开 */
+    #define DEVICE_OFLAG_STREAM_RX  0x002 /* 设备以轮训接收模式打开 */
+    #define DEVICE_OFLAG_INT_TX     0x004 /* 设备以中断发送模式打开 */
+    #define DEVICE_OFLAG_INT_RX     0x008 /* 设备以中断接收模式打开 */
+    #define DEVICE_OFLAG_DMA_TX     0x010 /* 设备以 DMA 发送模式打开 */
+    #define DEVICE_OFLAG_DMA_RX     0x020 /* 设备以 DMA 接收模式打开 */
+
+**device_close**
+^^^^^^^^^^^^^^^^
+
+``device_close`` 用于设备的关闭。
+
+.. code-block:: C
+
+    int device_close(struct device *dev);   
+
+- dev 设备句柄
+- return 错误码，0 表示关闭成功，其他表示错误
+    
+**device_control**
+^^^^^^^^^^^^^^^^^^^
+
+``device_control`` 用于根据命令对设备进行控制和参数的修改。
+
+.. code-block:: C
+
+    int device_control(struct device *dev, int cmd, void *args);   
+
+- dev 设备句柄
+- cmd 设备控制命令
+- args 控制参数
+- return 不同的控制命令返回的意义不同。
+
+DMA 设备除了标准的控制命令，还具有自己特殊的控制命令。
+
+.. code-block:: C
+
+    #define DMA_CHANNEL_GET_STATUS  0x10
+    #define DMA_CHANNEL_START       0x11
+    #define DMA_CHANNEL_STOP        0x12
+    #define DMA_CHANNEL_UPDATE      0x13
+
+``args`` 根据不同的 ``cmd`` 传入不同，具体如下：
+
++---------------------------+-------------+------------------------+
+|cmd                        |args         |description             |
++===========================+=============+========================+
+|DEVICE_CTRL_SET_INT        |NULL         |开启dma传输完成中断     |
++---------------------------+-------------+------------------------+
+|DEVICE_CTRL_CLR_INT        |NULL         |关闭dma传输完成中断     |
++---------------------------+-------------+------------------------+
+|DMA_CHANNEL_GET_STATUS     |NULL         |获取dma通道完成状态     |
++---------------------------+-------------+------------------------+
+|DMA_CHANNEL_START          |NULL         |开启dma通道             |
++---------------------------+-------------+------------------------+
+|DMA_CHANNEL_STOP           |NULL         |关闭dma通道             |
++---------------------------+-------------+------------------------+
+|DMA_CHANNEL_UPDATE         |uint32_t     |更新dma传输配置         |
++---------------------------+-------------+------------------------+
+
+**device_set_callback**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``device_set_callback`` 用于注册一个DMA通道中断回调函数。
+
+.. code-block:: C
+
+    int device_set_callback(struct device *dev, void (*callback)(struct device *dev, void *args, uint32_t size, uint32_t event));
+
+- dev 设备句柄
+- callback 要注册的中断回调函数
+
+    - dev 设备句柄
+    - args 无用
+    - size 无用
+    - event 中断事件类型    
+
+DMA 设备 ``event`` 类型如下
+
+.. code-block:: C
+
+    enum dma_event_type
+    {
+        DMA_EVENT_COMPLETE,
+    };
+
+
+**dma_channel_start**
+^^^^^^^^^^^^^^^^^^^^^^
+
+``dma_channel_start`` 用于开启DMA通道。实际是调用 ``device_control`` ，其中 ``cmd`` 为 ``DMA_CHANNEL_START``。
+
+.. code-block:: C
+
+    dma_channel_start(dev)
+
+- dev 需要开启的pwm通道句柄
+
+
+**dma_channel_stop**
+^^^^^^^^^^^^^^^^^^^^^^
+
+``dma_channel_stop`` 用于关闭DMA通道。实际是调用 ``device_control`` ，其中 ``cmd`` 为 ``DMA_CHANNEL_STOP``。
+
+.. code-block:: C
+
+    dma_channel_stop(dev)
+
+- dev 需要关闭的pwm通道句柄
+
+
+**dma_channel_update**
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``dma_channel_update`` 用于更新DMA配置。实际是调用 ``device_control`` ，其中 ``cmd`` 为 ``DMA_CHANNEL_UPDATE``。
+
+.. code-block:: C
+
+    dma_channel_update(dev,list)
+
+- dev 需要更新的pwm通道句柄
+- list dma_lli_ctrl_t句柄
+
+
+**dma_channel_check_busy**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``dma_channel_check_busy`` 用于查询当前使用的DMA通道是否传输完成。实际是调用 ``device_control`` ，其中 ``cmd`` 为 ``DMA_CHANNEL_GET_STATUS``。
+
+.. code-block:: C
+
+    dma_channel_check_busy(dev)
+
+- dev 需要查询的DMA通道句柄
+- 返回当前DMA状态，0为传输完成，1为未传输完成
+
+**dma_reload**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``dma_reload`` 用于更新DMA某个通道的配置，相比于 ``dma_channel_update`` ,该函数无需用户传递很多参数，只需要填入源地址和目标地址，以及长度，内部会自己计算后再进行配置。此函数调用后，DMA通道是没有开启的，需要手动调用 ``dma_channel_start`` 函数。
+
+.. code-block:: C
+
+    int dma_reload(struct device *dev, uint32_t src_addr, uint32_t dst_addr, uint32_t transfer_size);
+
+- dev 需要查询的DMA通道句柄
+- src_addr 传输源地址
+- dst_addr 传输目标地址
+- transfer_size 传输字节总长度，如果传输的位数是16位、32位，这里需要进行转换成字节长度。

docs/development_guide/source/api_reference/api_gpio.rst

@@ -0,0 +1,114 @@
+GPIO 设备
+=========================
+
+简介
+------------------------
+
+GPIO 全称 General Purpose Input Output（通用输入 / 输出），博流系列芯片的 GPIO 外设主要有以下功能。
+
+- 普通输入输出带上下拉
+- 复用功能带上下拉
+- 模拟功能
+- 外部中断（上升沿、下降沿、高电平、低电平）
+- 硬件消抖
+- 驱动能力控制
+
+bl mcu sdk 的引脚配置方式分为两种。
+
+- GPIO 复用功能通过专门的 **pinmux table** ，用户只需要修改 table 中的相关引脚的功能，程序会自动配置这些引脚。**pinmux table** 位于 ``bsp/board/xxx_board`` 目录下 ``pinmux_config.h`` 文件。
+- 通过标准的 GPIO 设备接口配置引脚，缺点是只能配置普通的输入输出和中断功能，复用功能建议还是使用 table 进行配置。
+
+GPIO 设备接口
+------------------------
+
+**gpio_set_mode**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``gpio_set_mode`` 用来配置 gpio 的模式。
+
+.. code-block:: C
+    
+    void gpio_set_mode(uint32_t pin, uint32_t mode);
+
+- pin 要配置的引脚
+- mode 要配置的引脚功能
+
+``mode`` 提供以下几种类型
+
+.. code-block:: C
+    
+    #define GPIO_OUTPUT_MODE                        0
+    #define GPIO_OUTPUT_PP_MODE                     1
+    #define GPIO_OUTPUT_PD_MODE                     2
+    #define GPIO_INPUT_MODE                         3
+    #define GPIO_INPUT_PP_MODE                      4
+    #define GPIO_INPUT_PD_MODE                      5
+    #define GPIO_ASYNC_RISING_TRIGER_INT_MODE       6
+    #define GPIO_ASYNC_FALLING_TRIGER_INT_MODE      7
+    #define GPIO_ASYNC_HIGH_LEVEL_INT_MODE          8
+    #define GPIO_ASYNC_LOW_LEVEL_INT_MODE           9
+    #define GPIO_SYNC_RISING_TRIGER_INT_MODE        10
+    #define GPIO_SYNC_FALLING_TRIGER_INT_MODE       11
+    #define GPIO_SYNC_HIGH_LEVEL_INT_MODE           12
+    #define GPIO_SYNC_LOW_LEVEL_INT_MODE            13
+
+**gpio_write**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``gpio_write`` 设置引脚电平
+
+.. code-block:: C
+    
+    void gpio_write(uint32_t pin, uint32_t value);
+
+
+- pin 要设置的引脚
+- value 要设置的电平
+  
+**gpio_toggle**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``gpio_toggle`` 翻转引脚电平
+
+.. code-block:: C
+    
+    void gpio_toggle(uint32_t pin);
+
+- pin 要翻转的引脚
+
+**gpio_read**
+^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+``gpio_read`` 读取引脚电平
+
+.. code-block:: C
+    
+    int  gpio_read(uint32_t pin);
+
+
+- pin 要读取电平的引脚
+- return 0 为低电平，1 为高电平
+
+**gpio_attach_irq**
+^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+``gpio_attach_irq`` 为中断引脚附加中断回调函数
+
+.. code-block:: C
+    
+    void gpio_attach_irq(uint32_t pin, void (*cbfun)(uint32_t pin));
+
+- pin 要附加中断回调的引脚
+- cbfun 要注册的中断回调函数
+
+**gpio_irq_enable**
+^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+``gpio_irq_enable`` 开启gpio某个引脚的中断
+
+.. code-block:: C
+    
+    void gpio_irq_enable(uint32_t pin,uint8_t enabled);
+
+- pin 要开启或者关闭中断的引脚
+- enabled 0 为关闭中断，1 为打开中断

docs/development_guide/source/api_reference/api_i2c.rst

@@ -0,0 +1,164 @@
+I2C 设备
+=========================
+
+简介
+------------------------
+
+I2C (Inter-Intergrated Circuit) 是一种串行通讯总线，使用多主从架构，用来连接低速外围装置。每个器件都有一个唯
+一的地址识别，并且都可以作为一个发送器或接收器。每个连接到总线的器件都可以通过唯一的地址和一直存在的主、
+从机关系用软件设置地址，主机可以作为主机发送器或主机接收器。如果有两个或多个主机同时初始化，数据传输可
+以通过冲突检测和仲裁防止数据被破坏。博流系列 MCU 中 I2C 设备具有以下特性：
+
+- 灵活配置的从机地址 ``slaveAddr`` 、寄存器地址 ``subAddr``
+- 可以灵活调整的时钟频率
+- 支持轮询、中断、DMA传输
+
+
+I2C 设备结构体定义
+------------------------
+
+.. code-block:: C
+
+    typedef struct i2c_device
+    {
+        struct device parent;
+        uint8_t id;
+        uint8_t mode;
+        uint32_t phase;
+    } i2c_device_t;
+
+- parent    继承父类属性
+- ch        i2c id，0表示i2c0,1表示i2c1
+- mode      i2c传输模式，0 为使用硬件i2c，1为使用软件i2c，当前软件i2c暂时无效
+- phase 
+- 其他待补充
+
+I2C 设备参数配置表
+------------------------
+
+每一个 I2C 设备都有一个参数配置宏,宏定义位于 ``bsp/board/xxx`` 目录下 ``peripheral_config.h`` 文件,变量定义位于 ``hal_pwm.c`` 中，因此无需用户自己定义变量。当用户打开对应设备的宏，该设备的配置才生效。例如打开宏 ``BSP_USING_I2C0`` ，``I2C0_CONFIG`` 即生效，同时 ``I2C`` 设备就可以进行注册和使用了。
+
+.. code-block:: C
+
+    /*参数配置宏*/
+    #if defined(BSP_USING_I2C0)
+    #ifndef I2C0_CONFIG
+    #define I2C0_CONFIG \
+    {   \
+    .id = 0, \
+    .mode = I2C_HW_MODE,\
+    .phase = 15, \
+    }
+    #endif
+    #endif
+
+    /*变量定义*/
+    static i2c_device_t i2cx_device[I2C_MAX_INDEX] =
+    {
+    #ifdef BSP_USING_I2C0
+        I2C0_CONFIG,
+    #endif
+    };
+
+.. note:: 上述配置可以通过 ``I2C_DEV(dev)->xxx`` 进行修改，只能在调用 ``device_open`` 之前使用。
+
+
+I2C 设备接口
+------------------------
+
+I2C 设备标准接口当前仅使用 ``device_open`` , 并提供标准的数据收发接口。
+
+**i2c_register**
+^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+``i2c_register`` 用来注册一个 I2C 设备，在注册之前需要打开对应 I2C 设备的宏定义。例如定义宏 ``BSP_USING_I2C0`` 方可使用 ``I2C0`` 设备,注册完成以后才可以使用其他接口，如果没有定义宏，则无法使用 ``I2C0`` 设备。
+
+.. code-block:: C
+    
+    int i2c_register(enum i2c_index_type index, const char *name, uint16_t flag);
+
+- index 要注册的设备索引
+- name 为注册的设备命名
+- flag 默认可读可写属性
+
+``index`` 用来选择 I2C 设备,一个 index 对应一个 I2C 设备配置，比如 ``I2C0_INDEX`` 对应 ``I2C0_CONFIG`` 配置，``index`` 有如下可选类型
+
+.. code-block:: C
+    
+    enum i2c_index_type
+    {
+    #ifdef BSP_USING_I2C0
+        I2C0_INDEX,
+    #endif
+        I2C_MAX_INDEX
+    };
+
+**device_open**
+^^^^^^^^^^^^^^^^
+
+``device_open`` 用于设备的打开，``oflag`` 表示以何种方式打开。
+
+.. code-block:: C
+
+    int device_open(struct device *dev, uint16_t oflag);   
+
+- dev 设备句柄
+- oflag 设备的打开方式
+- return 错误码，0 表示打开成功，其他表示错误
+
+``oflag`` 可以写入以下参数：
+
+.. code-block:: C
+
+    #define DEVICE_OFLAG_STREAM_TX  0x001 /* 设备以轮训发送模式打开 */
+    #define DEVICE_OFLAG_STREAM_RX  0x002 /* 设备以轮训接收模式打开 */
+    #define DEVICE_OFLAG_INT_TX     0x004 /* 设备以中断发送模式打开 */
+    #define DEVICE_OFLAG_INT_RX     0x008 /* 设备以中断接收模式打开 */
+    #define DEVICE_OFLAG_DMA_TX     0x010 /* 设备以 DMA 发送模式打开 */
+    #define DEVICE_OFLAG_DMA_RX     0x020 /* 设备以 DMA 接收模式打开 */
+
+**i2c_transfer**
+^^^^^^^^^^^^^^^^
+
+``i2c_transfer`` 用于设备的数据传输，形参中 ``msgs`` 中的成员 ``flags`` 指示传输的方向是写还是读，并且指定寄存器地址长度是0、1、2。
+
+.. code-block:: C
+
+    int i2c_transfer(struct device *dev, i2c_msg_t msgs[], uint32_t num);   
+
+- dev 设备句柄
+- msgs 需要传输的消息
+- num 消息个数
+- return 错误码，0 表示打开成功，其他表示错误
+
+``i2c_msg_t`` 结构体定义如下：
+
+.. code-block:: C
+
+    typedef struct i2c_msg
+    {
+        uint8_t slaveaddr;
+        uint32_t subaddr;
+        uint16_t flags;
+        uint16_t len;
+        uint8_t *buf;
+    } i2c_msg_t;
+
+- slaveaddr i2c从设备7位从机地址
+- subaddr i2c从设备寄存器地址
+- flags 读写模式以及寄存器地址长度
+- len 传输数据长度
+- buf 数据缓冲区
+
+其中 ``flags`` 有如下定义：
+
+.. code-block:: C
+
+    /*读写模式*/
+    #define I2C_WR 0x0000
+    #define I2C_RD 0x0001
+
+    /*寄存器地址长度*/
+    #define SUB_ADDR_0BYTE 0x0010
+    #define SUB_ADDR_1BYTE 0x0020
+    #define SUB_ADDR_2BYTE 0x0040

docs/development_guide/source/api_reference/api_pwm.rst

@@ -0,0 +1,263 @@
+PWM 设备
+=========================
+
+简介
+------------------------
+
+脉冲宽度调制（Pulse width modulation，简称 PWM）是一种用数字方式实现模拟电压控制的技术。它是通过对一系列脉冲的宽度进行调制，等效出所需要的波形（包含形状以及幅值），对模拟信号电平进行数字编码，也就是说通过调节占空比的变化来调节信号、能量等的变化，占空比就是指在一个周期内，信号处于高电平的时间占据整个信号周期的百分比，例如方波的占空比就是50%。博流系列 MCU 中 DMA 设备具有以下特性：
+
+- 支持5通道PWM信号生成
+- 三种时钟源可选择（总线时钟 <bclk>、晶振时钟 <xtal_ck>、慢速时钟 <32k>），搭配 16-bit 时钟分频器
+- 双门限值域设定，增加脉冲弹性
+
+PWM 设备结构体定义
+------------------------
+
+.. code-block:: C
+
+    typedef struct pwm_device
+    {
+        struct device parent;
+        uint8_t ch;
+        uint32_t frequency;
+        uint8_t dutycycle;
+        uint16_t it_pulse_count;
+    } pwm_device_t;
+
+- parent    继承父类属性
+- ch        通道号，使能PWM通道0则ch为0，使能PWM通道0则ch为1，以此类推
+- frequency 默认频率
+- dutycycle 默认占空比（0-100）
+- it_pulse_count 触发中断条件的周期计数值
+
+PWM 设备参数配置表
+------------------------
+
+每一个 PWM 设备都有一个参数配置宏,宏定义位于 ``bsp/board/xxx`` 目录下 ``peripheral_config.h`` 文件,变量定义位于 ``hal_pwm.c`` 中，因此无需用户自己定义变量。当用户打开对应设备的宏，该设备的配置才生效。例如打开宏 ``BSP_USING_PWM_CH2`` ，``PWM_CH2_CONFIG`` 即生效，同时 ``PWM`` 设备的通道2就可以进行注册和使用了。
+
+.. code-block:: C
+
+    /*参数配置宏*/
+    #if defined(BSP_USING_PWM_CH2)
+    #ifndef PWM_CH2_CONFIG
+    #define PWM_CH2_CONFIG \
+    {   \
+        .ch = 2, \
+        .frequency = 1000000, \
+        .dutycycle = 0, \
+    }
+    #endif
+    #endif
+
+    /*变量定义*/
+    static pwm_device_t pwmx_device[PWM_MAX_INDEX] = {
+    #ifdef BSP_USING_PWM_CH0
+        PWM_CH0_CONFIG,
+    #endif
+    #ifdef BSP_USING_PWM_CH1
+        PWM_CH1_CONFIG,
+    #endif
+    #ifdef BSP_USING_PWM_CH2
+        PWM_CH2_CONFIG,
+    #endif
+    #ifdef BSP_USING_PWM_CH3
+        PWM_CH3_CONFIG,
+    #endif
+    #ifdef BSP_USING_PWM_CH4
+        PWM_CH4_CONFIG,
+    #endif
+    };
+
+.. note:: 上述配置可以通过 ``PWM_DEV(dev)->xxx`` 进行修改，只能在调用 ``device_open`` 之前使用。
+
+PWM 设备接口
+------------------------
+
+PWM 设备接口全部遵循标准设备驱动管理层提供的接口。并且为了方便用户调用，将某些标准接口使用宏来重定义。
+
+**pwm_register**
+^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+``pwm_register`` 用来注册一个 PWM 设备的一个通道，在注册之前需要打开对应 PWM 设备某个通道的宏定义,例如定义 ``BSP_USING_PWM_CH0`` 方可使用 ``PWM`` 通道0 设备。注册完成以后才可以使用其他接口，如果没有定义宏，则无法使用 PWM 设备。
+
+.. code-block:: C
+    
+    int pwm_register(enum pwm_index_type index, const char *name, uint16_t flag);
+
+- index 要注册的设备索引
+- name 为注册的设备命名
+- flag 默认可读可写属性
+
+``index`` 用来选择 PWM 设备某个通道的配置，一个 index 对应一个 PWM 设备的一个通道配置，比如 ``PWM_CH0_INDEX`` 对应 PWM 通道0 配置，``index`` 有如下可选类型
+
+.. code-block:: C
+    
+    enum pwm_index_type
+    {
+    #ifdef BSP_USING_PWM_CH0
+        PWM_CH0_INDEX,
+    #endif
+    #ifdef BSP_USING_PWM_CH1
+        PWM_CH1_INDEX,
+    #endif
+    #ifdef BSP_USING_PWM_CH2
+        PWM_CH2_INDEX,
+    #endif
+    #ifdef BSP_USING_PWM_CH3
+        PWM_CH3_INDEX,
+    #endif
+    #ifdef BSP_USING_PWM_CH4
+        PWM_CH4_INDEX,
+    #endif
+        PWM_MAX_INDEX
+    };
+
+**device_open**
+^^^^^^^^^^^^^^^^
+
+``device_open`` 用于设备的打开，``oflag`` 表示以何种方式打开。
+
+.. code-block:: C
+
+    int device_open(struct device *dev, uint16_t oflag);   
+
+- dev 设备句柄
+- oflag 设备的打开方式
+- return 错误码，0 表示打开成功，其他表示错误
+
+``oflag`` 可以写入以下参数：
+
+.. code-block:: C
+
+    #define DEVICE_OFLAG_STREAM_TX  0x001 /* 设备以轮训发送模式打开 */
+    #define DEVICE_OFLAG_STREAM_RX  0x002 /* 设备以轮训接收模式打开 */
+    #define DEVICE_OFLAG_INT_TX     0x004 /* 设备以中断发送模式打开 */
+    #define DEVICE_OFLAG_INT_RX     0x008 /* 设备以中断接收模式打开 */
+    #define DEVICE_OFLAG_DMA_TX     0x010 /* 设备以 DMA 发送模式打开 */
+    #define DEVICE_OFLAG_DMA_RX     0x020 /* 设备以 DMA 接收模式打开 */
+
+**device_close**
+^^^^^^^^^^^^^^^^
+
+``device_close`` 用于设备的关闭。
+
+.. code-block:: C
+
+    int device_close(struct device *dev);   
+
+- dev 设备句柄
+- return 错误码，0 表示关闭成功，其他表示错误
+    
+**device_control**
+^^^^^^^^^^^^^^^^^^^
+
+``device_control`` 用于根据命令对设备进行控制和参数的修改。
+
+.. code-block:: C
+
+    int device_control(struct device *dev, int cmd, void *args);   
+
+- dev 设备句柄
+- cmd 设备控制命令
+- args 控制参数
+- return 不同的控制命令返回的意义不同。
+
+PWM 设备除了标准的控制命令，还具有自己特殊的控制命令。
+
+.. code-block:: C
+
+    #define DEIVCE_CTRL_PWM_IT_PULSE_COUNT_CONFIG 0x10
+
+``args`` 根据不同的 ``cmd`` 传入不同，具体如下：
+
++------------------------------------------+-----------------+----------------------------+
+|cmd                                       |args             |description                 |
++==========================================+=================+============================+
+|DEVICE_CTRL_SET_INT                       |NULL             |开启pwm传输完成中断         |
++------------------------------------------+-----------------+----------------------------+
+|DEVICE_CTRL_CLR_INT                       |NULL             |关闭pwm传输完成中断         |
++------------------------------------------+-----------------+----------------------------+
+|DEVICE_CTRL_RESUME                        |NULL             |恢复pwm通道                 |
++------------------------------------------+-----------------+----------------------------+
+|DEVICE_CTRL_SUSPEND                       |NULL             |挂起pwm通道                 |
++------------------------------------------+-----------------+----------------------------+
+|DEVICE_CTRL_CONFIG                        |pwm_config_t     |配置pwm通道频率和占空比     |
++------------------------------------------+-----------------+----------------------------+
+|DEIVCE_CTRL_PWM_IT_PULSE_COUNT_CONFIG     |uint32_t*        |配置中断计数阈值            |
++------------------------------------------+-----------------+----------------------------+
+
+**device_set_callback**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``device_set_callback`` 用于注册一个PWM通道中断回调函数。
+
+.. code-block:: C
+
+    int device_set_callback(struct device *dev, void (*callback)(struct device *dev, void *args, uint32_t size, uint32_t event));
+
+- dev 设备句柄
+- callback 要注册的中断回调函数
+
+    - dev 设备句柄
+    - args 无用
+    - size 无用
+    - event 中断事件类型    
+
+PWM设备 ``event`` 类型如下
+
+.. code-block:: C
+
+    enum pwm_event_type
+    {
+        PWM_EVENT_COMPLETE,
+    };
+
+**pwm_channel_start**
+^^^^^^^^^^^^^^^^^^^^^^
+
+``pwm_channel_start`` 用于开启PWM通道。实际是调用 ``device_control`` ，其中 ``cmd`` 为 ``DEVICE_CTRL_RESUME``。
+
+.. code-block:: C
+
+    pwm_channel_start(dev)
+
+- dev 需要开启的pwm通道句柄
+
+
+**pwm_channel_stop**
+^^^^^^^^^^^^^^^^^^^^^^
+
+``pwm_channel_stop`` 用于关闭PWM通道。实际是调用 ``device_control`` ，其中 ``cmd`` 为 ``DEVICE_CTRL_SUSPEND``。
+
+.. code-block:: C
+
+    pwm_channel_stop(dev)
+
+- dev 需要关闭的pwm通道句柄
+
+
+**pwm_channel_update**
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``pwm_channel_update`` 用于更新PWM通道的频率和占空比。实际是调用 ``device_control`` ，其中 ``cmd`` 为 ``DEVICE_CTRL_CONFIG``。
+
+.. code-block:: C
+
+    pwm_channel_update(dev,cfg)
+
+- dev 需要更新的pwm通道句柄
+- cfg pwm_config_t句柄
+
+
+**pwm_it_pulse_count_update**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``pwm_it_pulse_count_update`` 用于更新PWM通道的计数值，需要先使能PWM中断才起作用，当pwm计数达到设置的周期计数值则会产生中断。实际是调用 ``device_control`` ，其中 ``cmd`` 为 ``DEIVCE_CTRL_PWM_IT_PULSE_COUNT_CONFIG``。
+
+.. code-block:: C
+
+    pwm_it_pulse_count_update(dev,count)
+
+- dev 需要更新周期计数值的pwm通道句柄
+- count 周期计数值
+

docs/development_guide/source/api_reference/api_spi.rst

@@ -0,0 +1,350 @@
+SPI 设备
+=========================
+
+简介
+------------------------
+
+串行外设接口（Serial Peripheral Interface Bus, SPI）是一种用于短程通信的同步串行通信接口规范，装置之间使用全
+双工模式通信，是一个主机和一个或多个从机的主从模式。需要至少 4 根线，事实上 3 根也可以（单向传输时）, 包括
+SDI（数据输入）、SDO（数据输出）、SCLK（时钟）、CS（片选）。博流系列 MCU 中 SPI 设备具有以下特性：
+
+- 既可以作为 SPI 主机也可以作为 SPI 从机。
+- 发送和接收通道各有深度为 4 个字的 FIFO
+- 主从设备都支持 4 种时钟格式（CPOL，CPHA）
+- 主从设备都支持 1/2/3/4 字节传输模式
+- 灵活的时钟配置，最高可支持 40M 时钟
+- 可配置 MSB/LSB 优先传输
+- 接收过滤功能
+- 从设备下的超时机制
+- 支持轮询、中断、DMA传输
+
+SPI 设备结构体定义
+------------------------
+
+.. code-block:: C
+    
+    typedef struct spi_device
+    {
+        struct device parent;
+        uint8_t id;
+        uint32_t clk;
+        uint8_t mode;
+        uint8_t direction;
+        uint8_t clk_polaraity;
+        uint8_t clk_phase;
+        uint8_t datasize;
+        uint8_t fifo_threshold;
+        void* tx_dma;
+        void* rx_dma;
+    } spi_device_t;
+
+- parent        继承父类属性
+- id            SPI id，0表示 SPI0
+- clk           SPI 时钟频率
+- mode          主机模式或者从机模式
+- direction     传输先行模式
+- clk_polaraity 时钟极性
+- clk_phase     时钟相位
+- datasize      数据传输位宽
+- fifo_threshold fifo 阈值, 最大为4
+- tx_dma        附加的发送 dma 句柄
+- rx_dma        附加的接收 dma 句柄
+
+``mode`` 提供以下类型
+
+.. code-block:: C
+
+    #define SPI_SLVAE_MODE                                0
+    #define SPI_MASTER_MODE                               1
+
+``direction`` 提供以下类型
+
+.. code-block:: C
+
+    #define SPI_LSB_BYTE0_DIRECTION_FIRST 0
+    #define SPI_LSB_BYTE3_DIRECTION_FIRST 1
+    #define SPI_MSB_BYTE0_DIRECTION_FIRST 2
+    #define SPI_MSB_BYTE3_DIRECTION_FIRST 3
+
+``clk_polaraity`` 提供以下类型
+
+.. code-block:: C
+
+    #define SPI_POLARITY_LOW                              0
+    #define SPI_POLARITY_HIGH                             1
+
+``clk_phase`` 提供以下类型
+
+.. code-block:: C
+
+    #define SPI_PHASE_1EDGE                               0
+    #define SPI_PHASE_2EDGE                               1
+
+
+``datasize`` 提供以下类型
+
+.. code-block:: C
+    
+    #define SPI_DATASIZE_8BIT                            0
+    #define SPI_DATASIZE_16BIT                           1
+    #define SPI_DATASIZE_24BIT                           2
+    #define SPI_DATASIZE_32BIT                           3
+
+SPI 设备参数配置表
+------------------------
+
+每一个 SPI 设备都有一个参数配置宏,宏定义位于 ``bsp/board/xxx`` 目录下 ``peripheral_config.h`` 文件,变量定义位于 ``hal_uart.c`` 中，因此无需用户自己定义变量。当用户打开对应设备的宏，该设备的配置才生效。例如打开宏 ``BSP_USING_SPI0`` ，``SPI0_CONFIG`` 即生效，同时 ``SPI0`` 设备就可以进行注册和使用了。
+
+.. code-block:: C
+
+    /*参数配置宏*/
+    #if defined(BSP_USING_SPI0)
+    #ifndef SPI0_CONFIG
+    #define SPI0_CONFIG \
+    {   \
+    .id = 0, \
+    .clk = 18000000,\
+    .mode = SPI_MASTER_MODE, \
+    .direction = SPI_MSB_BYTE0_DIRECTION_FIRST, \
+    .clk_polaraity = SPI_POLARITY_LOW, \
+    .clk_phase = SPI_PHASE_1EDGE, \
+    .datasize = SPI_DATASIZE_8BIT, \
+    .fifo_threshold = 1, \
+    }
+    #endif
+    #endif
+
+    /*变量定义*/
+    static spi_device_t spix_device[SPI_MAX_INDEX] =
+    {
+    #ifdef BSP_USING_SPI0
+        SPI0_CONFIG,
+    #endif
+    };
+
+.. note:: 上述配置可以通过 ``SPI_DEV(dev)->xxx`` 进行修改，只能在调用 ``device_open`` 之前使用。
+
+
+SPI 设备接口
+------------------------
+
+SPI 设备接口全部遵循标准设备驱动管理层提供的接口。
+
+**spi_register**
+^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+``spi_register`` 用来注册一个 SPI 设备，在注册之前需要打开对应 SPI 设备的宏定义,例如定义宏 ``BSP_USING_SPI0`` 方可使用 SPI0 设备。注册完成以后才可以使用其他接口，如果没有定义宏，则无法使用 SPI 设备。
+
+.. code-block:: C
+    
+    int spi_register(enum spi_index_type index, const char *name, uint16_t flag);
+
+- index 要注册的设备索引
+- name 为注册的设备命名
+- flag 默认可读可写属性
+
+``index`` 用来选择 SPI 设备配置，一个 index 对应一个 SPI 设备配置，比如 ``SPI0_INDEX`` 对应 ``SPI0_CONFIG`` 配置，``index`` 有如下可选类型
+
+.. code-block:: C
+    
+    enum spi_index_type
+    {
+    #ifdef BSP_USING_SPI0
+        SPI0_INDEX,
+    #endif
+        SPI_MAX_INDEX
+    };
+
+**device_open**
+^^^^^^^^^^^^^^^^
+
+``device_open`` 用于设备的打开，``oflag`` 表示以何种方式打开。
+
+.. code-block:: C
+
+    int device_open(struct device *dev, uint16_t oflag);   
+
+- dev 设备句柄
+- oflag 设备的打开方式
+- return 错误码，0 表示打开成功，其他表示错误
+
+``oflag`` 可以写入以下参数：
+
+.. code-block:: C
+
+    #define DEVICE_OFLAG_STREAM_TX  0x001 /* 设备以轮训发送模式打开 */
+    #define DEVICE_OFLAG_STREAM_RX  0x002 /* 设备以轮训接收模式打开 */
+    #define DEVICE_OFLAG_INT_TX     0x004 /* 设备以中断发送模式打开 */
+    #define DEVICE_OFLAG_INT_RX     0x008 /* 设备以中断接收模式打开 */
+    #define DEVICE_OFLAG_DMA_TX     0x010 /* 设备以 DMA 发送模式打开 */
+    #define DEVICE_OFLAG_DMA_RX     0x020 /* 设备以 DMA 接收模式打开 */
+
+**device_close**
+^^^^^^^^^^^^^^^^
+
+``device_close`` 用于设备的关闭。
+
+.. code-block:: C
+
+    int device_close(struct device *dev);   
+
+- dev 设备句柄
+- return 错误码，0 表示关闭成功，其他表示错误
+    
+**device_control**
+^^^^^^^^^^^^^^^^^^^
+
+``device_control`` 用于根据命令对设备进行控制和参数的修改。
+
+.. code-block:: C
+
+    int device_control(struct device *dev, int cmd, void *args);   
+
+- dev 设备句柄
+- cmd 设备控制命令
+- args 控制参数
+- return 不同的控制命令返回的意义不同。
+
+SPI 设备除了标准的控制命令，还具有自己特殊的控制命令。
+
+.. code-block:: C
+
+    #define DEVICE_CTRL_SPI_CONFIG_CLOCK       0x10
+
+``args`` 根据不同的 ``cmd`` 传入不同，具体如下：
+
++---------------------------------+-------------------+-----------------------+
+|cmd                              |args               |description            |
++=================================+===================+=======================+
+|DEVICE_CTRL_SET_INT              |NULL               |开启spi设备中断        |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_CLR_INT              |NULL               |关闭spi设备中断        |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_RESUME               |NULL               |恢复spi设备            |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_SUSPEND              |NULL               |挂起spi设备            |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_ATTACH_TX_DMA        |struct device*     |链接发送dma设备        |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_ATTACH_RX_DMA        |struct device*     |链接接收dma设备        |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_SPI_CONFIG_CLOCK     |uint32_t           |修改SPI设备时钟        |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_TX_DMA_SUSPEND       |NULL               |挂起spi tx dma模式     |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_RX_DMA_SUSPEND       |NULL               |挂起spi rx dma模式     |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_TX_DMA_RESUME        |NULL               |恢复spi tx dma模式     |
++---------------------------------+-------------------+-----------------------+
+|DEVICE_CTRL_RX_DMA_RESUME        |NULL               |恢复spi rx dma模式     |
++---------------------------------+-------------------+-----------------------+
+
+**device_write**
+^^^^^^^^^^^^^^^^
+
+``device_write`` 用于 SPI 设备数据的发送，发送方式根据打开方式可以是轮询、中断、dma。
+
+.. code-block:: C
+
+    int device_write(struct device *dev, uint32_t pos, const void *buffer, uint32_t size);  
+
+- dev 设备句柄
+- pos 无作用
+- buffer 要写入的 buffer 缓冲区
+- size 要写入的长度
+- return 错误码，0 表示写入成功，其他表示错误
+
+**device_read**
+^^^^^^^^^^^^^^^^
+
+``device_read`` 用于 SPI 设备数据的接收，接收方式根据打开方式可以是轮询、中断、dma。
+
+.. code-block:: C
+
+    int device_read(struct device *dev, uint32_t pos, void *buffer, uint32_t size);  
+
+- dev 设备句柄
+- pos 无作用
+- buffer 要读入的 buffer 缓冲区
+- size 要读入的长度
+- return 错误码，0 表示读入成功，其他表示错误
+
+**device_set_callback**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``device_set_callback`` 用于注册一个 SPI 设备中断回调函数。
+
+.. code-block:: C
+
+    int device_set_callback(struct device *dev, void (*callback)(struct device *dev, void *args, uint32_t size, uint32_t event));
+
+- dev 设备句柄
+- callback 要注册的中断回调函数
+
+    - dev 设备句柄
+    - args 接收发送缓冲区，数据类型为 uint8_t*
+    - size 传输长度
+    - event 中断事件类型    
+
+SPI 设备 ``event`` 类型如下
+
+.. code-block:: C
+
+    enum spi_event_type
+    {
+        SPI_EVENT_TX_FIFO,
+        SPI_EVENT_RX_FIFO,
+        SPI_EVENT_UNKNOWN
+    };
+
+**spi_transmit**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``spi_transmit`` 用于 SPI 设备数据的发送。
+
+.. code-block:: C
+
+    int spi_transmit(struct device *dev, void *buffer, uint32_t size, uint8_t type);
+
+- dev 设备句柄
+- buffer 发送数据缓冲区
+- size 发送长度
+- type 发送位宽类型
+
+``type`` 提供以下类型
+
+.. code-block:: C
+
+    #define SPI_TRANSFER_TYPE_8BIT    0
+    #define SPI_TRANSFER_TYPE_16BIT   1
+    #define SPI_TRANSFER_TPYE_24BIT   2
+    #define SPI_TRANSFER_TYPE_32BIT   3
+
+**spi_receive**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``spi_receive`` 用于 SPI 设备数据的接收。
+
+.. code-block:: C
+
+    int spi_receive(struct device *dev, void *buffer, uint32_t size, uint8_t type);
+
+- dev 设备句柄
+- buffer 接收数据缓冲区
+- size 接收长度
+- type 位宽类型
+
+**spi_transmit_receive**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``spi_transmit_receive`` 用于 SPI 设备数据的发送和接收。
+
+.. code-block:: C
+
+    int spi_transmit_receive(struct device *dev, const void *send_buf, void *recv_buf, uint32_t length, uint8_t type);
+
+- dev 设备句柄
+- send_buf 发送数据缓冲区
+- recv_buf 接收数据缓冲区
+- length 收发长度
+- type 位宽类型

docs/development_guide/source/api_reference/api_structure.rst

@@ -0,0 +1,299 @@
+API 分层模型
+=========================
+
+简介
+----
+
+为了不影响用户应用层代码因为芯片驱动的不同而频繁修改，**bl_mcu_sdk** 的外设 API 采用了 HAL 层的思想，屏蔽了底层硬件的实现。而 HAL 层又分为两大类：
+
+- 设备驱动管理层：提供一套标准的接口，具体实现由外设驱动适配层实现。
+- 外设驱动适配层：实现设备驱动管理层的标准接口，并且拓展自己的独特的接口。
+
+整体的代码分层框架如图所示：
+
+.. figure:: img/api1.png
+    :alt:
+
+    code structure
+
+- 应用层是用户自己编写的代码，接口则是调用 hal 层的接口。
+- HAL 层提供给应用层接口，底层调用 std 层，不同的芯片调用不同的 std 层。
+- STD 层则是对硬件寄存器进行简单封装，由外设驱动适配层进行调用。
+
+设备驱动管理层实现
+---------------------
+
+设备驱动管理层的实现采用了面向对象的思想，首先我们将外设看成是一个设备或者是文件，秉承 **一切皆文件** 的理念，而文件又都具有标准的调用接口：``open``、``close``、``ctrl``、``write``、``read``、``callback``，不同文件类别不同（比如串口设备、ADC设备、SPI设备），并且打开的方式也不同（比如轮询、中断、DMA），由此，我们可以构建出一个对象的基类（父类）。
+
+**基类**
+
+.. code-block:: C
+
+    struct device
+    {
+        char name[NAME_MAX];            /*name of device */
+        dlist_t list;                   /*list node of device */
+        enum device_status_type status; /*status of device */
+        enum device_class_type type;    /*type of device */
+        uint16_t oflag;                 /*oflag of device */
+
+        int (*open)(struct device *dev, uint16_t oflag);
+        int (*close)(struct device *dev);
+        int (*control)(struct device *dev, int cmd, void *args);
+        int (*write)(struct device *dev, uint32_t pos, const void *buffer, uint32_t size);
+        int (*read)(struct device *dev, uint32_t pos, void *buffer, uint32_t size);
+        void (*callback)(struct device *dev, void *args, uint32_t size, uint32_t event);
+        void *handle;
+    };
+
+**基类成员：name**
+
+给设备取名，后面会使用 ``device_find`` 找到这个设备。
+
+**基类成员：type**
+
+``type`` 记录当前设备的类别，可以选择的 ``type`` 类型如下。
+
+.. code-block:: C
+
+    enum device_class_type
+    {
+        DEVICE_CLASS_NONE = 0,
+        DEVICE_CLASS_GPIO,
+        DEVICE_CLASS_UART,
+        DEVICE_CLASS_SPI,
+        DEVICE_CLASS_I2C,
+        DEVICE_CLASS_ADC,
+        DEVICE_CLASS_DMA,
+        DEVICE_CLASS_TIMER,
+        DEVICE_CLASS_PWM,
+        DEVICE_CLASS_SDIO,
+        DEVICE_CLASS_USB,
+        DEVICE_CLASS_I2S,
+        DEVICE_CLASS_CAMERA,
+        DEVICE_CLASS_SEC_HASH,
+    } ;
+
+**基类成员：status**
+
+``status`` 用来记录当前设备的状态，当前提供 4 种状态。
+
+.. code-block:: C
+
+    enum device_status_type
+    {
+        DEVICE_UNREGISTER = 0,
+        DEVICE_REGISTERED,
+        DEVICE_OPENED,
+        DEVICE_CLOSED
+    } ;
+
+**基类成员：oflag**
+
+``oflag`` 记录 注册时填入的 flag 信息以及使用 ``device_open`` 时填入的 ``oflag`` 信息。
+
+**基类成员：list**
+
+设备的增加和删除使用双向链表进行存储，节省内存。
+
+**基类成员：标准的函数指针**
+
+为不同的外设提供了标准的函数接口，当外设实现此类接口并赋值给该成员，便能达到重写的功能。
+
+设备驱动管理层标准接口
+-----------------------
+
+**device_register**
+^^^^^^^^^^^^^^^^^^^^
+
+``device_register`` 用于设备的注册，将设备信息注册到链表当中。
+
+.. code-block:: C
+
+    int device_register(struct device *dev, const char *name, uint16_t flag);   
+
+- dev 设备句柄。
+- name 设备名称。
+- flag 设备的读写属性
+- return 返回错误码，0 表示注册成功，其他表示错误。
+
+``flag`` 可以写入以下参数，表示：**只读**、**只写**、**可读可写**。
+
+.. code-block:: C
+
+    #define DEVICE_OFLAG_RDONLY 0x1000 /* 以只读方式打开设备 */
+    #define DEVICE_OFLAG_WRONLY 0x2000 /* 以只写方式打开设备 */
+    #define DEVICE_OFLAG_RDWR   0x3000 /* 以读写方式打开设备 */
+
+
+**device_unregister**
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``device_unregister`` 用于设备的删除，将设备信息从链表中删除。
+
+.. code-block:: C
+
+    int device_unregister(const char *name);   
+
+- dev 设备句柄
+- name 要删除的设备名称
+- return 错误码，0 表示删除，其他表示错误
+
+**device_find**
+^^^^^^^^^^^^^^^^
+
+``device_find`` 用于根据 ``name`` 从链表中寻找设备，并返回设备句柄的首地址。
+
+.. code-block:: C
+
+    struct device *device_find(const char *name);
+
+- dev 设备句柄
+- name 要查找的设备名称
+- return 错误码，不为 0 表示找到的设备句柄，NULL 表示未找到该设备。
+
+
+**device_open**
+^^^^^^^^^^^^^^^^
+
+``device_open`` 用于设备的打开，``oflag`` 表示以何种方式打开，目前提供 6 种打开方式。底层调用 ``dev`` 句柄中的 ``open`` 成员。
+
+.. code-block:: C
+
+    int device_open(struct device *dev, uint16_t oflag);   
+
+- dev 设备句柄
+- oflag 设备的打开方式
+- return 错误码，0 表示打开成功，其他表示错误
+
+``oflag`` 可以写入以下参数：
+
+.. code-block:: C
+
+    #define DEVICE_OFLAG_STREAM_TX  0x001 /* 设备以轮训发送模式打开 */
+    #define DEVICE_OFLAG_STREAM_RX  0x002 /* 设备以轮训接收模式打开 */
+    #define DEVICE_OFLAG_INT_TX     0x004 /* 设备以中断发送模式打开 */
+    #define DEVICE_OFLAG_INT_RX     0x008 /* 设备以中断接收模式打开 */
+    #define DEVICE_OFLAG_DMA_TX     0x010 /* 设备以 DMA 发送模式打开 */
+    #define DEVICE_OFLAG_DMA_RX     0x020 /* 设备以 DMA 接收模式打开 */
+
+**device_close**
+^^^^^^^^^^^^^^^^
+
+``device_close`` 用于设备的关闭。底层调用 ``dev`` 句柄中的 ``close`` 成员。
+
+.. code-block:: C
+
+    int device_close(struct device *dev);   
+
+- dev 设备句柄
+- return 错误码，0 表示关闭成功，其他表示错误
+    
+**device_control**
+^^^^^^^^^^^^^^^^^^^
+
+``device_control`` 用于根据命令对设备进行控制和参数的修改。底层调用 ``dev`` 句柄中的 ``control`` 成员。
+
+.. code-block:: C
+
+    int device_control(struct device *dev, int cmd, void *args);   
+
+- dev 设备句柄
+- cmd 设备控制命令
+- args 控制参数
+- return 不同的控制命令返回的意义不同。
+
+``cmd`` 提供了以下标准命令，除此之外，不同外设还具有自己的命令
+
+.. code-block:: C
+
+    #define DEVICE_CTRL_SET_INT             0x01    /* set interrupt */
+    #define DEVICE_CTRL_CLR_INT             0x02    /* clear interrupt */
+    #define DEVICE_CTRL_GET_INT             0x03    /* get interrupt status*/
+    #define DEVICE_CTRL_RESUME              0x04    /* resume device */
+    #define DEVICE_CTRL_SUSPEND             0x05    /* suspend device */
+    #define DEVICE_CTRL_CONFIG              0x06    /* config device */
+    #define DEVICE_CTRL_GET_CONFIG          0x07    /* get device configuration */
+    #define DEVICE_CTRL_ATTACH_TX_DMA       0x08
+    #define DEVICE_CTRL_ATTACH_RX_DMA       0x09
+    #define DEVICE_CTRL_TX_DMA_SUSPEND      0x0a
+    #define DEVICE_CTRL_RX_DMA_SUSPEND      0x0b
+    #define DEVICE_CTRL_TX_DMA_RESUME       0x0c
+    #define DEVICE_CTRL_RX_DMA_RESUME       0x0d
+    #define DEVICE_CTRL_RESVD1              0x0E
+    #define DEVICE_CTRL_RESVD2              0x0F
+
+**device_write**
+^^^^^^^^^^^^^^^^
+
+``device_write`` 用于数据的发送，发送方式根据打开方式可以是轮询、中断、dma。底层调用 ``dev`` 句柄中的 ``write`` 成员。
+
+.. code-block:: C
+
+    int device_write(struct device *dev, uint32_t pos, const void *buffer, uint32_t size);  
+
+- dev 设备句柄
+- pos 不同的设备 pos 的意义不同
+- buffer 要写入的 buffer 缓冲区
+- size 要写入的长度
+- return 错误码，0 表示写入成功，其他表示错误
+
+**device_read**
+^^^^^^^^^^^^^^^^
+
+``device_read`` 用于数据的接收，接收方式根据打开方式可以是轮询、中断、dma。底层调用 ``dev`` 句柄中的 ``read`` 成员。
+
+.. code-block:: C
+
+    int device_read(struct device *dev, uint32_t pos, void *buffer, uint32_t size);  
+
+- dev 设备句柄
+- pos 不同的设备 pos 的意义不同
+- buffer 要读入的 buffer 缓冲区
+- size 要读入的长度
+- return 错误码，0 表示读入成功，其他表示错误
+
+**device_set_callback**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``device_set_callback`` 用于中断回调函数的注册。底层调用 ``dev`` 句柄中的 ``callback`` 成员。
+
+.. code-block:: C
+
+    int device_set_callback(struct device *dev, void (*callback)(struct device *dev, void *args, uint32_t size, uint32_t event));
+
+- dev 设备句柄
+- callback 要注册的中断回调函数
+
+
+    * dev 设备句柄
+    * args 不同外设意义不同
+    * size 传输长度
+    * event 中断事件类型
+
+外设驱动适配层实现
+------------------------
+
+**子类继承父类**
+
+不同的外设首成员为 ``struct device`` ，这就相当于父类的继承，从而可以使用子类来访问父类成员，当使用子类修改父类成员时，便拥有了子类自己的功能。实现原理是不同结构体的首地址是该结构体中首个成员的地址。
+
+.. code-block:: C
+
+    typedef struct xxx_device
+    {
+        struct device parent;
+
+    } xxx_device_t;
+
+**重写标准接口**
+
+每个外设都有一个 ``xxx_register`` 函数，用来重写标准接口。
+
+.. code-block:: C
+
+    dev->open = xxx_open;
+    dev->close = xxx_close;
+    dev->control = xxx_control;
+    dev->write = xxx_write;
+    dev->read = xxx_read;

docs/development_guide/source/api_reference/api_uart.rst

@@ -0,0 +1,296 @@
+UART 设备
+=========================
+
+简介
+------------------------
+
+UART 全称（Universal Asynchronous Receiver/Transmitter）通用异步收发传输器，提供了与外部设备进行全双工数据交换的灵活方式。博流系列 MCU 中 UART 设备具有以下特性：
+
+- 数据位长度可选择 5/6/7/8 比特
+- 停止位长度可选择 0.5/1/1.5/2 比特
+- 支持奇/偶/无校验比特
+- 支持硬件流控（RTS/CTS）
+- 自动波特率检测
+- 支持 LIN 协议（收发 BREAK/SYNC）
+- 硬件字节发送/接收 FIFO
+- 支持轮询、中断、DMA传输
+- 特有的 rto 中断
+
+UART 设备结构体定义
+------------------------
+
+.. code-block:: C
+    
+    typedef struct uart_device
+    {
+        struct device parent;
+        uint8_t id;
+        uint32_t baudrate;
+        uart_databits_t databits;
+        uart_stopbits_t stopbits;
+        uart_parity_t parity;
+        uint8_t fifo_threshold;
+        void* tx_dma;
+        void* rx_dma;
+    } uart_device_t;
+
+- parent    继承父类属性
+- id        串口 id，使能串口0则id为0，使能串口1则id为1，以此类推
+- baudrate  波特率
+- databits  数据位
+- stopbits  停止位
+- parity    校验位
+- fifo_threshold fifo 阈值,不同 mcu 最大值不同
+- tx_dma    附加的发送 dma 句柄
+- rx_dma    附加的接收 dma 句柄
+
+``databits`` 提供以下类型
+
+.. code-block:: C
+
+    typedef enum  
+    {
+        UART_DATA_LEN_5 = 0,  /*!< Data length is 5 bits */
+        UART_DATA_LEN_6 = 1,  /*!< Data length is 6 bits */
+        UART_DATA_LEN_7 = 2,  /*!< Data length is 7 bits */
+        UART_DATA_LEN_8 = 3   /*!< Data length is 8 bits */
+    } uart_databits_t;
+
+``stopbits`` 提供以下类型
+
+.. code-block:: C
+    
+    typedef enum  
+    {
+        UART_STOP_ONE = 0,  /*!< One stop bit */
+        UART_STOP_ONE_D_FIVE = 1,  /*!< 1.5 stop bit */
+        UART_STOP_TWO = 2   /*!< Two stop bits */
+    } uart_stopbits_t;
+
+``parity`` 提供以下类型
+
+.. code-block:: C
+    
+    typedef enum  
+    {
+        UART_PAR_NONE = 0,  /*!< No parity */
+        UART_PAR_ODD  = 1,  /*!< Parity bit is odd */
+        UART_PAR_EVEN = 2,  /*!< Parity bit is even */
+    } uart_parity_t;
+
+UART 设备参数配置表
+------------------------
+
+每一个 UART 设备都有一个参数配置宏,宏定义位于 ``bsp/board/xxx`` 目录下 ``peripheral_config.h`` 文件,变量定义位于 ``hal_uart.c`` 中，因此无需用户自己定义变量。当用户打开对应设备的宏，该设备的配置才生效。例如打开宏 ``BSP_USING_UART0`` ，``UART0_CONFIG`` 即生效，同时 ``UART0`` 设备就可以进行注册和使用了。
+
+.. code-block:: C
+
+    /*参数配置宏*/
+    #if defined(BSP_USING_UART0)
+    #ifndef UART0_CONFIG
+    #define UART0_CONFIG \
+    {   \
+    .id = 0, \
+    .baudrate = 2000000,\
+    .databits = UART_DATA_LEN_8, \
+    .stopbits = UART_STOP_ONE, \
+    .parity = UART_PAR_NONE, \
+    .fifo_threshold = 1, \
+    }
+    #endif
+    #endif
+
+    /*变量定义*/
+    static uart_device_t uartx_device[UART_MAX_INDEX] =
+    {
+    #ifdef BSP_USING_UART0
+            UART0_CONFIG,
+    #endif
+    #ifdef BSP_USING_UART1
+            UART1_CONFIG,
+    #endif
+    };
+
+.. note:: 上述配置可以通过 ``UART_DEV(dev)->xxx`` 进行修改，只能在调用 ``device_open`` 之前使用。
+
+UART 设备接口
+------------------------
+
+UART 设备接口全部遵循标准设备驱动管理层提供的接口。
+
+**uart_register**
+^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+``uart_register`` 用来注册一个 UART 设备，在注册之前需要打开对应 UART 设备的宏定义。例如定义宏 ``BSP_USING_UART0`` 方可使用 ``UART0`` 设备,注册完成以后才可以使用其他接口，如果没有定义宏，则无法使用 ``UART0`` 设备。
+
+.. code-block:: C
+    
+    int uart_register(enum uart_index_type index, const char *name, uint16_t flag);
+
+- index 要注册的设备索引
+- name 为注册的设备命名
+- flag 默认可读可写属性
+
+``index`` 用来选择 UART 设备配置，一个 index 对应一个 UART 设备配置，比如 ``UART0_INDEX`` 对应 ``UART0_CONFIG`` 配置，``index`` 有如下可选类型
+
+.. code-block:: C
+    
+    enum uart_index_type
+    {
+    #ifdef BSP_USING_UART0
+        UART0_INDEX,
+    #endif
+    #ifdef BSP_USING_UART1
+        UART1_INDEX,
+    #endif
+        UART_MAX_INDEX
+    };
+
+**device_open**
+^^^^^^^^^^^^^^^^
+
+``device_open`` 用于 UART 设备的打开，``oflag`` 表示以何种方式打开。
+
+.. code-block:: C
+
+    int device_open(struct device *dev, uint16_t oflag);   
+
+- dev 设备句柄
+- oflag 设备的打开方式
+- return 错误码，0 表示打开成功，其他表示错误
+
+``oflag`` 可以写入以下参数：
+
+.. code-block:: C
+
+    #define DEVICE_OFLAG_STREAM_TX  0x001 /* 设备以轮训发送模式打开 */
+    #define DEVICE_OFLAG_STREAM_RX  0x002 /* 设备以轮训接收模式打开 */
+    #define DEVICE_OFLAG_INT_TX     0x004 /* 设备以中断发送模式打开 */
+    #define DEVICE_OFLAG_INT_RX     0x008 /* 设备以中断接收模式打开 */
+    #define DEVICE_OFLAG_DMA_TX     0x010 /* 设备以 DMA 发送模式打开 */
+    #define DEVICE_OFLAG_DMA_RX     0x020 /* 设备以 DMA 接收模式打开 */
+
+**device_close**
+^^^^^^^^^^^^^^^^
+
+``device_close`` 用于设备的关闭。
+
+.. code-block:: C
+
+    int device_close(struct device *dev);   
+
+- dev 设备句柄
+- return 错误码，0 表示关闭成功，其他表示错误
+    
+**device_control**
+^^^^^^^^^^^^^^^^^^^
+
+``device_control`` 用于根据命令对 UART 设备进行控制和参数的修改。
+
+.. code-block:: C
+
+    int device_control(struct device *dev, int cmd, void *args);   
+
+- dev 设备句柄
+- cmd 设备控制命令
+- args 控制参数
+- return 不同的控制命令返回的意义不同。
+
+串口设备除了标准的控制命令，还具有自己特殊的控制命令。
+
+.. code-block:: C
+
+    #define DEVICE_CTRL_UART_GET_TX_FIFO        0x10
+    #define DEVICE_CTRL_UART_GET_RX_FIFO        0x11
+
+``args`` 根据不同的 ``cmd`` 传入不同，具体如下：
+
+
++---------------------------------+---------------------+------------------------------+
+|cmd                              |args                 |description                   |
++=================================+=====================+==============================+
+|DEVICE_CTRL_SET_INT              |uart_it_type         |开启spi设备中断               |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_CLR_INT              |uart_it_type         |关闭spi设备中断               |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_CONFIG               |uart_param_cfg_t*    |修改串口配置                  |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_ATTACH_TX_DMA        |struct device*       |链接发送dma设备               |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_ATTACH_RX_DMA        |struct device*       |链接接收dma设备               |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_ATTACH_RX_DMA        |struct device*       |链接接收dma设备               |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_TX_DMA_SUSPEND       |NULL                 |挂起uart tx dma模式           |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_RX_DMA_SUSPEND       |NULL                 |挂起uart rx dma模式           |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_TX_DMA_RESUME        |NULL                 |恢复uart tx dma模式           |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_RX_DMA_RESUME        |NULL                 |恢复uart rx dma模式           |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_UART_GET_TX_FIFO     |uint32_t*            |获取uart 发送fifo数据个数     |
++---------------------------------+---------------------+------------------------------+
+|DEVICE_CTRL_UART_GET_RX_FIFO     |uint32_t*            |获取uart 接收fifo数据个数     |
++---------------------------------+---------------------+------------------------------+
+
+**device_write**
+^^^^^^^^^^^^^^^^
+
+``device_write`` 用于 UART 设备数据的发送，发送方式根据打开方式可以是轮询、中断、dma。
+
+.. code-block:: C
+
+    int device_write(struct device *dev, uint32_t pos, const void *buffer, uint32_t size);  
+
+- dev 设备句柄
+- pos 无作用
+- buffer 要写入的 buffer 缓冲区
+- size 要写入的长度
+- return 错误码，0 表示写入成功，其他表示错误
+
+**device_read**
+^^^^^^^^^^^^^^^^
+
+``device_read`` 用于 UART 设备数据的接收，接收方式根据打开方式可以是轮询、中断、dma。
+
+.. code-block:: C
+
+    int device_read(struct device *dev, uint32_t pos, void *buffer, uint32_t size);  
+
+- dev 设备句柄
+- pos 无作用
+- buffer 要读入的 buffer 缓冲区
+- size 要读入的长度
+- return 错误码，0 表示读入成功，其他表示错误
+
+**device_set_callback**
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``device_set_callback`` 用于注册一个串口中断回调函数。
+
+.. code-block:: C
+
+    int device_set_callback(struct device *dev, void (*callback)(struct device *dev, void *args, uint32_t size, uint32_t event));
+
+- dev 设备句柄
+- callback 要注册的中断回调函数
+
+    - dev 设备句柄
+    - args 接收发送缓冲区，数据类型为 uint8_t*
+    - size 传输长度
+    - event 中断事件类型    
+
+串口设备 ``event`` 类型如下
+
+.. code-block:: C
+
+    enum uart_event_type
+    {
+        UART_EVENT_TX_END,
+        UART_EVENT_TX_FIFO,
+        UART_EVENT_RX_END,
+        UART_EVENT_RX_FIFO,
+        UART_EVENT_RTO,
+        UART_EVENT_UNKNOWN
+    };