begriffs open source - cmsis-freertos/blob - Documentation/Doxygen/src/example_projects.md

   1 # Example Projects {#page_example_projects}
   2
   3 This pack contains two example projects:
   4
   5 - [Hello World](#example_hello_world)
   6 - [TrustZone](#example_trustzone)
   7
   8 The first example shows how to configure a simple application using FreeRTOS with CMSIS-RTOS2,
   9 whereas the second example shows how to use the FreeRTOS with CMSIS-RTOS2 in an application
  10 that utilizes TrustZone secure/non-secure execution.
  11
  12 Provided examples use the [CMSIS Solution Project File Format](https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format/)
  13 and can be built for multiple Cortex-M targets using [CMSIS Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/)
  14 either from the command line or from Visual Studio Code by using [Arm Keil Studio Cloud extensions](https://developer.arm.com/documentation/108029/0000/?lang=en).
  15
  16 The **Examples** solution defines projects and build information for each project.
  17
  18 ## Build and Run
  19
  20 The **Examples** solution supports only "Debug" Build-Type which is optimized for debugging.
  21 It disables compiler optimization and retains all debug-related information. By default,
  22 Arm Compiler 6 is used to build the projects.
  23
  24 ### Targets
  25
  26 Each example can be built for multiple target processors. The below table lists supported target
  27 processors together with the corresponding context target-types and model executable that shall
  28 be used for running the application image.
  29
  30 | Target processor | Target-Type | Model Executable       |
  31 |:-----------------|:------------|:-----------------------|
  32 | Cortex-M0        | CM0         | FVP_MPS2_Cortex-M0     |
  33 | Cortex-M0+       | CM0plus     | FVP_MPS2_Cortex-M0plus |
  34 | Cortex-M3        | CM3         | FVP_MPS2_Cortex-M3     |
  35 | Cortex-M4        | CM4         | FVP_MPS2_Cortex-M4     |
  36 | Cortex-M7        | CM7         | FVP_MPS2_Cortex-M7     |
  37 | Cortex-M23       | CM23        | FVP_MPS2_Cortex-M23    |
  38 | Cortex-M23       | CM23_noTZ   | FVP_MPS2_Cortex-M23    |
  39 | Cortex-M33       | CM33        | FVP_MPS2_Cortex-M33    |
  40 | Cortex-M33       | CM33_noTZ   | FVP_MPS2_Cortex-M33    |
  41 | Cortex-M55       | CM55        | FVP_Corstone_SSE-300   |
  42 | Cortex-M55       | CM55_noTZ   | FVP_Corstone_SSE-300   |
  43 | Cortex-M85       | CM85        | FVP_Corstone_SSE-310   |
  44 | Cortex-M85       | CM85_noTZ   | FVP_Corstone_SSE-310   |
  45
  46 ### Build in VS Code using Arm Keil Studio Pack extensions
  47
  48 - See [Arm Keil Studio Visual Studio Code Extensions User Guide](https://developer.arm.com/documentation/108029/0000/?lang=en) for more information about using the Keil Studio extensions.
  49 - Search for [Arm Keil Studio Pack](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack) in the Visual Studio Marketplace to download the extensions.
  50
  51 To build a project using Keil Studio extensions open CMSIS view, open "Manage CMSIS Solution" view and select "Active Context" and "Active Projects". Build Type is automatically selected since there is only one option.
  52
  53 Once the context and projects are selected one can build them by selecting "Build" in CMSIS view.
  54
  55 ### Build via command line
  56
  57 - See [CMSIS-Toolbox documentation](https://open-cmsis-pack.github.io/cmsis-toolbox/) to learn more about CMSIS Solution project build and management tools.
  58
  59 To build the project via command line one can use the following command syntax:
  60
  61 ```shell
  62 cbuild Examples.csolution.yml --context <project-name>.<build-type>+<target-type>
  63 ```
  64
  65 To list the available contexts execute the following command:
  66
  67 ```shell
  68 cbuild list contexts Examples.csolution.yml
  69 ```
  70
  71 ### Execute on Virtual Hardware Target
  72
  73 [Arm Virtual Hardware Target](https://www.arm.com/products/development-tools/simulation/virtual-hardware) simulation models are used to execute the example application images.
  74
  75 To execute application image (axf or elf) on a simulation model use the following command syntax:
  76
  77 ```shell
  78 <model-executable> -f ./Target/<target_type>/fvp_config.txt -a ./out/<project>/<project>.axf
  79 ```
  80
  81 ## Hello World {#example_hello_world}
  82
  83 The **Hello World** application can be used as a starting point when developing a new application. Using it, one can verify initial system setup and configuration.
  84
  85 The application is simple and shows how to use CMSIS-RTOS2:
  86
  87 - how to initialize and start the RTOS kernel
  88 - how to create a new thread
  89 - how to retarget stdout
  90
  91 #### Build via command line
  92
  93 The following cbuild command may be used to build Hello World example project for Cortex-M3:
  94
  95 ```shell
  96   cbuild Examples.csolution.yml --context Hello.Debug+CM3 --update-rte
  97 ```
  98
  99 #### Execute via command line
 100
 101 To execute simulation model and run Hello World project executable for Cortex-M3 use the following command:
 102
 103 ```shell
 104   FVP_MPS2_Cortex-M3 -f ./Target/CM3/fvp_config.txt -a ./out/Hello/Hello.axf
 105 ```
 106
 107 When executed, application outputs the following to the serial terminal:
 108
 109 ![Hello Output](hello_out.png)
 110 (Press Ctrl + C to stop the simulation model.)
 111
 112 ## TrustZone {#example_trustzone}
 113
 114 The **TrustZone** application explains how to setup projects for booting and execution from TrustZone secure to non-secure domain and vice versa.
 115
 116 The application shows:
 117
 118 - how to boot from the secure domain and switch the execution to the non-secure domain
 119 - how to create the interface functions between secure and non-secure domain
 120 - how to use the secure/non-secure interface functions
 121
 122 #### Build via command line
 123
 124 TrustZone example must always be built in two steps:
 125
 126 1. Build secure side project for Cortex-M55
 127    ```shell
 128    cbuild Examples.csolution.yml --context TZ_Secure.Debug+CM55 --update-rte
 129    ```
 130
 131 2. Build non-secure side project for Cortex-M55
 132    ```shell
 133    cbuild Examples.csolution.yml --context TZ_NonSecure.Debug+CM55 --update-rte
 134    ```
 135
 136 #### Execute via command line
 137
 138 To execute simulation model and run TrustZone project executable for Cortex-M55 use the following command:
 139
 140 ```shell
 141   FVP_Corstone_SSE-300 -f ./Target/CM55/fvp_config.txt -a ./out/TZ_NonSecure/TZ_NonSecure.axf -a ./out/TZ_Secure/TZ_Secure.axf
 142 ```
 143
 144 When executed, application outputs the following to the serial terminal:
 145
 146 ![TrustZone Output](trustzone_out.png)
 147 (Press Ctrl + C to stop the simulation model.)