diff --git a/README.md b/README.md index 2eac3d5f..ce7ed0df 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,9 @@ # SDK Versions & Chip Support -Note1：**drivers before v1.4.5 use v1.0（hal + std）, the later version will use v2.0 (lhal + soc)**。If you want to use **v1.4.5**, please checkout your branch to [release-v1.4.5](https://github.com/bouffalolab/bl_mcu_sdk/tree/release_v1.4.5). +Note1: **drivers before v1.4.5 use v1.0（hal + std）, the later version will use v2.0 (lhal + soc)**。If you want to use **v1.4.5**, please checkout your branch to [release-v1.4.5](https://github.com/bouffalolab/bl_mcu_sdk/tree/release_v1.4.5). -Note2：due to the non-generic peripherals, the code style and interface name in **soc** are still the previous version, but will be subsequently updated to the new code style。 +Note2: due to the non-generic peripherals, the code style and interface name in **soc** are still the previous version, but will be subsequently updated to the new code style. | CHIP | v1.4.5 | latest | |:-------------:|:--------:|:-------:| @@ -24,7 +24,7 @@ Note2：due to the non-generic peripherals, the code style and interface name in **LHAL** is a low level hal driver for common peripherals designed by Bouffalo Lab, in order to support all the Bouffalo chips with the same api . Also it is convenient for users to use and port to other platforms. -Note：**√** means supported ；**×** means not supported；**○** means supported but not tested ；**-** means no such peripheral。 +Note：**√** means supported ; **×** means not supported; **○** means supported but not tested ; **-** means no such peripheral. | Peripheral | BL602/BL604 | BL702/BL704/BL706 | BL616/BL618 | BL808 | |:------------:|:--------------:|:--------------------:|:-----------:|:--------:| @@ -61,6 +61,7 @@ Note：**√** means supported ；**×** means not supported；**○** means sup bl_mcu_sdk ├── bsp │ ├── board +│ │ └── bl602 │ │ └── bl702 │ │ └── bl616 │ │ └── bl808 @@ -113,7 +114,7 @@ bl_mcu_sdk ## Command Line Development -Before compiling with the command line, you need to select the corresponding toolchain according to your operating system, configure it to the system environment variables, and install the **make**, then you can do the following. +Before compiling with the command line, you need to select the corresponding toolchain according to your operating system, configure it to the system environment variables, and install the **make** or **ninja**, then you can do the following. For the details, you can visit [bl mcu sdk Environment Setup](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/index.html). - Go to the demo directory where you want to compile and there are `main.c` and `Makefile` files in that directory - Just execute the following command, take **BL616** as an example @@ -128,6 +129,15 @@ make CHIP=bl616 BOARD=bl616dk - If you use **BL808** or **BL606P**, you need to add **CPU_ID** with m0 or d0. +If you want to use **ninja**, you can try: + +``` +cd bl_mcu_sdk +chmod +x tools/cmake/bin/cmake +cd examples/helloworld +make ninja CHIP=bl616 BOARD=bl616dk +``` + ``` cd bl_mcu_sdk chmod +x tools/cmake/bin/cmake @@ -141,14 +151,14 @@ TODO ## Debug -Only supports debug with CKLink currently. See [bl mcu sdk debug chapter](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/debug.html). +Only supports debug with CKLink currently. See [bl mcu sdk Debug Guide](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/debug.html). ## Firmware Download We recommend you to use this **BL DevCube** and download firmware with serial. -- [BL DevCube Tool](https://dev.bouffalolab.com/download) -- [BL DevCube download guide](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/devcube.html) +- [Bouffalo Lab Dev Cube](https://dev.bouffalolab.com/download) +- [Bouffalo Lab Dev Cube User Guide](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/devcube.html) # Resources @@ -167,20 +177,13 @@ To get more bl mcu sdk documentation tutorial, like api manual or peripheral dem - [BL706 MCU Development Series Video Tutorial](https://www.bilibili.com/video/BV1xK4y1P7ur) -### Flash Tool - -In addition to using CK-link, J-link and command line programming, it also supports graphical programming tools. -Graphical programming tools provided by Bouffalolab: - -- [Bouffalo Lab Dev Cube](https://dev.bouffalolab.com/download) - ## Forum Bouffalolab Developer Forum: [https://bbs.bouffalolab.com/](https://bbs.bouffalolab.com/) # License -**bl mcu sdk** is completely open source and follows the Apache License 2.0 open source license agreement. It can be used in commercial products for free and does not require public private code. +**bl mcu sdk** follows the Apache License 2.0 open source license agreement. It can be used in commercial products for free and does not require public private code. ``` /* diff --git a/README_zh.md b/README_zh.md index 8b8a1aa2..829f42a9 100644 --- a/README_zh.md +++ b/README_zh.md @@ -33,7 +33,7 @@ | CKS | ○ | √ | √ | ○ | | DAC | ○ | √ | √ | ○ | | DMA | ○ | √ | √ | √ | -| EFUSE | × | × | × | × | +| EFUSE | × | √ | √ | √ | | EMAC | - | √ | √ | √ | | FLASH | √ | √ | √ | √ | | GPIO | ○ | √ | √ | √ | @@ -61,6 +61,7 @@ bl_mcu_sdk ├── bsp │ ├── board +│ │ └── bl602 │ │ └── bl702 │ │ └── bl616 │ │ └── bl808 @@ -113,7 +114,7 @@ bl_mcu_sdk ## 命令行编译 -在进行命令行编译之前，需要根据你的操作系统，选择对应的工具链，并配置到系统环境变量，并安装了 **make** 工具，然后才能进行下面操作。 +在进行命令行编译之前，需要根据你的操作系统，选择对应的工具链，并配置到系统环境变量，并安装了 **make** 或者 **ninja** 工具，然后才能进行下面操作。更详细的搭建过程，参考 [bl mcu sdk 环境搭建](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/index.html). - 进入要编译的 demo 目录，且该目录下有 `main.c` 和 `Makefile` 文件 - 执行下面命令即可,以 **BL616** 为例 @@ -135,20 +136,29 @@ cd examples/helloworld make CHIP=bl808 BOARD=bl808dk CPU_ID=m0 ``` +如果你想使用 **ninja** 编译，你可以尝试： + +``` +cd bl_mcu_sdk +chmod +x tools/cmake/bin/cmake +cd examples/helloworld +make ninja CHIP=bl808 BOARD=bl808dk CPU_ID=m0 +``` + ## CDK 编译 TODO ## 调试 -当前仅支持使用 CKLink 调试。详细参考 [bl mcu sdk 调试章节](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/debug.html)。 +当前仅支持使用 CKLink 调试。详细参考 [bl mcu sdk 调试指南](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/debug.html)。 ## 固件烧录 推荐使用 **BL DevCube** 并通过串口进行固件的烧录。 -- [BL DevCube Tool](https://dev.bouffalolab.com/download) -- [BL DevCube download guide](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/devcube.html) +- [Bouffalo Lab Dev Cube](https://dev.bouffalolab.com/download) +- [Bouffalo Lab Dev Cube User Guide](https://bl-mcu-sdk.readthedocs.io/zh_CN/latest/get_started/devcube.html) # 芯片手册 @@ -171,7 +181,7 @@ TODO # 许可协议 -**bl mcu sdk** 完全开源，遵循 Apache License 2.0 开源许可协议，可以免费在商业产品中使用，并且不需要公开私有代码。 +**bl mcu sdk** 遵循 Apache License 2.0 开源许可协议，可以免费在商业产品中使用，并且不需要公开私有代码。 ``` /* diff --git a/docs/source/advance_samples/index.rst b/docs/source/advance_samples/index.rst new file mode 100644 index 00000000..e33647e3 --- /dev/null +++ b/docs/source/advance_samples/index.rst @@ -0,0 +1,2 @@ +TODO +==================== diff --git a/docs/source/api_reference/components/bflog.rst b/docs/source/api_reference/components/bflog.rst index f2609f63..58b043af 100644 --- a/docs/source/api_reference/components/bflog.rst +++ b/docs/source/api_reference/components/bflog.rst @@ -3,6 +3,7 @@ BFLOG 简介 ------------ + - BFLOG 是一个移植简单，功能多样的多线程日志记录库 - 具有同步异步两种工作模式，异步模式如果缓冲区溢出会将最早的一条记录完整删除 - 总体三部分、记录器、定向输出、格式化器 @@ -20,7 +21,8 @@ BFLOG log 样式 配置BFLOG相关功能 ------------- +------------------- + 如果需要配置BFLOG的相关功能需要在对应的工程目录下 `proj.conf` 文件中添加对应的代码，举例如下： .. note:: BFLOG 默认依赖 VLIBC 需要先启用 VLIBC。 @@ -62,7 +64,7 @@ BFLOG set(CONFIG_BSP_SDH_SDCARD 1) # 使能 Fatfs 的 SD 卡接口 - set(CONFIG_BSP_FATFS_SDH_SDCARD 1) + set(CONFIG_FATFS_SDH_SDCARD 1) 此外在 `proj.conf` 配置中添加以下配置可以使用用户的 **bflog_user.h** 配置文件，配置文件模板为 **bflog_default.h** diff --git a/docs/source/api_reference/peripherals/adc.rst b/docs/source/api_reference/peripherals/adc.rst index ea07d9d6..e27654b3 100644 --- a/docs/source/api_reference/peripherals/adc.rst +++ b/docs/source/api_reference/peripherals/adc.rst @@ -12,7 +12,7 @@ adc channel adc clock div ^^^^^^^^^^^^^^^^^^^^ -对 adc 时钟再一次进行分频。分频后的时钟必须小于 2M。 +对 adc 时钟再一次进行分频。分频后的时钟必须小于等于 500K。ADC CLK = CLK_SOURCE/CLK_DIV/adc_clk_div。 .. code-block:: c :linenos: @@ -480,3 +480,41 @@ bflb_adc_tsen_get_temp - 设备句柄 * - return - 温度 + +bflb_adc_vbat_enable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 开启 vbat 。 + +.. code-block:: c + :linenos: + + void bflb_adc_vbat_enable(struct bflb_device_s *dev); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + +bflb_adc_vbat_disable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 关闭 vbat。 + +.. code-block:: c + :linenos: + + void bflb_adc_vbat_disable(struct bflb_device_s *dev); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 diff --git a/docs/source/api_reference/peripherals/cks.rst b/docs/source/api_reference/peripherals/cks.rst new file mode 100644 index 00000000..084092ad --- /dev/null +++ b/docs/source/api_reference/peripherals/cks.rst @@ -0,0 +1,15 @@ +CKS +============= + +Macros +------------ + +无 + +Structs +------------ + +无 + +Functions +------------ \ No newline at end of file diff --git a/docs/source/api_reference/peripherals/dma.rst b/docs/source/api_reference/peripherals/dma.rst index f7715d09..8015a6e2 100644 --- a/docs/source/api_reference/peripherals/dma.rst +++ b/docs/source/api_reference/peripherals/dma.rst @@ -25,8 +25,8 @@ dma 地址自增使能。 .. code-block:: c :linenos: - #define DMA_ADDR_INCREMENT_DISABLE 0 /*!< Addr increment mode disable */ - #define DMA_ADDR_INCREMENT_ENABLE 1 /*!< Addr increment mode enable */ + #define DMA_ADDR_INCREMENT_DISABLE 0 + #define DMA_ADDR_INCREMENT_ENABLE 1 dma data width ^^^^^^^^^^^^^^^^^^^^^ @@ -53,7 +53,7 @@ dma 突发传输个数，最多 16 字节突发。 #define DMA_BURST_INCR8 2 #define DMA_BURST_INCR16 3 -.. warning:: 位宽 * 突发个数 需要小于等于 16 +.. warning:: 位宽 * 突发个数 需要小于等于 16 字节 dma addr ^^^^^^^^^^^^^^^^^^^^^ @@ -315,7 +315,31 @@ bflb_dma_channel_lli_reload * - count - 传输次数 * - return - - 小于0 表示参数错误或者内存池过小 + - 返回使用的 lli count个数，小于0表示错误 + +bflb_dma_channel_lli_link_head +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 将 lli 最后一个链表与头部连接，表示开启循环模式。 + +.. code-block:: c + :linenos: + + void bflb_dma_channel_lli_link_head(struct bflb_device_s *dev, + struct bflb_dma_channel_lli_pool_s *lli_pool, uint32_t used_lli_count); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - lli_pool + - lli 内存池 + * - used_lli_count + - 已经使用的 lli 个数 bflb_dma_feature_control ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -347,3 +371,5 @@ bflb_dma_feature_control #define DMA_CMD_SET_SRCADDR_INCREMENT (0x01) #define DMA_CMD_SET_DSTADDR_INCREMENT (0x02) + #define DMA_CMD_SET_ADD_MODE (0x03) + #define DMA_CMD_SET_REDUCE_MODE (0x04) diff --git a/docs/source/api_reference/peripherals/flash.rst b/docs/source/api_reference/peripherals/flash.rst new file mode 100644 index 00000000..b17920f2 --- /dev/null +++ b/docs/source/api_reference/peripherals/flash.rst @@ -0,0 +1,235 @@ +FLASH +============= + +Macros +------------ + +flash iomode +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: c + :linenos: + + #define FLASH_IOMODE_NIO 0 + #define FLASH_IOMODE_DO 1 + #define FLASH_IOMODE_QO 2 + #define FLASH_IOMODE_DIO 3 + #define FLASH_IOMODE_QIO 4 + +Structs +------------ + +无 + +Functions +------------ + +bflb_flash_init +^^^^^^^^^^^^^^^^^^^^ + +说明: flash 初始化，自动识别支持的 flash 并重新配置 flash 的参数。如果返回错误，必须停止运行代码。 + +.. code-block:: c + :linenos: + + int bflb_flash_init(void); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - return + - 返回 0 表示成功，其他表示错误，必须停止运行代码 + +bflb_flash_get_jedec_id +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取 flash jedec id。 + +.. code-block:: c + :linenos: + + uint32_t bflb_flash_get_jedec_id(void); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - return + - 返回 flash jedec id + +bflb_flash_get_cfg +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取 flash 配置。 + +.. code-block:: c + :linenos: + + void bflb_flash_get_cfg(uint8_t **cfg_addr, uint32_t *len); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - cfg_addr + - 保存 flash 配置的地址 + * - len + - flash 配置的长度 + +bflb_flash_set_iomode +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 设置 flash IO 工作模式。 + +.. code-block:: c + :linenos: + + void bflb_flash_set_iomode(uint8_t iomode); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - iomode + - flash IO 工作模式 + +bflb_flash_get_image_offset +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取代码 xip 虚拟地址实际所在的 flash 物理地址。 + +.. code-block:: c + :linenos: + + uint32_t bflb_flash_get_image_offset(void); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - return + - 返回 flash xip 物理地址 + +bflb_flash_erase +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: flash 扇区擦除。 **len** 为擦除的长度，需要为 4096 倍数，假设 **addr** 为0 ， **len** 为 4096，则擦除范围为 0 ~ 4095。 + +.. code-block:: c + :linenos: + + int bflb_flash_erase(uint32_t addr, uint32_t len); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - addr + - 擦除的物理地址 + * - len + - 擦除长度，需要是 4096 的倍数 + * - return + - 返回 0 表示成功，其他表示错误 + +bflb_flash_write +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取代码 xip 虚拟地址实际所在的 flash 物理地址。 + +.. code-block:: c + :linenos: + + int bflb_flash_write(uint32_t addr, uint8_t *data, uint32_t len); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - addr + - 写入的物理地址 + * - data + - 写入的数据缓冲区 + * - len + - 写入长度 + * - return + - 返回 0 表示成功，其他表示错误 + +bflb_flash_read +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取代码 xip 虚拟地址实际所在的 flash 物理地址。 + +.. code-block:: c + :linenos: + + int bflb_flash_read(uint32_t addr, uint8_t *data, uint32_t len); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - addr + - 读取的物理地址 + * - data + - 读取的数据缓冲区 + * - len + - 读取长度 + * - return + - 返回 0 表示成功，其他表示错误 + +bflb_flash_aes_init +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 配置某一段 flash 区域进行硬件 aes 解密，能够通过 xip 直接读取解密后的内容。 + +.. code-block:: c + :linenos: + + void bflb_flash_aes_init(struct bflb_flash_aes_config_s *config); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - config + - flash aes 配置 + +bflb_flash_aes_enable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 使能 flash aes 解密。 + +.. code-block:: c + :linenos: + + void bflb_flash_aes_enable(void); + +bflb_flash_aes_disable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 关闭 flash aes 解密。 + +.. code-block:: c + :linenos: + + void bflb_flash_aes_disable(void); + diff --git a/docs/source/api_reference/peripherals/index.rst b/docs/source/api_reference/peripherals/index.rst index 458daf57..c239b738 100644 --- a/docs/source/api_reference/peripherals/index.rst +++ b/docs/source/api_reference/peripherals/index.rst @@ -71,7 +71,7 @@ API 支持情况 * - peripheral - BL602/BL604 - BL702/BL704/BL706 - - BL616 + - BL616/BL618 - BL808 * - ADC - ❓ @@ -83,6 +83,11 @@ API 支持情况 - ❌ - ❌ - ❌ + * - CKS + - ❓ + - ✔️ + - ✔️ + - ❓ * - DAC - ❓ - ✔️ @@ -94,20 +99,20 @@ API 支持情况 - ✔️ - ✔️ * - EFUSE - - ❌ - - ❌ - - ❌ - - ❌ + - ❓ + - ✔️ + - ✔️ + - ✔️ * - EMAC - ➖ - ✔️ - ✔️ - ✔️ * - FLASH - - ❌ - - ❌ - - ❌ - - ❌ + - ✔️ + - ✔️ + - ✔️ + - ✔️ * - GPIO - ❓ - ✔️ @@ -125,8 +130,8 @@ API 支持情况 - ✔️ * - MJPEG - ❌ - - ❌ - - ❌ + - ✔️ + - ✔️ - ❌ * - PWM_v1 - ❓ @@ -158,6 +163,11 @@ API 支持情况 - ✔️ - ✔️ - ✔️ + * - SEC_PKA + - ❓ + - ✔️ + - ✔️ + - ✔️ * - SPI - ❓ - ✔️ @@ -183,6 +193,11 @@ API 支持情况 - ➖ - ✔️ - ✔️ + * - WDG + - ❓ + - ✔️ + - ✔️ + - ✔️ API 列表 --------------- @@ -191,9 +206,11 @@ API 列表 :maxdepth: 1 ADC + CKS CLOCK DAC DMA + FLASH GPIO I2C IRQ @@ -204,6 +221,7 @@ API 列表 RTC SEC_AES SEC_SHA + SEC_PKA SPI TIMER UART diff --git a/docs/source/api_reference/peripherals/irq.rst b/docs/source/api_reference/peripherals/irq.rst index a7611ff9..68fcac9e 100644 --- a/docs/source/api_reference/peripherals/irq.rst +++ b/docs/source/api_reference/peripherals/irq.rst @@ -32,7 +32,7 @@ bflb_irq_save .. code-block:: c :linenos: - uint32_t bflb_irq_save(void); + uintptr_t bflb_irq_save(void); .. list-table:: :widths: 10 10 @@ -51,7 +51,7 @@ bflb_irq_restore .. code-block:: c :linenos: - void bflb_irq_restore(uint32_t flags); + void bflb_irq_restore(uintptr_t flags); .. list-table:: :widths: 10 10 @@ -100,29 +100,6 @@ bflb_irq_detach * - flags - 关闭之前的状态 -bflb_irq_set_priority -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -说明: 设置中断优先级。 - -.. code-block:: c - :linenos: - - void bflb_irq_set_priority(int irq, uint8_t preemptprio, uint8_t subprio); - -.. list-table:: - :widths: 10 10 - :header-rows: 1 - - * - parameter - - description - * - irq - - 中断号 - * - preemptprio - - 抢占优先级 - * - subprio - - 子优先级 - bflb_irq_enable ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -160,3 +137,83 @@ bflb_irq_disable - description * - irq - 中断号 + +bflb_irq_set_pending +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 设置中断 pending 位。 + +.. code-block:: c + :linenos: + + void bflb_irq_set_pending(int irq); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - irq + - 中断号 + +bflb_irq_clear_pending +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 清除中断 pending 位。 + +.. code-block:: c + :linenos: + + void bflb_irq_clear_pending(int irq); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - irq + - 中断号 + +bflb_irq_set_nlbits +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 设置中断分组。 + +.. code-block:: c + :linenos: + + void bflb_irq_set_nlbits(uint8_t nlbits); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - irq + - 中断号 + +bflb_irq_set_priority +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 设置中断优先级。 + +.. code-block:: c + :linenos: + + void bflb_irq_set_priority(int irq, uint8_t preemptprio, uint8_t subprio); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - irq + - 中断号 + * - preemptprio + - 抢占优先级 + * - subprio + - 子优先级 \ No newline at end of file diff --git a/docs/source/api_reference/peripherals/l1c.rst b/docs/source/api_reference/peripherals/l1c.rst index 124ea48f..d40d7e11 100644 --- a/docs/source/api_reference/peripherals/l1c.rst +++ b/docs/source/api_reference/peripherals/l1c.rst @@ -1,11 +1,19 @@ L1C ============= -.. note:: BL602、BL702 无 L1C 函数操作。 - Macros ------------ +无 + +Structs +------------ + +无 + +Functions +------------ + bflb_l1c_icache_enable ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -108,13 +116,3 @@ bflb_l1c_dcache_clean_invalidate_range - 首地址（必须 32 字节对齐） * - len - 长度 - -Structs ------------- - -无 - -Functions ------------- - -无 \ No newline at end of file diff --git a/docs/source/api_reference/peripherals/mtimer.rst b/docs/source/api_reference/peripherals/mtimer.rst index 773e84f1..7c546192 100644 --- a/docs/source/api_reference/peripherals/mtimer.rst +++ b/docs/source/api_reference/peripherals/mtimer.rst @@ -12,4 +12,120 @@ Structs 无 Functions ------------- \ No newline at end of file +------------ + +bflb_mtimer_config +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: mtimer 定时配置。 + +.. code-block:: c + :linenos: + + void bflb_mtimer_config(uint64_t ticks, void (*interruptfun)(void)); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - ticks + - 定时 tick 数 + * - interruptfun + - 中断回调 + +bflb_mtimer_get_freq +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取 mtimer 频率。默认 mtimer 经过分频后设置成了 1M，所以频率就是 1M。 + +.. code-block:: c + :linenos: + + uint32_t bflb_mtimer_get_freq(void); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - return + - 频率 + +bflb_mtimer_delay_ms +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: mtimer 毫秒延时。 + +.. code-block:: c + :linenos: + + void bflb_mtimer_delay_ms(uint32_t time); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - time + - 延时时间 + +bflb_mtimer_delay_us +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: mtimer 微妙延时。 + +.. code-block:: c + :linenos: + + void bflb_mtimer_delay_us(uint32_t time); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - time + - 延时时间 + +bflb_mtimer_get_time_us +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取 mtimer 当前时间，us 为单位。 + +.. code-block:: c + :linenos: + + uint64_t bflb_mtimer_get_time_us(); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - return + - 当前时间 + +bflb_mtimer_get_time_ms +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取 mtimer 当前时间，ms 为单位。 + +.. code-block:: c + :linenos: + + uint64_t bflb_mtimer_get_time_ms(); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - return + - 当前时间 diff --git a/docs/source/api_reference/peripherals/pwm_v1.rst b/docs/source/api_reference/peripherals/pwm_v1.rst index 8c0a1001..d6a54737 100644 --- a/docs/source/api_reference/peripherals/pwm_v1.rst +++ b/docs/source/api_reference/peripherals/pwm_v1.rst @@ -1,13 +1,15 @@ PWM_v1 ============= +.. note:: PWM V1 版本每个 PWM 的所有通道频率可以单独设置。 + Macros ------------ pwm channel ^^^^^^^^^^^^^^ -PWM V1 版本共 5个 pwm 通道。 +PWM V1 版本共 5 个 pwm 通道。（BL702L 只有通道 0）。 Structs ------------ diff --git a/docs/source/api_reference/peripherals/pwm_v2.rst b/docs/source/api_reference/peripherals/pwm_v2.rst index 5a53e281..0c60fb36 100644 --- a/docs/source/api_reference/peripherals/pwm_v2.rst +++ b/docs/source/api_reference/peripherals/pwm_v2.rst @@ -1,15 +1,483 @@ PWM_v2 ============= +.. note:: PWM V2 版本每个 PWM 的所有通道共用一个频率。 + Macros ------------ -无 +pwm channel +^^^^^^^^^^^^^^ + +PWM V2 版本每个 PWM 共 4 个 pwm 通道。 + +pwm polarity +^^^^^^^^^^^^^^ + +PWM V2 版本输出有效极性。当正向通道阈值位于设置的低阈值和高阈值之间，为有效极性，如果设置有效极性为高，则输出高电平，反之输出低电平。反向通道相反，阈值位于设置的低阈值和高阈值之外，为有效极性，如果设置有效极性为高，则输出高电平，反之输出低电平。 + +.. code-block:: c + :linenos: + + #define PWM_POLARITY_ACTIVE_LOW 0 + #define PWM_POLARITY_ACTIVE_HIGH 1 Structs ------------ -无 +struct bflb_pwm_v2_config_s +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +pwm v2 初始化配置结构体。 + +.. code-block:: c + :linenos: + + struct bflb_pwm_v2_config_s { + uint8_t clk_source; + uint16_t clk_div; + uint16_t period; + }; + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - clk_source + - 时钟源选择：PBCLK or XCLK or 32K_CLK + * - clk_div + - 分频值 + * - period + - 周期值 + +.. note:: PWM 最终产生的频率 = clk_source/clk_div/period + +struct bflb_pwm_v2_channel_config_s +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +pwm v2 初始化配置结构体。 + +.. code-block:: c + :linenos: + + struct bflb_pwm_v2_channel_config_s { + uint8_t positive_polarity; + uint8_t negative_polarity; + uint8_t positive_stop_state; + uint8_t negative_stop_state; + uint8_t positive_brake_state; + uint8_t negative_brake_state; + uint8_t dead_time; + }; + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - positive_polarity + - 正向输出极性 + * - negative_polarity + - 反向输出极性 + * - positive_stop_state + - 正向输出空闲状态 + * - negative_stop_state + - 反向输出空闲状态 + * - positive_brake_state + - 正向输出刹车状态 + * - negative_brake_state + - 反向输出刹车状态 + * - dead_time + - 死区时间 Functions ------------- \ No newline at end of file +------------ + +bflb_pwm_v2_init +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 初始化 pwm 。使用之前需要选择 gpio 为 pwm 功能。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_init(struct bflb_device_s *dev, const struct bflb_pwm_v2_config_s *config); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - config + - 配置项 + +bflb_pwm_v2_deinit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 复位 pwm 。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_deinit(struct bflb_device_s *dev); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + +bflb_pwm_v2_start +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 启动 pwm 输出。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_start(struct bflb_device_s *dev); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + +bflb_pwm_v2_stop +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 关闭 pwm 输出。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_stop(struct bflb_device_s *dev); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + +bflb_pwm_v2_set_period +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 修改 pwm 周期值，从而更改 pwm 输出的频率。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_set_period(struct bflb_device_s *dev, uint16_t period); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - period + - 周期值 + +bflb_pwm_v2_channel_init +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: PWM 通道初始化。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_channel_init(struct bflb_device_s *dev, uint8_t ch, struct bflb_pwm_v2_channel_config_s *config); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - ch + - 通道号 + * - config + - 通道配置 + +bflb_pwm_v2_channel_set_threshold +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 设置 PWM 占空比。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_channel_set_threshold(struct bflb_device_s *dev, uint8_t ch, uint16_t low_threhold, uint16_t high_threhold); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - ch + - 通道号 + * - low_threhold + - 低阈值 + * - high_threhold + - 高阈值,需要大于 low_threhold，并且小于等于 period + +.. note:: PWM 占空比 = (high_threhold - low_threhold)/period + +bflb_pwm_v2_channel_positive_start +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: PWM 正向通道使能输出。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_channel_positive_start(struct bflb_device_s *dev, uint8_t ch); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - ch + - 通道号 + +bflb_pwm_v2_channel_negative_start +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: PWM 反向通道使能输出。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_channel_negative_start(struct bflb_device_s *dev, uint8_t ch); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - ch + - 通道号 + +bflb_pwm_v2_channel_positive_stop +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: PWM 正向通道停止输出。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_channel_positive_stop(struct bflb_device_s *dev, uint8_t ch); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - ch + - 通道号 + +bflb_pwm_v2_channel_negative_stop +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: PWM 反向通道停止输出。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_channel_negative_stop(struct bflb_device_s *dev, uint8_t ch); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - ch + - 通道号 + +bflb_pwm_v2_int_enable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: PWM 中断使能和关闭。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_int_enable(struct bflb_device_s *dev, uint32_t int_en, bool enable); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - int_en + - 中断使能位 + * - enable + - 是否开启中断 + +`int_en` 可以填入以下值，多个中断可以使用 `|` 连接： + +.. code-block:: c + :linenos: + + #define PWM_INTEN_CH0_L (1 << 0) + #define PWM_INTEN_CH0_H (1 << 1) + #define PWM_INTEN_CH1_L (1 << 2) + #define PWM_INTEN_CH1_H (1 << 3) + #define PWM_INTEN_CH2_L (1 << 4) + #define PWM_INTEN_CH2_H (1 << 5) + #define PWM_INTEN_CH3_L (1 << 6) + #define PWM_INTEN_CH3_H (1 << 7) + #define PWM_INTEN_PERIOD (1 << 8) + #define PWM_INTEN_BRAKE (1 << 9) + #define PWM_INTEN_REPT (1 << 10) + +bflb_pwm_v2_get_intstatus +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 获取 PWM 中断标志。 + +.. code-block:: c + :linenos: + + uint32_t bflb_pwm_v2_get_intstatus(struct bflb_device_s *dev); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - return + - 返回中断标志 + +返回值如下： + +.. code-block:: c + :linenos: + + #define PWM_INTSTS_CH0_L (1 << 0) + #define PWM_INTSTS_CH0_H (1 << 1) + #define PWM_INTSTS_CH1_L (1 << 2) + #define PWM_INTSTS_CH1_H (1 << 3) + #define PWM_INTSTS_CH2_L (1 << 4) + #define PWM_INTSTS_CH2_H (1 << 5) + #define PWM_INTSTS_CH3_L (1 << 6) + #define PWM_INTSTS_CH3_H (1 << 7) + #define PWM_INTSTS_PERIOD (1 << 8) + #define PWM_INTSTS_BRAKE (1 << 9) + #define PWM_INTSTS_REPT (1 << 10) + +bflb_pwm_v2_int_clear +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: 清除 PWM 中断标志。 + +.. code-block:: c + :linenos: + + void bflb_pwm_v2_int_clear(struct bflb_device_s *dev, uint32_t int_clear); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - int_clear + - 清除值 + +`int_clear` 可以填入以下参数: + +.. code-block:: c + :linenos: + + #define PWM_INTCLR_CH0_L (1 << 0) + #define PWM_INTCLR_CH0_H (1 << 1) + #define PWM_INTCLR_CH1_L (1 << 2) + #define PWM_INTCLR_CH1_H (1 << 3) + #define PWM_INTCLR_CH2_L (1 << 4) + #define PWM_INTCLR_CH2_H (1 << 5) + #define PWM_INTCLR_CH3_L (1 << 6) + #define PWM_INTCLR_CH3_H (1 << 7) + #define PWM_INTCLR_PERIOD (1 << 8) + #define PWM_INTCLR_BRAKE (1 << 9) + #define PWM_INTCLR_REPT (1 << 10) + +bflb_pwm_v2_feature_control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +说明: PWM 其他特性相关控制，一般不常用。 + +.. code-block:: c + :linenos: + + int bflb_pwm_v2_feature_control(struct bflb_device_s *dev, int cmd, size_t arg); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - dev + - 设备句柄 + * - cmd + - 控制字 + * - arg + - 控制参数 + * - return + - 负值表示不支持此命令 + +`cmd` 可以填入以下参数: + +.. code-block:: c + :linenos: + + #define PWM_CMD_SET_TRIG_ADC_SRC (0x01) + #define PWM_CMD_SET_EXT_BRAKE_POLARITY (0x02) + #define PWM_CMD_SET_EXT_BRAKE_ENABLE (0x03) + #define PWM_CMD_SET_SW_BRAKE_ENABLE (0x04) + #define PWM_CMD_SET_STOP_ON_REPT (0x05) + #define PWM_CMD_SET_REPT_COUNT (0x06) \ No newline at end of file diff --git a/docs/source/api_reference/peripherals/sec_aes.rst b/docs/source/api_reference/peripherals/sec_aes.rst new file mode 100644 index 00000000..3100e06c --- /dev/null +++ b/docs/source/api_reference/peripherals/sec_aes.rst @@ -0,0 +1,15 @@ +SEC_AES +============= + +Macros +------------ + +无 + +Structs +------------ + +无 + +Functions +------------ \ No newline at end of file diff --git a/docs/source/api_reference/peripherals/sec_pka.rst b/docs/source/api_reference/peripherals/sec_pka.rst new file mode 100644 index 00000000..45df6cdf --- /dev/null +++ b/docs/source/api_reference/peripherals/sec_pka.rst @@ -0,0 +1,15 @@ +SEC_PKA +============= + +Macros +------------ + +无 + +Structs +------------ + +无 + +Functions +------------ \ No newline at end of file diff --git a/docs/source/api_reference/peripherals/sec_sha.rst b/docs/source/api_reference/peripherals/sec_sha.rst new file mode 100644 index 00000000..032b4a1d --- /dev/null +++ b/docs/source/api_reference/peripherals/sec_sha.rst @@ -0,0 +1,15 @@ +SEC_SHA +============= + +Macros +------------ + +无 + +Structs +------------ + +无 + +Functions +------------ \ No newline at end of file diff --git a/docs/source/api_reference/peripherals/spi.rst b/docs/source/api_reference/peripherals/spi.rst index ace19f9b..6d3a94ca 100644 --- a/docs/source/api_reference/peripherals/spi.rst +++ b/docs/source/api_reference/peripherals/spi.rst @@ -309,7 +309,7 @@ bflb_spi_errint_mask bflb_spi_get_intstatus ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -说明: 获取 uart 中断标志。 +说明: 获取 spi 中断标志。 .. code-block:: c :linenos: @@ -332,16 +332,17 @@ bflb_spi_get_intstatus .. code-block:: c :linenos: - SPI_TXF_INT - SPI_RXF_INT - SPI_STO_INT - SPI_TXU_INT - SPI_FER_INT + #define SPI_INTSTS_TC (1 << 0) + #define SPI_INTSTS_TX_FIFO (1 << 1) + #define SPI_INTSTS_RX_FIFO (1 << 2) + #define SPI_INTSTS_SLAVE_TIMEOUT (1 << 3) + #define SPI_INTSTS_SLAVE_TX_UNDERRUN (1 << 4) + #define SPI_INTSTS_FIFO_ERR (1 << 5) bflb_spi_int_clear ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -说明: 清除 uart 中断标志。 +说明: 清除 spi 中断标志。 .. code-block:: c :linenos: @@ -364,8 +365,9 @@ bflb_spi_int_clear .. code-block:: c :linenos: - SPI_CR_SPI_STO_CLR - SPI_CR_SPI_TXU_CLR + #define SPI_INTCLR_TC (1 << 16) + #define SPI_INTCLR_SLAVE_TIMEOUT (1 << 19) + #define SPI_INTCLR_SLAVE_TX_UNDERRUN (1 << 20) bflb_spi_feature_control ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/api_reference/peripherals/timer.rst b/docs/source/api_reference/peripherals/timer.rst index e17d73d1..51dfe1d4 100644 --- a/docs/source/api_reference/peripherals/timer.rst +++ b/docs/source/api_reference/peripherals/timer.rst @@ -7,7 +7,7 @@ Macros timer clock source ^^^^^^^^^^^^^^^^^^^^^^ -定时器输入时钟源可以选择以下类型，注意： `TIMER_CLKSRC_GPIO` BL602/BL702 系列没有此功能 +定时器输入时钟源可以选择以下类型，注意： `TIMER_CLKSRC_GPIO` BL602/BL702 系列没有此功能。 .. code-block:: c :linenos: @@ -22,7 +22,7 @@ timer clock source timer counter mode ^^^^^^^^^^^^^^^^^^^^^^ -定时器计数模式分为两种: freerun(向上计数模式)、preload(重装载模式) +定时器计数模式分为两种: freerun(向上计数模式)、preload(重装载模式)。 .. code-block:: c :linenos: @@ -33,7 +33,7 @@ timer counter mode timer compare id ^^^^^^^^^^^^^^^^^^^^^^ -定时器一共三个 compare id,用于设置不同的定时时间，当三个定时器使用 +定时器一共三个 compare id, 用于设置不同的定时时间，可以当三个定时器使用。 .. code-block:: c :linenos: diff --git a/docs/source/api_reference/peripherals/uart.rst b/docs/source/api_reference/peripherals/uart.rst index b8a389a6..1f47fa40 100644 --- a/docs/source/api_reference/peripherals/uart.rst +++ b/docs/source/api_reference/peripherals/uart.rst @@ -228,7 +228,7 @@ bflb_uart_getchar * - dev - 设备句柄 * - return - - 返回 -1 表示没有数据，返回其他表示接收字符 + - 返回 -1 表示没有数据，返回其他表示接收的字符 bflb_uart_txready ^^^^^^^^^^^^^^^^^^^^ @@ -487,4 +487,13 @@ bflb_uart_feature_control #define UART_CMD_SET_TX_RS485_EN (0x11) #define UART_CMD_SET_TX_RS485_POLARITY (0x12) #define UART_CMD_SET_ABR_ALLOWABLE_ERROR (0x13) - #define UART_CMD_SET_SW_RTS_CONTROL (0x14) \ No newline at end of file + #define UART_CMD_SET_SW_RTS_CONTROL (0x14) + #define UART_CMD_IR_CONFIG (0x15) + #define UART_CMD_SET_TX_FREERUN (0x16) + #define UART_CMD_SET_TX_END_INTERRUPT (0x17) + #define UART_CMD_SET_RX_END_INTERRUPT (0x18) + #define UART_CMD_SET_TX_TRANSFER_LEN (0x19) + #define UART_CMD_SET_RX_TRANSFER_LEN (0x20) + #define UART_CMD_SET_TX_EN (0x21) + #define UART_CMD_SET_BCR_END_INTERRUPT (0x22) + #define UART_CMD_GET_BCR_COUNT (0x23) \ No newline at end of file diff --git a/docs/source/api_reference/utils/libc.rst b/docs/source/api_reference/utils/libc.rst index 10ef51ce..ecbfe37e 100644 --- a/docs/source/api_reference/utils/libc.rst +++ b/docs/source/api_reference/utils/libc.rst @@ -3,12 +3,14 @@ LIBC 简介 ------------ + - LIBC 中实现了一个vsnprintf，用以避开使用完整的c库，减少代码体积。 .. note:: LIBC 中浮点打印只能最大支持到7位小数精度 配置LIBC相关功能 ------------- +------------------- + 如果需要配置LIBC的相关功能需要在对应的工程目录下 `proj.conf` 文件中添加对应的代码，举例如下： .. code-block:: cmake @@ -18,9 +20,9 @@ LIBC set(CONFIG_VSNPRINTF_FLOAT 1) 格式化控制字符 ------------- +---------------- -.. list-table:: +.. list-table:: :header-rows: 1 * - proj.conf 配置项 @@ -34,7 +36,7 @@ LIBC * - CONFIG_VSNPRINTF_LONG_LONG - 使能格式化输出 (%lld,%lli,%llo,%llx,%llX,%llu) 长整型格式化支持 -.. list-table:: +.. list-table:: :header-rows: 1 * - 格式化控制字符 (specifier) @@ -68,7 +70,7 @@ LIBC * - %n - ❌ -.. list-table:: +.. list-table:: :header-rows: 1 * - 格式化控制变量长度字符 (length) @@ -88,7 +90,7 @@ LIBC * - z - ✔️ -.. list-table:: +.. list-table:: :header-rows: 1 * - 格式化控制标志字符 (flags) @@ -105,7 +107,7 @@ LIBC - ✔️ 格式化输出格式 ------------- +---------------- .. code-block:: c :linenos: diff --git a/docs/source/api_reference/utils/vlibc.rst b/docs/source/api_reference/utils/vlibc.rst index 97db8731..a29e8dd5 100644 --- a/docs/source/api_reference/utils/vlibc.rst +++ b/docs/source/api_reference/utils/vlibc.rst @@ -3,6 +3,7 @@ VLIBC 简介 ------------ + - VLIBC 是适用于MCU使用的C标准库 STDIO的重新实现，与标准的STDIO库具有相同的API以及相同的使用方法。 - VLIBC 支持文件操作，诸如fopen、fwrite、fprintf等API，与Fatfs文件系统对接，为其他依赖标准C库文件操作的组件提供支持。 - VLIBC 同时支持对外设进行操作，例如将UART当做文件进行处理，使用fprintf进行输出。 @@ -11,7 +12,8 @@ VLIBC .. note:: VLIBC 中浮点打印只能最大支持到11位小数精度 配置VLIBC相关功能 ------------- +-------------------- + 如果需要配置VLIBC的相关功能需要在对应的工程目录下 `proj.conf` 文件中添加对应的代码，举例如下： .. code-block:: cmake @@ -21,9 +23,9 @@ VLIBC set(CONFIG_VSNPRINTF_FLOAT 1) 格式化控制字符 ------------- +----------------- -.. list-table:: +.. list-table:: :header-rows: 1 * - proj.conf 配置项 @@ -41,7 +43,7 @@ VLIBC * - CONFIG_VSNPRINTF_WRITEBACK - 使能格式化字符 (%n) 字符统计支持 -.. list-table:: +.. list-table:: :header-rows: 1 * - 格式化控制字符 (specifier) @@ -75,7 +77,7 @@ VLIBC * - %n - ✔️ -.. list-table:: +.. list-table:: :header-rows: 1 * - 格式化控制变量长度字符 (length) @@ -95,7 +97,7 @@ VLIBC * - z - ✔️ -.. list-table:: +.. list-table:: :header-rows: 1 * - 格式化控制标志字符 (flags) @@ -112,7 +114,8 @@ VLIBC - ✔️ 格式化输出格式 ------------- +-------------------- + .. code-block:: c :linenos: @@ -125,7 +128,7 @@ VLIBC printf("% 8x\r\n", var) IO 接口移植 ------------- +--------------- .. code-block:: c :linenos: @@ -187,5 +190,6 @@ IO 接口移植 API参考 ------------ + - API 基本与标准C库一致 - 等待完善 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index ff81db97..48b17c7d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,74 +1,74 @@ -# Configuration file for the Sphinx documentation builder. - -# -- Project information - -project = 'CherryUSB' -copyright = '2022, sakumisu' -author = 'sakumisu' - -release = '0.4' -version = '0.4.0' - -# -- General configuration - -extensions = [ - 'sphinx.ext.duration', - 'sphinx.ext.doctest', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', - 'recommonmark', - 'sphinx_markdown_tables' -] - -intersphinx_mapping = { -# 'python': ('https://docs.python.org/3/', None), -# 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), -} -intersphinx_disabled_domains = ['std'] - -templates_path = ['_templates'] - -# -- Options for HTML output - -html_theme = 'sphinx_rtd_theme' - -# -- Options for EPUB output -epub_show_urls = 'footnote' -# Configuration file for the Sphinx documentation builder. - -# -- Project information - -project = 'BL_MCU_SDK' -copyright = '2022, Bouffalolab Team' -author = 'Bouffalolab Team' - -release = '0.1' -version = '0.1.0' - -# -- General configuration - -extensions = [ - 'sphinx.ext.duration', - 'sphinx.ext.doctest', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', - 'recommonmark', - 'sphinx_markdown_tables' -] - -intersphinx_mapping = { -# 'python': ('https://docs.python.org/3/', None), -# 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), -} -intersphinx_disabled_domains = ['std'] - -templates_path = ['_templates'] - -# -- Options for HTML output - -html_theme = 'sphinx_rtd_theme' - -# -- Options for EPUB output -epub_show_urls = 'footnote' +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'CherryUSB' +copyright = '2022, sakumisu' +author = 'sakumisu' + +release = '0.4' +version = '0.4.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'recommonmark', + 'sphinx_markdown_tables' +] + +intersphinx_mapping = { +# 'python': ('https://docs.python.org/3/', None), +# 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'BL_MCU_SDK' +copyright = '2022, Bouffalolab Team' +author = 'Bouffalolab Team' + +release = '0.1' +version = '0.1.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'recommonmark', + 'sphinx_markdown_tables' +] + +intersphinx_mapping = { +# 'python': ('https://docs.python.org/3/', None), +# 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' diff --git a/docs/source/get_started/cmake.rst b/docs/source/get_started/cmake.rst index e7adb15d..6e7e8e48 100644 --- a/docs/source/get_started/cmake.rst +++ b/docs/source/get_started/cmake.rst @@ -37,13 +37,16 @@ CMake 框架的使用 - 添加静态库（满足 if 条件） * - sdk_add_subdirectory_ifdef - 编译子目录下的 cmakelist（满足 if 条件） + * - sdk_add_static_library + - 添加外部静态库 * - sdk_set_linker_script - 设置链接脚本 * - sdk_set_main_file - 设置 main 函数所在文件 * - project - 工程编译 - + * - target_source(app PRIVATE xxx) + - 添加源文件到 app 库中，当用户需要自己添加一些源文件又不想创建 cmakelist 单独编译成库，可以使用该项 新建工程 ---------------- diff --git a/docs/source/get_started/debug.rst b/docs/source/get_started/debug.rst index 29ddbef4..e3479d80 100644 --- a/docs/source/get_started/debug.rst +++ b/docs/source/get_started/debug.rst @@ -41,54 +41,8 @@ 使用 CKLink + Eclipse 调试代码 ------------------------------------------- -- 从 Bouffalo Lab 开发者社区下载带有 RISC-V 工具链的 `Eclipse 安装包 `_ 。 - 从 T-HEAD 官网下载最新版本 `CKLink 驱动 `_ -安装和配置 Eclipse -^^^^^^^^^^^^^^^^^^^^ - -- 将获取到的 eclipse 压缩包拷贝到您的工作目录，解压 eclipse 压缩包 -- 进入 eclipse 目录，双击 ``eclipse.exe`` 启动 eclipse -- 选择您的 ``Workspace`` 目录，点击 ``Launch`` 进入工作空间 - -.. figure:: img/eclipse1.png - :alt: - -- 点击菜单栏中 ``Window->preferences`` 打开环境配置相关页面，准备导入相关的配置环境 - -.. figure:: img/eclipse2.png - :alt: - -- 点击下图 1 处的图标，打开导入配置界面，按照如图所示步骤，选择 ``eclipse.exe`` 目录下的 ``bflb_mcu_preferences.epf`` 配置文件。 - -.. figure:: img/eclipse3.png - :alt: - -- 选择好对应的文件后，点击 ``Finish``，在弹出的对话框选中点击 ``cancel`` ，不用重新启动。 - -.. figure:: img/eclipse4.png - :alt: - -- 点击 菜单栏 ``File->Import`` ，打开导入项目的配置界面 - -.. figure:: img/eclipse5.png - :alt: - -- 在打开的 ``Import`` 窗口中选择 ``C/C++->Existing Code as Makefile Project`` ，然后点击 ``Next`` - -.. figure:: img/eclipse6.png - :alt: - -- 导入 bl_mcu_sdk 的工程路径后，点击 ``Finsh`` 完成 - -.. figure:: img/eclipse7.png - :alt: - -- 最终效果如下 - -.. figure:: img/eclipse8.png - :alt: - 安装和配置 CKLink ^^^^^^^^^^^^^^^^^^^^ @@ -105,23 +59,7 @@ .. figure:: img/cklink3.png :alt: - -调试 ELF +使用 Eclipse 调试 ^^^^^^^^^^^^^^^^^^^^ -完成上述两步以后，如果是在 **flash 上调试，需要先将 bin 文件烧录到芯片中** ，最后才能够进行下面的调试环节。 - -- 在 Eclipse 中 点击 `debug` 图标，并点击 `Debug Configurations` - -.. figure:: img/eclipse9.png - :alt: - -- 左侧打开 `GDB Hardware Debugging`，选择对应芯片的配置按钮，并导入编译生成的 **elf**,最后点击 `Debug` - -.. figure:: img/eclipse10.png - :alt: - -- 最终进入调试界面 - -.. figure:: img/eclipse11.png - :alt: +参考 :ref:`eclipse_gcc` diff --git a/docs/source/get_started/eclipse.rst b/docs/source/get_started/eclipse.rst new file mode 100644 index 00000000..4a39557b --- /dev/null +++ b/docs/source/get_started/eclipse.rst @@ -0,0 +1,69 @@ +.. _eclipse_gcc: + +Build and Debug with Eclipse +================================= + +本节主要介绍如何使用 Eclipse 进行开发。 + +环境搭建 +------------- + +- 首先下载 `Eclipse `_ , 选择 **Eclipse IDE for C/C++ Developers** , 并根据你的电脑版本进行下载。 + +.. figure:: img/eclipse1.png + :alt: + +- 其余需要的环境参考 :ref:`windows_cmd` + +- 解压 Eclipse 并双击打开 `Eclipse.exe` + +.. figure:: img/eclipse2.png + :alt: + +- 选择工作路径并点击 `Launch` + +.. figure:: img/eclipse3.png + :alt: + +- 点击左上角 `File` 选择 `Import`，选择 `General > Existing project into workspace` 并点击 `Next` + +.. figure:: img/eclipse4.png + :alt: + +- 导入 bl_mcu_sdk + +.. figure:: img/eclipse5.png + :alt: + +编译 +------------- + +- 双击 `Build Targets` 中的 `make` 即可编译 helloworld。双击 `clean` 即可清除 helloworld 下的缓存 + +.. figure:: img/eclipse6.png + :alt: + +- 如果需要更换 demo ，右击 `Build Targets` 中的 `make`，修改中间方框里的内容即可，内容为指定 demo 下 Makefile 文件的路径 + +.. figure:: img/eclipse7.png + :alt: + +调试 +------------- + +完成上述步骤以后，如果是在 **flash 上调试，需要先将 bin 文件烧录到芯片中** ，然后才能够进行下面的调试环节。 + +- 在 Eclipse 中 点击 `debug` 图标，并点击 `Debug Configurations` + +.. figure:: img/eclipse8.png + :alt: + +- 左侧打开 `GDB Hardware Debugging`，选择对应芯片的配置按钮，并导入编译生成的 **elf**, 最后点击 `Debug` + +.. figure:: img/eclipse9.png + :alt: + +- 最终进入调试界面 + +.. figure:: img/eclipse10.png + :alt: diff --git a/docs/source/get_started/img/eclipse1.png b/docs/source/get_started/img/eclipse1.png index 9866e309..54524026 100644 Binary files a/docs/source/get_started/img/eclipse1.png and b/docs/source/get_started/img/eclipse1.png differ diff --git a/docs/source/get_started/img/eclipse10.png b/docs/source/get_started/img/eclipse10.png index 645071f4..ed88d031 100644 Binary files a/docs/source/get_started/img/eclipse10.png and b/docs/source/get_started/img/eclipse10.png differ diff --git a/docs/source/get_started/img/eclipse11.png b/docs/source/get_started/img/eclipse11.png deleted file mode 100644 index 3fd4ef3c..00000000 Binary files a/docs/source/get_started/img/eclipse11.png and /dev/null differ diff --git a/docs/source/get_started/img/eclipse2.png b/docs/source/get_started/img/eclipse2.png index 2d5129bc..726b9ebb 100644 Binary files a/docs/source/get_started/img/eclipse2.png and b/docs/source/get_started/img/eclipse2.png differ diff --git a/docs/source/get_started/img/eclipse3.png b/docs/source/get_started/img/eclipse3.png index 0e20a992..ef249be7 100644 Binary files a/docs/source/get_started/img/eclipse3.png and b/docs/source/get_started/img/eclipse3.png differ diff --git a/docs/source/get_started/img/eclipse4.png b/docs/source/get_started/img/eclipse4.png index 9424826d..e666db06 100644 Binary files a/docs/source/get_started/img/eclipse4.png and b/docs/source/get_started/img/eclipse4.png differ diff --git a/docs/source/get_started/img/eclipse5.png b/docs/source/get_started/img/eclipse5.png index 40158e36..7466772f 100644 Binary files a/docs/source/get_started/img/eclipse5.png and b/docs/source/get_started/img/eclipse5.png differ diff --git a/docs/source/get_started/img/eclipse6.png b/docs/source/get_started/img/eclipse6.png index 0ce0f1f5..d1215b64 100644 Binary files a/docs/source/get_started/img/eclipse6.png and b/docs/source/get_started/img/eclipse6.png differ diff --git a/docs/source/get_started/img/eclipse7.png b/docs/source/get_started/img/eclipse7.png index ee0ad4ef..229c4c69 100644 Binary files a/docs/source/get_started/img/eclipse7.png and b/docs/source/get_started/img/eclipse7.png differ diff --git a/docs/source/get_started/img/eclipse8.png b/docs/source/get_started/img/eclipse8.png index 5a3e87c0..10c926eb 100644 Binary files a/docs/source/get_started/img/eclipse8.png and b/docs/source/get_started/img/eclipse8.png differ diff --git a/docs/source/get_started/img/eclipse9.png b/docs/source/get_started/img/eclipse9.png index e18f7da5..17458465 100644 Binary files a/docs/source/get_started/img/eclipse9.png and b/docs/source/get_started/img/eclipse9.png differ diff --git a/docs/source/get_started/img/windows_path.png b/docs/source/get_started/img/windows_path.png index 75513b84..00aae81d 100644 Binary files a/docs/source/get_started/img/windows_path.png and b/docs/source/get_started/img/windows_path.png differ diff --git a/docs/source/get_started/img/windows_path2.png b/docs/source/get_started/img/windows_path2.png deleted file mode 100644 index fbf3816c..00000000 Binary files a/docs/source/get_started/img/windows_path2.png and /dev/null differ diff --git a/docs/source/get_started/img/windows_path3.png b/docs/source/get_started/img/windows_path3.png deleted file mode 100644 index 1cbc09fb..00000000 Binary files a/docs/source/get_started/img/windows_path3.png and /dev/null differ diff --git a/docs/source/get_started/index.rst b/docs/source/get_started/index.rst index 8b48595b..626c3a7b 100644 --- a/docs/source/get_started/index.rst +++ b/docs/source/get_started/index.rst @@ -10,3 +10,4 @@ BL MCU SDK 提供了以下几种开发环境，包含安装、编译、烧录和 Windows_CDK Windows_CMD Linux or WSL + Eclipse diff --git a/docs/source/get_started/linux_wsl.rst b/docs/source/get_started/linux_wsl.rst index 8bc5d257..6816b14e 100644 --- a/docs/source/get_started/linux_wsl.rst +++ b/docs/source/get_started/linux_wsl.rst @@ -1,32 +1,23 @@ -Linux or WSL +.. _linux_cmd: + +Build with Linux or WSL ================================ 本节主要介绍如何在 Linux 或者 WSL 下使用 **命令行** 进行开发。Windows 下如何安装 WSL 请自行百度。 -安装 +环境搭建 ----------------- -安装前需要下载好 git 工具。 +- 首先打开 linux 终端，并安装依赖工具 .. code-block:: bash :linenos: :emphasize-lines: 1 $ cd ~ - $ sudo apt install git + $ sudo apt install git make ninja-build -y -安装 make -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: bash - :linenos: - :emphasize-lines: 1 - - $ cd ~ - $ sudo apt install make - -安装 RISC-V 工具链 -^^^^^^^^^^^^^^^^^^^^^^^^ +- 其次使用 git 下载 RISC-V 工具链 .. code-block:: bash :linenos: @@ -38,10 +29,7 @@ Linux or WSL $ echo "export PATH=\"$PATH:/usr/bin/toolchain_gcc_t-head_linux/bin\"" >> ~/.bashrc $ source ~/.bashrc -安装检查 -------------- - -完成上述两步以后，需要检查是否真的安装成功。打开 linux 终端。输入下列命令： +- 完成上述步骤以后，需要检查是否真的安装成功，输入下列命令： .. code-block:: bash :linenos: @@ -60,7 +48,6 @@ Linux or WSL This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. - .. code-block:: bash :linenos: @@ -81,7 +68,7 @@ Linux or WSL gcc version 10.2.0 (Xuantie-900 elf newlib gcc Toolchain V2.2.5 B-20220323) -在 linux 中，有严格的权限限制，通常一个用户对应一个权限，所以如果提示下面信息，表示需要设置 cmake 权限。 +- 在 linux 中，有严格的权限限制，通常一个用户对应一个权限，所以如果提示下面信息，表示需要设置 cmake 权限。 .. figure:: img/cmake_error.png :align: center @@ -91,17 +78,28 @@ Linux or WSL .. code-block:: bash :linenos: + $ cd bl_mcu_sdk $ sudo chmod +x tools/cmake/bin/cmake 编译 ------------- -进入 **examples** ,选择你想要编译的 case，且该 case 下必须有 **main.c** 文件。生成的 bin 文件会输出到 `build/build_out` 目录下。 +打开 linux 终端，进入 **examples** ，选择你想要编译的 case，且该 case 下必须有 **Makefile** 文件。使用下面命令编译，生成的 bin 文件会输出到 `build/build_out` 目录下。 + +- 使用 make 编译 .. code-block:: bash :linenos: - $ cd .\examples\helloworld\ + $ cd examples/helloworld $ make CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 +- 使用 ninja 编译 + +.. code-block:: bash + :linenos: + + $ cd examples/helloworld + $ make ninja CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 + .. note :: 如果使用 BL808 或者 BL606P，需要在上面基础上添加 CPU_ID=id ,id 可以为 m0 或者 d0 \ No newline at end of file diff --git a/docs/source/get_started/windows_cdk.rst b/docs/source/get_started/windows_cdk.rst index 80abb403..991716f0 100644 --- a/docs/source/get_started/windows_cdk.rst +++ b/docs/source/get_started/windows_cdk.rst @@ -1,2 +1,2 @@ -Windows CDK -============== \ No newline at end of file +Build and Debug with CDK +============================ \ No newline at end of file diff --git a/docs/source/get_started/windows_cmd.rst b/docs/source/get_started/windows_cmd.rst index 21c8a53b..a67361ed 100644 --- a/docs/source/get_started/windows_cmd.rst +++ b/docs/source/get_started/windows_cmd.rst @@ -1,44 +1,29 @@ -Windows CMD -============== +.. _windows_cmd: + +Build with Windows CMD +============================ 本节主要介绍如何在 Windows 下使用 **命令行** 进行开发。 -安装 +环境搭建 ----------------- -安装前需要下载好 git 工具。这里自行百度。 - -安装 make -^^^^^^^^^^^^^^^^^^^^^^^^ - -在 `bl_mcu_sdk/tools/make` 目录下已经准备好了 windows 版本的 make 工具，将 make 工具的绝对路径配置到系统环境变量即可。如图所示： - -.. figure:: img/windows_path.png - :align: center - -.. figure:: img/windows_path2.png - :align: center - -安装 RISC-V 工具链 -^^^^^^^^^^^^^^^^^^^^^^^^ - -克隆 windows 端工具链到你的目录。 +- 首先需要安装 git 工具，这里自行百度。 +- 使用 git 下载 RISC-V 工具链, 这里比如安装到 D 盘 .. code-block:: bash :linenos: :emphasize-lines: 1 + $ cd d $ git clone git@gitee.com:bouffalolab/toolchain_gcc_t-head_windows.git -设置工具链的路径到环境变量中, 如图所示： +- 将 make、ninja、下载的 risc-v 工具链路径配置到系统环境变量中, 其中 make 和 ninja 工具位于 `bl_mcu_sdk/tools` 目录下。 -.. figure:: img/windows_path3.png - :align: center +.. figure:: img/windows_path.png + :alt: -安装检查 -------------- - -完成上述两步以后，需要检查是否真的安装成功。打开 powershell 或者 cmd。输入下列命令： +- 完成上述步骤以后，需要检查是否真的安装成功。打开 powershell 或者 cmd，输入下列命令： .. code-block:: bash :linenos: @@ -79,7 +64,9 @@ Windows CMD 编译 ------------- -进入 **examples** ,选择你想要编译的 case，且该 case 下必须有 **main.c** 文件。生成的 bin 文件会输出到 `build/build_out` 目录下。 +打开 powershell 或者 cmd，进入 **examples** ，选择你想要编译的 case，且该 case 下必须有 **Makefile** 文件。使用下面命令编译，生成的 bin 文件会输出到 `build/build_out` 目录下。 + +- 使用 make 编译 .. code-block:: bash :linenos: @@ -87,4 +74,12 @@ Windows CMD $ cd .\examples\helloworld\ $ make CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 +- 使用 ninja 编译 + +.. code-block:: bash + :linenos: + + $ cd .\examples\helloworld\ + $ make ninja CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 + .. note :: 如果使用 BL808 或者 BL606P，需要在上面基础上添加 CPU_ID=id ,id 可以为 m0 或者 d0 \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 93741439..109c4d6a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,3 +30,19 @@ BL MCU SDK 使用指南 :caption: 基础例程 samples/peripherals/index + samples/components/index + +.. toctree:: + :maxdepth: 1 + :caption: 进阶例程 + + advance_samples/index + +.. toctree:: + :maxdepth: 1 + :caption: 应用笔记 + + notes/note_uart + notes/note_dma + notes/note_cache + notes/note_808dualcore diff --git a/docs/source/notes/img/devcube_808.png b/docs/source/notes/img/devcube_808.png new file mode 100644 index 00000000..66688b6e Binary files /dev/null and b/docs/source/notes/img/devcube_808.png differ diff --git a/docs/source/notes/img/dma_lli.png b/docs/source/notes/img/dma_lli.png new file mode 100644 index 00000000..6442a0d9 Binary files /dev/null and b/docs/source/notes/img/dma_lli.png differ diff --git a/docs/source/notes/img/dma_lli.svg b/docs/source/notes/img/dma_lli.svg new file mode 100644 index 00000000..ce44652b --- /dev/null +++ b/docs/source/notes/img/dma_lli.svg @@ -0,0 +1,325 @@ + +image/svg+xmlSource AddressDest AddressNext LLIDMA ControlSource AddressDest AddressNext LLIDMA ControlSource AddressDest AddressNext LLIDMA ControlSource AddressDest AddressNext LLIDMA ControlIDLEchannel enableIntTCEnable=0IntTCEnable=0IntTCEnable=0IntTCEnable=1 diff --git a/docs/source/notes/img/dma_lli2.png b/docs/source/notes/img/dma_lli2.png new file mode 100644 index 00000000..6b77b4fa Binary files /dev/null and b/docs/source/notes/img/dma_lli2.png differ diff --git a/docs/source/notes/img/uart_sig.png b/docs/source/notes/img/uart_sig.png new file mode 100644 index 00000000..04c55882 Binary files /dev/null and b/docs/source/notes/img/uart_sig.png differ diff --git a/docs/source/notes/note_808dualcore.rst b/docs/source/notes/note_808dualcore.rst new file mode 100644 index 00000000..40fb9c67 --- /dev/null +++ b/docs/source/notes/note_808dualcore.rst @@ -0,0 +1,53 @@ +BL808 双核启动流程 +======================= + +本节主要介绍 BL808 M0 和 D0 两个核的启动流程。首先我们需要知道以下信息： + +- M0 使用 t-head E907 ,D0 使用 t-head C906，为异构双核 +- M0 和 D0 外设共享，但是中断不共享，M0 能触发的中断不一定能在 D0上触发，比如 UART0，中断只能在 M0 上使用 +- 工具烧录时，MCU 界面有 group0 和 group1 选项 + +工具烧写的秘密 +------------------ + +在工具上，烧录的时候会提示选择 group0 和 group1, 如果都不选的话，是没法烧录代码的。假如我们使用 M0 选择 group0，D0 unused，那么就是简单的 +单核启动，D0 不会启动。如果 M0 选择 group0，D0 选择 group1，则两个核都会启动。那么问题来了，为什么工具选了之后会影响双核启动呢？原因就是工具选完后的配置，会在 +烧录的时候传递给 bootrom，bootrom 会做处理。那么我们就知道了双核启动的第一步了。 + +.. figure:: img/devcube_808.png + :alt: + + +SystemInit 干了什么 +------------------------- + +``SystemInit`` 函数位于 `soc/bl808/startup/m0` 和 `soc/bl808/startup/d0` 中的 `system_bl808.c` 中。 + +系统启动时，会根据 ld 文件中设置的 entry(__start) 去找 ``__start`` 函数, 这个便是我们芯片启动的入口，位于 `start.S` 中。看标题可以知道，我们主要是了解 +``SystemInit`` 函数干了什么，而 `start.S` 中做了什么是不需要关心的，只需要知道，里面会调用 ``SystemInit`` 函数。 + +- D0 ``SystemInit`` + +首先我们先看 D0 ``SystemInit``，一上来就是一个 while 死循环，系统启动时，这个条件一定是不会满足的，所以 D0 一上来就会在这死循环，等待条件成立。 + +.. code-block:: c + :linenos: + + while ((BL_RD_WORD(IPC_SYNC_ADDR1) != IPC_SYNC_FLAG) || + (BL_RD_WORD(IPC_SYNC_ADDR2) != IPC_SYNC_FLAG)) { + // clang-format off + __NOP(); __NOP(); __NOP(); __NOP(); + __NOP(); __NOP(); __NOP(); __NOP(); + __NOP(); __NOP(); __NOP(); __NOP(); + __NOP(); __NOP(); __NOP(); __NOP(); + // clang-format on + /* if cache is off, comment this and this api need to start load itcm*/ + // L1C_DCache_Invalid_By_Addr(IPC_SYNC_ADDR1, 8); + }; + /* clear this flags for system reboot */ + BL_WR_WORD(IPC_SYNC_ADDR1, 0x0); + BL_WR_WORD(IPC_SYNC_ADDR2, 0x0); + +- M0 ``SystemInit`` + +根据上述信息我们知道， M0 一定会在某个时刻，向这两个寄存器写入 ``IPC_SYNC_FLAG``, 从而让 D0 运行起来。 \ No newline at end of file diff --git a/docs/source/notes/note_cache.rst b/docs/source/notes/note_cache.rst new file mode 100644 index 00000000..968f04e4 --- /dev/null +++ b/docs/source/notes/note_cache.rst @@ -0,0 +1,2 @@ +CACHE 一致性问题如何解决 +=============================== \ No newline at end of file diff --git a/docs/source/notes/note_dma.rst b/docs/source/notes/note_dma.rst new file mode 100644 index 00000000..85d1bcf7 --- /dev/null +++ b/docs/source/notes/note_dma.rst @@ -0,0 +1,98 @@ +DMA 链表模式（LLI）深度解析 +=============================== + +博流系列芯片的 DMA 都支持链表模式（LLI）。 + +在进行一次 DMA 读或者写的时候，可以配置多个链表，从而当一个链表的数据传输完成时，会跳到下一个链表的起始地址，并继续传输数据，直到链表的下一个地址为 0。如果 DMA 使能了完成中断，则当 DMA 发送或者接收完成时，会进入完成中断。 + +.. figure:: img/dma_lli.svg + :alt: + +那么有了这种 DMA 链表模式，我们就可以实现以下功能： + +- DMA 发送或者接收长度不限制 +- DMA 发送接收地址可以不连续 +- DMA 实现多种中断模式，半中断、3中断、4中断等等 +- DMA 实现循环功能 + +OK，那么当我们开始研究链表配置之前，我们需要了解一些前提： +- 每个链表最多传输 4095 ,单位根据位宽决定 +- 每个链表都可以触发中断 + + +支持长度不限制 +-------------------- + +由于每个 dma 链表最多支持 4905，假设位宽用的是字节，那么一个链表最多传输 4095 字节，很显然这个不能满足我们需求，性能太低。那么如何提高传输长度呢？ + +我们可以使用多个链表，串接起来，这样就能够支持更大的传输长度了，并且传输的地址是连续的，dma 链表连接如图所示： + +.. figure:: img/dma_lli.png + :alt: + + +这个时候还有一个问题，当一个链表使用了 4095 字节，下一个链表是从 4095 的偏移开始，这个时候，就会产生非对齐的问题，如果是在 cache 场景下，是会有问题的。 +因此，我们将 4095 减少到 4064，这样保证每个链表的首地址都是 32 字节对齐的。到这就实现了长度不限制的功能，具体实现参考 ``bflb_dma_lli_config`` 函数。 + +.. code-block:: c + :linenos: + + void bflb_dma_lli_config(struct bflb_device_s *dev, struct bflb_dma_channel_lli_pool_s *lli_pool, uint32_t lli_count, uint32_t src_addr, uint32_t dst_addr, uint32_t transfer_offset, uint32_t last_transfer_len) + { + uint32_t channel_base; + union bflb_dma_lli_control_s dma_ctrl_cfg; + + channel_base = dev->reg_base; + + dma_ctrl_cfg = (union bflb_dma_lli_control_s)getreg32(channel_base + DMA_CxCONTROL_OFFSET); + + dma_ctrl_cfg.bits.TransferSize = 4064; + dma_ctrl_cfg.bits.I = 0; + + /* nbytes will be integer multiple of 4064*n or 4064*2*n or 4064*4*n,(n>0) */ + for (uint32_t i = 0; i < lli_count; i++) { + lli_pool[i].src_addr = src_addr; + lli_pool[i].dst_addr = dst_addr; + lli_pool[i].nextlli = 0; + + if (dma_ctrl_cfg.bits.SI) { + src_addr += transfer_offset; + } + + if (dma_ctrl_cfg.bits.DI) { + dst_addr += transfer_offset; + } + + if (i == lli_count - 1) { + dma_ctrl_cfg.bits.TransferSize = last_transfer_len; + dma_ctrl_cfg.bits.I = 1; + } + + if (i) { + lli_pool[i - 1].nextlli = (uint32_t)(uintptr_t)&lli_pool[i]; + } + + lli_pool[i].control = dma_ctrl_cfg; + } + } + +支持地址不连续 +-------------------- + +刚刚我们解决了长度限制问题，那么本身 dma 链表是支持地址不连续的，我们只需要把上面使用的多个链表当成一个大链表，然后两个大链表拼接，并且两个链表传输的首地址不连续，就可以实现地址不连续了。 +具体实现参考 ``bflb_dma_channel_lli_reload`` 函数中的 ``bflb_dma_channel_lli_transfer_s``。dma 链表连接如图所示： + +.. figure:: img/dma_lli2.png + :alt: + + +支持多中断 +-------------------- + +完成了上述两步以后，多中断也就完成了。 +当我们支持完长度不限制后，最后一个链表会开启中断，当传输完成最后一个链表时，就会触发中断。 +当我们支持完地址不连续后，多个大链表（也就是长度不限制的链表的最后一个链表）完成都会触发中断，假设设定了三个传输 ``bflb_dma_channel_lli_transfer_s``, 那么会触发三次 DMA 完成中断。 + + +支持循环模式 +-------------------- diff --git a/docs/source/notes/note_uart.rst b/docs/source/notes/note_uart.rst new file mode 100644 index 00000000..ea4f0b7a --- /dev/null +++ b/docs/source/notes/note_uart.rst @@ -0,0 +1,37 @@ +UART 引脚映射详解 +=============================== + +博流系列芯片每个 pin 都可以配置成 UART 任意一个功能，这种灵活的配置就会出现一些坑，比如多个 pin 配成了一个 uart 功能。 +下面介绍下如何正确的理解 `每个 pin 都可以配置成 UART 任意一个功能` 并防止踩坑。最后讲下 ``bflb_gpio_uart_init`` 函数的实现。 + + +UART SIG +------------------- + +在博流系列芯片中，有个 `UART SIG` 的概念, 每个 SIG 对应到 UART 所有功能，功能类似于 8选1 选择器或者 12 选1 选择器。并且每个 SIG 都有一个默认的 UART 功能，如图所示： + +.. figure:: img/uart_sig.png + :alt: + + +2 个 pin 选了一个 SIG +^^^^^^^^^^^^^^^^^^^^^^^ + +每个 GPIO 对应一个 SIG, 对应关系跟芯片相关，比如 BL602/BL702 是 mod 8 的关系，而 BL616/BL808 是 mod 12 的关系，这个时候就会产生一个问题， **存在重复的可能性**， +**假设现在是 mod 8 的关系，则 GPIO0 跟 GPIO8 都对应 SIG0，如果 GPIO0 配置了 UART 一个功能，则不能再使用 GPIO8，否则会出现两个 GPIO 共用一个功能的情况**。 + + +2 个 SIG 选了一个 UART 功能 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +为了方便软件，代码中将默认功能全部改成了 `0xF`，所有 SIG 都指向一个没有作用的功能。为什么这么做？ + +假设 GPIO2 默认使用 UART0 TX，这个时候我想使用 GPIO6 作为 UART0 TX，当我软件中配置 GPIO6 为 UART0 TX 以后，请问，GPIO2 是什么功能？没错，还是 UART0 TX，这个时候就是有问题的。 + +bflb_gpio_uart_init +------------------------ + +针对以上两个问题，出现了 ``bflb_gpio_uart_init``。该函数的作用是避免了 `2 个 SIG 选了一个 UART 功能` ，如果出现了，则后配置的覆盖前面的。 +而对于 `2 个 pin 选了一个 SIG` 则是无法靠软件避免的，只能人为的避免。 + + diff --git a/docs/source/samples/components/freertos.rst b/docs/source/samples/components/freertos.rst new file mode 100644 index 00000000..f807df0e --- /dev/null +++ b/docs/source/samples/components/freertos.rst @@ -0,0 +1,72 @@ +FreeRTOS +==================== + +本 demo 主要演示 FreeRTOS 基本功能：任务创建和任务切换、信号量、内存管理。更详细的代码请参考 **examples/freertos**。 + +内存管理 +--------------- + +FreeRTOS 内存管理默认使用 heap5, 可以管理多块内存，并调用 ``vPortDefineHeapRegions`` 进行初始化。 + +中断管理 +--------------- + +FreeRTOS 为 RISC-V 提供了统一的中断和异常入口，名为 ``freertos_risc_v_trap_handler``，该函数主要作用如下： + +- 压栈 +- 根据 mcause 查找 `mtimer` 中断，并执行 ``xTaskIncrementTick`` +- 根据 mcause 查找 `ecall` 异常，并执行 ``vTaskSwitchContext`` +- 根据 mcause，如果是非 `ecall` 异常，则执行 ``exception_entry``；如果是非 `mtimer` 中断，则执行 ``portasmHANDLE_INTERRUPT``, ``portasmHANDLE_INTERRUPT`` 实际调用 ``interrupt_entry``。 +- 出栈 + +那么问题来了，是如何统一中断和异常的呢？ + +通常 RISC-V SOC 中断支持 vector 模式和 direct 模式，博流系列芯片都使用了 vector 模式，在 `startup/start.S` 文件中可以看到 + +.. code-block:: C + :linenos: + + /* mtvec: for all exceptions and non-vector mode IRQs */ + la a0, default_trap_handler + ori a0, a0, 3 + csrw mtvec, a0 + + /* mtvt: for all vector mode IRQs */ + la a0, __Vectors + csrw mtvt, a0 + +在 `startup/interrupt` 中可以找到 ``__Vectors``: + +.. code-block:: C + :linenos: + + const pFunc __Vectors[] __attribute__((section(".init"), aligned(64))) = { + default_interrupt_handler, /* */ + default_interrupt_handler, /* */ + default_interrupt_handler, /* */ + .... + }; + +此时还没有跟 ``freertos_risc_v_trap_handler`` 扯上关系，在 `freertos/CMakelist.txt` 中配置了 ``freertos_risc_v_trap_handler`` 和 ``default_interrupt_handler`` 之间的关系。那么当中断触发时， +调用 ``default_interrupt_handler`` 其实就是调用 ``freertos_risc_v_trap_handler`` 了。 + +.. code-block:: C + :linenos: + + sdk_add_compile_definitions(-DportasmHANDLE_INTERRUPT=interrupt_entry -Ddefault_interrupt_handler=freertos_risc_v_trap_handler) + +在 `portASM.S` 文件中 ``xPortStartFirstTask`` 函数又重新配置了 ``mtvec`` 为 ``freertos_risc_v_trap_handler``,这个时候，中断和异常就统一使用 ``freertos_risc_v_trap_handler`` 函数了。 + +编译和烧录 +----------------------------- + +- **命令行编译** + +参考 :ref:`linux_cmd` 或者 :ref:`windows_cmd` + +- **烧录** + +参考 :ref:`bl_dev_cube` + +实验现象 +----------------------------- \ No newline at end of file diff --git a/docs/source/samples/components/index.rst b/docs/source/samples/components/index.rst new file mode 100644 index 00000000..ec31c931 --- /dev/null +++ b/docs/source/samples/components/index.rst @@ -0,0 +1,10 @@ +======================= +Components +======================= + +组件例程如果没有特殊说明，则表示适用于博流所有系列芯片。 + +.. toctree:: + :maxdepth: 1 + + FreeRTOS diff --git a/docs/source/samples/peripherals/adc/adc_oneshot_1ch.rst b/docs/source/samples/peripherals/adc/adc_oneshot_1ch.rst deleted file mode 100644 index 9fda84b4..00000000 --- a/docs/source/samples/peripherals/adc/adc_oneshot_1ch.rst +++ /dev/null @@ -1,121 +0,0 @@ -ADC - 电压检测 -==================== - -本 demo 主要介绍基于 ADC 的电压检测功能，使用 ADC 检测 CH8 输入的电压值。 - -硬件连接 ------------------------------ - -将 ADC CH8 对应的 GPIO 口与 3.3 V 引脚相连。不同芯片 ADC CH8 对应的 GPIO 口如下表所示： - -.. table:: GPIO 口 - :widths: 30, 30, 40 - :width: 80% - :align: center - - +----------+-----------+---------------------------+ - | 名称 | 芯片型号 | GPIO | - +==========+===========+===========================+ - | ADC CH8 | BL702 | GPIO 18 | - + +-----------+---------------------------+ - | | BL616 | GPIO 1 | - +----------+-----------+---------------------------+ - -软件实现 ------------------------------ - -更详细的代码请参考 ``examples/peripherals/adc/adc_oneshot_1ch`` - -.. code-block:: C - :linenos: - - board_init(); - -- ``board_init`` 中会开启 adc 外设，并且初始化 adc 的时钟 - -.. code-block:: C - :linenos: - - board_adc_gpio_init(); - -- 配置相关引脚为 `ADC` 功能 - -.. code-block:: C - :linenos: - - adc = bflb_device_get_by_name("adc"); - - struct bflb_adc_config_s cfg; - - cfg.clk_div = ADC_CLK_DIV_32; - cfg.scan_conv_mode = false; - cfg.continuous_conv_mode = false; - cfg.differential_mode = false; - cfg.resolution = ADC_RESOLUTION_16B; - cfg.vref = ADC_VREF_3P2V; - - bflb_adc_init(adc, &cfg); - -- 获取 `adc` 句柄，并初始化 adc - -.. code-block:: C - :linenos: - - struct bflb_adc_channel_s chan; - - chan.pos_chan = ADC_CHANNEL_8; - chan.neg_chan = ADC_CHANNEL_GND; - - bflb_adc_channel_config(adc, &chan, 1); - -- 配置 adc 通道信息，当前使用了一对通道 - -.. code-block:: C - :linenos: - - for (uint32_t i = 0; i < 10; i++) { - bflb_adc_start_conversion(adc); - - while (bflb_adc_get_count(adc) == 0) { - } - struct bflb_adc_result_s result; - uint32_t raw_data = bflb_adc_read_raw(adc); - printf("raw data:%08x\r\n", raw_data); - bflb_adc_parse_result(adc, &raw_data, &result, 1); - printf("pos chan %d,%d mv \r\n", result.pos_chan, result.millivolt); - bflb_adc_stop_conversion(adc); - bflb_mtimer_delay_ms(100); - } - -- 调用 ``bflb_adc_start_conversion(adc)`` 启用 adc 的转换 -- 调用 ``bflb_adc_read_raw(adc)`` 读取一次 adc 的转换值 -- 调用 ``bflb_adc_parse_result(adc, &raw_data, &result, 1)`` 对 adc 的转换结果进行解析，解析的值保存到 ``result`` 结构体中 -- 调用 ``bflb_adc_stop_conversion(adc)`` 停止 adc 转换 - -编译和烧录 ------------------------------ - -- **命令行编译** - -.. code-block:: bash - :linenos: - - $ cd /examples/peripherals/adc/adc_oneshot_1ch - $ make CHIP=blxxx BOARD=blxxx_dk - -.. note:: blxxx为所使用的芯片型号，以bl616为例，编译命令为：make CHIP=bl616 BOARD=bl616_dk - -- **烧录** - - 详见 :ref:`bl_dev_cube` - -实验现象 ------------------------------ - -将 ADC_CH8 对应的 GPIO口与 3.3V 相连，打印的信息如下： - -.. figure:: img/adc_log.png - :align: center - - log 信息 - diff --git a/docs/source/samples/peripherals/adc/adc_poll.rst b/docs/source/samples/peripherals/adc/adc_poll.rst new file mode 100644 index 00000000..fde28cbe --- /dev/null +++ b/docs/source/samples/peripherals/adc/adc_poll.rst @@ -0,0 +1,95 @@ +ADC - poll +==================== + +本 demo 主要演示 adc poll 单端模式下读取电压值。默认扫描通道 0 ~ 通道10。 **需要注意，有些芯片不一定支持全部通道**。 + +硬件连接 +----------------------------- + +本 demo 使用到的 gpio 参考 ``board_adc_gpio_init`` 。 + +软件实现 +----------------------------- + +更详细的代码请参考 **examples/peripherals/adc/adc_poll** + +.. code-block:: C + :linenos: + + board_init(); + +- ``board_init`` 中会开启 ADC IP 时钟，并选择 ADC 时钟源和分频。 + +.. code-block:: C + :linenos: + + board_adc_gpio_init(); + +- 配置相关引脚为 `ADC` 功能 + +.. code-block:: C + :linenos: + + adc = bflb_device_get_by_name("adc"); + + /* adc clock = XCLK / 2 / 32 */ + struct bflb_adc_config_s cfg; + cfg.clk_div = ADC_CLK_DIV_32; + cfg.scan_conv_mode = true; + cfg.continuous_conv_mode = false; + cfg.differential_mode = false; + cfg.resolution = ADC_RESOLUTION_16B; + cfg.vref = ADC_VREF_3P2V; + + bflb_adc_init(adc, &cfg); + +- 获取 `adc` 句柄，并初始化 adc 配置，设置 adc 采样频率为 500K + +.. code-block:: C + :linenos: + + bflb_adc_channel_config(adc, chan, TEST_ADC_CHANNELS); + +- 配置 adc 通道信息，使用的对数根据 `TEST_ADC_CHANNELS` 可配，默认开启通道 0 ~ 10，根据 ``board_adc_gpio_init`` 需要选择性关闭其他通道。 + +.. code-block:: C + :linenos: + + for (uint32_t i = 0; i < TEST_COUNT; i++) { + bflb_adc_start_conversion(adc); + + while (bflb_adc_get_count(adc) < TEST_ADC_CHANNELS) { + bflb_mtimer_delay_ms(1); + } + + for (size_t j = 0; j < TEST_ADC_CHANNELS; j++) { + struct bflb_adc_result_s result; + uint32_t raw_data = bflb_adc_read_raw(adc); + printf("raw data:%08x\r\n", raw_data); + bflb_adc_parse_result(adc, &raw_data, &result, 1); + printf("pos chan %d,%d mv \r\n", result.pos_chan, result.millivolt); + } + + bflb_adc_stop_conversion(adc); + bflb_mtimer_delay_ms(100); + } + +- 调用 ``bflb_adc_start_conversion(adc)`` 启用 adc 的转换 +- 调用 ``bflb_adc_get_count(adc)`` 读取转换完成的个数 +- 调用 ``bflb_adc_read_raw(adc)`` 读取一次 adc 的转换值 +- 调用 ``bflb_adc_parse_result(adc, &raw_data, &result, 1)`` 对 adc 的转换结果进行解析，解析的值保存到 ``result`` 结构体中 +- 调用 ``bflb_adc_stop_conversion(adc)`` 停止 adc 转换 + +编译和烧录 +----------------------------- + +- **命令行编译** + +参考 :ref:`linux_cmd` 或者 :ref:`windows_cmd` + +- **烧录** + +参考 :ref:`bl_dev_cube` + +实验现象 +----------------------------- \ No newline at end of file diff --git a/docs/source/samples/peripherals/adc/index.rst b/docs/source/samples/peripherals/adc/index.rst index 34f1bf2b..d1f74688 100644 --- a/docs/source/samples/peripherals/adc/index.rst +++ b/docs/source/samples/peripherals/adc/index.rst @@ -1,8 +1,8 @@ -======================= -ADC 示例 -======================= - -.. toctree:: - :maxdepth: 1 - - ADC - 电压检测 \ No newline at end of file +===== +ADC +===== + +.. toctree:: + :maxdepth: 1 + + ADC - poll \ No newline at end of file diff --git a/docs/source/samples/peripherals/dac/dac_polling.rst b/docs/source/samples/peripherals/dac/dac_polling.rst index 5a71448d..e4704bae 100644 --- a/docs/source/samples/peripherals/dac/dac_polling.rst +++ b/docs/source/samples/peripherals/dac/dac_polling.rst @@ -1,89 +1,83 @@ -DAC - 正弦波 -==================== - -本 demo 主要介绍基于 DAC 生成正弦波。 - -硬件连接 ------------------------------ - -不同芯片 DAC Channel A 对应的 GPIO 口如下表所示： - -.. table:: GPIO 口 - :widths: 30, 30, 40 - :width: 80% - :align: center - - +----------------+-----------+---------------------------+ - | 名称 | 芯片型号 | GPIO | - +================+===========+===========================+ - | DAC Channel A | BL702 | GPIO 11 | - + +-----------+---------------------------+ - | | BL616 | GPIO 3 | - +----------------+-----------+---------------------------+ - -软件实现 ------------------------------ - -更详细的代码请参考 ``examples/peripherals/dac/dac_polling`` - -.. code-block:: C - :linenos: - - board_init(); - -- ``board_init`` 中会开启 dac 外设 - -.. code-block:: C - :linenos: - - board_dac_gpio_init(); - -- 配置相关引脚为 `DAC` 功能 - -.. code-block:: C - :linenos: - - dac = bflb_device_get_by_name("dac"); - - bflb_dac_init(dac, DAC_SAMPLING_FREQ_32K); - -- 获取 `dac` 句柄，并初始化 dac，时钟配置为 32K - -.. code-block:: C - :linenos: - - bflb_dac_channel_enable(dac, DAC_CHANNEL_A); - -- 配置 dac 通道信息，当前使用的 A 通道 - -.. code-block:: C - :linenos: - - for (uint16_t i = 0; i < sizeof(SIN_LIST) / sizeof(uint16_t); i++) { - bflb_dac_set_value(dac, DAC_CHANNEL_A, SIN_LIST[i]); - bflb_mtimer_delay_us(100); - } - -- 调用 ``bflb_dac_set_value(dac, DAC_CHANNEL_A, SIN_LIST[i])`` ，将需要转换的数据通过通道 A 输出 - -编译和烧录 ------------------------------ - -- **命令行编译** - -.. code-block:: bash - :linenos: - - $ cd /examples/peripherals/dac/dac_polling - $ make CHIP=blxxx BOARD=blxxx_dk - -.. note:: blxxx为所使用的芯片型号，以bl616为例，编译命令为：make CHIP=bl616 BOARD=bl616_dk - -- **烧录** - - 详见 :ref:`bl_dev_cube` - -实验现象 ------------------------------ - -DAC Channel A 对应的 GPIO 输出正弦波。 +DAC - poll +==================== + +本 demo 主要介绍基于 DAC 轮询模式生成正弦波。 + +硬件连接 +----------------------------- + +本 demo 使用到的 gpio 如下表： + +.. table:: GPIO 口 + :widths: 30, 30, 40 + :width: 80% + :align: center + + +----------------+-----------+---------------------------+ + | 名称 | 芯片型号 | GPIO | + +================+===========+===========================+ + | DAC Channel A | BL702 | GPIO 11 | + + +-----------+---------------------------+ + | | BL616 | GPIO 3 | + +----------------+-----------+---------------------------+ + +软件实现 +----------------------------- + +更详细的代码请参考 **examples/peripherals/dac/dac_polling** + +.. code-block:: C + :linenos: + + board_init(); + +- ``board_init`` 中会开启 DAC IP 时钟，并选择 DAC 时钟源和分频。 + +.. code-block:: C + :linenos: + + board_dac_gpio_init(); + +- 配置相关引脚为 `DAC` 功能 + +.. code-block:: C + :linenos: + + dac = bflb_device_get_by_name("dac"); + + bflb_dac_init(dac, DAC_SAMPLING_FREQ_32K); + +- 获取 `dac` 句柄，并初始化 dac 频率为 32K + +.. code-block:: C + :linenos: + + bflb_dac_channel_enable(dac, DAC_CHANNEL_A); + +- 配置 dac 通道信息，当前使用的 A 通道 + +.. code-block:: C + :linenos: + + for (uint16_t i = 0; i < sizeof(SIN_LIST) / sizeof(uint16_t); i++) { + bflb_dac_set_value(dac, DAC_CHANNEL_A, SIN_LIST[i]); + bflb_mtimer_delay_us(100); + } + +- 调用 ``bflb_dac_set_value(dac, DAC_CHANNEL_A, SIN_LIST[i])`` ，将需要转换的数据通过通道 A 输出 + +编译和烧录 +----------------------------- + +- **命令行编译** + +参考 :ref:`linux_cmd` 或者 :ref:`windows_cmd` + +- **烧录** + +参考 :ref:`bl_dev_cube` + +实验现象 +----------------------------- + +DAC Channel A 对应的 GPIO 输出正弦波。 diff --git a/docs/source/samples/peripherals/dac/index.rst b/docs/source/samples/peripherals/dac/index.rst index f7684f7d..720267bc 100644 --- a/docs/source/samples/peripherals/dac/index.rst +++ b/docs/source/samples/peripherals/dac/index.rst @@ -1,8 +1,8 @@ -======================= -DAC 示例 -======================= - -.. toctree:: - :maxdepth: 1 - - DAC - 生成正弦波 \ No newline at end of file +==== +DAC +==== + +.. toctree:: + :maxdepth: 1 + + DAC - poll \ No newline at end of file diff --git a/docs/source/samples/peripherals/index.rst b/docs/source/samples/peripherals/index.rst index 0772d22e..89c9894b 100644 --- a/docs/source/samples/peripherals/index.rst +++ b/docs/source/samples/peripherals/index.rst @@ -8,5 +8,5 @@ Peripherals :maxdepth: 1 ADC + DAC UART - DAC \ No newline at end of file diff --git a/docs/source/samples/peripherals/uart/index.rst b/docs/source/samples/peripherals/uart/index.rst index a1bfe777..2550907c 100644 --- a/docs/source/samples/peripherals/uart/index.rst +++ b/docs/source/samples/peripherals/uart/index.rst @@ -1,8 +1,9 @@ -======================= -UART 轮询收发数据 -======================= - -.. toctree:: - :maxdepth: 1 - - UART - poll \ No newline at end of file +====== +UART +====== + +.. toctree:: + :maxdepth: 1 + + UART - poll + UART - dma \ No newline at end of file diff --git a/docs/source/samples/peripherals/uart/uart_dma.rst b/docs/source/samples/peripherals/uart/uart_dma.rst new file mode 100644 index 00000000..61a1ce9d --- /dev/null +++ b/docs/source/samples/peripherals/uart/uart_dma.rst @@ -0,0 +1,160 @@ +UART - dma +==================== + +本 demo 主要演示 UART dma 模式收发功能。 + +硬件连接 +----------------------------- + +- 芯片 UART TX 引脚连接 USB2TTL 模块 RX +- 芯片 UART RX 引脚连接 USB2TTL 模块 TX + +本 demo 使用到的 gpio 如下表： + +.. table:: GPIO 口 + :widths: 30, 30, 40 + :width: 80% + :align: center + + +----------+-----------+---------------------------+ + | 名称 | 芯片型号 | GPIO | + +==========+===========+===========================+ + | UART1_TX | BL702 | GPIO 18 | + + +-----------+---------------------------+ + | | BL616 | GPIO 23 | + +----------+-----------+---------------------------+ + | UART1_RX | BL702 | GPIO 19 | + + +-----------+---------------------------+ + | | BL616 | GPIO 24 | + +----------+-----------+---------------------------+ + +软件实现 +----------------------------- + +具体软件代码见 **examples/peripherals/uart/uart_podma** + +.. code-block:: C + :linenos: + + board_init(); + +- ``board_init`` 中会开启 UART IP 时钟，并选择 UART 时钟源和分频。 + +.. code-block:: C + :linenos: + + board_uartx_gpio_init(); + +- 配置相关引脚为 ``UARTx TX`` 、 ``UARTx RX`` 功能，默认 demo 使用 UART1 外设。 + +.. code-block:: C + :linenos: + + uartx = bflb_device_get_by_name(DEFAULT_TEST_UART); + + struct bflb_uart_config_s cfg; + + cfg.baudrate = 2000000; + cfg.data_bits = UART_DATA_BITS_8; + cfg.stop_bits = UART_STOP_BITS_1; + cfg.parity = UART_PARITY_NONE; + cfg.flow_ctrl = 0; + cfg.tx_fifo_threshold = 7; + cfg.rx_fifo_threshold = 7; + bflb_uart_init(uartx, &cfg); + +- 获取 `DEFAULT_TEST_UART` 句柄，并初始化 UART + +.. code-block:: C + :linenos: + + bflb_uart_link_txdma(uartx, true); + bflb_uart_link_rxdma(uartx, true); + +- 使能 uart tx、rx dma 功能 + +.. code-block:: C + :linenos: + + struct bflb_dma_channel_config_s config; + + config.direction = DMA_MEMORY_TO_PERIPH; + config.src_req = DMA_REQUEST_NONE; + config.dst_req = DEFAULT_TEST_UART_DMA_TX_REQUEST; + config.src_addr_inc = DMA_ADDR_INCREMENT_ENABLE; + config.dst_addr_inc = DMA_ADDR_INCREMENT_DISABLE; + config.src_burst_count = DMA_BURST_INCR1; + config.dst_burst_count = DMA_BURST_INCR1; + config.src_width = DMA_DATA_WIDTH_8BIT; + config.dst_width = DMA_DATA_WIDTH_8BIT; + bflb_dma_channel_init(dma0_ch0, &config); + + struct bflb_dma_channel_config_s rxconfig; + + rxconfig.direction = DMA_PERIPH_TO_MEMORY; + rxconfig.src_req = DEFAULT_TEST_UART_DMA_RX_REQUEST; + rxconfig.dst_req = DMA_REQUEST_NONE; + rxconfig.src_addr_inc = DMA_ADDR_INCREMENT_DISABLE; + rxconfig.dst_addr_inc = DMA_ADDR_INCREMENT_ENABLE; + rxconfig.src_burst_count = DMA_BURST_INCR1; + rxconfig.dst_burst_count = DMA_BURST_INCR1; + rxconfig.src_width = DMA_DATA_WIDTH_8BIT; + rxconfig.dst_width = DMA_DATA_WIDTH_8BIT; + bflb_dma_channel_init(dma0_ch1, &rxconfig); + + bflb_dma_channel_irq_attach(dma0_ch0, dma0_ch0_isr, NULL); + bflb_dma_channel_irq_attach(dma0_ch1, dma0_ch1_isr, NULL); + +- 配置 `DMA CH0` 为 `UARTx TX` ， `DMA CH1` 为 `UARTx RX` . +- 注册 dma 通道中断 + +.. code-block:: C + :linenos: + + struct bflb_dma_channel_lli_pool_s tx_llipool[20]; /* max trasnfer size 4064 * 20 */ + struct bflb_dma_channel_lli_transfer_s tx_transfers[3]; + + tx_transfers[0].src_addr = (uint32_t)src_buffer; + tx_transfers[0].dst_addr = (uint32_t)DEFAULT_TEST_UART_DMA_TDR; + tx_transfers[0].nbytes = 4100; + + tx_transfers[1].src_addr = (uint32_t)src2_buffer; + tx_transfers[1].dst_addr = (uint32_t)DEFAULT_TEST_UART_DMA_TDR; + tx_transfers[1].nbytes = 4100; + + tx_transfers[2].src_addr = (uint32_t)src3_buffer; + tx_transfers[2].dst_addr = (uint32_t)DEFAULT_TEST_UART_DMA_TDR; + tx_transfers[2].nbytes = 4100; + + struct bflb_dma_channel_lli_pool_s rx_llipool[20]; + struct bflb_dma_channel_lli_transfer_s rx_transfers[1]; + rx_transfers[0].src_addr = (uint32_t)DEFAULT_TEST_UART_DMA_RDR; + rx_transfers[0].dst_addr = (uint32_t)receive_buffer; + rx_transfers[0].nbytes = 50; + + bflb_dma_channel_lli_reload(dma0_ch0, tx_llipool, 20, tx_transfers, 3); + bflb_dma_channel_lli_reload(dma0_ch1, rx_llipool, 20, rx_transfers, 1); + bflb_dma_channel_start(dma0_ch0); + bflb_dma_channel_start(dma0_ch1); + +- 分配一块 lli 内存池，个数为20，最多可以传输 4094 * 20 字节 +- 配置三块不连续的内存进行传输 +- 调用 ``bflb_dma_channel_lli_reload`` 初始化 +- 调用 ``bflb_dma_channel_start`` 启动传输 +- 等待传输完成并进入中断 + +编译和烧录 +----------------------------- + +- **命令行编译** + +参考 :ref:`linux_cmd` 或者 :ref:`windows_cmd` + +- **烧录** + +参考 :ref:`bl_dev_cube` + +实验现象 +----------------------------- + + diff --git a/docs/source/samples/peripherals/uart/uart_poll.rst b/docs/source/samples/peripherals/uart/uart_poll.rst index eb35e5b5..cc306ea8 100644 --- a/docs/source/samples/peripherals/uart/uart_poll.rst +++ b/docs/source/samples/peripherals/uart/uart_poll.rst @@ -1,102 +1,99 @@ -UART - 轮询收发数据 -==================== - -本 demo 主要介绍 UART1 外设的轮询发送和轮询接收，实现自发自收功能。 - -硬件连接 ------------------------------ - -将 UART1 TX 和 RX 引脚分别与 USB2TTL 模块 RX 和 TX 相连。本 demo 中不同芯片 UART1 引脚对应的 GPIO 口如下表所示： - -.. table:: GPIO 口 - :widths: 30, 30, 40 - :width: 80% - :align: center - - +----------+-----------+---------------------------+ - | 名称 | 芯片型号 | GPIO | - +==========+===========+===========================+ - | UART1_TX | BL702 | GPIO 18 | - + +-----------+---------------------------+ - | | BL616 | GPIO 23 | - +----------+-----------+---------------------------+ - | UART1_RX | BL702 | GPIO 19 | - + +-----------+---------------------------+ - | | BL616 | GPIO 24 | - +----------+-----------+---------------------------+ - -软件实现 ------------------------------ - -具体软件代码见 ``examples/peripherals/uart/uart_poll`` - -.. code-block:: C - :linenos: - - board_init(); - -- ``board_init`` 中会开启 uart1 外设，并且初始化 uart1 的时钟 - -.. code-block:: C - :linenos: - - board_uart1_gpio_init(); - -- 配置相关引脚为 ``UART1 TX`` 、 ``UART1 RX`` 功能 - -.. code-block:: C - :linenos: - - uart1 = bflb_device_get_by_name("uart1"); - - struct bflb_uart_config_s cfg; - - cfg.baudrate = 2000000; - cfg.data_bits = UART_DATA_BITS_8; - cfg.stop_bits = UART_STOP_BITS_1; - cfg.parity = UART_PARITY_NONE; - cfg.flow_ctrl = 0; - cfg.tx_fifo_threshold = 7; - cfg.rx_fifo_threshold = 7; - bflb_uart_init(uart1, &cfg); - -- 获取 `uart1` 句柄，并初始化 UART1 - -.. code-block:: C - :linenos: - - int ch; - while (1) { - ch = bflb_uart_getchar(uart1); - if (ch != -1) { - bflb_uart_putchar(uart1, ch); - } - } - -- 调用 ``bflb_uart_getchar(uart1)`` ，从 UART1 RX FIFO 中读取 USB2TTL 模块发送给 UART1 的数据，保存在 ch 中，如果没有数据则返回 -1 -- 调用 ``bflb_uart_putchar(uart1, ch)`` 将数据 ch 写入 UART1 TX FIFO 中，并发送给 USB2TTL 模块 - -编译和烧录 ------------------------------ - -- **命令行编译** - -.. code-block:: bash - :linenos: - - $ cd /examples/peripherals/uart/uart_poll - $ make CHIP=blxxx BOARD=blxxx_dk - -.. note:: blxxx为所使用的芯片型号，以bl616为例，编译命令为：make CHIP=bl616 BOARD=bl616_dk - -- **烧录** - - 详见 :ref:`bl_dev_cube` - -实验现象 ------------------------------ - -将 UART1 TX, RX, GND 引脚分别与 USB2TTL 模块 RX, TX, GND 相连，按下 reset 按键。 -使用串口给 UART1 发送 ``0123456789`` ，USB2TTL 模块能接收到同样的数据。 - - +UART - poll +==================== + +本 demo 主要演示 UART 轮询模式收发功能。 + +硬件连接 +----------------------------- + +- 芯片 UART TX 引脚连接 USB2TTL 模块 RX +- 芯片 UART RX 引脚连接 USB2TTL 模块 TX + +本 demo 使用到的 gpio 如下表： + +.. table:: GPIO 口 + :widths: 30, 30, 40 + :width: 80% + :align: center + + +----------+-----------+---------------------------+ + | 名称 | 芯片型号 | GPIO | + +==========+===========+===========================+ + | UART1_TX | BL702 | GPIO 18 | + + +-----------+---------------------------+ + | | BL616 | GPIO 23 | + +----------+-----------+---------------------------+ + | UART1_RX | BL702 | GPIO 19 | + + +-----------+---------------------------+ + | | BL616 | GPIO 24 | + +----------+-----------+---------------------------+ + +软件实现 +----------------------------- + +具体软件代码见 **examples/peripherals/uart/uart_poll** + +.. code-block:: C + :linenos: + + board_init(); + +- ``board_init`` 中会开启 UART IP 时钟，并选择 UART 时钟源和分频。 + +.. code-block:: C + :linenos: + + board_uartx_gpio_init(); + +- 配置相关引脚为 ``UARTx TX`` 、 ``UARTx RX`` 功能，默认 demo 使用 UART1 外设。 + +.. code-block:: C + :linenos: + + uartx = bflb_device_get_by_name(DEFAULT_TEST_UART); + + struct bflb_uart_config_s cfg; + + cfg.baudrate = 2000000; + cfg.data_bits = UART_DATA_BITS_8; + cfg.stop_bits = UART_STOP_BITS_1; + cfg.parity = UART_PARITY_NONE; + cfg.flow_ctrl = 0; + cfg.tx_fifo_threshold = 7; + cfg.rx_fifo_threshold = 7; + bflb_uart_init(uartx, &cfg); + +- 获取 `DEFAULT_TEST_UART` 句柄，并初始化 UART + +.. code-block:: C + :linenos: + + int ch; + while (1) { + ch = bflb_uart_getchar(uartx); + if (ch != -1) { + bflb_uart_putchar(uartx, ch); + } + } + +- 调用 ``bflb_uart_getchar`` 从 uart rx fifo 中读取数据，如果返回 -1，表示没有数据 +- 调用 ``bflb_uart_putchar`` 将数据 `ch` 填充到 uart tx fifo 中 + +编译和烧录 +----------------------------- + +- **命令行编译** + +参考 :ref:`linux_cmd` 或者 :ref:`windows_cmd` + +- **烧录** + +参考 :ref:`bl_dev_cube` + +实验现象 +----------------------------- + +将 UART1 TX, RX, GND 引脚分别与 USB2TTL 模块 RX, TX, GND 相连，按下 reset 按键。 +使用串口给 UART1 发送 ``0123456789`` ，USB2TTL 模块能接收到同样的数据。 + +