Minor update to USART driver validation

[cmsis-driver-validation] / Doxygen / DriverValidation.txt

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\mainpage Introduction

This manual explains the scope and the usage of the Software Pack for <b>CMSIS-Driver Validation</b>.<br>
<a href="http://www.keil.com/pack/doc/CMSIS/Driver/html/index.html" target="_blank">CMSIS-Driver</a> specifies the 
software API for peripheral driver interfaces that connect microcontroller peripherals with middleware or the user application. 

The CMSIS-Driver Validation is used to validate the driver implementation compliance to the CMSIS-Driver specification.

The CMSIS-Driver Validation provides:
  - Configurable validation tests for various CMSIS-Driver interfaces
  - Example projects that show the usage of the CMSIS-Driver Validation
  - Various Servers used for testing

The CMSIS-Driver Validation tests and verifies:
  - <b>API interface</b> using the driver capabilities as well as valid and invalid parameters
  - <b>Data communication</b> with various transfer sizes and communication parameters:
    - <b>Loopback testing</b> (for some interfaces) for testing of the underlying hardware with usage of a local loopback
    - <b>Server testing</b> (for some interfaces) for extensive testing of the underlying hardware with usage of a dedicated Server
  - <b>Transfer speed</b> of the data communication with time measurement of data transfer duration
  - <b>Event</b> signaling

The CMSIS-Driver Validation requires
<a href="http://www.keil.com/pack/doc/CMSIS/RTOS2/html/index.html" target="_blank">CMSIS-RTOS2</a> functionality and can be
used to verify the setup and configuration of the CMSIS-Driver interfaces in a user system.<br>

The diagram below shows an overview of the CMSIS-Driver Validation configuration.

\image html cmsis_dv.png

This manual contains the following chapters:
  - \ref setup                 - Describes the general setup of the CMSIS-Driver Validation test and how to generate test report.
  - \ref report                - Describes the reports produced by the CMSIS-Driver Validation.
  - \ref debugging             - Describes procedure for debugging of the interface drivers using the CMSIS-Driver Validation.
  - \ref resource_requirements - Lists memory and CMSIS-RTOS2 requirements.
  - \ref examples              - Contains information about several example projects including the required hardware setup.
  - <a class="el" href="./modules.html">Reference</a> - Explains the configuration and tests for the various CMSIS-Driver interfaces.

The CMSIS-Driver Validation provides validation for the following interfaces:
  - \ref dv_can   "CAN"        - Controller Area Network (CAN) interface driver.
  - \ref dv_eth   "Ethernet"   - Ethernet MAC and PHY peripheral interface driver.
  - \ref dv_i2c   "I2C"        - Inter-Integrated Circuit (I2C) multi-master serial single-ended bus interface driver.
  - \ref dv_mci   "MCI"        - Memory Card Interface driver for SD/MMC memory.
  - \ref dv_spi   "SPI"        - Serial Peripheral Interface (SPI) driver.
  - \ref dv_usart "USART"      - Universal Synchronous and Asynchronous Receiver/Transmitter (USART) interface driver.
  - \ref dv_usbd  "USB Device" - Universal Serial Bus (USB) Device interface driver.
  - \ref dv_usbh  "USB Host"   - Universal Serial Bus (USB) Host interface driver.
  - \ref dv_wifi  "WiFi"       - WiFi (Wireless Fidelity Interface) module/shield driver.

\note Extensive testing using dedicated Server is available for SPI and USART drivers.

This manual assumes that you are familiar with MDK. Refer to
<a href="http://www2.keil.com/mdk5/install" target="_blank">MDK Version 5 - Getting Started</a> for additional information.

<hr>

Revision History
----------------

