This section explains how to configure and run runtime testing. It covers:

General Configuration

By default, it is assumed that the C++test project for running tests on Keil uVision project is created in the same location as the original Keil uVision project. This approach is not required; however it does significantly simplify the setup process, and all Test Configurations provided for running tests on Keil uVision projects are created with this assumption.

To be able to correctly execute unit testing or application monitoring, you may need to modify the original project by extending the program stack size and extending the program heap size. Typically, it should be sufficient to add about 0x1000 bytes of additional stack and heap (0x1000 for each). The size of the required additional heap and stack depends on the tests configuration and may be different for different projects configurations.

Runtime Library and Communication Channel

All Test Configurations for uVision projects contain a special step that will automatically build the runtime library. Thus, there is no need to perform an external build of runtime library and add its product to the linker command line.

If you prefer to use a prebuilt version of the runtime library in the testing process, you need to manually build the library and add it to the C++test build settings> linker flags. For more details, see Working with the C++test Runtime Library.

If you are NOT using the automatically-built runtime library...

To build the runtime library for uVision tools (assuming the required environment is configured correctly):

Go to the <CPPTEST_INSTALL_DIR>/engine/runtime directory.
Execute makeTARGET_CFG=ARM_armcc3_1_uV3.mk (for uVision3) or make TARGET_CFG=ARM_armcc4_0_uV4.mk (for uVision4).

Alternatively, the runtime library can be built directly in Keil uVision using the project file located in the <CPPTEST_INSTALL_DIR>/engine/runtime/projects/Keil_uV directory.

The Runtime Library for Keil uVision is preconfigured to use:

Serial communication channel for development environments with ULINK2 debug connector.
ITM based communication channel for development environments with ULINKPro (Recommended to be used with simulator also).

The implementation of ITM based communication channel is based on CMSIS header files and does not depend on particular hardware. It should work for all Cortex M3/M4 microcontrollers that support the ARM Core Sight Debug and Trace Technology with Instrumentation Trace Macrocell. This is the recommended solution from C++test version 7.3.2.x on. In most cases, you should not need to introduce any modifications to the communication channel implementation.

The serial communication channel is implemented specifically for the STM32F103 chip (USART2 is used by default). If you want to run testing on a different chip or use another communication channel, you may need to modify the definition of the communication channel or add a new one. The default implementation of the communication channel for the STM32F103ZE chip assumes that UART will be initialized by a hardware initialization routine provided by your project. Thus, the implementation of the communication channel init function

int localRsInitInternalSerial(CppTestStreamParameters *par)

is left empty. If you want to perform initialization of UART inside the C++test runtime library, you need to provide the initialization code for this routine. The UART parameters will be provided via the CppTestStreamParameters structure, passed as a function argument (CppTestStreamParameters is defined in CppTestTransportRS232Common.h file). It is initialized with the values defined in the TestRunnerGenerationStep execution flow step (see the test flow definitions in Keil-specific Test Configurations).

Hardware-Specific Initialization

Some projects require hardware-specific initialization code to be called before test cases for the source under test can be called. You can ensure that a hardware initialization function is called at a very early stage of the test executable by providing a definition of the void CppTest_Initialize(void) function. See Initialization and Finalization, for details.

Semihosting and Retargeting

Beginning with MDK-ARM 4.6, applications must be retargeted to drop all semihosting dependencies (see Known Limitations). C++test instrumentation of tested application and its Runtime Library force semihosting calls from ARM libraries, so full semihosting retargeting must be applied to the Test Application to allow successfull execution.

To facilitate application retargeting, ARM Compiler tools provide the __use_no_semihosting (or __use_no_semihosting_swi for earlier versions) import pragma and assembly symbol. When the import is included in even a single application's compilation unit, the ARM linker reports errors for all semihosted routines/symbols. If the tested application already contains __use_no_semihosting, the import will also apply to the Test App. Customized retargeting symbols in the tested application also apply to the Test App. The Test Application may produce more semihosting dependencies and therefore require additional retargeting.

To facilitate retargeting of test applications for non or partially retargeted code, C++test:

