diff --git a/docs/source/api_reference/components/bflog.rst b/docs/source/api_reference/components/bflog.rst index 58b043af..5297eb8f 100644 --- a/docs/source/api_reference/components/bflog.rst +++ b/docs/source/api_reference/components/bflog.rst @@ -7,12 +7,13 @@ BFLOG - BFLOG 是一个移植简单，功能多样的多线程日志记录库 - 具有同步异步两种工作模式，异步模式如果缓冲区溢出会将最早的一条记录完整删除 - 总体三部分、记录器、定向输出、格式化器 -- 一个记录器可多重定向输出，可同时输出到缓冲区、IO外设、文件、文件大小划分、文件时间划分 +- 一个记录器可多重定向输出,可同时输出到缓冲区、IO外设、文件、文件大小划分、文件时间划分 - 定向到文件输出，支持设定保留数量，支持按文件大小划分，支持按时间划分 -- 每个定向输出可单独设定格式化器，输出等级，输出方式，颜色 +- 每个定向输出可单独设定格式化器、输出等级、TAG标签过滤、输出方式、颜色 - 格式化器支持简单格式、用户自定义格式、YAML格式(实现中)、CSV格式(规划中) -- 六级日志等级控制，FATAL、ERROR、WARNING、INFO、DEBUG、TRACE +- 六级日志等级控制, FATAL、ERROR、WARNING、INFO、DEBUG、TRACE - 支持等级、TAG标签、函数、行数、文件名、TICK数、TIME、线程信息输出 +- 支持等级、TAG标签过滤功能 - 可对不需要的等级、功能、标签进行裁剪，缩小代码体积 .. figure:: img/bflog_log.png @@ -25,51 +26,457 @@ BFLOG 如果需要配置BFLOG的相关功能需要在对应的工程目录下 `proj.conf` 文件中添加对应的代码，举例如下： -.. note:: BFLOG 默认依赖 VLIBC 需要先启用 VLIBC。 - 如果需要支持文件输出，还需要启用Fatfs和 VLIBC的Fatfs接口支持 - - -以下是一个不支持BFLOG文件输出的 `proj.conf` 配置 +以下是一个不支持文件输出的 `proj.conf` 配置 .. code-block:: cmake :linenos: - # 使能VLIBC - set(CONFIG_VLIBC 1) - # 使能 BFLOG set(CONFIG_BFLOG 1) + # 使能参数检查, 可不开启 + set(CONFIG_BFLOG_DEBUG 1) - -以下是一个支持BFLOG文件输出的 `proj.conf` 配置 - -.. code-block:: cmake - :linenos: - - # 使能VLIBC - set(CONFIG_VLIBC 1) - # 使能VLIBC FATFS 文件接口 - set(CONFIG_VLIBC_FATFS 1) - - # 使能 BFLOG - set(CONFIG_BFLOG 1) - - # 使能 Fatfs - set(CONFIG_FATFS 1) - - # 使能 BSP_COMMON 文件夹中驱动支持 - set(CONFIG_BSP_COMMON 1) - - # 使能 SD卡 - set(CONFIG_BSP_SDH_SDCARD 1) - - # 使能 Fatfs 的 SD 卡接口 - set(CONFIG_FATFS_SDH_SDCARD 1) - -此外在 `proj.conf` 配置中添加以下配置可以使用用户的 **bflog_user.h** 配置文件，配置文件模板为 **bflog_default.h** +此外在 `proj.conf` 配置中添加以下配置可以使用用户的 **bflog_user.h** 配置文件，配置文件默认为 **bflog_default.h** .. code-block:: cmake :linenos: # 使能 BFLOG_USER 配置文件 set(CONFIG_BFLOG_USER 1) + +Macros +------------ + +BFLOG_CSI +^^^^^^^^^^^^^^^^^^^^ + +Control Sequence Introducer +用于控制终端 + +.. code-block:: c + :linenos: + + #define BFLOG_CSI_START "\033[" + #define BFLOG_CSI_CUU "A" + #define BFLOG_CSI_CUD "B" + #define BFLOG_CSI_CUF "C" + #define BFLOG_CSI_CUB "D" + #define BFLOG_CSI_CNL "E" + #define BFLOG_CSI_CPL "F" + #define BFLOG_CSI_CHA "G" + #define BFLOG_CSI_CUP "H" + #define BFLOG_CSI_ED "J" + #define BFLOG_CSI_EL "K" + #define BFLOG_CSI_SU "S" + #define BFLOG_CSI_SD "T" + #define BFLOG_CSI_SGR "m" + +BFLOG_SGR +^^^^^^^^^^^^^^^^^^^^ + +Select Graphic Rendition +用于文字图形 + +.. code-block:: c + :linenos: + + #define BFLOG_SGR_RESET "0" + #define BFLOG_SGR_BOLD "1" + #define BFLOG_SGR_FAINT "2" + #define BFLOG_SGR_ITALICS "3" + #define BFLOG_SGR_UNDERLINE "4" + #define BFLOG_SGR_BLINKS "5" + #define BFLOG_SGR_BLINKR "6" + #define BFLOG_SGR_REVERSE "7" + #define BFLOG_SGR_HIDE "8" + #define BFLOG_SGR_STRIKE "9" + #define BFLOG_SGR_NORMAL "22" + #define BFLOG_SGR_FG_BLACK "30" + #define BFLOG_SGR_FG_RED "31" + #define BFLOG_SGR_FG_GREEN "32" + #define BFLOG_SGR_FG_YELLOW "33" + #define BFLOG_SGR_FG_BLUE "34" + #define BFLOG_SGR_FG_MAGENTA "35" + #define BFLOG_SGR_FG_CYAN "36" + #define BFLOG_SGR_FG_WHITE "37" + #define BFLOG_SGR_BG_BLACK "40" + #define BFLOG_SGR_BG_RED "41" + #define BFLOG_SGR_BG_GREEN "42" + #define BFLOG_SGR_BG_YELLOW "43" + #define BFLOG_SGR_BG_BLUE "44" + #define BFLOG_SGR_BG_MAGENTA "45" + #define BFLOG_SGR_BG_CYAN "46" + #define BFLOG_SGR_BG_WHITE "47" + +BFLOG_COLOR +^^^^^^^^^^^^^^^^^^^^ + +一系列颜色用于配置使用 + +.. code-block:: c + :linenos: + + #define BFLOG_COLOR_START BFLOG_CSI_START + #define BFLOG_COLOR_END BFLOG_CSI_SGR + #define BFLOG_CLOLR_SEP ";" + #define BFLOG_COLOR_DEFAULT + #define BFLOG_COLOR_RESET BFLOG_SGR_RESET BFLOG_CLOLR_SEP + #define BFLOG_COLOR_FG_NONE + #define BFLOG_COLOR_FG_BLACK BFLOG_SGR_FG_BLACK BFLOG_CLOLR_SEP + #define BFLOG_COLOR_FG_RED BFLOG_SGR_FG_RED BFLOG_CLOLR_SEP + #define BFLOG_COLOR_FG_GREEN BFLOG_SGR_FG_GREEN BFLOG_CLOLR_SEP + #define BFLOG_COLOR_FG_YELLOW BFLOG_SGR_FG_YELLOW BFLOG_CLOLR_SEP + #define BFLOG_COLOR_FG_BLUE BFLOG_SGR_FG_BLUE BFLOG_CLOLR_SEP + #define BFLOG_COLOR_FG_MAGENTA BFLOG_SGR_FG_MAGENTA BFLOG_CLOLR_SEP + #define BFLOG_COLOR_FG_CYAN BFLOG_SGR_FG_CYAN BFLOG_CLOLR_SEP + #define BFLOG_COLOR_FG_WHITE BFLOG_SGR_FG_WHITE BFLOG_CLOLR_SEP + #define BFLOG_COLOR_BG_NONE + #define BFLOG_COLOR_BG_BLACK BFLOG_SGR_BG_BLACK BFLOG_CLOLR_SEP + #define BFLOG_COLOR_BG_RED BFLOG_SGR_BG_RED BFLOG_CLOLR_SEP + #define BFLOG_COLOR_BG_GREEN BFLOG_SGR_BG_GREEN BFLOG_CLOLR_SEP + #define BFLOG_COLOR_BG_YELLOW BFLOG_SGR_BG_YELLOW BFLOG_CLOLR_SEP + #define BFLOG_COLOR_BG_BLUE BFLOG_SGR_BG_BLUE BFLOG_CLOLR_SEP + #define BFLOG_COLOR_BG_MAGENTA BFLOG_SGR_BG_MAGENTA BFLOG_CLOLR_SEP + #define BFLOG_COLOR_BG_CYAN BFLOG_SGR_BG_CYAN BFLOG_CLOLR_SEP + #define BFLOG_COLOR_BG_WHITE BFLOG_SGR_BG_WHITE BFLOG_CLOLR_SEP + +BFLOG_COLOR_CONTROL +^^^^^^^^^^^^^^^^^^^^ + +默认配置的各等级LOG颜色 + +.. code-block:: c + :linenos: + + #ifndef BFLOG_COLOR_FATAL + #define BFLOG_COLOR_FATAL BFLOG_COLOR_FG_MAGENTA BFLOG_COLOR_BG_NONE BFLOG_SGR_BLINKS + #endif + + #ifndef BFLOG_COLOR_ERROR + #define BFLOG_COLOR_ERROR BFLOG_COLOR_FG_RED BFLOG_COLOR_BG_NONE BFLOG_SGR_NORMAL + #endif + + #ifndef BFLOG_COLOR_WARN + #define BFLOG_COLOR_WARN BFLOG_COLOR_FG_YELLOW BFLOG_COLOR_BG_NONE BFLOG_SGR_NORMAL + #endif + + #ifndef BFLOG_COLOR_INFO + #define BFLOG_COLOR_INFO BFLOG_COLOR_FG_NONE BFLOG_COLOR_BG_NONE BFLOG_SGR_RESET + #endif + + #ifndef BFLOG_COLOR_DEBUG + #define BFLOG_COLOR_DEBUG BFLOG_COLOR_FG_WHITE BFLOG_COLOR_BG_NONE BFLOG_SGR_NORMAL + #endif + + #ifndef BFLOG_COLOR_TRACE + #define BFLOG_COLOR_TRACE BFLOG_COLOR_FG_WHITE BFLOG_COLOR_BG_NONE BFLOG_SGR_FAINT + #endif + +BFLOG_LEVEL_STRING +^^^^^^^^^^^^^^^^^^^^ + +默认配置的各等级提示信息 + +.. code-block:: c + :linenos: + + #ifndef BFLOG_LEVEL_FATAL_STRING + #define BFLOG_LEVEL_FATAL_STRING "FATL" + #endif + + #ifndef BFLOG_LEVEL_ERROR_STRING + #define BFLOG_LEVEL_ERROR_STRING "ERRO" + #endif + + #ifndef BFLOG_LEVEL_WARN_STRING + #define BFLOG_LEVEL_WARN_STRING "WARN" + #endif + + #ifndef BFLOG_LEVEL_INFO_STRING + #define BFLOG_LEVEL_INFO_STRING "INFO" + #endif + + #ifndef BFLOG_LEVEL_DEBUG_STRING + #define BFLOG_LEVEL_DEBUG_STRING "DBUG" + #endif + + #ifndef BFLOG_LEVEL_TRACE_STRING + #define BFLOG_LEVEL_TRACE_STRING "TRAC" + #endif + +BFLOG_LEVEL +^^^^^^^^^^^^^^^^^^^^ + +用于配置 recorder 和 direct 的 LOG等级 + +.. code-block:: c + :linenos: + + #define BFLOG_LEVEL_FATAL 0x00 /*!< level fatal, create a panic */ + #define BFLOG_LEVEL_ERROR 0x01 /*!< level error */ + #define BFLOG_LEVEL_WARN 0x02 /*!< level warning */ + #define BFLOG_LEVEL_INFO 0x03 /*!< level information */ + #define BFLOG_LEVEL_DEBUG 0x04 /*!< level debug */ + #define BFLOG_LEVEL_TRACE 0x05 /*!< level trace information */ + + +BFLOG_FLAG +^^^^^^^^^^^^^^^^^^^^ + +用于配置 recorder 和 direct 的功能 + +.. code-block:: c + :linenos: + + #define BFLOG_FLAG_LEVEL ((uint8_t)0x01) /*!< supported print level */ + #define BFLOG_FLAG_TAG ((uint8_t)0x02) /*!< supported record tag */ + #define BFLOG_FLAG_FUNC ((uint8_t)0x04) /*!< supported record function */ + #define BFLOG_FLAG_LINE ((uint8_t)0x08) /*!< supported record line */ + #define BFLOG_FLAG_FILE ((uint8_t)0x10) /*!< supported record file */ + #define BFLOG_FLAG_CLK ((uint8_t)0x20) /*!< supported record clock */ + #define BFLOG_FLAG_TIME ((uint8_t)0x40) /*!< supported record time */ + #define BFLOG_FLAG_THREAD ((uint8_t)0x80) /*!< supported record thread */ + + +BFLOG_MODE +^^^^^^^^^^^^^^^^^^^^ + +用于配置 recorder 的模式 + +.. code-block:: c + :linenos: + + #define BFLOG_MODE_SYNC ((uint8_t)0x00) + #define BFLOG_MODE_ASYNC ((uint8_t)0x01) + +BFLOG_COMMAND +^^^^^^^^^^^^^^^^^^^^ + +用于 bflog_control 第二个参数 + +.. code-block:: c + :linenos: + + #define BFLOG_CMD_FLAG ((uint32_t)0x01) + #define BFLOG_CMD_LEVEL ((uint32_t)0x02) + #define BFLOG_CMD_QUEUE_POOL ((uint32_t)0x03) + #define BFLOG_CMD_QUEUE_SIZE ((uint32_t)0x04) + #define BFLOG_CMD_QUEUE_RST ((uint32_t)0x05) + #define BFLOG_CMD_ENTER_CRITICAL ((uint32_t)0x06) + #define BFLOG_CMD_EXIT_CRITICAL ((uint32_t)0x07) + #define BFLOG_CMD_FLUSH_NOTICE ((uint32_t)0x08) + #define BFLOG_CMD_MODE ((uint32_t)0x09) + +BFLOG_DIRECT_COMMAND +^^^^^^^^^^^^^^^^^^^^ + +用于 bflog_direct_control 第二个参数 + +.. code-block:: c + :linenos: + + #define BFLOG_DIRECT_CMD_ILLEGAL ((uint32_t)0x00) + #define BFLOG_DIRECT_CMD_LEVEL ((uint32_t)0x02) + #define BFLOG_DIRECT_CMD_LOCK ((uint32_t)0x06) + #define BFLOG_DIRECT_CMD_UNLOCK ((uint32_t)0x07) + #define BFLOG_DIRECT_CMD_COLOR ((uint32_t)0x0A) + +BFLOG_DIRECT_COMMAND +^^^^^^^^^^^^^^^^^^^^ + +用于 bflog_direct_create 第二个参数 + +.. code-block:: c + :linenos: + + #define BFLOG_DIRECT_TYPE_ILLEGAL ((uint8_t)0x00) + #define BFLOG_DIRECT_TYPE_BUFFER ((uint8_t)0x01) + #define BFLOG_DIRECT_TYPE_STREAM ((uint8_t)0x02) + #define BFLOG_DIRECT_TYPE_FILE ((uint8_t)0x03) + #define BFLOG_DIRECT_TYPE_FILE_TIME ((uint8_t)0x04) + #define BFLOG_DIRECT_TYPE_FILE_SIZE ((uint8_t)0x05) + +BFLOG_DIRECT_COLOR +^^^^^^^^^^^^^^^^^^^^ + +用于 bflog_direct_create 第三个参数 + +.. code-block:: c + :linenos: + + #define BFLOG_DIRECT_COLOR_DISABLE ((uint8_t)0) + #define BFLOG_DIRECT_COLOR_ENABLE ((uint8_t)1) + +BFLOG_LAYOUT_TYPE +^^^^^^^^^^^^^^^^^^^^ + +用于 bflog_layout_create 第二个参数 + +.. code-block:: c + :linenos: + + #define BFLOG_LAYOUT_TYPE_SIMPLE ((uint8_t)0) + #define BFLOG_LAYOUT_TYPE_FORMAT ((uint8_t)1) + #define BFLOG_LAYOUT_TYPE_YAML ((uint8_t)2) + +Port Functions +------------ + +bflog_clock +^^^^^^^^^^^^^^^^^^^^ + +获取当前cpu时钟数 + +.. code-block:: c + :linenos: + + uint64_t bflog_clock(void); + +bflog_time +^^^^^^^^^^^^^^^^^^^^ + +获取当前UTC时间戳 + +.. code-block:: c + :linenos: + + uint32_t bflog_time(void); + +bflog_thread +^^^^^^^^^^^^^^^^^^^^ + +获取当前线程名称 + +.. code-block:: c + :linenos: + + char *bflog_thread(void); + +Global Functions +------------ + +bflog_global_filter +^^^^^^^^^^^^^^^^^^^^ + +用于对标签过滤器进行全局的开关,会影响所有的recorder和direct + +.. code-block:: c + :linenos: + + int bflog_global_filter(void *tag_string, uint8_t enable); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - tag_string + - 标签字符串的指针 + * - enable + - 是否使能 + + +Recorder Functions +------------ + +recorder负责收集日志, 具有illegal、ready、running、suspend四种状态 +running状态可以收集日志, ready、suspend状态可以对其进行配置 +除level配置操作外, 其他配置操作必须在ready、suspend下 + +bflog_create +^^^^^^^^^^^^^^^^^^^^ + +创建一个recorder, 需要定义一个bflog_t结构体并将其指针传入,定义一块内存数组用于换冲 +成功返回0,失败返回-1 + +.. code-block:: c + :linenos: + + int bflog_create(bflog_t *log, void *pool, uint16_t size, uint8_t mode); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - log + - recorder 指针 + * - pool + - 用于缓冲的数组 + * - size + - 用户缓冲的数组大小 + * - mode + - BFLOG_MODE + +bflog_delete +^^^^^^^^^^^^^^^^^^^^ + +删除一个recorder +处于ready、suspend +线程安全的 +成功返回0,失败返回-1 + +.. code-block:: c + :linenos: + + int bflog_delete(bflog_t *log); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - log + - recorder 指针 + +bflog_append +^^^^^^^^^^^^^^^^^^^^ + +将一个direct添加到此recorder +处于ready、suspend +线程安全的 +成功返回0,失败返回-1 + +.. code-block:: c + :linenos: + + int bflog_append(bflog_t *log, bflog_direct_t *direct); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - log + - recorder 指针 + * - direct + - direct 指针 + +bflog_remove +^^^^^^^^^^^^^^^^^^^^ + +将一个direct从recorder移除 +处于ready、suspend +线程安全的 +成功返回0,失败返回-1 + +.. code-block:: c + :linenos: + + int bflog_remove(bflog_t *log, bflog_direct_t *direct); + +.. list-table:: + :widths: 10 10 + :header-rows: 1 + + * - parameter + - description + * - log + - recorder 指针 + * - direct + - direct 指针 + diff --git a/docs/source/api_reference/peripherals/dac.rst b/docs/source/api_reference/peripherals/dac.rst index 8fe73be4..97df5bf6 100644 --- a/docs/source/api_reference/peripherals/dac.rst +++ b/docs/source/api_reference/peripherals/dac.rst @@ -4,18 +4,18 @@ DAC Macros ------------ -dac sampling frequence +dac clock div ^^^^^^^^^^^^^^^^^^^^^^^^^ -dac 采样频率可以选择 32K、16K、8K，512K 只有 dma 模式下才可以使用。 +dac 分频，只有 DMA 模式下可以使用 1 分频。 .. code-block:: c :linenos: - #define DAC_SAMPLING_FREQ_32K 0 - #define DAC_SAMPLING_FREQ_16K 1 - #define DAC_SAMPLING_FREQ_8K 3 - #define DAC_SAMPLING_FREQ_512K 4 + #define DAC_CLK_DIV_16 0 + #define DAC_CLK_DIV_32 1 + #define DAC_CLK_DIV_64 3 + #define DAC_CLK_DIV_1 4 dac channel ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -44,7 +44,7 @@ bflb_dac_init .. code-block:: c :linenos: - void bflb_dac_init(struct bflb_device_s *dev, uint8_t frequence); + void bflb_dac_init(struct bflb_device_s *dev, uint8_t clk_div); .. list-table:: :widths: 10 10 @@ -54,8 +54,8 @@ bflb_dac_init - description * - dev - 设备句柄 - * - frequence - - 采样率 + * - clk_div + - 分频值 bflb_dac_deinit ^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/api_reference/peripherals/doxygen.png b/docs/source/api_reference/peripherals/doxygen.png new file mode 100644 index 00000000..fe7b62e3 Binary files /dev/null and b/docs/source/api_reference/peripherals/doxygen.png differ diff --git a/docs/source/api_reference/peripherals/index.rst b/docs/source/api_reference/peripherals/index.rst index c239b738..e674063e 100644 --- a/docs/source/api_reference/peripherals/index.rst +++ b/docs/source/api_reference/peripherals/index.rst @@ -5,7 +5,7 @@ Peripherals 简介 --------- -BL MCU SDK 中外设驱动分为两类： **LHAL** 和 **SOC** ，前者对通用外设进行了统一的封装，不同芯片使用同一套接口，方便用户使用和移植到其他平台。后者则是每个芯片独有且特殊的部分，比如 GLB、HBN、PDS、AON 等等。 +BouffaloSDK 中外设驱动分为两类： **LHAL** 和 **SOC** ，前者对通用外设进行了统一的封装，不同芯片使用同一套接口，方便用户使用和移植到其他平台。后者则是每个芯片独有且特殊的部分，比如 GLB、HBN、PDS、AON 等等。 下面主要列出 **LHAL** 相关 API 的使用。 @@ -22,7 +22,6 @@ BL MCU SDK 中外设驱动分为两类： **LHAL** 和 **SOC** ，前者对通 uint8_t sub_idx; uint8_t dev_type; void *user_data; - bflb_dlist_t list; }; .. list-table:: @@ -202,6 +201,13 @@ API 支持情况 API 列表 --------------- +除了使用网页版查看 API 以外， 还提供了 **LHAL Doxygen** 版本，离线生成文档。 Doxyfile 文件在 ``drivers/lhal`` 目录下。 + +使用 Doxywizard 导入并运行即可。 + +.. figure:: doxygen.png + :alt: + .. toctree:: :maxdepth: 1 diff --git a/docs/source/conf.py b/docs/source/conf.py index 632c807b..9e35d51e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,37 +1,37 @@ -# Configuration file for the Sphinx documentation builder. - -# -- Project information - -project = 'BL_MCU_SDK' -copyright = '2022, Bouffalolab Team' -author = 'Bouffalolab Team' - -release = '2.0' -version = '2.0.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 = 'BouffaloSDK' +copyright = '2022, Bouffalolab Team' +author = 'Bouffalolab Team' + +release = '2.0' +version = '2.0.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 6e7e8e48..3454588b 100644 --- a/docs/source/get_started/cmake.rst +++ b/docs/source/get_started/cmake.rst @@ -1,7 +1,7 @@ CMake 框架的使用 ================== -本节主要介绍如何使用 CMake 框架。bl_mcu_sdk 中为用户封装了以下函数接口，基本满足常用场景的使用。 +本节主要介绍如何使用 CMake 框架。BouffaloSDK 中为用户封装了以下函数接口，基本满足常用场景的使用。 .. list-table:: :widths: 30 30 diff --git a/docs/source/get_started/devcube.rst b/docs/source/get_started/devcube.rst index 7e16cd70..10a2ef88 100644 --- a/docs/source/get_started/devcube.rst +++ b/docs/source/get_started/devcube.rst @@ -3,9 +3,11 @@ Bouffalo Lab DevCube 的使用 ============================= -本文档将简要介绍一下如何使用 Bouffalo Lab DevCube 集成开发工具烧写代码. +.. caution:: BouffaloSDK 不再使用此工具，使用 SDK 自带的命令行烧录工具 -Bouffalo Lab Dev Cube 工具可以从博流智能开发者社区下载适合您操作系统的版本，下载地址：`https://dev.bouffalolab.com/download `_ 。没有注册开发者账号的用户，可以点击开发者入口，使用 ``guest`` 用户进入。 +本文档将简要介绍一下如何使用 Bouffalo Lab DevCube 集成开发工具烧写代码。 + +Bouffalo Lab Dev Cube 工具可以从博流智能开发者社区下载适合您操作系统的版本，下载地址： `https://dev.bouffalolab.com/download `_ 。没有注册开发者账号的用户，可以点击开发者入口，使用 ``guest`` 用户进入。 下载完成后，解压后即可使用。 diff --git a/docs/source/get_started/eclipse.rst b/docs/source/get_started/eclipse.rst index 4a39557b..417a1978 100644 --- a/docs/source/get_started/eclipse.rst +++ b/docs/source/get_started/eclipse.rst @@ -13,7 +13,7 @@ Build and Debug with Eclipse .. figure:: img/eclipse1.png :alt: -- 其余需要的环境参考 :ref:`windows_cmd` +- 其余步骤参考 :ref:`windows_cmd` - 解压 Eclipse 并双击打开 `Eclipse.exe` diff --git a/docs/source/get_started/flash_prog.rst b/docs/source/get_started/flash_prog.rst new file mode 100644 index 00000000..cc74d328 --- /dev/null +++ b/docs/source/get_started/flash_prog.rst @@ -0,0 +1,84 @@ +.. _flash_prog_cfg: + +Flash prog cfg.ini 的使用 +================================= + +在用户执行 ``make flash`` 会调用 **bouffalo_flash_cube** 下的可执行文件，并根据 **Flash prog cfg.ini** 进行烧录， +本节主要介绍一下 **Flash prog cfg.ini** 的语法。 + +常规 MCU 使用（不使用无线功能） +--------------------------------- + +.. code-block:: ini + :linenos: + + [cfg] + # 0: no erase, 1:programmed section erase, 2: chip erase + erase = 1 + # skip mode set first para is skip addr, second para is skip len, multi-segment region with ; separated + skip_mode = 0x0, 0x0 + # 0: not use isp mode, #1: isp mode + boot2_isp_mode = 0 + + [firmware] + filedir = ./build/build_out/xxx*_$(CHIPNAME).bin + address = 0x0000 + + +- **cfg** 表示烧录时的一些配置，正常不需要改动 +- **firmware** 要烧录的应用固件，必须使用 **firmware** 名称。 + + - **filedir** 表示应用固件所在相对路径，正常来说是编译完后放在 `build/build_out` 目录。 ``_$(CHIPNAME).bin`` 是必须要的后缀，用于区分不同芯片。 ``xxx`` 表示应用固件名称，与 `CMakeLists.txt` 中 `project(xxx)` 中名称一致。 ``*`` 表示正则匹配，可用可不用。 + - **address** 必须使用 0 地址 + + +常规 IOT 使用（使用无线功能） +--------------------------------- + +.. code-block:: ini + :linenos: + + [cfg] + # 0: no erase, 1:programmed section erase, 2: chip erase + erase = 1 + # skip mode set first para is skip addr, second para is skip len, multi-segment region with ; separated + skip_mode = 0x0, 0x0 + # 0: not use isp mode, #1: isp mode + boot2_isp_mode = 0 + + [firmware] + filedir = ./build/build_out/xxx*_$(CHIPNAME).bin + address = 0x10000 + + [boot2] + filedir = ./build/build_out/boot2_*.bin + address = 0x000000 + + [partition] + filedir = ./build/build_out/partition*.bin + address = 0xE000 + + [mfg] + filedir = ./build/build_out/mfg*.bin + address = 0x210000 + +- **cfg** 表示烧录时的一些配置，正常不需要改动 +- **firmware** 要烧录的应用固件，必须使用 **firmware** 名称。 + + - **filedir** 表示应用固件所在相对路径，正常来说是编译完后放在 `build/build_out` 目录。 ``_$(CHIPNAME).bin`` 是必须要的后缀，用于区分不同芯片。 ``xxx`` 表示应用固件名称，与 `CMakeLists.txt` 中 `project(xxx)` 中名称一致。 + - **address** 由 `partition_xxx.toml` 指定 + +- **boot2** 要烧录的 boot2 固件，必须使用 **boot2** 名称。 + + - **filedir** 表示 boot2 固件所在相对路径，正常来说是编译完后放在 `build/build_out` 目录。 **自动从 bsp/board/board_name/config 目录拷贝**。 + - **address** 必须使用 0 地址 + +- **partition** 要烧录的 partition 固件，必须使用 **partition** 名称。 + + - **filedir** 表示 partition 固件所在相对路径，正常来说是编译完后放在 `build/build_out` 目录。 **自动从 bsp/board/board_name/config 目录 partition_xxx.toml 转换成 bin 文件并拷贝**。 + - **address** 由 `partition_xxx.toml` 指定 + +- **mfg** 要烧录的 mfg 固件，必须使用 **mfg** 名称。 + + - **filedir** 表示 mfg 固件所在相对路径，正常来说是编译完后放在 `build/build_out` 目录。 **自动从 bsp/board/board_name/config 目录拷贝**。 + - **address** 由 `partition_xxx.toml` 指定 diff --git a/docs/source/get_started/img/repo.png b/docs/source/get_started/img/repo.png new file mode 100644 index 00000000..069bd896 Binary files /dev/null and b/docs/source/get_started/img/repo.png differ diff --git a/docs/source/get_started/index.rst b/docs/source/get_started/index.rst index 626c3a7b..62440999 100644 --- a/docs/source/get_started/index.rst +++ b/docs/source/get_started/index.rst @@ -2,7 +2,7 @@ 开发环境搭建 ======================= -BL MCU SDK 提供了以下几种开发环境，包含安装、编译、烧录和调试，选择一种适合你的即可。 +BouffaloSDK 提供了以下几种开发环境，包含环境搭建、编译、烧录和调试，选择一种适合你的即可。 .. toctree:: :maxdepth: 1 diff --git a/docs/source/get_started/linux_wsl.rst b/docs/source/get_started/linux_wsl.rst index 6816b14e..07bb433c 100644 --- a/docs/source/get_started/linux_wsl.rst +++ b/docs/source/get_started/linux_wsl.rst @@ -68,7 +68,7 @@ Build with Linux or WSL gcc version 10.2.0 (Xuantie-900 elf newlib gcc Toolchain V2.2.5 B-20220323) -- 在 linux 中，有严格的权限限制，通常一个用户对应一个权限，所以如果提示下面信息，表示需要设置 cmake 权限。 +- 在 linux 中，有严格的权限限制，通常一个用户对应一个权限，所以如果提示下面信息，表示需要设置权限。因此，我们将使用到的工具都设置好权限即可 .. figure:: img/cmake_error.png :align: center @@ -78,8 +78,10 @@ Build with Linux or WSL .. code-block:: bash :linenos: - $ cd bl_mcu_sdk - $ sudo chmod +x tools/cmake/bin/cmake + $ cd bouffalo_sdk + $ chmod 777 +x tools/cmake/bin/cmake + $ chmod 777 +x tools/bflb_tools/bflb_fw_post_proc/bflb_fw_post_proc + $ chmod 777 +x tools/bflb_tools/bouffalo_flash_cube/BLFlashCommand 编译 ------------- @@ -92,7 +94,7 @@ Build with Linux or WSL :linenos: $ cd examples/helloworld - $ make CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 + $ make CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl602、bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 - 使用 ninja 编译 @@ -100,6 +102,14 @@ Build with Linux or WSL :linenos: $ cd examples/helloworld - $ make ninja CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 + $ make ninja CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl602、bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 -.. note :: 如果使用 BL808 或者 BL606P，需要在上面基础上添加 CPU_ID=id ,id 可以为 m0 或者 d0 \ No newline at end of file +.. note :: 如果使用 BL808 或者 BL606P，需要在上面基础上添加 CPU_ID=id ,id 可以为 m0 或者 d0 + +- 烧录 + +.. code-block:: bash + :linenos: + + $ cd examples/helloworld + $ make flash CHIP=chip_name COMX=port_name ## port_name 为串口号名称，比如 linux 中/dev/ttyACMx，wsl 中对应使用 /dev/ttySx diff --git a/docs/source/get_started/repo.rst b/docs/source/get_started/repo.rst new file mode 100644 index 00000000..14197477 --- /dev/null +++ b/docs/source/get_started/repo.rst @@ -0,0 +1,39 @@ +Repo 的使用 +======================= + +Repo 是谷歌用 Python 脚本写的调用 git 的一个脚本，可以实现管理多个 git 库，简单的几行命令便可以拉取很多仓库的代码。 + +安装 +-------- + +- 下载 `repo `_ 。 + +- windows 下将 `repo.exe` 文件（在 win 目录中）所在的路径配置到系统环境变量。 + +.. figure:: img/repo.png + :alt: + +- Linux 下执行以下命令。 + +.. code-block:: bash + :linenos: + + cd repo/linux + chmod +x repo + mv repo /usr/bin/repo + +下载代码 +---------- + +- 获取 SDK (只包含 BL616/BL618 版本) + +.. code-block:: bash + :linenos: + + repo init -u https://gerrit.bouffalolab.com/bouffalo/manifest/bouffalo_sdk -b master -m bl616-public.xml + + +同步代码 +---------- + +后续只需要使用 ``repo sync`` 即可同步代码。 \ 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 a67361ed..1371de2c 100644 --- a/docs/source/get_started/windows_cmd.rst +++ b/docs/source/get_started/windows_cmd.rst @@ -18,7 +18,8 @@ Build with Windows CMD $ cd d $ git clone git@gitee.com:bouffalolab/toolchain_gcc_t-head_windows.git -- 将 make、ninja、下载的 risc-v 工具链路径配置到系统环境变量中, 其中 make 和 ninja 工具位于 `bl_mcu_sdk/tools` 目录下。 +- 将 make、ninja、下载的 risc-v 工具链路径配置到系统环境变量中, 其中 make 和 ninja 工具位于 `bouffalo_sdk/tools` 目录下。 +- windows 11 配置完以后需要重启电脑才生效。 .. figure:: img/windows_path.png :alt: @@ -72,7 +73,7 @@ Build with Windows CMD :linenos: $ cd .\examples\helloworld\ - $ make CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 + $ make CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl602、bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 - 使用 ninja 编译 @@ -80,6 +81,14 @@ Build with Windows CMD :linenos: $ cd .\examples\helloworld\ - $ make ninja CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 + $ make ninja CHIP=chip_name BOARD=board_name ## chip_name 为芯片型号，可以填写 bl602、bl702、bl616、bl808、bl606p, board_name 为开发板名称，详见 bsp/board 目录 -.. note :: 如果使用 BL808 或者 BL606P，需要在上面基础上添加 CPU_ID=id ,id 可以为 m0 或者 d0 \ No newline at end of file +.. note :: 如果使用 BL808 或者 BL606P，需要在上面基础上添加 CPU_ID=id ,id 可以为 m0 或者 d0 + +- 烧录 + +.. code-block:: bash + :linenos: + + $ cd examples/helloworld + $ make flash CHIP=chip_name COMX=port_name ## port_name 为串口号名称，比如 COM5 diff --git a/docs/source/index.rst b/docs/source/index.rst index 109c4d6a..8f6dc7c2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,21 +1,23 @@ -.. BL MCU SDK 使用指南 documentation master file, created by +.. BouffaloSDK 使用指南 documentation master file, created by sphinx-quickstart on Thu Nov 21 10:50:33 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -BL MCU SDK 使用指南 +BouffaloSDK 使用指南 ====================================================== -欢迎来到 Bouffalo Lab BL_MCU_SDK 文档中心。 +欢迎来到 Bouffalo Lab BouffaloSDK 文档中心。 .. toctree:: :maxdepth: 1 :caption: 快速入门 get_started/index + get_started/flash_prog get_started/devcube get_started/debug get_started/cmake + get_started/repo .. toctree:: :maxdepth: 1