<table class="cmtable" summary="Revision History">
    <tr>
      <th>Version</th>
      <th>Description</th>
    </tr>

    <tr>
      <td>V3.0.0-dev10</td>
      <td>
      - Minor update to USART driver validation (data buffers aligned to 32 bytes for DMA testing, 
        Tx Underflow and Rx Overflow tests not executed in synchronous master mode)
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev9</td>
      <td>
        - Minor update to SPI driver validation (enable Data Bits tests in loopback mode)
        - Minor update to SPI_Server application (use software controlled Slave Select in Master mode)
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev8</td>
      <td>
        - Minor update to USART driver validation (corrected RTS/CTS tests, less strict Initialize/Uninitialize and PowerControl tests)
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev7</td>
      <td>
        - Add support for Arm Cortex-M85 processor based devices
        - Add support for Arm China Star-MC1 processor based devices
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev6</td>
      <td>
        - Add pack version information in Test Report
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev5</td>
      <td>
        - Minor update to WiFi driver validation (less strict SocketAccept and SocektSend tests)
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev4</td>
      <td>
        - Minor update to USART driver validation (USART_TxBreak test documentation)
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev3</td>
      <td>
        - Update validation examples for Espressif ESP32, ESP8266 and WizNet WizFi360
        - Add SockServer application for IMXRT1050-EVKB
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev2</td>
      <td>
        - Minor update of WiFi Driver non-blocking mode tests
        - Update examples
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev1</td>
      <td>
        - Add WiFi Driver tests (socket functions in non-blocking mode)
        - Update examples (WiFi Driver related)
      </td>
    </tr>
    <tr>
      <td>V3.0.0-dev0</td>
      <td>
        - Rework USART driver validation (introduced USART_Server)
        - Add USART_Server application for Keil MCBSTM32F400 evaluation board
        - Update examples
        - Update documentation
      </td>
    </tr>
    <tr>
      <td>V2.0.1-dev2</td>
      <td>
        - Minor update to SPI driver validation documentation
        - Minor update to SPI_Server
      </td>
    </tr>
    <tr>
      <td>V2.0.1-dev1</td>
      <td>
        - Improved robustness of SPI Driver testing
        - Improved robustness of SPI Server
      </td>
    </tr>
    <tr>
      <td>V2.0.1-dev0</td>
      <td>
        - Minor update to SPI Driver testing
      </td>
    </tr>
    <tr>
      <td>V2.0.0</td>
      <td>
        - Remove bundle from components
        - Change configuration from single file to a file per component
        - Rework SPI Driver testing (introduced SPI_Server)
        - Add SPI_Server application for Keil MCBSTM32F400 evaluation board
        - Update WiFi Driver tests (support for WiFi Driver API V1.1.0)
        - Update all examples
        - Deprecate CMSIS-RTOS1
      </td>
    </tr>
    <tr>
      <td>V1.4.0</td>
      <td>
        - Updated conditions to support all Cortex-M devices
        - Introduced test groups (each driver is organized in a group)
        - Improved XSL for XML display
        - Updated all examples
        - Removed example for Atmel board
        - WiFi Driver Testing: Added SockServer application for PC running Microsoft Windows
        - WiFi Driver Testing: Added upstream and downstream bandwidth testing
        - WiFi Driver Testing: Added example for Inventek ISM43362 WiFi Driver testing on STMicroelectronics B-L475E-IOT01A1 board
        - WiFi Driver Testing: Added example for Inventek ISM43362 WiFi Driver testing using ISMART43362-E WiFi shield mounted on NXP LPCXpresso55S69 board
        - WiFi Driver Testing: Added examples for Espressif ESP8266 and ESP32 WiFi Driver testing with NXP MIMXRT1064-EVK board
        - WiFi Driver Testing: Added example for WIZnet WizFi360 WiFi Driver testing with NXP MIMXRT1064-EVK board
      </td>
    </tr>
    <tr>
      <td>V1.3.0</td>
      <td>
        - Added WiFi tests
      </td>
    </tr>
    <tr>
      <td>V1.2.0</td>
      <td>
        - Added CMSIS-RTOS2 and Arm Compiler 6 compatibility
      </td>
    </tr>
    <tr>
      <td>V1.1.0</td>
      <td>
        - Added USB Host, CAN and Ethernet Precision Time Protocol tests
      </td>
    </tr>
    <tr>
      <td>V1.0.0</td>
      <td>
        - Initial release for CMSIS-Driver API V2.0
      </td>
    </tr>
 </table>


*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page setup Setup

\section step1 Step 1: Create an MDK project for your target microcontroller device


\section step2 Step 2: Add the required software components

For proper operation, add the following software components in the <b>Manage Run-Time Environment</b> window:
- <b>CMSIS Driver Validation: Framework</b>
- <b>CMSIS Driver Validation: driver</b>, driver interfaces to be tested
- <b>CMSIS Driver: driver</b>, driver implementations to be tested
- <b>CMSIS: RTOS2 (API): Keil RTX5</b>
- <b>Compiler: I/O: STDOUT</b>, variant \b ITM (if your hardware does not support ITM select \b EVR to use Event Recorder instead of ITM)
- Resolve any unresolved component dependencies


\section step3 Step 3: Add the application's main file (main.c)

Right-click <b>Source Group 1...</b> and select <b>Add New Item to Group</b>, select <b>User Code Template</b> and choose the
<b>CMSIS-RTOS2 'main' function</b> file from <b>CMSIS: RTOS2:Keil RTX5</b>.

Add this include:
\code
#include "cmsis_dv.h"
\endcode

