|
| 1 | +# Create a Test Project |
| 2 | + |
| 3 | +## Initial Setup |
| 4 | + |
| 5 | +1. Create a new directory in the [FreeRTOS Partner Supported Demos Repository](https://github.com/FreeRTOS/FreeRTOS-Partner-Supported-Demos/tree/main) |
| 6 | + or [FreeRTOS Community Supported Demos Repository](https://github.com/FreeRTOS/FreeRTOS-Community-Supported-Demos/tree/main). |
| 7 | + The suggested name for the directory is `<hardware_name>_<compiler_name>`. |
| 8 | +2. Create a project for your hardware and tool-chain in this directory. |
| 9 | +3. Copy all the files in the [FreeRTOS/Demo/ThirdParty/Template](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS/Demo/ThirdParty/Template) |
| 10 | + directory to your project directory: |
| 11 | + * `IntQueueTimer.h` |
| 12 | + * `IntQueueTimer.c` |
| 13 | + * `TestRunner.h` |
| 14 | + * `TestRunner.c` |
| 15 | + * `RegTests.h` |
| 16 | + * `RegTests.c` |
| 17 | + |
| 18 | +## Project Configuration |
| 19 | + |
| 20 | +1. Compile the following additional files in your project: |
| 21 | + * All files in the [FreeRTOS/Demo/Common/Minimal](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS/Demo/Common/Minimal) directory except |
| 22 | + `comtest_strings.c`, `crhook.c` , `comtest.c` ,`crflash.c`,`flash.c`, `flash_timer.c` and `sp_flop.c`. |
| 23 | +2. Add the following paths to your include search path: |
| 24 | + * `FreeRTOS/Demo/Common/include`. |
| 25 | +3. Call the `void vStartTests( void )` function from your `main` function after |
| 26 | + doing all the hardware initialization. Note that this function starts the |
| 27 | + scheduler and therefore, never returns. |
| 28 | +```c |
| 29 | +#include "TestRunner.h" |
| 30 | + |
| 31 | +void main( void ) |
| 32 | +{ |
| 33 | + /* Startup and Hardware initialization. */ |
| 34 | + |
| 35 | + /* Start tests. */ |
| 36 | + vStartTests(); |
| 37 | + |
| 38 | + /* Should never reach here. */ |
| 39 | + for( ; ; ); |
| 40 | +} |
| 41 | +``` |
| 42 | +
|
| 43 | +## Set up FreeRTOSConfig.h |
| 44 | +
|
| 45 | +1. Enable tick hook by adding the following line in your `FreeRTOSConfig.h`: |
| 46 | +```c |
| 47 | +#define configUSE_TICK_HOOK 1 |
| 48 | +``` |
| 49 | +2. Set the task notification array size to 3 by adding the following line in |
| 50 | + your `FreeRTOSConfig.h`: |
| 51 | +```c |
| 52 | +#define configTASK_NOTIFICATION_ARRAY_ENTRIES 3 |
| 53 | +``` |
| 54 | +3. Enable printing by mapping `configPRINTF` to your print function. Note that |
| 55 | + `configPRINTF` calls are wrapped in double parentheses to support C89. If you |
| 56 | + have a thread-safe `printf` function, the following is what should be added |
| 57 | + in your `FreeRTOSConfig.h`: |
| 58 | +```c |
| 59 | +#define configPRINTF( X ) printf X |
| 60 | +``` |
| 61 | +4. Add the following defines in your `FreeRTOSConfig.h`: |
| 62 | +```c |
| 63 | +#define configSTART_TASK_NOTIFY_TESTS 0 |
| 64 | +#define configSTART_TASK_NOTIFY_ARRAY_TESTS 0 |
| 65 | +#define configSTART_BLOCKING_QUEUE_TESTS 0 |
| 66 | +#define configSTART_SEMAPHORE_TESTS 0 |
| 67 | +#define configSTART_POLLED_QUEUE_TESTS 0 |
| 68 | +#define configSTART_INTEGER_MATH_TESTS 0 |
| 69 | +#define configSTART_GENERIC_QUEUE_TESTS 0 |
| 70 | +#define configSTART_PEEK_QUEUE_TESTS 0 |
| 71 | +#define configSTART_MATH_TESTS 0 |
| 72 | +#define configSTART_RECURSIVE_MUTEX_TESTS 0 |
| 73 | +#define configSTART_COUNTING_SEMAPHORE_TESTS 0 |
| 74 | +#define configSTART_QUEUE_SET_TESTS 0 |
| 75 | +#define configSTART_QUEUE_OVERWRITE_TESTS 0 |
| 76 | +#define configSTART_EVENT_GROUP_TESTS 0 |
| 77 | +#define configSTART_INTERRUPT_SEMAPHORE_TESTS 0 |
| 78 | +#define configSTART_QUEUE_SET_POLLING_TESTS 0 |
| 79 | +#define configSTART_BLOCK_TIME_TESTS 0 |
| 80 | +#define configSTART_ABORT_DELAY_TESTS 0 |
| 81 | +#define configSTART_MESSAGE_BUFFER_TESTS 0 |
| 82 | +#define configSTART_STREAM_BUFFER_TESTS 0 |
| 83 | +#define configSTART_STREAM_BUFFER_INTERRUPT_TESTS 0 |
| 84 | +#define configSTART_TIMER_TESTS 0 |
| 85 | +#define configSTART_INTERRUPT_QUEUE_TESTS 0 |
| 86 | +#define configSTART_REGISTER_TESTS 0 |
| 87 | +#define configSTART_DELETE_SELF_TESTS 0 |
| 88 | +``` |
| 89 | +
|
| 90 | +## Create and Run Register Tests |
| 91 | +
|
| 92 | +1. Fill the definitions of the following functions in the `RegTests.c` file |
| 93 | + copied in the [Initial Setup](#Initial-Setup) step: |
| 94 | + * `prvRegisterTest1Task` |
| 95 | + * `prvRegisterTest2Task` |
| 96 | + * `prvRegisterTest3Task` |
| 97 | + * `prvRegisterTest4Task` |
| 98 | +2. Define `configSTART_REGISTER_TESTS` to `1` in your `FreeRTOSConfig.h`: |
| 99 | +```c |
| 100 | +#define configSTART_REGISTER_TESTS 1 |
| 101 | +``` |
| 102 | +3. Build and run the register tests. The output should look like the following: |
| 103 | +``` |
| 104 | +No errors |
| 105 | +No errors |
| 106 | +No errors |
| 107 | +No errors |
| 108 | +``` |
| 109 | +
|
| 110 | +## Setup and Run Interrupt Nesting Tests |
| 111 | +
|
| 112 | +1. If your hardware **does not** support interrupt nesting, skip this section. |
| 113 | +2. Fill the `void vInitialiseTimerForIntQueueTest( void )` function in the |
| 114 | + `IntQueueTimer.c` file copied in the [Initial Setup](#Initial-Setup) step to |
| 115 | + initialize and start a hardware timer. Make sure that the timer interrupt |
| 116 | + runs at a logical priority less than or equal to `configMAX_SYSCALL_INTERRUPT_PRIORITY`. |
| 117 | + The following is an example for ARM MPS2 which starts TIM0 timer: |
| 118 | +```c |
| 119 | +void vInitialiseTimerForIntQueueTest( void ) |
| 120 | +{ |
| 121 | + /* Clear interrupt. */ |
| 122 | + CMSDK_TIMER0->INTCLEAR = ( 1ul << 0 ); |
| 123 | +
|
| 124 | + /* Reload value is slightly offset from the other timer. */ |
| 125 | + CMSDK_TIMER0->RELOAD = ( configCPU_CLOCK_HZ / tmrTIMER_0_FREQUENCY ) + 1UL; |
| 126 | + CMSDK_TIMER0->CTRL = ( ( 1ul << 3 ) | ( 1ul << 0 ) ); |
| 127 | +
|
| 128 | + NVIC_SetPriority( TIMER0_IRQn, configMAX_SYSCALL_INTERRUPT_PRIORITY ); |
| 129 | + NVIC_EnableIRQ( TIMER0_IRQn ); |
| 130 | +} |
| 131 | +``` |
| 132 | +3. Either install `void IntQueueTestTimerHandler( void )` function as the timer |
| 133 | + interrupt handler or call it from the timer interrupt handler of the above |
| 134 | + timer. The following is an example for ARM MPS2 which calls |
| 135 | + `IntQueueTestTimerHandler` from the TIM0 handler: |
| 136 | +```c |
| 137 | +void TIMER0_Handler( void ) |
| 138 | +{ |
| 139 | + /* Clear interrupt. */ |
| 140 | + CMSDK_TIMER0->INTCLEAR = ( 1ul << 0 ); |
| 141 | + |
| 142 | + IntQueueTestTimerHandler(); |
| 143 | +} |
| 144 | +``` |
| 145 | +4. Define `configSTART_INTERRUPT_QUEUE_TESTS` to `1` in your `FreeRTOSConfig.h`: |
| 146 | +```c |
| 147 | +#define configSTART_INTERRUPT_QUEUE_TESTS 1 |
| 148 | +``` |
| 149 | +5. Build and run the tests. The output should look like the following: |
| 150 | +``` |
| 151 | +No errors |
| 152 | +No errors |
| 153 | +No errors |
| 154 | +No errors |
| 155 | +``` |
| 156 | + |
| 157 | +## Running All Tests |
| 158 | + |
| 159 | +1. Define all the `configSTART_<Test_Name>_TESTS` macros to `1` in your |
| 160 | +`FreeRTOSConfig.h`. |
| 161 | +2. Build and run the tests. The output should look like the following: |
| 162 | +``` |
| 163 | +No errors |
| 164 | +No errors |
| 165 | +No errors |
| 166 | +No errors |
| 167 | +``` |
| 168 | +3. If you cannot fit all the tests in one binary because of Flash or RAM space, |
| 169 | +you can run tests one by one or in groups by defining |
| 170 | +`configSTART_<Test_Name>_TESTS` macros to `0` or `1` as needed. |
| 171 | + |
| 172 | +## Add README |
| 173 | +Add a `README.md` file in the project directory with the following information: |
| 174 | +* Link to the hardware page. |
| 175 | +* How to setup tool-chain. |
| 176 | +* How to build and run the project. |
| 177 | +* Any other relevant information. |
0 commit comments