blob: abb2fa02fb78089cfc4c1986c856217e1e06a5be [file] [log] [blame]
/*
* FreeRTOS Kernel V10.3.0
* Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
* http://www.FreeRTOS.org
* http://aws.amazon.com/freertos
*
* 1 tab == 4 spaces!
*/
/*
* An example that mimics a message buffer being used to pass data from one core
* to another. The core that sends the data is referred to as core A. The core
* that receives the data is referred to as core B. The task implemented by
* prvCoreATask() runs on core A. Two instances of the task implemented by
* prvCoreBTasks() run on core B. prvCoreATask() sends messages via message
* buffers to both instances of prvCoreBTasks(), one message buffer per channel.
* A third message buffer is used to pass the handle of the message buffer
* written to by core A to an interrupt service routine that is triggered by
* core A but executes on core B.
*
* The example relies on the FreeRTOS provided default implementation of
* sbSEND_COMPLETED() being overridden by an implementation in FreeRTOSConfig.h
* that writes the handle of the message buffer that contains data into the
* control message buffer, then generates an interrupt in core B. The necessary
* implementation is provided in this file and can be enabled by adding the
* following to FreeRTOSConfig.h:
*
* #define sbSEND_COMPLETED( pxStreamBuffer ) vGenerateCoreBInterrupt( pxStreamBuffer )
*
* Core to core communication via message buffer requires the message buffers
* to be at an address known to both cores within shared memory.
*
* Note that, while this example uses three message buffers, the same
* functionality can be implemented using a single message buffer by using the
* same design pattern described on the link below for queues, but using message
* buffers instead. It is actually simpler with a message buffer as variable
* length data can be written into the message buffer directly:
* http://www.freertos.org/Pend-on-multiple-rtos-objects.html#alternative_design_pattern
*/
/* Standard includes. */
#include "stdio.h"
#include "string.h"
/* FreeRTOS includes. */
#include "FreeRTOS.h"
#include "task.h"
#include "message_buffer.h"
/* Demo app includes. */
#include "MessageBufferAMP.h"
/* Enough for 3 4 byte pointers, including the additional 4 bytes per message
overhead of message buffers. */
#define mbaCONTROL_MESSAGE_BUFFER_SIZE ( 24 )
/* Enough four 4 8 byte strings, plus the additional 4 bytes per message
overhead of message buffers. */
#define mbaTASK_MESSAGE_BUFFER_SIZE ( 60 )
/* The number of instances of prvCoreBTasks that are created. */
#define mbaNUMBER_OF_CORE_B_TASKS 2
/* A block time of 0 simply means, don't block. */
#define mbaDONT_BLOCK 0
/* Macro that mimics an interrupt service routine executing by simply calling
the routine inline. */
#define mbaGENERATE_CORE_B_INTERRUPT() prvCoreBInterruptHandler()
/*-----------------------------------------------------------*/
/*
* Implementation of the task that, on a real dual core device, would run on
* core A and send message to tasks running on core B.
*/
static void prvCoreATask( void *pvParameters );
/*
* Implementation of the task that, on a real dual core device, would run on
* core B and receive message from core A. The demo creates two instances of
* this task.
*/
static void prvCoreBTasks( void *pvParameters );
/*
* The function that, on a real dual core device, would handle inter-core
* interrupts, but in this case is just called inline.
*/
static void prvCoreBInterruptHandler( void );
/*-----------------------------------------------------------*/
/* The message buffers used to pass data from core A to core B. */
static MessageBufferHandle_t xCoreBMessageBuffers[ mbaNUMBER_OF_CORE_B_TASKS ];
/* The control message buffer. This is used to pass the handle of the message
message buffer that holds application data into the core to core interrupt
service routine. */
static MessageBufferHandle_t xControlMessageBuffer;
/* Counters used to indicate to the check that the tasks are still executing. */
static uint32_t ulCycleCounters[ mbaNUMBER_OF_CORE_B_TASKS ];
/* Set to pdFALSE if any errors are detected. Used to inform the check task
that something might be wrong. */
BaseType_t xDemoStatus = pdPASS;
/*-----------------------------------------------------------*/
void vStartMessageBufferAMPTasks( configSTACK_DEPTH_TYPE xStackSize )
{
BaseType_t x;
xControlMessageBuffer = xMessageBufferCreate( mbaCONTROL_MESSAGE_BUFFER_SIZE );
xTaskCreate( prvCoreATask, /* The function that implements the task. */
"AMPCoreA", /* Human readable name for the task. */
xStackSize, /* Stack size (in words!). */
NULL, /* Task parameter is not used. */
tskIDLE_PRIORITY, /* The priority at which the task is created. */
NULL ); /* No use for the task handle. */
for( x = 0; x < mbaNUMBER_OF_CORE_B_TASKS; x++ )
{
xCoreBMessageBuffers[ x ] = xMessageBufferCreate( mbaTASK_MESSAGE_BUFFER_SIZE );
configASSERT( xCoreBMessageBuffers[ x ] );
/* Pass the loop counter into the created task using the task's
parameter. The task then uses the value as an index into the
ulCycleCounters and xCoreBMessageBuffers arrays. */
xTaskCreate( prvCoreBTasks,
"AMPCoreB1",
xStackSize,
( void * ) x,
tskIDLE_PRIORITY + 1,
NULL );
}
}
/*-----------------------------------------------------------*/
static void prvCoreATask( void *pvParameters )
{
BaseType_t x;
uint32_t ulNextValue = 0;
const TickType_t xDelay = pdMS_TO_TICKS( 250 );
char cString[ 15 ]; /* At least large enough to hold "4294967295\0" (0xffffffff). */
/* Remove warning about unused parameters. */
( void ) pvParameters;
for( ;; )
{
/* Create the next string to send. The value is incremented on each
loop iteration, and the length of the string changes as the number of
digits in the value increases. */
sprintf( cString, "%lu", ( unsigned long ) ulNextValue );
/* Send the value from this (pseudo) Core A to the tasks on the (pseudo)
Core B via the message buffers. This will result in sbSEND_COMPLETED()
being executed, which in turn will write the handle of the message
buffer written to into xControlMessageBuffer then generate an interrupt
in core B. */
for( x = 0; x < mbaNUMBER_OF_CORE_B_TASKS; x++ )
{
xMessageBufferSend( /* The message buffer to write to. */
xCoreBMessageBuffers[ x ],
/* The source of the data to send. */
( void * ) cString,
/* The length of the data to send. */
strlen( cString ),
/* The block time, should the buffer be full. */
mbaDONT_BLOCK );
}
/* Delay before repeating with a different and potentially different
length string. */
vTaskDelay( xDelay );
ulNextValue++;
}
}
/*-----------------------------------------------------------*/
static void prvCoreBTasks( void *pvParameters )
{
BaseType_t x;
size_t xReceivedBytes;
uint32_t ulNextValue = 0;
char cExpectedString[ 15 ]; /* At least large enough to hold "4294967295\0" (0xffffffff). */
char cReceivedString[ 15 ];
/* The index into the xCoreBMessageBuffers and ulLoopCounter arrays is
passed into this task using the task's parameter. */
x = ( BaseType_t ) pvParameters;
configASSERT( x < mbaNUMBER_OF_CORE_B_TASKS );
for( ;; )
{
/* Create the string that is expected to be received this time round. */
sprintf( cExpectedString, "%lu", ( unsigned long ) ulNextValue );
/* Wait to receive the next message from core A. */
memset( cReceivedString, 0x00, sizeof( cReceivedString ) );
xReceivedBytes = xMessageBufferReceive( /* The message buffer to receive from. */
xCoreBMessageBuffers[ x ],
/* Location to store received data. */
cReceivedString,
/* Maximum number of bytes to receive. */
sizeof( cReceivedString ),
/* Ticks to wait if buffer is empty. */
portMAX_DELAY );
/* Check the number of bytes received was as expected. */
configASSERT( xReceivedBytes == strlen( cExpectedString ) );
( void ) xReceivedBytes; /* Incase configASSERT() is not defined. */
/* If the received string matches that expected then increment the loop
counter so the check task knows this task is still running. */
if( strcmp( cReceivedString, cExpectedString ) == 0 )
{
( ulCycleCounters[ x ] )++;
}
else
{
xDemoStatus = pdFAIL;
}
/* Expect the next string in sequence the next time around. */
ulNextValue++;
}
}
/*-----------------------------------------------------------*/
/* Called by the reimplementation of sbSEND_COMPLETED(), which can be defined
as follows in FreeRTOSConfig.h:
#define sbSEND_COMPLETED( pxStreamBuffer ) vGenerateCoreBInterrupt( pxStreamBuffer )
*/
void vGenerateCoreBInterrupt( void * xUpdatedMessageBuffer )
{
MessageBufferHandle_t xUpdatedBuffer = ( MessageBufferHandle_t ) xUpdatedMessageBuffer;
/* If sbSEND_COMPLETED() has been implemented as above, then this function
is called from within xMessageBufferSend(). As this function also calls
xMessageBufferSend() itself it is necessary to guard against a recursive
call. If the message buffer just updated is the message buffer written to
by this function, then this is a recursive call, and the function can just
exit without taking further action. */
if( xUpdatedBuffer != xControlMessageBuffer )
{
/* Use xControlMessageBuffer to pass the handle of the message buffer
written to by core A to the interrupt handler about to be generated in
core B. */
xMessageBufferSend( xControlMessageBuffer, &xUpdatedBuffer, sizeof( xUpdatedBuffer ), mbaDONT_BLOCK );
/* This is where the interrupt would be generated. In this case it is
not a genuine interrupt handler that executes, just a standard function
call. */
mbaGENERATE_CORE_B_INTERRUPT();
}
}
/*-----------------------------------------------------------*/
/* Handler for the interrupts that are triggered on core A but execute on core
B. */
static void prvCoreBInterruptHandler( void )
{
MessageBufferHandle_t xUpdatedMessageBuffer;
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
/* xControlMessageBuffer contains the handle of the message buffer that
contains data. */
if( xMessageBufferReceive( xControlMessageBuffer,
&xUpdatedMessageBuffer,
sizeof( xUpdatedMessageBuffer ),
mbaDONT_BLOCK ) == sizeof( xUpdatedMessageBuffer ) )
{
/* Call the API function that sends a notification to any task that is
blocked on the xUpdatedMessageBuffer message buffer waiting for data to
arrive. */
xMessageBufferSendCompletedFromISR( xUpdatedMessageBuffer, &xHigherPriorityTaskWoken );
}
/* Normal FreeRTOS yield from interrupt semantics, where
xHigherPriorityTaskWoken is initialzed to pdFALSE and will then get set to
pdTRUE if the interrupt safe API unblocks a task that has a priority above
that of the currently executing task. */
portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
/*-----------------------------------------------------------*/
BaseType_t xAreMessageBufferAMPTasksStillRunning( void )
{
static uint32_t ulLastCycleCounters[ mbaNUMBER_OF_CORE_B_TASKS ] = { 0 };
BaseType_t x;
/* Called by the check task to determine the health status of the tasks
implemented in this demo. */
for( x = 0; x < mbaNUMBER_OF_CORE_B_TASKS; x++ )
{
if( ulLastCycleCounters[ x ] == ulCycleCounters[ x ] )
{
xDemoStatus = pdFAIL;
}
else
{
ulLastCycleCounters[ x ] = ulCycleCounters[ x ];
}
}
return xDemoStatus;
}