In the <c>app_main</c> function, create the \c cmsis_dv thread, before endless <c>for</c> loop:
\code
osThreadNew(cmsis_dv, NULL, NULL);
\endcode
to run all the tests that you have chosen in the next step.


\section step4 Step 4: Configure the CMSIS-Driver Validation framework in DV_Config.h file

Open <b>DV_Config.h</b> under the <b>CMSIS Driver Validation</b> group in the Project window.

In the configuration file <b>DV_Config.h</b> select <b>Plain Text</b> as the <b>Report Format</b>.

\section step5 Step 5: Configure the interface settings and tests in related DV_interface_Config.h files

Each interface has a related <b>DV_<i>interface</i>_Config.h</b> file, where <i>interface</i> represents interface's acronym or abbreviation.<br>
For example for Serial Peripheral Interface (SPI) related config file name is DV_SPI_Config.h.

For details on interface specific configuration and test selection please check the Configuration section in the 
<a class="el" href="./modules.html">Reference</a> of the related interface.


\section step6 Step 6: Configure the Heap memory

Depending on the buffer sizes used for data transfer tests the heap size has to be adjusted to provide enough memory for these 
buffers to be allocated.<br>
Depending on how heap is configured in your system, open your <b>startup_<i>device</i>.s</b> file from the \b Device group in the \b Project window 
or use a <b>linker script</b> to adjust the heap size.<br>
Set the <b>heap size</b> to minimum of <b>16384</b> bytes.

For details on heap requirements please refer to the \ref heap_req "Heap Memory requirements" documentation.


\section step7 Step 7: Configure the CMSIS-RTOS2 (Keil RTX5)

Open <b>RTX_Config.h</b> and set:
- <b>System Configuration: Global Dynamic Memory size [bytes]</b> to \a 16384
- <b>Thread configuration: Default Thread stack size [bytes]</b> to \a 3072

For details on CMSIS-RTOS2 requirements please refer to the \ref rtos2_req "CMSIS-RTOS2 requirements" documentation.

\section step8 Step 8: Configure the Device

Depending on your device, you might have different pin/hardware configuration options. Usually, you can configure the device
using the \c RTE_Device.h file from the \b Device group or with a vendor provided pin configuration tool. 
Enable all interfaces you wish to test and make all necessary pin-out changes required by your actual board layout (consult the board schematics).<br> 
You can check the provided \ref examples "examples" as a reference point.

For a robust test with good coverage, implement various targets with different settings:
- Use <b>non-DMA (IRQ)</b> and <b>DMA</b> configurations if they are available on the driver
- Use different compiler <b>optimization levels</b> in the
  <a href="http://www.keil.com/support/man/docs/uv4/uv4_dg_adscc.htm" target="_blank">C/C++ tab</a> of the
  <b>Options for Target</b> dialog


\section step9 Step 9: Setup the required hardware

For the interfaces that support loopback testing: \ref dv_eth "Ethernet", \ref dv_usart "USART" and \ref dv_spi "SPI", 
connect the following pins on your target hardware together (refer to the hardware schematics):

- Ethernet: RX+ and TX+, RX- and TX-
- USART:    RX and TX
- SPI:      MOSI and MISO

For the interfaces that support testing with dedicated server: \ref dv_wifi "WiFi" and \ref dv_spi "SPI", 
connect the related hardware as required by the related server:

- WiFi: WiFi module has to be in close proximity to the Access Point which is in the same network as the required \ref wifi_sock_setup
- SPI:  MOSI, MISO, SCLK, SS, GND to the same lines on the \ref spi_server


\section step10 Step 10: Download and Run the Project

In the <b>Options for Target</b> dialog, under debug settings, if you use ITM as standard output channel ensure that 
\b Trace and <b>ITM port 0</b> are enabled and that the correct <b>Core Clock</b> frequency is set:

\image html target_dialog.png "ITM Channel setting"

Build, load and run the project. The output is displayed in the <b>Debug (printf) Viewer</b> window.<br>
Example below shows output result of an SPI driver testing:
\verbatim
CMSIS-Driver_Validation v3.0.0 CMSIS-Driver SPI Test Report   March  30 2022   13:44:11 

TEST 01: SPI_GetVersion                   
  DV_SPI.c (1023): [INFO] Driver API version 2.3, Driver version 2.15
                                          PASSED
TEST 02: SPI_GetCapabilities              PASSED
TEST 03: SPI_Initialize_Uninitialize      PASSED
TEST 04: SPI_PowerControl                 
  DV_SPI.c (1314): [WARNING] PowerControl (ARM_POWER_LOW) is not supported
                                          PASSED
