FreeRTOS PSoC5 CY8C5588 Demo
The demo application has been tested on the following evaluation kits:
The PSoC5 demo includes a schematic design with several peripherals to demonstrate their integration with the RTOS. The included peripherals are the UART, LCD Character Display and two different types of timer implementations.
The demo uses:
Please read all the following points before using this RTOS port.
See also the FAQ My application does not run, what could be wrong?
See the Source Code Organization section of the FreeRTOS site for a description of the downloaded files and information on creating a new project.
PSoC Creator Workspace - GCC
PSoC Creator Workspace - Keil
PSoC Creator Workspace - RVDS
The PSoC5 contains reconfigurable hardware. The Schematic Design for the components required by the demo is shown here. The design includes: four digital outputs, one digital input, a UART driver and four separate timers, two implemented as PWMs and two as Timers. The Schematic Design requires the outputs and inputs to be mapped to physical pins on the board. These pins can be configured in the Design-wide-resource but the defaults are documented below.
To enable the LEDs and UART COM tests, there are several connections that need to be made on the board.
The demo application also utilises the LCD Character Display which consumes pins P2[0:6]. No additional set-up is required.
The CY8C5588 is programmed and debugged using the MiniProg3 Programmer/Debugger. You will be prompted to install various USB drivers the first time a USB connection is made between the evaluation board and a PC. The required USB drivers are installed as part of the PSoC Programmer which may be prompted during the PSoC Creator installation.
All three demo applications utilise the PSoC Creator IDE but are configured to use different toolchains to compile and link.
The demo application creates 52 persistent tasks, and periodically dynamically creates and destroys another 2. These tasks consist predominantly of the standard demo application tasks (see the demo application section for details of the individual tasks).
The following tasks and tests are created in addition to the standard demo tasks:
A high frequency periodic interrupt is generated using a free running timer to demonstrate the use of the configKERNEL_INTERRUPT_PRIORITY configuration constant. The interrupt service routine measures the number of processor clocks that occur between each interrupt - and in so doing measures the jitter in the interrupt timing. The maximum measured jitter time is latched in the usMaxJitter variable, and displayed on the LCD display by the 'Check' task as described below. The fast interrupt is configured and handled in the timertest.c source file. This demonstrates how the RTOS kernel can be configured so as to have no impact on higher priority interrupt processing.
This only executes every five seconds. Its main function is to check that all the standard demo tasks are still operational. Should any unexpected behaviour within a demo task be discovered the Check Task' function will write an error code to the LCD. If all the demo tasks are executing with their expected behaviour then the check task writes Pass with the number of iterations it has completed and the max jitter time to the LCD, as described above.
The PWM peripherals generate interrupts at 2000Hz and 2001Hz. These interrupts are used as triggers to manipulate queues which generate context switching between tasks that are waiting on those queues. The Interrupt frequency is much higher than the System Tick pre-emption meaning that the interrupts cause much more frequent context switching between a subset of tasks.
When executing, the demo application will behave as follows:
Configuration items specific to these demos are contained in FreeRTOS/Demo/CORTEX_CY8C5588_PSoC_Creator_nnn/FreeRTOSConfig.h (where nnn is the compiler being used). The constants defined in this file can be edited to suit your application. In particular -
This sets the frequency of the RTOS tick. The supplied value of 1000Hz is useful for testing the RTOS kernel functionality but is faster than most applications require. Lowering this value will improve efficiency.
See the RTOS kernel configuration documentation for full information on these configuration constants.
Attention please!: Remember that ARM Cortex-M3 cores use numerically low priority numbers to represent HIGH priority interrupts, which 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 can 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.
The lowest priority on a ARM Cortex-M3 core is in fact 255 - however different ARM Cortex-M3 vendors implement a different number of priority bits and supply library functions that expect priorities to be specified in different ways. Use the supplied examples as a reference.
The Cypress Design Wide Resource can be used to configure the priority of the interrupts generated by each of the peripherals. If the application provides its own implementation of an interrupt service routine, which accesses the Kernel API, ensure that the priority is equal to or numerically greater than the configMAX_SYSCALL_INTERRUPT_PRIORITY so it in effect has a lower actual priority.
To install a customised interrupt service routine, call the Peripheral_StartEx(vCustomISR) function (where 'Peripheral' is the name of the peripheral to which the ISR relates) passing the interrupt service routine function which had its prototype declared as CY_ISR_PROTO(vCustomISR) and the function declared with CY_ISR(vCustomISR). See the function vInitialiseTimerForIntQTests() in IntQueueTimer.c for an example. In this function the ISR is installed using a call to isr_High_Frequency_2001Hz_StartEx().
Each port #defines 'BaseType_t' to equal the most efficient data type for that processor. This port defines BaseType_t to be of type long.
Note that vPortEndScheduler() has not been implemented.
In the demo application the vector table is copied into the RAM.
Unlike most ports, interrupt service routines that cause a context switch have no special requirements and can be written as per the compiler documentation.
The macro portEND_SWITCHING_ISR() can be used to request a context switch from within an ISR. The ISR called vUartRxISR() in serial.c demonstrates portEND_SWITCHING_ISR() being used.
Note that portEND_SWITCHING_ISR() will leave interrupts enabled.
Note also the information provided in the "RTOS port specific configuration" section above regarding the installation of custom interrupt service routines.
Set the definition configUSE_PREEMPTION within FreeRTOS/Demo/CORTEX_CY8C5588_PSoC_Creator_nnn/FreeRTOSConfig.h (where nnn is the compiler being used) to 1 to use pre-emption or 0 to use co-operative.
As with all the ports, it is essential that the correct compiler options are used. The best way to ensure this is to base your application on the provided demo application files.
Source/Portable/MemMang/heap_2.c is included in the ARM Cortex-M3 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.
The Design-wide-resource, FreeRTOS_Demo.cydwr, contains configuration options for generating a linker script. Select the 'System' tab and expand 'Configuration' to configure the 'Heap Size' when using Heap 3, Source/Portable/MemMang/heap_3.c, as part of your project.