2 * FreeRTOS Kernel V10.2.0
\r
3 * Copyright (C) 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\r
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
\r
6 * this software and associated documentation files (the "Software"), to deal in
\r
7 * the Software without restriction, including without limitation the rights to
\r
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
\r
9 * the Software, and to permit persons to whom the Software is furnished to do so,
\r
10 * subject to the following conditions:
\r
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\r
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\r
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
\r
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
\r
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
\r
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
\r
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\r
22 * http://www.FreeRTOS.org
\r
23 * http://aws.amazon.com/freertos
\r
25 * 1 tab == 4 spaces!
\r
29 * See https://www.freertos.org/STM32H7_Dual_Core_AMP_RTOS_demo.html for usage
\r
30 * instructions (TBD, not available at the time of writing).
\r
35 * This example stress tests a simple Asymmetric Multi Processing (AMP) core to
\r
36 * core communication mechanism implemented using FreeRTOS message buffers:
\r
37 * https://www.freertos.org/RTOS-stream-message-buffers.html Message buffers
\r
38 * are used to pass an ASCII representation of an incrementing number (so "0",
\r
39 * followed by "1", followed by "2", etc.) from a single 'sending' task that
\r
40 * runs on the Arm Cortex-M7 core (the M7 core) to two "receiving" tasks
\r
41 * running on the Arm Cortex-M4 core (the M4 core). There are two data message
\r
42 * buffers, one for each receiving task. To distinguish between the receiving
\r
43 * tasks one is assigned the task number 0, and the other task number 1.
\r
45 * The M7 task sits in a loop sending the ascii strings to each M4 task. If a
\r
46 * receiving task receives the next expected value in the sequence it prints its
\r
47 * task number to the UART. If a receiving task receives anything else, or its
\r
48 * attempt to receive data times out, then it hits an assert() that prints an
\r
49 * error message to the UART before stopping all further processing on the M4
\r
50 * core. If the example is running correctly you will see lots of "0"s (from
\r
51 * the receiving task assigned task number 0) and "1"s (from the receiving task
\r
52 * assigned task number 1) streaming from the UART. The time taken to output
\r
53 * characters from the UART is the only thing throttling the speed of the core
\r
54 * to core communication as it causes the message buffers to become full - which
\r
55 * would probably happen anyway as the M7 core is executing at twice the
\r
56 * frequency of the M4 core.
\r
59 * Implementation of sbSEND_COMPLETED()
\r
60 * ------------------------------------
\r
62 * sbSEND_COMPLETED is a macro called by FreeRTOS after data has been sent to a
\r
63 * message buffer in case there was a task blocked on the message buffer waiting
\r
64 * for data to become available - in which case the waiting task would be
\r
65 * unblocked: https://www.freertos.org/RTOS-message-buffer-example.html
\r
66 * However, the default sbSEND_COMPLETED implementation assumes the sending task
\r
67 * (or interrupt) and the receiving task are under the control of the same
\r
68 * instance of the FreeRTOS kernel and run on the same MCU core. In this AMP
\r
69 * example the sending task and the receiving tasks are under the control of two
\r
70 * different instances of the FreeRTOS kernel, and run on different MCU cores,
\r
71 * so the default sbSEND_COMPLETED implementation won't work (each FreeRTOS
\r
72 * kernel instance only knowns about the tasks under its control). AMP
\r
73 * scenarios therefore require the sbSEND_COMPLETED macro (and potentially the
\r
74 * sbRECEIVE_COMPLETED macro, see below) to be overridden, which is done by
\r
75 * simply providing your own implementation in the project's FreeRTOSConfig.h
\r
76 * file. Note this example has a FreeRTOSConfig.h file used by the application
\r
77 * that runs on the M7 core and a separate FreeRTOSConfig.h file used by the
\r
78 * application that runs on the M4 core. The implementation of sbSEND_COMPLETED
\r
79 * used by the M7 core simply triggers an interrupt in the M4 core. The
\r
80 * interrupt's handler (the ISR that was triggered by the M7 core but executes
\r
81 * on the M4 core) must then do the job that would otherwise be done by the
\r
82 * default implementation of sbSEND_COMPLETE - namely unblock a task if the task
\r
83 * was waiting to receive data from the message buffer that now contains data.
\r
84 * There are two data message buffers though, so first ISR must determine which
\r
85 * of the two contains data.
\r
87 * This demo only has two data message buffers, so it would be reasonable to
\r
88 * have the ISR simply query both to see which contained data, but that solution
\r
89 * would not scale if there are many message buffers, or if the number of
\r
90 * message buffers was unknown. Therefore, to demonstrate a more scalable
\r
91 * solution, this example introduced a third message buffer - a 'control'
\r
92 * message buffer as opposed to a 'data' message buffer. After the task on the
\r
93 * M7 core writes to a data message buffer it writes the handle of the message
\r
94 * buffer that contains data to the control message buffer. The ISR running on
\r
95 * the M4 core then reads from the control message buffer to know which data
\r
96 * message buffer contains data.
\r
98 * The above described scenario contains many implementation decisions.
\r
99 * Alternative methods of enabling the M4 core to know data message buffer
\r
100 * contains data include:
\r
102 * 1) Using a different interrupt for each data message buffer.
\r
103 * 2) Passing all data from the M7 core to the M4 core through a single message
\r
104 * buffer, along with additional data that tells the ISR running on the M4
\r
105 * core which task to forward the data to.
\r
108 * Implementation of sbRECEIVE_COMPLETED()
\r
109 * ---------------------------------------
\r
111 * sbRECEIVE_COMPLETED is the complement of sbSEND_COMPLETED. It is a macro
\r
112 * called by FreeRTOS after data has been read from a message buffer in case
\r
113 * there was a task blocked on the message buffer waiting for space to become
\r
114 * available - in which case the waiting task would be unblocked so it can
\r
115 * complete its write to the buffer.
\r
117 * In this example the M7 task writes to the message buffers faster than the M4
\r
118 * tasks read from them (in part because the M7 is running faster, and in part
\r
119 * because the M4 cores write to the UART), so the buffers become full, and the
\r
120 * M7 task enters the Blocked state to wait for space to become available. As
\r
121 * with the sbSEND_COMPLETED macro, the default implementation of the
\r
122 * sbRECEIVE_COMPLETED macro only works if the sender and receiver are under the
\r
123 * control of the same instance of FreeRTOS and execute on the same core.
\r
124 * Therefore, just as the application that executes on the M7 core overrides
\r
125 * the default implementation of sbSEND_SOMPLETED(), the application that runs
\r
126 * on the M4 core overrides the default implementation of sbRECEIVE_COMPLETED()
\r
127 * to likewise generate an interrupt in the M7 core - so sbRECEIVE_COMPLETED()
\r
128 * executes on the M4 core and generates an interrupt on the M7 core. To keep
\r
129 * things simple the ISR that runs on the M7 core does not use a control
\r
130 * message buffer to know which data message buffer contains space, and instead
\r
131 * simply sends a notification to both data message buffers. Note however that
\r
132 * this overly simplistic implementation is only acceptable because it is
\r
133 * known that there is only one sending task, and that task cannot be blocked on
\r
134 * both message buffers at the same time. Also, sending the notification to the
\r
135 * data message buffer updates the receiving task's direct to task notification
\r
136 * state: https://www.freertos.org/RTOS-task-notifications.html which is only ok
\r
137 * because it is known the task is not using its notification state for any
\r
142 /* Standard includes. */
\r
144 #include "string.h"
\r
146 /* STM32 includes. */
\r
147 #include "stm32h7xx_hal.h"
\r
148 #include "stm32h745i_discovery.h"
\r
150 /* FreeRTOS includes. */
\r
151 #include "FreeRTOS.h"
\r
153 #include "message_buffer.h"
\r
155 /* Demo includes. */
\r
156 #include "MessageBufferLocations.h"
\r
158 /*-----------------------------------------------------------*/
\r
160 /* Seen as an infinite block by the ST HAL. */
\r
161 #define mainHAL_MAX_TIMEOUT 0xFFFFFFFFUL
\r
163 /* When the cores boot they very crudely wait for each other in a non chip
\r
164 specific way by waiting for the other core to start incrementing a shared
\r
165 variable within an array. mainINDEX_TO_TEST sets the index within the array to
\r
166 the variable this core tests to see if it is incrementing, and
\r
167 mainINDEX_TO_INCREMENT sets the index within the array to the variable this core
\r
168 increments to indicate to the other core that it is at the sync point. Note
\r
169 this is not a foolproof method and it is better to use a hardware specific
\r
170 solution, such as having one core boot the other core when it was ready, or
\r
171 using some kind of shared semaphore or interrupt. */
\r
172 #define mainINDEX_TO_TEST 1
\r
173 #define mainINDEX_TO_INCREMENT 0
\r
175 /*-----------------------------------------------------------*/
\r
178 * Implements the tasks that receive messages from the M7 core.
\r
180 static void prvM4CoreTasks( void *pvParameters );
\r
183 * The interrupt triggered by the M7 core when there is data available in the
\r
184 * message buffer used for core to core communication.
\r
186 void HAL_GPIO_EXTI_Callback( uint16_t GPIO_Pin );
\r
189 * Just waits to see a variable being incremented by the M7 core to know when
\r
190 * the M7 has created the message buffers used for core to core communication.
\r
192 static void prvWaitForOtherCoreToStart( uint32_t ulIndexToTest, uint32_t ulIndexToIncrement );
\r
195 * Configures the hardware ready to run this demo.
\r
197 static void prvSetupHardware( void );
\r
199 /*-----------------------------------------------------------*/
\r
201 /* Handle to the UART used to output strings. */
\r
202 static UART_HandleTypeDef xUARTHandle = { 0 };
\r
204 /*-----------------------------------------------------------*/
\r
208 static const uint8_t pucBootMessage[] = "\r\nM4 started and waiting for the M7 to run.\r\n";
\r
209 static const uint8_t pucCreatingTasksMessage[] = "M4 core proceeding to create demo tasks.\r\n";
\r
212 /*** See the comments at the top of this page ***/
\r
215 /* Prep the hardware to run this demo. */
\r
216 prvSetupHardware();
\r
218 /* The M4 core task prints its status out at various places so you know what
\r
219 it is doing when debugging the M7 core. This messages is just to indicate
\r
220 it has booted and is about to wait for the M7 core. If the M7 is already
\r
221 running then reset the hardware so both cores start at once. */
\r
222 HAL_UART_Transmit( &xUARTHandle, ( uint8_t * ) pucBootMessage, sizeof( pucBootMessage ), mainHAL_MAX_TIMEOUT );
\r
223 prvWaitForOtherCoreToStart( mainINDEX_TO_TEST, mainINDEX_TO_INCREMENT );
\r
225 /* By this point the M7 should have initialized the message buffers used to
\r
226 send data from the M7 to the M4 core. The message buffers are statically
\r
227 allocated at a known location so both cores know where they are. See
\r
228 MessageBufferLocations.h. */
\r
229 configASSERT( ( xControlMessageBuffer != NULL ) && ( xDataMessageBuffers[ 0 ] != NULL ) && ( xDataMessageBuffers[ 1 ] != NULL ) );
\r
231 /* Everything seems as expected - print a message to say the M4 is about to
\r
232 create the tasks that receive data from the M7 core. */
\r
233 HAL_UART_Transmit( &xUARTHandle, ( uint8_t * ) pucCreatingTasksMessage, sizeof( pucCreatingTasksMessage ), mainHAL_MAX_TIMEOUT );
\r
235 for( x = 0; x < mbaNUMBER_OF_CORE_2_TASKS; x++ )
\r
237 /* Pass the loop counter into the created task using the task's
\r
238 parameter. The task then uses the value as an index into the
\r
239 xDataMessageBuffers arrays. */
\r
240 xTaskCreate( prvM4CoreTasks, /* Function that implements the task. */
\r
241 "AMPM4Core", /* Task name, for debugging only. */
\r
242 configMINIMAL_STACK_SIZE, /* Size of stack to allocate for this task - in words. */
\r
243 ( void * ) x, /* Task parameter. */
\r
244 tskIDLE_PRIORITY + 1, /* Task priority. */
\r
245 NULL ); /* Task handle. Not used in this case. */
\r
248 /* Start scheduler */
\r
249 vTaskStartScheduler();
\r
251 /* Will not get here if the scheduler starts successfully. If you do end up
\r
252 here then there wasn't enough heap memory available to start either the idle
\r
253 task or the timer/daemon task. https://www.freertos.org/a00111.html */
\r
256 /*-----------------------------------------------------------*/
\r
258 static void prvM4CoreTasks( void *pvParameters )
\r
260 static const uint8_t pucTaskStartedMessage[] = "M4 task started.\r\n";
\r
261 BaseType_t xTaskNumber;
\r
262 size_t xReceivedBytes;
\r
263 uint32_t ulNextValue = 0;
\r
264 char cExpectedString[ 15 ];
\r
265 char cReceivedString[ 15 ];
\r
267 const TickType_t xShortBlockTime = pdMS_TO_TICKS( 150 );
\r
269 /* This task is created more than once so the task's parameter is used to
\r
270 pass in a task number, which is then used as an index into the message
\r
272 xTaskNumber = ( BaseType_t ) pvParameters;
\r
273 configASSERT( xTaskNumber < mbaNUMBER_OF_CORE_2_TASKS );
\r
277 /* Message transmitted to indicate the task has started. */
\r
278 HAL_UART_Transmit( &xUARTHandle, ( uint8_t * ) pucTaskStartedMessage, sizeof( pucTaskStartedMessage ), mainHAL_MAX_TIMEOUT );
\r
282 /* The tasks print out a letter to indicate that the expected message was
\r
283 received from the other core. */
\r
284 if( xTaskNumber == 0 )
\r
295 /* The M7 core creates and sends to this core an ascii string of an
\r
296 incrementing number. Create the string that is expected to be received
\r
297 this time round the loop. */
\r
298 sprintf( cExpectedString, "%lu", ( unsigned long ) ulNextValue );
\r
300 /* Wait to receive the next message from core 1. */
\r
301 memset( cReceivedString, 0x00, sizeof( cReceivedString ) );
\r
302 xReceivedBytes = xMessageBufferReceive( /* Handle of message buffer. */
\r
303 xDataMessageBuffers[ xTaskNumber ],
\r
304 /* Buffer into which received data is placed. */
\r
306 /* Size of the receive buffer. */
\r
307 sizeof( cReceivedString ),
\r
308 /* Time to wait for data to arrive. */
\r
311 /* Check the number of bytes received was as expected. */
\r
312 configASSERT( xReceivedBytes == strlen( cExpectedString ) );
\r
314 /* If the received string matches that expected then output the task
\r
315 number to give visible indication that the task is still running. */
\r
316 if( strcmp( cReceivedString, cExpectedString ) == 0 )
\r
318 /* Also print out the task number to give a visual indication that
\r
319 the M4 core is receiving the expected data. */
\r
322 HAL_UART_Transmit( &xUARTHandle, ( uint8_t * ) &cMessage, sizeof( cMessage ), mainHAL_MAX_TIMEOUT );
\r
327 /* Expect the next string in sequence the next time around. */
\r
331 /*-----------------------------------------------------------*/
\r
333 void vGenerateM4ToM7Interrupt( void * xUpdatedMessageBuffer )
\r
335 /* Called by the implementation of sbRECEIVE_COMPLETED() in FreeRTOSConfig.h.
\r
336 See the comments at the top of this file. Write the handle of the data
\r
337 message buffer to which data was written to the control message buffer. */
\r
339 /* Generate interrupt in the M7 core. */
\r
340 HAL_EXTI_D2_EventInputConfig( EXTI_LINE1, EXTI_MODE_IT, DISABLE );
\r
341 HAL_EXTI_D1_EventInputConfig( EXTI_LINE1, EXTI_MODE_IT, ENABLE );
\r
342 HAL_EXTI_GenerateSWInterrupt( EXTI_LINE1 );
\r
344 /*-----------------------------------------------------------*/
\r
346 void HAL_GPIO_EXTI_Callback( uint16_t GPIO_Pin )
\r
348 MessageBufferHandle_t xUpdatedMessageBuffer;
\r
349 BaseType_t xHigherPriorityTaskWoken = pdFALSE;
\r
351 /* Avoid compiler warnings about unused parameters. */
\r
354 /* Clear interrupt. */
\r
355 HAL_EXTI_D2_ClearFlag( EXTI_LINE0 );
\r
357 configASSERT( ( xControlMessageBuffer != NULL ) && ( xDataMessageBuffers[ 0 ] != NULL ) && ( xDataMessageBuffers[ 1 ] != NULL ) );
\r
359 /* In this example there are mbaNUMBER_OF_CORE_2_TASKS receiving tasks that
\r
360 run on the M4 core. It would be possible for the M7 core to use a single
\r
361 message buffer to send to both tasks, but that would require additional data
\r
362 to be sent to the message buffer - namely an identifier to indicate which
\r
363 receiving task a message was intended for along with some arbitration in the
\r
364 ISR. As an alternative, this example uses one message buffer per receiving
\r
365 task and a control message buffer. The M7 core sends data to a receiving
\r
366 task using that task's dedicated message buffer, then sends the handle of
\r
367 the message buffer that it just sent data to to the control task. This
\r
368 interrupt service routine receives the handle from the control task then
\r
369 uses the handle to signal the message buffer that contains the data.
\r
371 Receive the handle of the message buffer that contains data from the
\r
372 control message buffer. */
\r
373 while( xMessageBufferReceiveFromISR( xControlMessageBuffer,
\r
374 &xUpdatedMessageBuffer,
\r
375 sizeof( xUpdatedMessageBuffer ),
\r
376 &xHigherPriorityTaskWoken ) == sizeof( xUpdatedMessageBuffer ) )
\r
378 /* Call the API function that sends a notification to any task that is
\r
379 blocked on the xUpdatedMessageBuffer message buffer waiting for data to
\r
381 xMessageBufferSendCompletedFromISR( xUpdatedMessageBuffer, &xHigherPriorityTaskWoken );
\r
384 /* Normal FreeRTOS "yield from interrupt" semantics, where
\r
385 xHigherPriorityTaskWoken is initialzed to pdFALSE and will then get set to
\r
386 pdTRUE if the interrupt unblocks a task that has a priority above that of
\r
387 the currently executing task. */
\r
388 portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
390 /*-----------------------------------------------------------*/
\r
392 static void prvWaitForOtherCoreToStart( uint32_t ulIndexToTest, uint32_t ulIndexToIncrement )
\r
394 volatile uint32_t ulInitialCount = ulStartSyncCounters[ ulIndexToTest ];
\r
396 /* When the cores boot they very crudely wait for each other in a non chip
\r
397 specific way by waiting for the other core to start incrementing a shared
\r
398 variable within an array. mainINDEX_TO_TEST sets the index within the array
\r
399 to the variable this core tests to see if it is incrementing, and
\r
400 mainINDEX_TO_INCREMENT sets the index within the array to the variable this
\r
401 core increments to indicate to the other core that it is at the sync point.
\r
402 Note this is not a foolproof method and it is better to use a hardware
\r
403 specific solution, such as having one core boot the other core when it was
\r
404 ready, or using some kind of shared semaphore or interrupt. */
\r
408 /* Indicate to the M7 core that this core is at the synchronisation
\r
410 ulStartSyncCounters[ ulIndexToIncrement ]++;
\r
412 /* Has the counter incremented by the other core changed? */
\r
413 if( ulStartSyncCounters[ ulIndexToTest ] != ulInitialCount )
\r
419 /* One more increment before exiting to avoid race. */
\r
420 ulStartSyncCounters[ ulIndexToIncrement ]++;
\r
422 /*-----------------------------------------------------------*/
\r
424 void vAssertCalled( const char *pcFile, const uint32_t ulLine )
\r
427 const uint8_t pucM4AssertFile[] = "M4 Assert hit in file ";
\r
428 const uint8_t pucM4AssertLine[] = "on line number ";
\r
430 /* Assert disables interrupts so no other code can run, prints out the
\r
431 location of the offending assert(), then loops doing nothing waiting for
\r
432 the user to inspect or reset. */
\r
433 taskDISABLE_INTERRUPTS();
\r
434 HAL_UART_Transmit( &xUARTHandle, ( uint8_t * ) pucM4AssertFile, sizeof( pucM4AssertFile ), mainHAL_MAX_TIMEOUT );
\r
435 HAL_UART_Transmit( &xUARTHandle, ( uint8_t * ) pcFile, strlen( pcFile ), mainHAL_MAX_TIMEOUT );
\r
436 HAL_UART_Transmit( &xUARTHandle, ( uint8_t * ) pucM4AssertLine, sizeof( pucM4AssertLine ), mainHAL_MAX_TIMEOUT );
\r
437 sprintf( pcLine, "%u\r\n", ulLine );
\r
438 HAL_UART_Transmit( &xUARTHandle, ( uint8_t * ) pcLine, strlen( pcLine ), mainHAL_MAX_TIMEOUT );
\r
441 /*-----------------------------------------------------------*/
\r
443 static void prvSetupHardware( void )
\r
445 /* Prevent the HAL's initialisation of SysTick actually starting the systick
\r
446 interrupt as the kernel has not started yet. */
\r
447 taskDISABLE_INTERRUPTS();
\r
449 BSP_LED_Init( LED2 );
\r
451 /* This core uses the UART, so initialise it. */
\r
452 xUARTHandle.Instance = USART3;
\r
453 xUARTHandle.Init.BaudRate = 115200;
\r
454 xUARTHandle.Init.WordLength = UART_WORDLENGTH_8B;
\r
455 xUARTHandle.Init.StopBits = UART_STOPBITS_1;
\r
456 xUARTHandle.Init.Parity = UART_PARITY_NONE;
\r
457 xUARTHandle.Init.HwFlowCtl = UART_HWCONTROL_NONE;
\r
458 xUARTHandle.Init.Mode = UART_MODE_TX_RX;
\r
459 xUARTHandle.Init.ClockPrescaler = UART_PRESCALER_DIV1;
\r
460 xUARTHandle.Init.OneBitSampling = UART_ONE_BIT_SAMPLE_DISABLE;
\r
461 xUARTHandle.Init.OverSampling = UART_OVERSAMPLING_16;
\r
462 HAL_UART_Init( &xUARTHandle );
\r
463 HAL_UARTEx_SetRxFifoThreshold( &xUARTHandle, UART_RXFIFO_THRESHOLD_1_4 );
\r
464 HAL_UARTEx_EnableFifoMode( &xUARTHandle );
\r
466 /* AIEC Common configuration: make CPU1 and CPU2 SWI line1 sensitive to
\r
468 HAL_EXTI_EdgeConfig( EXTI_LINE1, EXTI_RISING_EDGE );
\r
470 /* Interrupt used for M7 to M4 notifications. */
\r
471 HAL_NVIC_SetPriority( EXTI0_IRQn, 0xFU, 0U );
\r
472 HAL_NVIC_EnableIRQ( EXTI0_IRQn );
\r
projects / freertos / blob