TEST 05: SPI_Mode_Master_SS_Unused        PASSED
TEST 06: SPI_Mode_Master_SS_Sw_Ctrl       PASSED
TEST 07: SPI_Mode_Master_SS_Hw_Ctrl_Out   PASSED
TEST 08: SPI_Mode_Master_SS_Hw_Mon_In     PASSED
TEST 09: SPI_Mode_Slave_SS_Hw_Mon         PASSED
TEST 10: SPI_Mode_Slave_SS_Sw_Ctrl        PASSED
TEST 11: SPI_Format_Clock_Pol0_Pha0       PASSED
TEST 12: SPI_Format_Clock_Pol0_Pha1       PASSED
TEST 13: SPI_Format_Clock_Pol1_Pha0       PASSED
TEST 14: SPI_Format_Clock_Pol1_Pha1       PASSED
TEST 15: SPI_Format_Frame_TI              PASSED
TEST 16: SPI_Format_Clock_Microwire       NOT EXECUTED
TEST 17: SPI_Data_Bits_1                  NOT EXECUTED
TEST 18: SPI_Data_Bits_2                  NOT EXECUTED
TEST 19: SPI_Data_Bits_3                  NOT EXECUTED
TEST 20: SPI_Data_Bits_4                  NOT EXECUTED
TEST 21: SPI_Data_Bits_5                  NOT EXECUTED
TEST 22: SPI_Data_Bits_6                  NOT EXECUTED
TEST 23: SPI_Data_Bits_7                  NOT EXECUTED
TEST 24: SPI_Data_Bits_8                  PASSED
TEST 25: SPI_Data_Bits_9                  NOT EXECUTED
TEST 26: SPI_Data_Bits_10                 NOT EXECUTED
TEST 27: SPI_Data_Bits_11                 NOT EXECUTED
TEST 28: SPI_Data_Bits_12                 NOT EXECUTED
TEST 29: SPI_Data_Bits_13                 NOT EXECUTED
TEST 30: SPI_Data_Bits_14                 NOT EXECUTED
TEST 31: SPI_Data_Bits_15                 NOT EXECUTED
TEST 32: SPI_Data_Bits_16                 PASSED
TEST 33: SPI_Data_Bits_17                 NOT EXECUTED
TEST 34: SPI_Data_Bits_18                 NOT EXECUTED
TEST 35: SPI_Data_Bits_19                 NOT EXECUTED
TEST 36: SPI_Data_Bits_20                 NOT EXECUTED
TEST 37: SPI_Data_Bits_21                 NOT EXECUTED
TEST 38: SPI_Data_Bits_22                 NOT EXECUTED
TEST 39: SPI_Data_Bits_23                 NOT EXECUTED
TEST 40: SPI_Data_Bits_24                 NOT EXECUTED
TEST 41: SPI_Data_Bits_25                 NOT EXECUTED
TEST 42: SPI_Data_Bits_26                 NOT EXECUTED
TEST 43: SPI_Data_Bits_27                 NOT EXECUTED
TEST 44: SPI_Data_Bits_28                 NOT EXECUTED
TEST 45: SPI_Data_Bits_29                 NOT EXECUTED
TEST 46: SPI_Data_Bits_30                 NOT EXECUTED
TEST 47: SPI_Data_Bits_31                 NOT EXECUTED
TEST 48: SPI_Data_Bits_32                 NOT EXECUTED
TEST 49: SPI_Bit_Order_MSB_LSB            PASSED
TEST 50: SPI_Bit_Order_LSB_MSB            PASSED
TEST 51: SPI_Bus_Speed_Min                PASSED
TEST 52: SPI_Bus_Speed_Max                
  DV_SPI.c (3524): [WARNING] At requested bus speed of 10000000 bps, effective bus speed is 6477809 bps
                                          PASSED
TEST 53: SPI_Number_Of_Items              PASSED
TEST 54: SPI_Abort                        PASSED
TEST 55: SPI_DataLost                     PASSED
TEST 56: SPI_ModeFault                    PASSED

Test Summary: 56 Tests, 25 Passed, 0 Failed.
Test Result: PASSED
\endverbatim

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page report Report

The CMSIS-Driver Validation can output the test report in a <b>Plain Text</b> format or as an <b>XML</b> formatted file.<br>
Selection of the output report type is done in the <b>DV_Config.h</b> configuration file.

\image html dv_config_h.png "Configuration file DV_Config.h in Configuration Wizard view mode"

The <b>Plain Text</b> selection instructs the CMSIS-Driver Validation framework to generate a plain text report 
which can be seen in the <b>Debug (printf) Viewer</b> window and is mostly used for driver debugging purposes 
but can also be used as a final report.