Forces __use_no_semihosting import for ARM Compiler for uVision versions 5.0x or later (MDK-ARM versions 4.6x or later) in Runtime Library's armcc-specific compiler configuration header.
Provides a Custom ARM library retargeting wizard for creating a default retargeting implementation file (by default cpptest_retgt.c) in the test project's "factory" folder. The file is intended for free modifications as mentioned inside. Choose New> Other> Runtime - Custom ARM Compilation Tools C library retargeting to access the wizard.

For more information on Semihosting and Retargeting refer to ARM or Keil documentation.

Configuring uVision for Runtime Testing

In both Simulator or Real Hardware testing modes, the C++test-generated test executable is automatically started via the uVision debugger script. For fully-automated test session runs, uVision needs to be configured to find a C++test generated debugger script that automates the test executable load and run action.

Modify the original uVision project as follows to enable automated running of the test executable with the C++test generated debugger script:

Go to the Options for the active target and open the Debug tab.
In the Debug tab, change the debugger target to Use Simulator (or real hardware, depending on your needs) and specify .\cpptest.ini under Initialization file. cpptest.ini will be generated during test execution (prior to invoking uVision).

Testing on the Simulator

The configuration for testing on the simulator uses the uVision simulation capabilities to run the prepared test executable. Testing results are sent in one of the following ways:

Via simulated UART, using the Test Configuration "Run Keil uVision Tests - simulator (UART)".
Via the ITM based communication channel, using the Test Configuration "Run Keil uVision Tests - ULINKPro or Simulator (ITM)" (strongly recommended, available starting from MDK-ARM 4.11).

In both cases, the uVision IDE provides a convenient interface to save testing results to a file with the assistance of the uVision debugger scripting option for redirecting the serial or ITM output to a file. The configuration will compile and link the necessary test executable components and then use uVision to run the prepared test executable with the assistance of debugger script that is generated "on the fly."

The debugger script templates are located in the C++test distribution at <C++test Install dir>\engine\etc\templates\for_recipes\uvision_sim.tja for simulator with UART communication channel and <C++test Install dir>\engine\etc\templates\for_recipes\uvision_ulinkPro_itm.tja for ITM based communication.

Debugger script templates can include user specific debugger scripts or can be customized to fit particular environment needs. See Customizing Built-in Test Configurations.

Testing on Real Hardware With a ULINKPro/ULINK2 Interface

The configurations for testing on real target devices use the uVision with ULINKPro or ULINK2 debug and trace adapter to run the prepared test executable. Testing results are sent from the target platform in one of the following ways:

Via UART, using the Test Configuration "Run Keil uVision Tests - ULINK2 (UART)".
Via the ITM based communication channel "Run Keil uVision Tests - ULINKPro or Simulator (ITM)" (strongly recommended, available starting from MDK-ARM 4.11).

Test Configurations will compile and link the necessary test executable components and then use uVision to run the prepared test executable with the assistance of a debugger script that is generated "on the fly."

For Test Configuration that use UART for results transmission C++test will use a small utility program: a serial port listener that will capture all the data sent from testing and save it to a file. Configurations that use the ITM-based communication for results transmission rely on the uVision interface to save testing results to a file with the assistance of the uVision debugger scripting.

The debugger script templates are located in the C++test distribution at <C++test Install dir>\engine\etc\templates\for_recipes\uvision_ulink.tja for UART communication channel and <C++test Install dir>\engine\etc\templates\for_recipes\uvision_ulinkPro_itm.tja for ITM based communication.

Debugger script templates can include user specific debugger scripts or can be customized to fit particular environment needs. See Customizing Built-in Test Configurations.

Customizing Built-in Test Configurations

The Test Configurations provided to execute runtime tests for uVision projects may require environment specific customization. Note that all configurations available in the "Builtin> Embedded Systems> Keil uVision" Test Configuration assume that the C++test project is created in the original uVision project location; however, this location is not required. The typical customizations are done with the help of test flow definition properties that are listed for each Test Configuration (in the Execution> General tab, "Execution details" section).

The table below describes the test flow properties for the MDK-ARM dedicated built-in Test Configurations:

Run Keil uVision Application with Memory Monitoring - ULINK2(UART)
Run Keil uVision Application with Memory Monitoring - ULINKPro or Simulator (ITM)
Run Keil uVision Tests - ULINK2 (UART)
Run Keil uVision Tests - ULINKPro or Simulator (ITM)
Run Keil uVision Tests - simulator (UART)

Name	Default Value	Description
uVision project executable location	${uvision:project_executable}	Automatically expanded to the location of the uVision project build product—usually the executable file. This variable is used for replacing the original executable with the C++test-generated test executable. It typically should not be modified.
uVision project project file	${uvision:project_file}	Automatically expanded to the location of the uVision project file. This variable is used for starting uVision with the generated debugger script to automate test execution. It typically should not be modified.
uVision IDE executable file	Uv4.exe	The location of the uVision IDE executable. This is required to start automated tests. If it is not automatically detected by C++test, you need to specify it manually.
uVision project directory	${uvision:project_directory}	Automatically expanded to the location of the uVision project directory. Used as a default location for storing C++test-generated debugger scripts. It typically should not be modified.
Uvision debugger initialization script	Empty	The full path to a debugger script file that will be included at the beginning of the C++test-generated debugger script (Optional). It can be used to handle platform-specific initialization of the debugging interface. If no specific initialization is required, then this property should be left empty
uVision project's target	${uvision:project_target}	Automatically expanded to uVision project's current target. If a special target is created in the uVision project for testing purposes, it should be manually specified as a value of this property.
Executable exit point	_sys_exit	The function name or address that is considered to be an end-point of test execution. The default configuration of C++test assumes that the last function called from test executable is _sys_exit. The debugger script generated by C++test finalizes the test execution when the running test program will reach the _sys_exit function (or any other function that is specified here).
Serial comm: target port	USART1	The uart port label. Can be used inside the C++test runtime library to implement conditional initialization.
Serial comm: host port	1	Host COM port number that is connected to a target device.
Serial comm: baud rate	9600	Serial transmission baud rate.
Serial comm: byte size	8	Serial transmission byte size.
Serial comm: parity	E	Serial transmission parity: none (N), odd (O), even (E), mark (M), or space (S).
Serial comm: stop bits		Serial transmission number of stop bits.

Serial Port Listener

When tests are executed on a real hardware device with the results emitted by UART, results reception on the host side is arranged with help of a utility serial port listener. For details about the serial port listener, see The RS232 Listener.

Unit Testing

The following test configurations are provided to facilitate the unit testing process:

Embedded Systems> Keil uVision> Run Keil uVision Tests - ULINK2 (UART)
Embedded Systems> Keil uVision> Run Keil uVision Tests - ULINKPro or Simulator (ITM)
Embedded Systems> Keil uVision> Run Keil uVision Tests – simulator (UART)

To run unit testing on the target or a simulator:

Manually create or automatically generate a set of test cases.
Duplicate one of the Keil uVision Test Configurations.
Modify the Test Configuration as needed.
- See General Configuration for details.
Select the desired testing context.
Run tests with the customized Test Configuration created above.

Debugging Test Cases

Use External Embedded debugging mode. For more details see:

Application Monitoring

The following test configurations are provided to facilitate the application monitoring process:

Embedded Systems> Keil uVision> Run Keil uVision Application with Memory Monitoring -ULINK2(UART)
Embedded Systems> Keil uVision> Run Keil uVision Application with Memory Monitoring -ULINKPro or Simulator (ITM)

To run application monitoring on the target:

Duplicate one of the Keil uVision Application Monitoring Test Configurations.
Modify the Test Configuration as needed.
- See General Configuration for details.
Select the desired testing context.
Run tests with the customized Test Configuration created above.

Known Limitations

All Supported MDK-ARM Versions

We recommend closing any running uVision instances before test application execution, which starts uVision in debugging mode. Leaving instances running (e.g. development) may prevent debugger from performing correctly.

MDK-ARM 4.6x and Later

Due to the changes in debugger and compiler libraries (especially Sys I/O lib module - sys_io.o) semihosting must be disabled when building the test executable. Standard symbols (such as _ttywrch and _sys_exit) and all I/O _sys_... and __std..._name symbols must be retargeted.

Page tree

Runtime Testing with Keil MDK-ARM Support