TI MSP432 ARM Cortex-M4F RTOS Demo
Supporting IAR, ARM (Keil), and TI (CCS) compilers
[RTOS Ports]
The MSP-EXP432P401R LaunchPad Development Kit
Introduction
This page documents the demo application that targets the
Texas Instruments MSP432 microcontroller
- which is a variant of the MSP430 low power microcontroller
that uses an ARM Cortex-M4F core.
Pre-configured MSP432 projects that target the MSP432P401R Launchpad Development
Kit are provided for each of the following three ARM Cortex-M4 compilers:
-
IAR using the Embedded Workbench for ARM IDE
-
ARM using the uVision IDE
-
TI using the Code Composer Studio Eclipse based tools
Each project can be compiled to create either a simple blinky demo,
or a comprehensive test and demo application.
The comprehensive demo uses FreeRTOS+CLI
to create a simple command line interface through a UART.
The blinky demo uses FreeRTOS's tickless idle mode to reduce power consumption.
Stopping the RTOS tick interrupt allows the microcontroller to remain in a deep power
saving state until either an interrupt occurs, or it is time for the RTOS kernel
to transition a task into the Ready state.
Note that only the generic ARM Cortex-M tickless implementation is demonstrated,
which prevents any of the advanced MSP432 low power modes from being entered, and
therefore does not get close to demonstrating the power saving that could otherwise
be achieved.
FreeRTOS is designed to allow the generic tickless mode to be overridden by an
application specific implementation. Providing a target specific tickless
implementation allows the RTOS tick interrupt to be
generated from a low power clock, instead of the ARM Cortex-M SysTick clock. The
application writer can then tailor the implementation to be specific to the
application through the use of pre and post sleep macros. Tailoring a tickless
implementation specifically to the MSP432 will allow significantly
greater power savings to be achieved.
See the Low Power Support
and the Low Power RTOS For ARM Cortex-M MCUs
pages for further information.
Screen shot of the FreeRTOS state viewer plug-in
that ships with the IAR IDE
IMPORTANT! Notes on using the TI MSP432 ARM Cortex-M4F Demo
Please read all the following points before using this RTOS port.
- Source Code Organisation
- The Demo Application
- RTOS Configuration and Usage Details
See also the FAQ My application does
not run, what could be wrong?
Source Code Organisation
The FreeRTOS download contains the source code for every FreeRTOS port and
all the demo applications, so contains a lot more files than are required by the MSP432
demos. See the Source Code Organization
section of this website for a description of the downloaded files.
The IAR, Keil uVision and CCS projects are all located in the
/FreeRTOS/Demo/CORTEX_M4F_MSP432_LaunchPad_IAR_CCS_Keil directory:
-
The IAR Embedded Workbench for ARM (EWARM) project is called RTOSDemo.eww
-
The Keil uVision project is called RTOSDemo.uvproj
-
The CCS project has the usual Eclipse project name .project
Building and Running the MSP432 ARM Cortex-M4F RTOS Application
The RTOS demo projects can be configured to build either
a simple blinky project that also demonstrates FreeRTOS's generic tickless low
power mode, or a comprehensive test and demo application. The constant
configCREATE_SIMPLE_TICKLESS_DEMO, which is defined at the top of the
projects' FreeRTOSConfig.h file, is used
to switch between the two.
-
The simple tickless demo is created if configCREATE_SIMPLE_TICKLESS_DEMO
is set to 1.
-
The comprehensive demo is created if configCREATE_SIMPLE_TICKLESS_DEMO
is set to 0.
Note the comments at the top of this page about the
difference in power saving that can be achieved by the demonstrated generic
tickless implementation when compared to what could be achieved using an MSP432
specific tickless implementation.
The demo uses an LED built onto the Launchpad development kit, so no
hardware setup is required.
The following sub-sections provide instructions on using each of the ARM
Cortex-M4 toolchains.
-
Building with the IAR Embedded Workbench
-
Building with ARM Keil
-
Building with Code Composer Studio
-
IAR Embedded Workbench should be able to use the CMSIS DAP debug interface
accessible via the Launchpad hardware's USB connector, but for the
fastest and most reliable debugging experience it is recommended to
connect a JLINK Lite to the Launchpad hardware's external JTAG connector.
If you are using the external JTAG connector then the Launchpad
hardware's "JTAG Switch" must be set to "Ext".
-
Open FreeRTOS/Demo/CORTEX_M4F_MSP432_LaunchPad_IAR_CCS_Keil/RTOSDemo.eww in the
IAR Embedded Workbench IDE.
-
Select "Rebuild All" from the IAR Embedded Workbench "Project" menu (or press F7) to build
the demo project.
-
Select "Download and Debug" from the IAR Embedded Workbench "Project"
menu to program the microcontroller flash memory and start a debug
session.
Note: The IAR project can fail to build and get corrupted (so it can no longer
be used with any IAR version) if it is opened in a version of EWARM that is older
than the version that was used to originally create the project.
-
Keil uVision should be able to use the CMSIS DAP debug interface
accessible via the Launchpad hardware's USB connector, but for the
fastest and most reliable debugging experience it is recommended to
connect a UINK ME to the Launchpad hardware's external JTAG connector.
If you are using the external JTAG connector then the Launchpad
hardware's "JTAG Switch" must be set to "Ext".
-
Ensure the MSP432 pack has been installed and is available for use by
the uVision IDE.
-
Open FreeRTOS/Demo/CORTEX_M4F_MSP432_LaunchPad_IAR_CCS_Keil/RTOSDemo.uvprojx in the
Keil IDE.
-
Select "Rebuild Target" from the Keil "Project" menu (or press F7) to build
the demo project.
-
Select "Start/Stop Debug Session" from the Keil "Project"
menu to program the microcontroller flash memory and start a debug
session.
-
Connect the Launchpad development kit directly to the host computer
(the computer running CCS) using the hardware's USB connector - no other debug
interface is required. Ensure the Launchpad hardware's "JTAG Switch" is
set to "XDS".
-
Start the CCS Eclipse IDE, and either create a new or select an existing
workspace when prompted.
-
Select "Import" from the IDE's "File" menu. The dialogue box shown below
will appear. Select "Code Composer Studio->CCS Projects", as shown below.
The dialogue box that appears when "Import" is first clicked
-
In the next dialogue box, select /FreeRTOS/Demo/CORTEX_M4F_MSP432_LaunchPad_IAR_CCS_Keil
as the root directory. Make sure the RTOSDemo project is checked in the "Projects" area,
and that the Copy Projects Into
Workspace box is not checked, before clicking
the Finish button (see the image below for the correct check box states).
Make sure RTOSDemo is checked, and "Copy projects into workspace" is not checked
-
Select "Build All" from the CCS Eclipse "Project" menu to build
the demo project.
-
Select "Debug" from the Eclipse "Run"
menu to program the microcontroller's flash memory and start a debug
session.
Note 1: The projects for all the compilers are contained in the same directory
within the FreeRTOS .zip file download. Code Composer Studio (CCS) will fail to build
the project if the directory already contains object files that were generated
by a different compiler. It is necessary to delete all intermediary files from the
directory, and its sub-directories, before it is possible to switch to using the
Code Composer Studio project after either the IAR or uVision projects have already
been used.
Note 2: The CCS project references files using relative paths, including
FreeRTOS+CLI files from the /FreeRTOS-Plus directory. The project may
fail to build if a directory path is changed or if a file is moved. Eclipse's
'export' features can be used to convert the project into a stand-alone project
that only uses directories under the directory in which the .project file is located.
Demo Application Functionality
The simply blinky example, using tick-less operation
The simple tickless example is created when configCREATE_SIMPLE_TICKLESS_DEMO is set
to 1. configCREATE_SIMPLE_TICKLESS_DEMO is defined at the top of FreeRTOSConfig.h.
The FreeRTOS tickless idle mode stops the periodic RTOS tick interrupt during
idle periods (periods when there are no application tasks that are able to execute).
The blinky example creates two tasks that only unblock once every second, so the
tick interrupt is stopped for the majority of the execution time.
Stopping the RTOS tick interrupt allows the microcontroller to remain in a deep power
saving state until either an interrupt occurs, or it is time for the RTOS kernel
to transition a task into the Ready state.
Note the comments at the top of this page about the
difference in power saving that can be achieved by the demonstrated generic
tickless implementation when compared to what could be achieved using an MSP432
specific tickless implementation.
Setting configCREATE_SIMPLE_TICKLESS_DEMO to 1 results in main() calling
main_blinky():
-
The main_blinky() Function:
main_blinky() creates a queue, a queue send task, and a queue receive
task, before starting the scheduler.
-
The Queue Send Task:
The queue send task is implemented by the prvQueueSendTask() function in main_blinky.c.
prvQueueSendTask() sends the value 100 to the queue every second.
-
The Queue Receive Task:
The queue receive task is implemented by the prvQueueReceiveTask() function
in main_blinky.c.
prvQueueReceiveTask() blocks to wait for data to arrive on the queue.
Each time the value 100 is received from the queue it flashes the LED.
As data is sent to the queue every second, the LED will flash every
second.
The comprehensive test and demo application
Sample CLI session
The comprehensive example is created when configCREATE_SIMPLE_TICKLESS_DEMO is set
to 0. configCREATE_SIMPLE_TICKLESS_DEMO is defined in FreeRTOSConfig.h.
The comprehensive demo includes a
command line interface
(CLI) on which both task and run-time statistics can be viewed. Instructions on
connecting to and using the CLI are provided below.
Setting configCREATE_SIMPLE_TICKLESS_DEMO to 0 results in main() calling
main_full():
-
The main_full() Function:
main_full() creates a set of standard demo tasks,
the CLI, the Check task, the Register Test tasks, and starts the
scheduler.
-
The "Reg Test" Tasks:
The reg test tasks test the context switching mechanism by filling each
MCU register with a known value, then continuously checking that each
register maintains its expected value for the lifetime of the task.
-
The "Check" Task:
The "Check" task monitors the status of all the other tasks in
the system, looking for a task either stalling or reporting an error.
It toggles an LED each time it is called.
If the LED is toggling every three seconds then the check task has determined
the demo is running as expected. If the LED
is toggling every 200ms then at least one error has been found.
To connect to the CLI:
-
Power the Lauchpad hardware through the hardware's USB connector.
-
Run the comprehensive demo. A UART on the MPS432 will enumerate
as a virtual COM port called "XDS110 Class Application/User UART" on the
host computer.
-
Open a dumb terminal program, such as Tera Term or Hyper Terminal, and
connect to the enumerated COM port at 19200 baud.
-
As always with FreeRTOS+CLI - type "help" into the console to see a
list of registered commands. An example CLI session is shown on the right.
Interrupt service routines
Priority assignment
Attention please!: See the page dedicated to setting interrupt priorities on ARM Cortex-M devices. Remember that ARM Cortex-M cores use
numerically low priority numbers to represent HIGH priority interrupts. This
can seem counter-intuitive and is easy to forget! If you wish to assign an
interrupt a low priority do NOT assign it a priority of 0 (or other low numeric
value) as this will result in the interrupt actually having the highest priority
in the system - and therefore potentially make your system crash if this
priority is above configMAX_SYSCALL_INTERRUPT_PRIORITY. Also, do not leave
interrupt priorities unassigned, as by default they will have a priority of 0
and therefore the highest priority possible.
The lowest priority on a ARM Cortex-M core is in fact 255 - however different
ARM Cortex-M microcontroller manufacturers implement a different number of priority bits and supply library
functions that expect priorities to be specified in different ways. For example,
the TI MSP432 ARM Cortex-M4 microcontrollers implements 3 priority bits, which
allows for a maximum of 8 different priority levels (0 to 7 inclusive). The lowest priority being
the highest number. Some library functions will use the numeric value 7 as the
lowest priority, while others will use the numeric value 224 as the lowest (which
is 7 << 5, and how the ARM Cortex-M sees the value internally in the interrupt controller).
These two numbers are defined by configLIBRARY_LOWEST_INTERRUPT_PRIORITY and
configKERNEL_INTERRUPT_PRIORITY respectively in FreeRTOSConfig.h. The highest priority
that can be assigned is always zero.
It is also recommended to ensure that all priority bits are assigned as
being preemption priority bits, and none as sub priority bits.
Implementing interrupt service routines
Interrupt service routines that cause a context switch have
no special requirements. The function vUART_Handler(), defined in
/FreeRTOS/Demo/CORTEX_M4F_MSP432_LaunchPad_IAR_CCS_Keil/Full_Demo/serial.c
can be used as an example. Another example is provided below:
void Dummy_IRQHandler(void)
{
long lHigherPriorityTaskWoken = pdFALSE;
/* Clear the interrupt if necessary. */
Dummy_ClearITPendingBit();
/* This interrupt does nothing more than demonstrate how to synchronise a
task with an interrupt. A task notification is used for this purpose. Note
lHigherPriorityTaskWoken is initialised to zero. Only FreeRTOS API functions
that end in "FromISR" can be called from an ISR! */
vTaskNotifyGiveFromISR( xTaskToNotify, &lHigherPriorityTaskWoken );
/* If the task with handle xTaskToNotify was blocked waiting for a notification,
and giving the notification caused the task to unblock, and the unblocked
task has a priority higher than the current Running state task (the task that
this interrupt interrupted), then lHigherPriorityTaskWoken will have been set
to pdTRUE internally within vTaskNotifyGiveFromISR(). 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 );
}
RTOS port specific configuration
Configuration items specific to these demos are contained in the FreeRTOSConfig.h
file located in the same directory as the project file. The
constants defined in FreeRTOSConfig.h can be edited to meet the needs of your application. In particular -
Each port #defines 'BaseType_t' to equal the most efficient data type for that
processor. All ARM Cortex-M4F ports define BaseType_t to be of type long.
Note that vPortEndScheduler() has not been implemented.
Memory allocation
Source/Portable/MemMang/heap_4.c is included in the ARM Cortex-M4F 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.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.
|