The <b>XML</b> selection instructs the CMSIS-Driver Validation framework to generate an XML formatted report 
which is meant to be used as a final report and can be viewed nicely in any Web browser.<br>

The report file can be written into a <b>TestReport.xml</b> file directly by the uVision with an additional debugger script 
called <b>SaveXML.ini</b> which needs to be specified as <b>Initialization File:</b> for the <b>Debugger</b> in the 
<b>Options for target</b> dialog, or it can be copy-pasted manually from the <b>Debug (printf) Viewer</b> window to 
the TestReport.xml file.<br>
The SaveXML.ini script can be found in <c>\<pack root directory\></c><b>\\Scripts</b> directory.

To view <b>TestReport.xml</b> file in a Web browser an additional style sheet <b>TR_Style.xsl</b> file needs to be 
in the same directory as the TestReport.xml file.<br>
The TR_Style.xsl file contains the description of formatting for the Web browser to display the TestReport.xml report and 
can be found in <c>\<pack root directory\></c><b>\\Scripts</b> directory.


The XML file uses coloring to differentiate the results in the following way:
 - <span style="font-weight:bold; color:Green">Passed</span> status means that test function has passed successfully.
 - <span style="font-weight:bold; color:DarkOrange">Passed</span> status means that test function has passed but there were some warnings 
     (<c>More details</c> can be used to see the details about warnings).
 - <span style="font-weight:bold; color:Blue">Not executed</span> status means that test function did not check any assertions.
 - <span style="font-weight:bold; color:Red">Failed</span> status means that test function has failed 
     (<c>More details</c> can be used to see the details on reasons of failure).

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page debugging Debugging

After running the CMSIS-Driver Validation output report is used to see if the driver is compliant to the CMSIS-Driver specification.

If the result of the driver testing under <c>Test Summary</c> contains any <c>Failed</c> tests then the driver needs to be corrected.

Example of report in the Plain Text format of a non-compliant SPI driver:
\verbatim
CMSIS-Driver SPI Test Report   May  6 2020   10:47:11 

TEST 01: SPI_GetVersion                   
  DV_SPI.c (1023): [INFO] Driver API version 2.3, Driver version 2.15
                                          PASSED
TEST 02: SPI_GetCapabilities              PASSED
TEST 03: SPI_Initialize_Uninitialize      
  DV_SPI.c (1106): [FAILED]
  DV_SPI.c (1109): [FAILED]
  DV_SPI.c (1112): [FAILED]
                                          FAILED
TEST 04: SPI_PowerControl                 
  DV_SPI.c (1314): [WARNING] PowerControl (ARM_POWER_LOW) is not supported
                                          PASSED
...

Test Summary: 56 Tests, 24 Passed, 1 Failed.
Test Result: FAILED
\endverbatim

From previous report it is clear that one test function has failed.<br>
By Inspecting the details in previous report it is clear that <c>TEST 03: SPI_Initialize_Uninitialize</c> has failed 
on multiple assertions.<br>
Each failed assertion is recorded as a single  line in the test report.<br>
The failed assert information in the output report contains additional information about the <b>source module</b> and <b>line</b> 
in that module where the assertion is located with additional debugging info if available.

The documentation can be consulted regarding the failed function, for example in previous case 
documentation on the \ref SPI_Initialize_Uninitialize can be consulted.

Main way of fixing the driver consists of opening reported file mentioned as failed and inspecting the 
line in which failure was reported.

If there are many failures, it is recommended to deselect all tests except first failing one 
so it is easier to focus on just that failure.
Also, selecting only first failing test removes potential clutter from following failing tests that 
are all failing due to same cause.

In the previous report, opening <b>DV_SPI.c</b> module (available in the project) and inspecting the <b>1106</b> line 
which states:
\verbatim
  // Driver is uninitialized and peripheral is powered-off:
  // Call PowerControl(ARM_POWER_FULL) function and assert that it returned ARM_DRIVER_ERROR status
  TEST_ASSERT(drv->PowerControl (ARM_POWER_FULL) == ARM_DRIVER_ERROR);
\endverbatim

informs us that call to <c>PowerControl (ARM_POWER_FULL)</c>, when driver is not initialized, is expected to 
return <c>ARM_DRIVER_ERROR</c> status code but it has returned a different status code instead.

We should put a breakpoint to this line and start the debug session.<br>
When the breakpoint is hit we can see that a call to <c>PowerControl (ARM_POWER_FULL)</c> has returned <c>ARM_DRIVER_OK</c> 
instead of expected <c>ARM_DRIVER_ERROR</c> status code.

We can now go into source code of the driver and fix this.

After we have fixed the driver, the report now looks like below:

\verbatim
CMSIS-Driver SPI Test Report   May  6 2020   11:15:30 

