CMSIS 配置向导标记
字数: 0 字 阅读时间: 0 分钟
官方链接：Configuration Wizard Annotations
这里只是翻译一下。
标记规则
配置向导由标记条目和标记修饰组成。用这些标记可以为配置文件在 IDE 中创建 GUI 配置项 (参照下面的显示效果)。用 GUI 可以方便用户检查和修改配置文件，以满足实际应用需要。需要遵循以下规则：
- 标记向导区域必须在 100 行代码之内开头，而且必须以下面的标记开头：C
// <<< Use Configuration Wizard in Context Menu >>> - 标记向导区域以下面可选的标记结束：C
// <<< end of configuration section >>> - 在代码中，标记是写成注释的。每行标记必须以双斜杠注释打头 (
//) - 默认情况下，会修改标记后紧跟着的代码
- 下表中标记
*的条目可以有一个默认值。默认值可以跳过一些代码 (查看表中的跳过示例)。这会覆盖之前的规则 - 下表中标记
+的条目可以跟一个标识符。当指定标识符后，紧跟着的代码会匹配标识符然后修改。查看下表的标识符例子。标识符不可以与默认值同时使用 - 可以在标记条目中添加描述。描述内容可以在选中项目后显示 (查看下表)
- 标记条目和标记修饰符中的空白字符会被忽略
- 除了封闭注释条目以外，你不能在配置向导行中使用
<和>符号
下表是标记规则：
TIP
标记指的是 CMSIS 指定的标签，例如 <e> <h> 这种；标识符指的是 C 代码中的标识符，例如宏定义的名称。它这个配置向导语法类似 XML。
| 标记符 | 是否带文本 | 描述 |
|---|---|---|
<h> | 是 | 标题，创建一个组，由 <h> 和 </h> 括起来的配置项都属于一个组，可以展开、折叠。它不会修改代码，只是用来分组的。下面是选自代码示例一部分片段：标题条目如效果预览中的 Thread Configuration 所示。 |
<e>*+ | 是 | 启用或禁用一个组，可以选择是否启用组内的所有配置项。组内的配置项目都由<e> 和 </e> 括起来。下面是选自代码示例一部分片段：OS_ROBIN 为 1，没有选中则设置为 0。并且还会影响 OS_ROBINOUT 的设置。如效果预览中 <e>Round-Robin Thread switching ... </e> 所示。 |
<e.i>*+ | 是 | 可以修改特定位 (i)(例如：<e.4> - 修改 bit4 的值)。 Serial Number，选择框可以设置值。如果选中，USBD0_STR_DESC_SER_EN 置 1。 |
</h>, </e>, 或 </c> | 是 | 标题、组或注释的结尾 |
<n> | 是 | 显示提示文本 |
<i> | 是 | 对该条目的解释。 这个表中有许多例子都有解释。 |
<d> | 是 | 该条目的默认值 <e> 和 <q>，分别以 0 和 1 表示「禁用」和「启用」。用此选项可以实现「重置默认值」的功能。 |
<c>* | 是 | 启用代码片段：创建一个选择框来选择注释或不注释代码片段。勾选后代码会取消注释。 注释后，在每行前面都会添加双斜杠 (//) 注释，包括空格。 在这个例子中，如果勾选选择框，这些代码都不会被注释。 |
<!c>* | 是 | 禁用代码片段：创建一个选择框来选择注释或不注释代码片段。勾选后代码会被注释。 注释后，在每行前面都会添加双斜杠 (//) 注释，包括空格。 在这个例子中，如果勾选选择框，这些代码都会被注释。 |
<q>*+ | 是 | 通过选择框设置 0 或 1。 |
<o>*+ | 是 | 输入数值 Round-Robin Timeout [Ticks] 的值，输入范围可以是 1 ~ 1000。 |
<o.i>*+ | 是 | 设置单个 bit (例如：<e.4> - 修改 bit4 的值)。 USBD0_HS 的 bit4 将会被置 1。 |
<o.x..y>*+ | 是 | 设置一段 bit (例如：<o.4..5> - bit[5:4]). String Settings 和 Language ID。输入范围可以是 <0x0000-0xFCFF>。用户可以在这个范围里输入。这个选项可以修改 bit [15:0]。 |
<y>+ | 是 | 输入一个标识符或者数字 FAT_MAX_OPEN_FILES 的位置并设置它的值。 |
<s>*+ | 是 | 输入 ASCII 字符串 创建一个输入框，用户可以输入文本。字符串长度没有限制。 |
<s.i>*+ | 是 | 输入 ASCII 字符串，但是长度限制在 i 这个例子长度限制为 126 个字符。默认字符串是 "Keil Software"。 |
<a.i>*+ | 是 | 输入数组长度为 i 的数值 这个例子中数组的每个元素的大小都限制在 0 ~ 255 也就是 1 字节以内。默认全为零。可以用格式控制来确保显示为 16 进制。GUI 最多支持显示 64 个元素。 |
跳过示例 <qn>; | 无 | 跳过 n 个配置项。可以用在这个表中所有带 * 的标记项。 VALUE1 和 VALUE2，修改第三个 MODIFY_THIS 的数值。 |
标识符示例 <q identifier> | 无 | 修改所给标识符的值。可以用在这个表中所有带 + 的标记项。 VALUE1 和 VALUE2，修改标识符为 MODIFY_THIS 的数值。 |
| 修饰符 | 是否带文本 | 描述 |
|---|---|---|
<0-31> | 否 | (已弃用 1, 查看下面新的修改范围方法) 指定范围，包括边界值 |
<0-100:10> | 否 | (已弃用 1, 查看下面新的修改范围方法) 指定范围，但是只能是 10 的倍数，包括边界值 |
<0x40-0x1000:0x10> | 否 | (已弃用 1, 查看下面新的修改范围方法) 指定范围，但是只能是 0x10 也就是 16 的倍数。包括边界值 |
<-32..31> | 否 | 指定一定范围的值，包括负数。 |
<-50..100:10> | 否 | 指定范围，但是只能是 10 的倍数，包括边界值 |
<-0x40..0x1000:0x10> | 否 | 指定范围，但是只能是 0x10 也就是 16 的倍数。包括边界值 |
<value=> | 是 | 创建一个下拉框，可以选择并把 value 的值写入下一个配置项中。下面是选自代码示例一部分片段：Timer Thread Priority 创建一个下拉框，如果选择 High，OS_TIMERPRIO 会被设置为 5。当点击这个选项时，会显示一个下拉框。如效果预览中的 Thread Configuration 所示。 |
<identifier=> | 是 | 创建一个下拉框，会根据配置项所填的内容显示相应的文本，例如 dwt 在下拉框中会显示 DWT Cycle Counter。要注意的是这个选项只能用在带标识符 (<o identifier>) 的条目中。所选项目的文本会替换掉对应 identifier 后的内容，identifier 关键字由 <o identifier> 标签指定。 Time Stamp Source 的选择框，配置项填写的是 dwt，在选择框中会显示 DWT Cycle Counter 被选中。TIMESTAMP_SRC 设置为 dwt。当点击这个选项时，会显示一个下拉框。如效果预览中的 Thread Configuration 所示。也可以给结构体变量的成员赋值。例如： Red port mode 的下拉框，用来修改结构体成员 redPortMode 的值。可以选择 PushPull 或 OpenDrain，分别对应 OutPushPull_GPIO 和 OutOpenDrain_GPIO，选择后会替换 redPortMode 后的内容。 |
<#+1> <#-1> | 否 | 将输入的值，加减乘除后设置。 Default Thread stack size [byte] 的范围是 64 ~ 4096。输入的值 (这里是 200) 会被除 4 (<#/4>) 后设置。OS_STKSIZE 的结果是 200 / 4 也就是 50。输入框里会显示 200。如效果预览中的 Thread Configuration 所示。 |
<f.format-specifier> | 否 | 按照特定进制格式显示整数。format-specifier 必须是以下的字母：
|
1新版本的工具可能还会支持这些已弃用的功能。但是建议更新文件标记到最新版本。
代码示例
你可以复制下面的代码到一个头文件，然后打开 Keil uVision 预览：
C
//-------- <<< Use Configuration Wizard in Context Menu >>> -----------------
//
// <h>Thread Configuration
// =======================
//
// <o>Number of concurrent running threads <0-250>
// <i> Defines max. number of threads that will run at the same time.
// <i> Default: 6
#ifndef OS_TASKCNT
#define OS_TASKCNT 6
#endif
// <o>Default Thread stack size [bytes] <64-4096:8><#/4>
// <i> Defines default stack size for threads with osThreadDef stacksz = 0
// <i> Default: 200
#ifndef OS_STKSIZE
#define OS_STKSIZE 50
#endif
// <o>Main Thread stack size [bytes] <64-32768:8><#/4>
// <i> Defines stack size for main thread.
// <i> Default: 200
#ifndef OS_MAINSTKSIZE
#define OS_MAINSTKSIZE 50
#endif
// <o>Number of threads with user-provided stack size <0-250>
// <i> Defines the number of threads with user-provided stack size.
// <i> Default: 0
#ifndef OS_PRIVCNT
#define OS_PRIVCNT 0
#endif
// <o>Total stack size [bytes] for threads with user-provided stack size <0-1048576:8><#/4>
// <i> Defines the combined stack size for threads with user-provided stack size.
// <i> Default: 0
#ifndef OS_PRIVSTKSIZE
#define OS_PRIVSTKSIZE 0
#endif
// <q>Check for stack overflow
// <i> Includes the stack checking code for stack overflow.
// <i> Note that additional code reduces the Kernel performance.
#ifndef OS_STKCHECK
#define OS_STKCHECK 1
#endif
// <o>Processor mode for thread execution
// <0=> Unprivileged mode
// <1=> Privileged mode
// <i> Default: Privileged mode
#ifndef OS_RUNPRIV
#define OS_RUNPRIV 1
#endif
// </h>
// <h>RTX Kernel Timer Tick Configuration
// ======================================
// <q> Use Cortex-M SysTick timer as RTX Kernel Timer
// <i> Use the Cortex-M SysTick timer as a time-base for RTX.
#ifndef OS_SYSTICK
#define OS_SYSTICK 1
#endif
//
// <o>Timer clock value [Hz] <1-1000000000>
// <i> Defines the timer clock value.
// <i> Default: 12000000 (12MHz)
#ifndef OS_CLOCK
#define OS_CLOCK 12000000
#endif
// <o>Timer tick value [us] <1-1000000>
// <i> Defines the timer tick value.
// <i> Default: 1000 (1ms)
#ifndef OS_TICK
#define OS_TICK 1000
#endif
// </h>
// <h>System Configuration
// =======================
//
// <e>Round-Robin Thread switching
// ===============================
//
// <i> Enables Round-Robin Thread switching.
#ifndef OS_ROBIN
#define OS_ROBIN 1
#endif
// <o>Round-Robin Timeout [ticks] <1-1000>
// <i> Defines how long a thread will execute before a thread switch.
// <i> Default: 5
#ifndef OS_ROBINTOUT
#define OS_ROBINTOUT 5
#endif
// </e>
// <e>User Timers
// ==============
// <i> Enables user Timers
#ifndef OS_TIMERS
#define OS_TIMERS 1
#endif
// <o>Timer Thread Priority
// <1=> Low
// <2=> Below Normal <3=> Normal <4=> Above Normal
// <5=> High
// <6=> Realtime (highest)
// <i> Defines priority for Timer Thread
// <i> Default: High
#ifndef OS_TIMERPRIO
#define OS_TIMERPRIO 5
#endif
// <o>Timer Thread stack size [bytes] <64-4096:8><#/4>
// <i> Defines stack size for Timer thread.
// <i> Default: 200
#ifndef OS_TIMERSTKSZ
#define OS_TIMERSTKSZ 50
#endif
// <o>Timer Callback Queue size <1-32>
// <i> Number of concurrent active timer callback functions.
// <i> Default: 4
#ifndef OS_TIMERCBQS
#define OS_TIMERCBQS 4
#endif
// </e>
// <o>ISR FIFO Queue size<4=> 4 entries <8=> 8 entries
// <12=> 12 entries <16=> 16 entries
// <24=> 24 entries <32=> 32 entries
// <48=> 48 entries <64=> 64 entries
// <96=> 96 entries
// <i> ISR functions store requests to this buffer,
// <i> when they are called from the interrupt handler.
// <i> Default: 16 entries
#ifndef OS_FIFOSZ
#define OS_FIFOSZ 16
#endif
// </h>
//------------- <<< end of configuration section >>> -----------------------效果预览
下面是 Keil uVision 显示的效果：
如果解析成功，点击下方的 Configuration Wizard 就可以打开这个界面。
Option 是配置条目，以树形结构表示。每个项目都有提示 (如果有)。
Value 是设置的值，可以是选择框、输入框、下拉框 (项目需预先定义)。