From 9f95ff5b6ba01db09552b84a0ab79607060a2666 Mon Sep 17 00:00:00 2001 From: Ali Labbene Date: Wed, 11 Dec 2019 08:59:21 +0100 Subject: Official ARM version: v5.4.0 Add CMSIS V5.4.0, please refer to index.html available under \docs folder. Note: content of \CMSIS\Core\Include has been copied under \Include to keep the same structure used in existing projects, and thus avoid projects mass update Note: the following components have been removed from ARM original delivery (as not used in ST packages) - CMSIS_EW2018.pdf - .gitattributes - .gitignore - \Device - \CMSIS - \CoreValidation - \DAP - \Documentation - \DoxyGen - \Driver - \Pack - \RTOS\CMSIS_RTOS_Tutorial.pdf - \RTOS\RTX - \RTOS\Template - \RTOS2\RTX - \Utilities - All ARM/GCC projects files are deleted from \DSP, \RTOS and \RTOS2 Change-Id: Ia026c3f0f0d016627a4fb5a9032852c33d24b4d3 --- docs/Pack/html/configWizard.html | 471 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 471 insertions(+) create mode 100644 docs/Pack/html/configWizard.html (limited to 'docs/Pack/html/configWizard.html') diff --git a/docs/Pack/html/configWizard.html b/docs/Pack/html/configWizard.html new file mode 100644 index 0000000..7352e6c --- /dev/null +++ b/docs/Pack/html/configWizard.html @@ -0,0 +1,471 @@ + + + + + +Configuration Wizard Annotations +CMSIS-Pack: Configuration Wizard Annotations + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-Pack +  Version 1.5.0 +
+
Delivery Mechanism for Software Packs
+
+
+ +
+
    + +
+
+ + + +
+
+ +
+
+
+ +
+ + + + +
+ +
+ +
+
+
Configuration Wizard Annotations
+
+
+

+Annotation Rules

+

Configuration Wizard Annotations consist of annotation items and annotation modifiers. They create GUI-like elements in IDEs for configuration files (see Tool-specific display). Using a GUI-like approach makes it easier for the user to check and adapt configuration files to the application needs. The following rules apply:

+
    +
  • The Configuration Wizard section must begin within the first 100 lines of code and must start with the following comment line:
    // <<< Use Configuration Wizard in Context Menu >>>
    +
    • +
  • The Configuration Wizard section can end with the following optional comment:
    // <<< end of configuration section >>>
    +
    • +
  • Annotations are written as comments in the code. Each annotation line must start with a double forward slash (//).
    • +
  • By default, the next code symbol that follows the annotation is modified.
    • +
  • Items marked with * in the table below can be followed by a skip-value. A skip-value omits a number of code symbols (see skip example in table). This overwrites the previous rule.
    • +
  • A descriptive text can be added to items. This text is displayed on screen (see table).
    • +
  • Whitespace characters are ignored in annotation items or annotation modifiers (text excluded).
    • +
  • You must not use < or > within configuration wizard lines other than for enclosing annotation items.
    • +
+

The following table lists the Configuration Wizard Annotations:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Item Text Description
<h> yes Heading. Creates a header section. All items and options enclosed by <h> and </h> belong to one group and can be expanded. This entry makes no changes to code symbols. It is just used to group other items and modifiers.
+ Excerpt from the Code Example
// <h>Thread Configuration -- header without checkbox to group other items
+
// ...
+
// </h>
+
Is the header entry as shown in Tool-specific display.
<e>* yes Heading with enable. Creates a header section with a checkbox to enabled or disabled all items and options enclosed by <e> and </e>. Excerpt from the Code Example.
// <e>Round-Robin Thread switching -- header with checkbox
+
// ===============================
+
//
+
// <i> Enables Round-Robin Thread switching. -- tooltip information for the header
+
#ifndef OS_ROBIN
+
#define OS_ROBIN 1 -- this value is set through the checkbox
+
#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>
+
The entry <e>Round-Robin Thread switching ... </e> sets OS_ROBIN to 1 (checkbox enabled) or 0 (checkbox disabled) and encloses the OS_ROBINTOUT (Round-Robin Timeout) setting. See screen outcome in Tool-specific display.
<e.i>* yes Heading with Enable: modifies a specific bit (i) (example: <e.4> - changes bit 4 of a value).
// <e.4>Serial Number
+
// <i>Enable Serial Number String.
+
// <i>If disabled, Serial Number String will not be assigned to USB Device.
+
#define USBD0_STR_DESC_SER_EN 1
+
The example creates the heading Serial Number and a checkbox to set the value. If enabled, then bit 4 of USBD0_STR_DESC_SER_EN is set.
</h>, </e>, or </c> yes Heading, Enable, or Comment end.
<n> yes Notification text displayed
// <n> This is shown as plain text
+
<i> yes Tooltip help for previous item.
// <i>This is shown as a tooltip when hovering over a text.
+
Many examples in this table have tooltip examples.
<c>* yes Code enable: creates a checkbox to uncomment or comment code. All lines, including those with white spaces, get commented with double slashes (//) at the first found character when you disable the checkbox.
// <c1> Comment sequence block until block end when disabled
+
//<i> This may carry the block's description
+
+
foo
+
+
+bar
+
+
-xFoo
+
// </c>
+
In this example, the item is enabled, so that the sequence block is not commented.
<!c>* yes Code disable: creates a checkbox to comment or uncomment code. All lines, including those with white spaces, get commented with double slashes (//) at the first found character when you enable the checkbox.
// <!c1> Comment sequence block until block end when enabled
+
//<i> This may carry the block's description
+
//
+
//foo
+
//
+
//+bar
+
//
+
//-xFoo
+
// </c>
+
In this example, the item is enabled, so that the sequence block is commented.
<q>* yes Option for bit values which can be set via a checkbox.
// <h> Chip-select control
+
// <q> ASYNCWAIT: Wait signal during asynchronous transfer
+
// <i> Enables the FSMC to use the wait signal even during an asynchronous protocol.
+
// </h>
+
#define RTE_FSMC_BCR1_ASYNCWAIT 0 -- this is changed via a checkbox
+
<o>* yes Option with selection or number entry.
// <o>Round-Robin Timeout [ticks] <1-1000> -- text displayed on screen. Range of [ticks] is [1..1000]
+
// <i> Defines how long a thread will execute before a thread switch. -- tooltip info
+
// <i> Default: 5 -- tooltip info. Both displayed in one tooltip.
+
#ifndef OS_ROBINTOUT
+
#define OS_ROBINTOUT 5
+
#endif
+
// </e>
+
The example creates an option with the text Round-Robin Timeout [ticks] and a field to enter values that can range between {1..1000].
<o key-identifier>* (new!) yes

Option with identifier selection replacing the identifier after the specified key-identifier:

+
// <o TIMESTAMP_SRC>Time Stamp Source
+
// <dwt=> DWT Cycle Counter
+
// <systick=> SysTick
+
// <user=> User Timer
+
// <i>Selects source for 32-bit time stamp
+
#define TIMESTAMP_SRC dwt
+

The example creates an option with the text Time Stamp Source and a drop down-list showing the text items DWT Cycle Counter, SysTick and User Timer. The corresponding identifier within the tag <...=> will be used for replacement.

+

Use case for an assignment of an enumeration to a variable:

+
// <o redPortMode> Red port mode
+
// <OutPushPull_GPIO=> PushPull
+
// <OutOpenDrain_GPIO=> OpenDrain
+
// <i>Selects GPIO output
+
ledConf.redPortMode = OutOpenDrain_GPIO;
+

The example creates an option with the text Red port mode and a drop down-list showing the text items PushPull and OpenDrain. The corresponding identifier OutPushPull_GPIO or OutOpenDrain_GPIO will be used to replace the identifier after the key-identifier redPortMode.

+
<o.i>* yes Modify a single bit (example: <e.4> - modifies bit 4).
// <o.4> <o.0>High-speed
+
// <i>Enable High-speed functionality (if device supports it).
+
#define USBD0_HS 0
+
The example creates a heading with the text High-speed and a checkbox. If enabled, then bit 4 of USBD0_HS is set.
<o.x..y>* yes Modify a range of bits. (example: <o.4..5> - bit 4 to 5).
// <h>String Settings
+
// <i>These settings are used to create the String Descriptor.
+
// <o.0..15>Language ID <0x0000-0xFCFF>
+
// <i>English (United States) = 0x0409.
+
// </h>
+
#define USBD0_STR_DESC_LANGID 0x0409
+
This example creates an expandable header with the text String Settings and an option Language ID. The range of values is set to <0x0000-0xFCFF>. Users can enter a value from within that range. The option changes the bits 0..15.
<s>* yes Option with ASCII string entry.
// <s>Manufacturer String
+
// <i>String Descriptor describing Manufacturer.
+
#define USBD0_STR_DESC_MAN L"Keil Software"
+
Displays an option with the text Manufacturer String and creates a field in which the user can enter a text. The size of the string is not limited.
<s.i>* yes Option with ASCII string entry and a size limit of i characters.
// <s.126>Manufacturer String
+
// <i>String Descriptor describing Manufacturer.
+
#define USBD0_STR_DESC_MAN L"Keil Software"
+
The example sets a size limit of 126 character. Default string is "Keil Software".
skip example
+ <qi>;
+ <oi>; <oi.x>;
+ <si>; <si.x> 		yes Skip i items. Can be applied to all annotation items marked with a * in this table.
// <o2>Skip 2 and modify the third item after this entry <1-9>
+
#define VALUE1 1000
+
#define VALUE2 2000
+
#define MODIFY_THIS 3000
+
The example skips 2 items and modifies the third.
Modifier   Description
<0-31> no Value range for option fields.
<0-100:10> no Value range for option fields with step 10.
<0x40-0x1000:0x10> no Value range in hex format and step 10.
<value=> yes Creates a drop down-list and displays the text. value is written to the next item. Excerpt from the Code Example.
// <o>Timer Thread Priority -- creates a drop-down with the list below.
+
// <1=> Low
+
// <2=> Below Normal <3=> Normal <4=> Above Normal
+
// <5=> High
+
// <6=> Realtime (highest)
+
// <i> Defines priority for Timer Thread -- tooltip info
+
// <i> Default: High -- tooltip info
+
#ifndef OS_TIMERPRIO
+
#define OS_TIMERPRIO 5
+
#endif
+
In this example, the screen would show the option Timer Thread Priority. The field Value would display the text High. OS_TIMERPRIO is set to 5. When clicking on the field, a drop-down would show all options. See Tool-specific display.
<identifier=> yes Creates a drop down-list and displays the text following the definition of the identifiers dwt, systick and user. Note that this must only be used in the context of <o key-identifier>! The identifier corresponding to the selected text replaces the identifier following the key-identifier specified by the <o ...> tag.
// <o TIMESTAMP_SRC>Time Stamp Source
+
// <dwt=> DWT Cycle Counter
+
// <systick=> SysTick
+
// <user=> User Timer
+
// <i>Selects source for 32-bit time stamp
+
#define TIMESTAMP_SRC dwt
+
In this example, the screen would show the option Time Stamp Source. The field value would display the text DWT Cycle Counter. TIMESTAMP_SRC is set to dwt. When clicking on the field, a drop-down would show all options. See Tool-specific display.
<#+1>   <#-1>
+ <#*8>   <#/3> 		no Modifies the entered or displayed value according to the operator (add, sub, mul, div). The changed value is set for the code symbol.
+ Excerpt from Code Example.
// <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
+
The option Default Thread stack size [bytes] accepts values in the range [64..4096]. The value (here 200) set in the field is divided by 4 (<#/4>) . The result of the division (200/4) is put into the code symbol OS_STKSIZE, which was set to 50. The screen will display the number 200. See Tool-specific display.
+

+Code Example

+

You can copy the code into a C-file and check the outcome in the uVision Editor.

+
//-------- <<< 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 >>> -----------------------
+

+Tool-specific display

+

It is left to the development tool to interpret and display Configuration Wizard Annotations. The uVision IDE displays the code above in the following way:

+
+RTX_Conf_CM_Wizard_View.png +
+Configuration Wizard Display
+

Where

+

Option are device properties, which can be represented in a tree structure. Each item can have an explanatory tooltip.

+

Value sets the option value. Can contain controls to encapsulate data in predefined drop-down lists.

+
+
+ + + + -- cgit