TEST 01: SPI_GetVersion                   
  DV_SPI.c (1023): [INFO] Driver API version 2.3, Driver version 2.15
                                          PASSED
TEST 02: SPI_GetCapabilities              PASSED
TEST 03: SPI_Initialize_Uninitialize      PASSED
TEST 04: SPI_PowerControl                 
  DV_SPI.c (1314): [WARNING] PowerControl (ARM_POWER_LOW) is not supported
                                          PASSED
...

Test Summary: 56 Tests, 25 Passed, 0 Failed.
Test Result: PASSED
\endverbatim

The fix for the assertion failing in line 1106 has also fixed subsequent assertions 
in lines 1109 and 1112 thus the driver now reports no failed tests and reports that all 
of the 25 executed tests have passed.

This report could be used as an insurance that the SPI Driver on this device is compliant to the CMSIS-Driver specification.

The TestReport.xml report created instead of Plain Text opened in a Web browser looks similar to the the picture below:

\image html xml_report.png "XML test report"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page resource_requirements Resource Requirements

\section heap_req Heap Memory
Heap memory is used by the memory allocation functions.<br>
It is usually configured in the <a class="el" href="http://www.keil.com/support/man/docs/gsac/gsac_startupcodecortex.htm" target="_blank">startup_device.s</a>
file located under the \b Device component class but it can also, in some cases,  be configured by a <b>linker script</b> instead.

Some interface test functions allocate additional buffers from the heap memory.

The CMSIS-Driver Validation framework does not impose heap requirements because it does not use heap memory.

Each interface test module has specific requirements for the heap memory, default requirements are listed below:

| Interface test module   | Heap memory requirement (in bytes) |
| :---------------------: | :--------------------------------: |
| CAN                     | 128                                |
| Ethernet                | 1024                               |
| SPI                     | 12288                              |
| USART                   | 8192                               |

Interface test modules that are not listed in the previous table do not use heap memory.

The system heap memory size must support the largest heap requirement of any used interface test module.<br>
For example, if SPI driver testing is selected heap memory size should be set to at least 12 kB.

Suggested value for heap memory size is <b>16384</b> bytes.

\note Each module contains additional settings in related configuration file which are not exposed through 
      Configuration Wizard and impact the heap memory requirement.<br>
      If these values are changed please adjust heap memory size accordingly.

\section rtos2_req CMSIS-RTOS2

The thread requirements need to be reflected in the CMSIS-RTOS2 configuration. Refer to the
<a class="el" href="http://www.keil.com/pack/doc/cmsis/RTOS2/html/index.html" target="_blank">CMSIS-RTOS2 Reference</a> for further details.

For <a class="el" href="http://www.keil.com/pack/doc/cmsis/RTOS2/html/rtx5_impl.html" target="_blank">CMSIS-RTOS2 RTX5</a>, thread
requirements are configured in the
<a class=el href="http://www.keil.com/pack/doc/cmsis/RTOS2/html/config_rtx5.html" target="_blank">RTX_Config.h</a> file located
under the \b CMSIS component class:

| Option                                                            | Value                              |
| :---------------------------------------------------------------- | :--------------------------------: |
| System Configuration: Global Dynamic Memory size [bytes] (Note 1) | 16384                              |
| Thread Configuration: Default Thread Stack size [bytes]           | 3072                               |

\note Note 1: This setting is only necessary for WiFi driver testing, for other driver testing value of 4096 bytes is sufficient.

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples Examples

The CMSIS-Driver Validation Software Pack contains a set of examples that show how to use the CMSIS-Driver Validation on 
a real hardware.<br>
Use <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> to copy them to your machine.

The following example projects are available:

- \subpage examples_xmc4500_relax
- \subpage examples_mcbstm32f200
- \subpage examples_mcbstm32f400
- \subpage examples_b_l475e_iot01a1
- \subpage examples_stm32f746g
- \subpage examples_ismart43362_e
- \subpage examples_esp8266
- \subpage examples_esp32
- \subpage examples_wizfi360

\anchor example_targets
Targets
-------

Example projects contain some of the following targets:
- <b>Create Report</b>: Test results and statistics are printed to the <b>TestReport\TestReport.xml</b> file. Open the file in a Web browser of your choice.
- \b Debug: Results and statistics are printed to the <b>Debug (printf) Viewer</b> window or to the <b>Virtual COM Port</b> through the on-board debugger.
- \b Release: Same as the Debug target but with higher level of code optimization selected.
*/


/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_xmc4500_relax Infineon XMC4500 Relax Kit

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>Infineon::XMC4000_DFP</b> pack and copy the example project
<b>CMSIS-Driver Validation (XMC4500 Relax Lite Kit)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# If you wish to test the loopback mode for some of the interfaces, refer to the next section for proper board
   configuration.
