RTX5 RTOS Bare-metal Streamline example for Cortex-M33

Purpose and scope

This Bare-metal Streamline example shows RTX5 RTOS on a Cortex-M33 processor, collection of profiling information via ITM with DSTREAM, and analysis in Streamline.

This example is intended to be built with Arm Compiler for Embedded 6. If you wish to modify and rebuild the example, you must use Arm Compiler for Embedded 6 to rebuild it.

This example is intended to run on an Arm MPS2+ board with FPGA programmed as a Cortex-M33, using DSTREAM or ULINK debug hardware connected between the Debugger and MPS2+. A ready-made launch configuration RTX5_Cortex-M33_Blinky_Streamline_MPS2.launch is provided.

The example can also be run (only) on the Cortex-M33 FVP model supplied with Development Studio, but its performance cannot be analyzed with Streamline because the ITM trace feature is not modelled.

Overview of the example code

The example comprises a simple application in main.c that creates and executes a number of threads. It calls RTX5 RTOS functions from the referenced CMSIS Pack, and outputs characters to a UART via a simple driver retarget.c and uart.c.

It gets compiled with barman.c that was generated by Streamline to provide all the necessary bare-metal Streamline features.

The application in main.c illustrates the use of Streamline annotations (both marker and channel annotations).

Some additional "plumbing" code is provided in main.c to initialize barman, to allow barman to read the current task from RTX5, and for RTX5 to inform barman when a task switch occurs. To avoid having to modify the CMSIS Pack, armlink's $Sub/$Super mechanism is used to "patch" the original RTX5 functions, to allow some extra work to be done between caller and callee. The result is that all the plumbing code between RTX5 and barman is collected together into a single C file. This helps to simplify future maintenance and should ease the porting to other RTOSes and/or toolchains. For example, GNU ld has the "--wrap" command-line option that works in a similar way.

For this example, barman.c must be compiled with BM_ITM_TRACE_ID=1 to ensure that barman sets the ATBID to 1 in the ITM Trace Control Register, to match what the Debugger expects ("trace info" shows "Source ID: 1" for "Trace Source: CSITM").

Building the example

A pre-built executable is provided, so there is no need to build the example unless you modify the source code.

This example can be built with Arm Compiler for Embedded 6 using the supplied Eclipse managed builder project, or directly on the command-line with the supplied makefile.

The example depends on the CMSIS Packs ARM.CMSIS.6.0.0, ARM.Cortex_DFP.1.0.0, and ARM.CMSIS-RTX.5.8.0. These will be installed automatically by the Pack Manager, unless "Automatically install missing Packs when loading projects" in the "CMSIS Packs" preference page has been unticked. To install the CMSIS Packs manually, switch to the CMSIS Pack Manager perspective then, in the Packs tab, enter "ARM.CMSIS", locate 6.0.0 in the list, then click on Install. Do the same for the other Packs.

If building on the command-line with the supplied makefile, you must also set the CMSIS_PACKS environment variable in the makefile to the Pack's installation folder.

CMSIS Packs are Open Source. The source code can be downloaded from GitHub.

Building on the command-line

Before building this example, first install the ARM.CMSIS.6.0.0 Pack using the Pack Manager, then edit the makefile to set CMSIS_PACKS to its folder path.

To build the example on the command-line with the supplied make utility:

On Windows, open an Arm DS Command Prompt from the Start menu, run the select_toolchain utility, and select Arm Compiler for Embedded 6 from the list
On Linux, run the suite_exec utility with the --toolchain option to select the compiler and start a shell configured for the Development Studio environment, for example: ~/developmentstudio/bin/suite_exec --toolchain "Arm Compiler for Embedded 6" bash

Then navigate to the ...\RTX5_Cortex-M33_Blinky_Streamline directory, and type:

make

The usual make rules: clean and all are provided in the makefile.

Building within the IDE

To build the supplied projects within the IDE:

In the Project Explorer view, select the project you want to build.
Select Project → Build Project.

Running the example on an Arm MPS2+ Cortex-M33 board

Select Run → Debug Configurations....
In the Debug Configurations dialog, expand the list of Generic Arm C/C++ Application configurations on the left-hand side, and select RTX5_Cortex-M33_Blinky_Streamline_MPS2.
In the Connections panel, enter the USB: or TCP: IP address or name of your DSTREAM or ULINK unit in the Debug Hardware Address field, or click on Browse to select one from a list, otherwise an error will be reported: Launch configuration has errors: Configuration for connection type 'Bare Metal Debug' is not valid - Connection cannot be empty .
Click on the "DTSL Options" Edit... button.
In the Trace Capture tab, select DSTREAM 4GB Trace Buffer.
In the ITM tab, tick Enable CSITM Trace.
Click on OK to save the DTSL options.
Click on Debug to start debugging. The example executable will be downloaded to the target, and the program counter PC will be set to the entry point of the image.
In the Commands view, enter: trace start
Run the executable by clicking on the green Continue button in the Debug Control view, or by pressing F8 on the keyboard.
As it runs, DSTREAM captures ITM trace information. You should see the Buffer Used size increasing in the Trace view.
After a few seconds, stop execution by clicking on the yellow Interrupt button in the Debug Control view, or by pressing F9.
In the Commands view, enter: trace dump [path\to\a\local\folder] CSITM
In the Commands view, enter: trace stop
Launch Streamline, and use File → Import... → Import Capture → Next → Finish to browse to and select CSITM_0.bin.
In Select what to Import select Barman Agent Capture (via ITM), Next
In Provide Required Files enter the location of the executable image RTX5_Cortex-M33_Blinky_Streamline.axf and barman.xml, then Finish.
In the Streamline Data panel, right click on the capture file and select Analyze.... Ensure Use is ticked for the executable image RTX5_Cortex-M33_Blinky_Streamline.axf, then click Analyze.
After a few moments processing the data, Streamline presents a Timeline view containing charts of counters selected in barman.xml.
If you wish to change the selection of counter charts displayed in the Timeline, you can do so via Streamline → Generate Barman sources from saved configuration, and follow the prompts. This will generate new barman.c/.h/.xml files. You will then need to rebuild the image and run it again to collect the profiling data for your new counters selection.