/**************************************************************************************************/
/**
\page configWizard Configuration Wizard Annotations
\section configWizard_annotations Annotation Rules

<b>Configuration Wizard Annotations</b> consist of annotation items and annotation modifiers. They create GUI-like elements
in IDEs for configuration files (see \ref configWizard_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:
\code
// <<< Use Configuration Wizard in Context Menu >>>
\endcode
- The Configuration Wizard section can end with the following optional comment:
\code
// <<< end of configuration section >>>
\endcode
- 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
  <i>skip example</i> 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:

<table class="cmtable" summary="Annotations Tab">
    <tr>
      <th>Item</th>
      <th>Text</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>\<h></td>
      <td>yes</td>
      <td>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. 
      \n Excerpt from the \ref configWizard_codeExample 
      \code
      // <h>Thread Configuration                               -- header without checkbox to group other items
      //   ...
      // </h>
      \endcode
      Is the header entry as shown in \ref configWizard_display.
      </td>
    </tr>
    <tr>
      <td>\<e><sup>*</sup></td>
      <td>yes</td>
      <td>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 \ref configWizard_codeExample.
      \code
      // <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>
      \endcode
      The entry <code>\<e>Round-Robin Thread switching ... \</e></code> sets OS_ROBIN to \token{1} (checkbox enabled) or \token{0} (checkbox disabled) 
      and encloses the <i>OS_ROBINTOUT</i> (Round-Robin Timeout) setting. See screen outcome in \ref configWizard_display.
      </td>
    </tr>
    <tr>
      <td>\<e.<i>i</i>><sup>*</sup></td>
      <td>yes</td>
      <td>Heading with Enable: modifies a specific bit (<i>i</i>) (example: \<e.4> - changes bit 4 of a value).
      \code
       // <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
      \endcode
      The example creates the heading \token{Serial Number} and a checkbox to set the value. If enabled, then bit 4 of \token{USBD0_STR_DESC_SER_EN} is set.
      </td>
    </tr>
    <tr>
      <td>\</h>, \</e>, or \</c></td>
      <td>yes</td>
      <td>Heading, Enable, or Comment end.</td>
    </tr>
    <tr>
      <td>\<n></td>
      <td>yes</td>
      <td>Notification text displayed
      \code
      // <n> This is shown as plain text
      \endcode      
      </td>
    </tr>
    <tr>
      <td>\<i></td>
      <td>yes</td>
      <td>Tooltip help for previous item.
      \code
      // <i>This is shown as a tooltip when hovering over a text.
      \endcode
      Many examples in this table have tooltip examples.
      </td>
    </tr>
    <tr>
      <td>\<c><sup>*</sup></td>
      <td>yes</td>
      <td>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.
      \code
      // <c1> Comment sequence block until block end when disabled
      //<i> This may carry the block's description
      
      foo
      
      +bar
      
      -xFoo
      // </c>
      \endcode
      In this example, the item is enabled, so that the sequence block is not commented.
      </td>
    </tr>
    <tr>
      <td>\<!c><sup>*</sup></td>
      <td>yes</td>
      <td>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.
      \code
      // <!c1> Comment sequence block until block end when enabled
      //<i> This may carry the block's description
      //
      //foo
      //
      //+bar
      //
      //-xFoo
      // </c>
      \endcode
      In this example, the item is enabled, so that the sequence block is commented.
      </td>
    </tr>
    <tr>
      <td>\<q><sup>*</sup></td>
      <td>yes</td>
      <td>Option for bit values which can be set via a
      checkbox.
      \code
      //  <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
      \endcode  
      </td>
    </tr>
    <tr>
      <td>\<o><sup>*</sup></td>
      <td>yes</td>
      <td>Option with selection or number entry.
      \code
      // <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>
      \endcode
      The example creates an option with the text \token{Round-Robin Timeout [ticks]} and a field to enter values that can range between {1..1000].
      </td>
    </tr>
    <tr>
      <td>\<o <em>key-identifier</em>><sup>*  (new!)</sup></td>
      <td>yes</td>
      <td>Option with identifier selection replacing the identifier after the specified key-identifier:
      \code
      //   <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
      \endcode
      The example creates an option with the text \token{Time Stamp Source} and a drop down-list showing the text items 
      \token{DWT Cycle Counter}, \token{SysTick} and \token{User Timer}. The corresponding identifier within the tag \<...=> will be used for replacement.
      
      Use case for an assignment of an enumeration to a variable:
      \code
      //   <o redPortMode> Red port mode 
      //     <OutPushPull_GPIO=>  PushPull
      //     <OutOpenDrain_GPIO=> OpenDrain
      //   <i>Selects GPIO output
      ledConf.redPortMode = OutOpenDrain_GPIO;
      \endcode
      The example creates an option with the text \token{Red port mode} and a drop down-list showing the text items
      \token{PushPull} and \token{OpenDrain}. The corresponding identifier \token{OutPushPull_GPIO} or \token{OutOpenDrain_GPIO} will be used to replace the 
      identifier after the key-identifier \token{redPortMode}.
    </tr>
    <tr>
      <td>\<o.<i>i</i>><sup>*</sup></td>
      <td>yes</td>
      <td>Modify a single bit (example: \<e.4> - modifies bit 4).
      \code
      // <o.4> <o.0>High-speed
      //   <i>Enable High-speed functionality (if device supports it).
      #define USBD0_HS                        0
      \endcode
      The example creates a heading with the text \token{High-speed} and a checkbox. If enabled, then bit 4 of \token{USBD0_HS} is set.
      </td>
    </tr>
    <tr>
      <td>\<o.<i>x</i>..<i>y</i>><sup>*</sup>
      </td>
      <td>yes</td>
      <td>Modify a range of bits. (example: \<o.4..5> - bit 4 to 5).
      \code
      //   <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
      \endcode
      This example creates an expandable header with the text \token{String Settings} and an option \token{Language ID}. The range of values is set to \token{\<0x0000-0xFCFF>}.
      Users can enter a value from within that range. The option changes the bits \token{0..15}.
      </td>
    </tr>
    <tr>
      <td>\<s><sup>*</sup></td>
      <td>yes</td>
      <td>Option with ASCII string entry.
      \code
      //  <s>Manufacturer String
      //  <i>String Descriptor describing Manufacturer.
      #define USBD0_STR_DESC_MAN              L"Keil Software"
      \endcode
      Displays an option with the text \token{Manufacturer String} and creates a field in which the user can enter a text. 
      The size of the string is not limited.
      </td>
    </tr>
    <tr>
      <td>\<s.<i>i</i>><sup>*</sup></td>
      <td>yes</td>
      <td>Option with ASCII string entry and a size limit of <i>i</i> characters. 
      \code
      //  <s.126>Manufacturer String
      //  <i>String Descriptor describing Manufacturer.
      #define USBD0_STR_DESC_MAN              L"Keil Software"
      \endcode
      The example sets a size limit of 126 character. Default string is "Keil Software".
      </td>
    </tr>
    <tr>
      <td><i>skip example</i>
      <br> \<q\em i>; 
      <br> \<o\em i>;  \<o\em i.\em x>; 
      <br> \<s\em i>;  \<s\em i.\em x>
      </td>
      <td>yes</td>
      <td>Skip \em i items.  Can be applied to all annotation items marked with a * in this table.
      \code
      // <o2>Skip 2 and modify the third item after this entry <1-9>
      #define VALUE1       1000
      #define VALUE2       2000
      #define MODIFY_THIS  3000
      \endcode 
      The example skips 2 items and modifies the third.
      </td>
    </tr>
    <tr>
      <th>Modifier</th>
      <th>&nbsp;</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>\<0-31></td>
      <td>no</td>
      <td>Value range for option fields.</td>
    </tr>
    <tr>
      <td>\<0-100:10></td>
      <td>no</td>
      <td>Value range for option fields with step 10.</td>
    </tr>
    <tr>
      <td>\<0x40-0x1000:0x10></td>
      <td>no</td>
      <td>Value range in hex format and step 10.</td>
    </tr>
    <tr>
      <td>\<<i>value</i>=></td>
      <td>yes</td>
      <td>Creates a drop down-list and displays the \em <b>text</b>. \em <b>value</b> is written to the next item.
      Excerpt from the \ref configWizard_codeExample.
      \code
      //   <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
      \endcode
      In this example, the screen would show the option \token{Timer Thread Priority}. The field Value would display the text \token{High}. 
      OS_TIMERPRIO is set to \token{5}. When clicking on the field, a drop-down would show all options.
      See \ref configWizard_display.
      </td>
    </tr>
    <tr>
      <td>\<<i>identifier</i>=></td>
      <td>yes</td>
      <td>Creates a drop down-list and displays the \em <b>text</b> following the definition of the identifiers \token{dwt}, \token{systick} and \token{user}.
      Note that this must only be used in the context of \<o key-identifier>!
      The \em <b>identifier</b> corresponding to the selected text replaces the identifier following the key-identifier specified by the \<o ...> tag.
      \code
      //   <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
      \endcode
      In this example, the screen would show the option \token{Time Stamp Source}. The field value would display the text \token{DWT Cycle Counter}. 
      TIMESTAMP_SRC is set to \token{dwt}. When clicking on the field, a drop-down would show all options. See \ref configWizard_display.
    </tr>  
    <tr>
      <td>\<#+1>&nbsp;&nbsp; \<#-1><br>
          \<#*8>&nbsp;&nbsp; \<#/3></td>
      <td>no</td>
      <td>Modifies the entered or displayed value according to the operator (add, sub, mul, div). The changed value is set for the code symbol.
      \n Excerpt from \ref configWizard_codeExample.
      \code
      // <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
      \endcode
      The option <i>Default Thread stack size [bytes]</i> accepts values in the range \token{[64..4096]}. The value (here \token{200}) set in the field is divided by \token{4} (<#/4>) . 
      The result of the division (200/4) is put into the code symbol \em OS_STKSIZE, which was set to \token{50}. The screen will display the number \token{200}.
      See \ref configWizard_display.
      </td>
    </tr>
</table>

\section configWizard_codeExample Code Example

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

\code
//-------- <<< 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 >>> -----------------------
\endcode

\section configWizard_display 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:

\image html RTX_Conf_CM_Wizard_View.png "Configuration Wizard Display"

<b>Where</b>

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

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