-# Run the validation on the target hardware using the on-board JLink-Lite debugger.

Hardware Setup
--------------

The following picture shows the necessary external loopback connections for the Infineon XMC4500 Relax Kit evaluation board:
 - <b>UART2</b>: \b P0.4 (UART2_RX)  and \b P0.5 (UART2_TX)  (Header X2)
 - <b>SPI0</b>:  \b P5.0 (SPI0_MOSI) and \b P5.1 (SPI0_MISO) (Header X2)
 - For <b>Ethernet</b> use a loopback plug as described in \ref eth_loopback "Loopback Communication Setup". 

\image html xmc4500.png  "Connections for Loopback Communication Tests on the Infineon XMC4500 Relax Kit"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_mcbstm32f200 Keil MCBSTM32F200

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>Keil::STM32F2xx_DFP</b> pack and copy the example project
<b>CMSIS-Driver Validation (MCBSTM32F200)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# If you wish to test the loopback mode for some of the interfaces, refer to the next section for proper board
   configuration.
-# Run the validation on the target hardware.

\note The example is preconfigured to use an 
<a href="http://www2.keil.com/mdk5/ulink/ulinkplus/" target="_blank">ULINKplus</a> debug adapter.


Hardware Setup
--------------

The following picture shows the necessary external loopback connections for the Keil MCBSTM32F200 evaluation board:
 - <b>SPI2</b>: \b PB14 (SPI2_MISO) and \b PB15 (SPI2_MOSI) (for Loopback Test Mode)
 - <b>USART1</b>: \b PB6 (USART1_TX) and \b PB7 (USART1_RX)
 - For <b>Ethernet</b> use a loopback plug as described in \ref eth_loopback "Loopback Communication Setup". 

\image html mcbstm32f400.png  "Connections for Loopback Communication Tests on the Keil MCBSTM32F200"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_mcbstm32f400 Keil MCBSTM32F400

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>Keil::STM32F4xx_DFP</b> pack and copy the example project
<b>CMSIS-Driver Validation (MCBSTM32F400)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# If you wish to test the loopback mode for some of the interfaces, refer to the next section for proper board
   configuration.
-# Run the validation on the target hardware.

\note The example is preconfigured to use an 
<a href="http://www2.keil.com/mdk5/ulink/ulinkplus/" target="_blank">ULINKplus</a> debug adapter.


Hardware Setup
--------------

The following picture shows the necessary external loopback connections for the Keil MCBSTM32F400 evaluation board:
 - <b>SPI2</b>: \b PB14 (SPI2_MISO) and \b PB15 (SPI2_MOSI) (for Loopback Test Mode)
 - <b>USART1</b>: \b PB6 (USART1_TX) and \b PB7 (USART1_RX)
 - For <b>Ethernet</b> use a loopback plug as described in \ref eth_loopback "Loopback Communication Setup". 

\image html mcbstm32f400.png  "Connections for Loopback Communication Tests on the Keil MCBSTM32F400"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_b_l475e_iot01a1 STMicroelectronics B-L475E-IOT01A1

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>Keil::STM32L4xx_DFP</b> pack and copy the example project
<b>CMSIS-Driver WiFi Inventek ISM43362 Validation (B-L475E-IOT01A1)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# Run the validation on the target hardware using the on-board ST-Link/V2 debugger.

This example is prepared for verification of the WiFi driver and it requires \ref wifi_requirements "WiFi requirements", 
as well as, proper configuration described in \ref wifi_config "WiFi Configuration".

For details on WiFi driver validation please refer to \ref dv_wifi.

\image html b-l475e-iot01a.png  "STMicroelectronics B-L475E-IOT01A1 board"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_ismart43362_e Inventek ISMART43362-E WiFi Shield with NXP LPCXpresso55S69

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>NXP::LPC55S69_DFP</b> and <b>NXP::LPCXpresso55S69_EVK</b> packs and copy the example project
<b>CMSIS-Driver WiFi Inventek ISM43362 Validation (LPCXpresso55S69)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# Run the validation on the target hardware.

\note The example is preconfigured to use an 
<a href="http://www2.keil.com/mdk5/ulink/ulinkplus/" target="_blank">ULINKplus</a> debug adapter.

This example is prepared for verification of the WiFi driver and it requires \ref wifi_requirements "WiFi requirements", 
as well as, proper configuration described in \ref wifi_config "WiFi Configuration".

For details on WiFi driver tests please refer to \ref dv_wifi.

Hardware Setup
--------------

