Altera Cyclone V SoC RTOS Demo
(ARM Cortex-A9)
[RTOS Ports]
Introduction
This page documents a FreeRTOS demo application for a Cortex-A9 core in the
Altera Cyclone V SoC
Hard Processing System (HPS).
The project builds using the free Altera edition of the ARM DS-5 Eclipse based
IDE and the GCC compiler, both of which come as part of
the Altera Embedded Development Suite
(EDS). Note only the DS-5 and compiler components of the EDS are used - it is
not necessary to install any FPGA tools to build or use this RTOS demo.
The project is pre-configured to execute on the
Cyclone V SoC Development Kit
hardware.
FreeRTOS+CLI
is used to create a command console [Note the FreeRTOS+CLI
license is not the same as the FreeRTOS license]
IMPORTANT! Notes on using the FreeRTOS Cyclone V SoC ARM Cortex-A9 demo
Please read all the following points before using this RTOS port.
- Source Code Organisation
- The Demo Application Functionality
- Build Instructions
- RTOS Configuration and Usage Details
Also see the FAQ My application does not run, what could be wrong?, and
the page that provides instruction on using FreeRTOS on ARM Cortex-A embedded processors.
Source Code Organisation
Only a small subset of the files in the FreeRTOS .zip file download are are
required by the Altera Cyclone V SoC demo. The Source Code Organization page describes
the structure of the FreeRTOS zip file download.
The ARM DS-5 Eclipse project file is located in the FreeRTOS/Demo/CORTEX_A9_Cyclone_V_SoC_DK
directory. Note the RTOS project includes files that are contained in the
/FreeRTOS-Plus directory, so the projects will not build if the
/FreeRTOS-Plus directory has been deleted or the directory structure has
been changed.
The Altera Cyclone V SoC ARM Cortex-A9 Demo Application
Hardware and software set up
Although the RTOS demo presented on this page has been pre-configured to run
on the Altera Cyclone V SoC Development Kit it can be adapted easily to run on
any Cyclone V SoC evaluation board that provides access to one UART and one LED.
-
UART
A UART is used for console IO. The demo in the download uses UART 0 for
this purpose. UART 0 uses a UART to USB converter, so is connected using
a USB cable.
If it is necessary to use a UART other than UART 0 then update the
FreeRTOS/Demo/CORTEX_A9_Cyclone_V_SoC_DK/Altera_Code/SoCSupport/uart0_support.c
source file accordingly.
-
LED digital output
A digital output is used to toggle an LED. If it is necessary to use a
different digital output then update FreeRTOS/Demo/CORTEX_A9_Cyclone_V_SoC_DK/LEDs.c
accordingly.
Functionality
The behaviour of the demo is defined by the mainCREATE_SIMPLE_BLINKY_DEMO_ONLY
#define constant, which is declared at the top of main.c.
Functionality with mainCREATE_SIMPLE_BLINKY_DEMO_ONLY set to 1
If mainCREATE_SIMPLE_BLINKY_DEMO_ONLY is set to 1 then main() will
call main_blinky().
main_blinky() creates a very simple demo that includes two
tasks and one queue.
One task repeatedly sends the value 100 to the other task
through the queue. The receiving task toggles an LED each time it receives
the message. The message is sent every 200 milliseconds, so the LED toggles
every 200 milliseconds.
Functionality with mainCREATE_SIMPLE_BLINKY_DEMO_ONLY set to 0
An example CLI session
If mainCREATE_SIMPLE_BLINKY_DEMO_ONLY is set to 0 then main() will
call main_full(). main_full() creates a comprehensive test and demo application
that demonstrates:
Connect to FreeRTOS+CLI though the UART using 115200 baud. Type 'help' in the
CLI to see a list of the registered commands.
Most of the RTOS tasks created by the demo are from the set of standard demo
RTOS tasks. These are used by all FreeRTOS demo applications, and
have no specific functionality or purpose other than to demonstrate the FreeRTOS
API being used and test the RTOS kernel port.
A 'check' RTOS task is also created. The check task periodically queries the standard
demo tasks to ensure they are functioning as intended. The check task also
toggles an LED to give a visual indication of the system status.
If the LED toggles every 3 seconds then the check task has not discovered
any problems with the executing demo. If the LED toggles every 200 milliseconds
then the check task has discovered a problem in at least one task..
Build Instructions
Note that the ARM DS-5 Eclipse project
uses both virtual folders and links that reference files from both the /FreeRTOS-Plus and /FreeRTOS/Demo/Common
directories. The [virtual] file structure viewed in the Eclipse project explorer will
not therefore match the [actual] file structure viewed on the disk.
-
Open the ARM DS-5 Eclipse IDE and either create a new workspace or select an existing
workspace when prompted.
-
Select "Import" from the IDE's "File" menu to bring up the import
dialog box.
-
In the Import dialog box, select "General->Existing Projects Into Workspace"
then browse to and select the FreeRTOS/Demo/CORTEX_A9_Cyclone_V_SoC_DK
directory. A project called "RTOSDemo" will be visible.
-
Ensure RTOSDemo is checked and that Copy Projects Into Workspace is
not checked before clicking "Finish".
Import RTOSDemo into the Eclipse workspace without
copying it into the workspace.
-
The GCC compiler used to build the project is installed when the
Altera EDS
is installed. It is necessary to update the project to set the compiler's
location.
Select "Properties" from the IDE's "Project" menu to bring up the
properties dialogue box. In the dialogue box select "C/C++Build->Settings->
Cross Settings", then set the path to the compiler to be correct for your
installation.
Note: If the dialogue box tab shown in the
image below is missing, or contains an error message, then it is likely
your version of DS-5 does not have the CDT cross compiler plug in installed.
If this is the case the plug in can be installed manually by
following
the instructions provided on the ARM website. It will be necessary to
create a new workspace after the plug-in has been installed.
Setting the path to the compiler in the RTOS project's properties dialogue box
-
Open main.c and set mainCREATE_SIMPLE_BLINKY_DEMO_ONLY to generate either
the simple blinky demo, or the full test and demo application, as
required.
-
Ensure the target hardware is connected to the host computer using an
appropriate debug interface. The Cycle V SoC Development Kit has a build
it BitBlaster interface. Other debug interfaces, such as ARM's D-Stream,
can also be used.
-
Select "Build All" from the IDE's "Project" menu.
-
After the build completes, select "Debug Configurations..." from the
IDE's "Debug" menu, and configure and run a debug configuration that is
appropriate for your selected connection method (BitBlaster, D-Stream, etc.).
The clickable screenshots below show a configuration that is using the D-Stream
debugger. Note the selection of the preloader script in third screenshot.
FreeRTOS ARM Cortex-A port specific configuration
Attention please!: Refer to the the page that provides
instruction on using FreeRTOS on ARM Cortex-A embedded processors,
paying particular attention to the value and meaning of the
configMAX_API_CALL_INTERRUPT_PRIORITY setting.
In this demo configSETUP_TICK_INTERRUPT is defined to call vConfigureTickInterrupt(),
which in turn is implemented in main.c. vApplicationIRQHandler() is also implemented
in main.c.
Configuration items specific to this demo are contained in FreeRTOS/Demo/CORTEX_A9_Cyclone_V_SoC_DK/FreeRTOSConfig.h.
The constants defined in this file can be edited to suit your application.
[Application Defined] Interrupt service routines
This demo uses drivers provided by Altera to configure the interrupt controller but,
because the driver's own interrupt table is not accessible outside of its defining
source file, a FreeRTOS specific function is used to actually register interrupt
handlers. vRegisterIRQHandler() is used for this purpose, and is implemented in
main.c.
void vRegisterIRQHandler( uint32_t ulID,
alt_int_callback_t pxHandlerFunction,
void *pvContext );
vRegisterIRQHandler() function prototype
|
The C handlers themselves have the following prototype;
void vAnISRHandlingFunction( uint32_t ulICCIAR, void *pvContext );
The prototype of an interrupt handling function that can be registered using vRegisterIRQHandler()
|
If an ISR causes an RTOS task of equal or higher priority than the currently executing
task to leave the Blocked state (see description of the pxHigherPriorityTaskWoken
parameter in the API documentation for functions such as
xSemaphoreGiveFromISR())
then the ISR must request a context switch before
the ISR exits. When this is done the interrupt will interrupt one RTOS task,
but return to a different RTOS task.
The macros portYIELD_FROM_ISR() (or portEND_SWITCHING_ISR()) can be used to
request a context switch from within an ISR.
The following source code snippet is provided as an example. The example ISR
uses a semaphore to synchronise with a task (not shown), and calls portYIELD_FROM_ISR()
to ensure the interrupt returns directly to the task.
void Dummy_IRQHandler( uint32_t ulUnused, void *pvUnused )
{
long lHigherPriorityTaskWoken = pdFALSE;
/* The parameter is not used. */
( void ) ulUnused;
/* Clear the interrupt if necessary. */
Dummy_ClearITPendingBit();
/* This interrupt does nothing more than demonstrate how to synchronise a
task with an interrupt. A semaphore is used for this purpose. Note
lHigherPriorityTaskWoken is initialised to pdFALSE. */
xSemaphoreGiveFromISR( xTestSemaphore, &lHigherPriorityTaskWoken );
/* If there was a task that was blocked on the semaphore, and giving the
semaphore caused the task to unblock, and the unblocked task has a priority
higher than or equal to the currently Running task (the task that this
interrupt interrupted), then lHigherPriorityTaskWoken will have been set to
pdTRUE internally within xSemaphoreGiveFromISR(). Passing pdTRUE into the
portYIELD_FROM_ISR() macro will result in a context switch being pended to
ensure this interrupt returns directly to the unblocked, higher priority,
task. Passing pdFALSE into portYIELD_FROM_ISR() has no effect. */
portYIELD_FROM_ISR( lHigherPriorityTaskWoken );
}
An example interrupt handler
|
Only FreeRTOS API functions that end in "FromISR" can be called from an
interrupt service routine - and then only if the priority of the interrupt
is less than or equal to that set by the configMAX_API_CALL_INTERRUPT_PRIORITY
configuration constant (meaning a numerically higher value).
Resources used by FreeRTOS
Information is provided on the Using FreeRTOS on ARM Cortex-A Embedded Processors page.
This demo is configured to generate the tick interrupt from the Cortex-A9 core's
private timer.
Memory allocation
Source/Portable/MemMang/heap_4.c is included in the ARM Cortex-A demo application project to provide the memory
allocation required by the RTOS kernel.
Please refer to the Memory Management section of the API documentation for
full information.
Miscellaneous
Note that vPortEndScheduler() has not been implemented.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.
|