This example uses the ISMART module with SPI communication.<br>
By default, the shield is loaded with a UART firmware.<br>
Instructions on how to flash the SPI firmware can be found in the
[CMSIS-Driver documentation](https://arm-software.github.io/CMSIS-Driver/General/html/driver_WiFi.html#driver_ISM43362).

For proper operation of the Inventek ISMART43362-E WiFi Shield please connect the jumper between 5V_BOARD and 5V_MOD pins 
on the WiFi Shield.

\note Before running the validation on this hardware the WiFi Shield has to be reset by pressing SW2 push-button 
on the WiFi Shield and the debug session has to be started in less than 5 seconds after the reset push-button was released.

\image html lpcxpresso55s69.png  "NXP LPCXpresso55S69 with Inventek ISMART43362-E WiFi Shield attached"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_esp8266 Espressif ESP8266 SparkFun WiFi Shield with NXP MIMXRT1064-EVK

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>NXP::MIMXRT1064_DFP</b> and <b>NXP::EVK-MIMXRT1064_BSP</b> packs and copy the example project
<b>CMSIS-Driver WiFi Espressif ESP8266 Validation (EVK-MIMXRT1064)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# Run the validation on the target hardware using the on-board CMSIS-DAP Debugger.

This example is prepared for verification of the WiFi driver and it requires \ref wifi_requirements "WiFi equirements", 
as well as, proper configuration described in \ref wifi_config "WiFi Configuration".

For details on WiFi driver tests please refer to \ref dv_wifi.

\image html mimxrt1064evk.png    "NXP MIMXRT1064-EVK with"
\image html esp8266_sparkfun.png "Espressif ESP8266 SparkFun WiFi Shield"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_esp32 Espressif ESP32 WROOM SparkFun Thing Plus WiFi Shield with NXP MIMXRT1064-EVK

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>NXP::MIMXRT1064_DFP</b> and <b>NXP::EVK-MIMXRT1064_BSP</b> packs and copy the example project
<b>CMSIS-Driver WiFi Espressif ESP32 Validation (EVK-MIMXRT1064)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# Run the validation on the target hardware using the on-board CMSIS-DAP Debugger.

This example is prepared for verification of the WiFi driver and it requires \ref wifi_requirements "WiFi equirements", 
as well as, proper configuration described in \ref wifi_config "WiFi Configuration".

For details on WiFi driver tests please refer to \ref dv_wifi.

\image html mimxrt1064evk.png        "NXP MIMXRT1064-EVK with"
\image html esp32_wroom_sparkfun.png "Espressif ESP32 WROOM SparkFun Thing Plus WiFi Shield"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_wizfi360 WIZnet WizFi360-EVB WiFi Shield with NXP MIMXRT1064-EVK

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>NXP::MIMXRT1064_DFP</b> and <b>NXP::EVK-MIMXRT1064_BSP</b> packs and copy the example project
<b>CMSIS-Driver WiFi WIZnet WizFi360 Validation (EVK-MIMXRT1064)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# Run the validation on the target hardware using the on-board CMSIS-DAP Debugger.

This example is prepared for verification of the WiFi driver and it requires \ref wifi_requirements "WiFi equirements", 
as well as, proper configuration described in \ref wifi_config "WiFi Configuration".

For details on WiFi driver tests please refer to \ref dv_wifi.

\image html mimxrt1064evk.png "NXP MIMXRT1064-EVK with"
\image html wizfi360-evb.png  "WIZnet WizFi360-EVB WiFi Shield"

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page examples_stm32f746g STMicroelectronics STM32F746G-Discovery

Software Setup
--------------

Using the <a href="http://www2.keil.com/mdk5/packinstaller" target="_blank">Pack Installer</a> install the latest 
<b>Keil::STM32F7xx_DFP</b> pack and copy the example project
<b>CMSIS-Driver Validation (STM32F746G-Discovery)</b> to your machine.

-# Choose one of the available \ref example_targets "Targets" and build the project.
-# If you wish to test the loopback mode for some of the interfaces, refer to the next section for proper board
   configuration.
-# Run the validation on the target hardware using the on-board ST-Link/V2 debugger.


Hardware Setup
--------------

The following picture shows the necessary external loopback connections for the STMicroelectronics STM32F746G-Discovery evaluation board:
 - <b>SPI2</b>: \b D12 (SPI2_MISO) and \b D11 (SPI2_MOSI)
 - <b>USART6</b>: \b D1 (USART6_TX) and \b D0 (USART6_RX)
 - For <b>Ethernet</b> use a loopback plug as described in \ref eth_loopback "Loopback Communication Setup". 

\image html stm32f746g-disco.png  "Connections for Loopback Communication Tests on STM32F746G-Discovery"

*/