IntroductionThe PIC32MX RTOS portThis page presents the FreeRTOS port and demo application for the PIC32MX - a 32bit microcontroller from Microchip that has a MIPS M4K core.The FreeRTOS PIC32MX port:
FreeRTOS is an integral part of MPLAB Harmony - Microchip's integrated driver and middleware package. An older application note (and source code) is also available from the Microchip web site that shows how to integrate FreeRTOS with Microchip's now legacy peripheral and middleware libraries.
The demo applicationMPLAB X and MPLAB XC32 are now the preferred IDE and compiler respectively with which to build the FreeRTOS demos. MPLAB 8 projects are still included in the RTOS source code download, but will be retired at some time in a future release.Pre-configured support for multiple PIC32 derivatives and hardware platforms is provided by the provision of multiple build configurations within the MPLAB X project. Build configurations are provided for:
The MPLAB 8 project is pre-configured to target the PIC32MX360 microcontroller running on an Explorer 16 evaluation board. Each build configuration can be used to build either a simple blinky demo or a comprehensive test and demo application. The comprehensive application demonstrates and tests the interrupt nesting behaviour. Build instructions are provided on this page.
IMPORTANT! Notes on using the PIC32 RTOS portPlease read all the following points before using this RTOS port.See also the FAQ My application does not run, what could be wrong?
The MPLAB 8 demo application workspace for the PIC32MX / MIPS port is called RTOSDemo.mcw, and is located in the FreeRTOS/Demo/PIC32MX_MPLAB directory. The MPLAB X project is called RTOSDemo.X, and is located off of the same directory. Demo application hardware setup - Explorer 16All the Explorer 16 jumpers can remain in their default positions - in particular, JP2 should be fitted to ensure correct operation of the LEDs.The demo application includes tasks that send and receive characters over UART2. The characters sent by one task are received by another - with an error condition being flagged if any characters are missed or received out of order. A loopback connector is required on the Explorer16 9way D socket for this mechanism to operate (pins 2 and 3 should be connected together). The internal loopback mode of the UART itself is not used by default. NOTE: The UART interrupt service routine (ISR) uses an RTOS queue to send individual characters from the ISR to an RTOS tasks, and a separate RTOS queue to send individual characters from an RTOS task into the ISR. Using queues to send individual characters in this way is very inefficient. The provided UART driver is intended to demonstrate queues being used from an ISR and to stress test the RTOS port. It is not intended to represent an efficient interrupt implementation.
FunctionalityThe demo application can be configured to provide very simply 'blinky' style functionality, or a full and comprehensive test and demonstration of a subset of RTOS features. The mainCREATE_SIMPLE_BLINKY_DEMO_ONLY constant, which is #define(d) at the top of main.c, is used to switch between the two.Demo application tasks are split between standard demo tasks, and demo specific tasks. Standard demo tasks are used by all FreeRTOS port demo applications. They have no purpose other than to demonstrate the FreeRTOS API, and test a port.
When mainCREATE_SIMPLE_BLINKY_DEMO_ONLY is set to 1When mainCREATE_SIMPLE_BLINKY_DEMO_ONLY is set to 1 main() calls main_blinky(). main_blinky() creates a very simple example that uses two tasks, one queue, and one software timer.
When mainCREATE_SIMPLE_BLINKY_DEMO_ONLY is set to 0When mainCREATE_SIMPLE_BLINKY_DEMO_ONLY is set to 0 main() calls main_full(). main_full() creates a very comprehensive test and demo application that creates numerous RTOS tasks and software timers. The demo will execute on both the Explorer 16 and the USB II Starter Kit, although when on the starter kit the LCD and UART tasks are not used (as they are not available on the hardware) and fewer flash tasks are created to allow the 'check timer' (described below) access to one of the three LEDs available on the Starter Kit hardware. The description below is correct when the demo is executed on the Explorer 16.
Building and debugging the demo application with MPLAB XThese instructions assume you have MPLAB X and the MPLAB XC32 compiler correctly installed on your host computer.
Configuration and Usage DetailsRTOS port specific configurationConfiguration items specific to this demo are contained in FreeRTOS/Demo/PIC32MX_MPLAB/FreeRTOSConfig.h. The constants defined in that file can be edited to suit your application. In particular -
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. Interrupt service routinesInterrupt service routines that cannot nest have no special requirements and can be written as per the compiler documentation. However interrupts written in this manner will utilise the stack of whichever task was interrupted, rather than the system stack, necessitating that adequate stack space be allocated to each created task. It is therefore not recommended to write interrupt service routines in this manner.Interrupts service routines that can nest require a simple assembly wrapper, as demonstrated below. It is recommended that all interrupts be written in this manner. The UART interrupt within the PIC32 demo can be used as an example - an outline of the assembly code wrapper for which is shown in Listing 1, and an outline of the corresponding C function handler is shown in Listing 2:
/* Prototype to be included in a C file to ensure the vector is correctly installed. Note that because this ISR uses the FreeRTOS assembly wrapper the IPL setting in the following prototype has no effect. The interrupt priority is set using the ConfigIntUART2() PIC32 peripheral library call. */ void __attribute__( (interrupt(ipl1), vector(_UART2_VECTOR))) vU2InterruptWrapper( void ); /* Header file in which portSAVE_CONTEXT and portRESTORE_CONTEXT are defined. */ #include "ISR_Support.h" /* Ensure correct instructions is used. */ .set nomips16 .set noreorder /* Interrupt entry point. */ vU2InterruptWrapper: /* Save the current task context. This line MUST be included! */ portSAVE_CONTEXT /* Call the C function to handle the interrupt. */ jal vU2InterruptHandler nop /* Restore the context of the next task to execute. This line MUST be included! */ portRESTORE_CONTEXT .end vU2InterruptWrapper Listing 1: Assembly code wrapper for handling an interrupt that can cause a context switch
Some notes on the assembly file wrapper:
Second, the C function called by the assembly file wrapper:
void vU2InterruptHandler( void ) { /* Declared static to minimise stack use. */ static BaseType_t xYieldRequired; xYieldRequired = pdFALSE; /* Are any Rx interrupts pending? */ if( mU2RXGetIntFlag() ) { /* Process Rx data here. */ /* Clear Rx interrupt. */ mU2RXClearIntFlag(); } /* Are any Tx interrupts pending? */ if( mU2TXGetIntFlag() ) { /* Process Tx data here. */ /* Clear Tx interrupt. */ mU2TXClearIntFlag(); } /* If sending or receiving necessitates a context switch, then switch now. */ portEND_SWITCHING_ISR( xYieldRequired ); } Listing 2: The C portion of an ISR that can cause a context switch
Some notes on the C function:
Critical sectionsExiting a critical section will always set the interrupt priority such that all interrupts are enabled, no matter what its level when the critical section was entered. FreeRTOS API functions themselves will use critical sections.Execution contextIn line with the conventions documented in the XC32 compiler manual, the RTOS kernel assumes all access to the K0 and K1 registers will be atomic. Code generated by the XC32 compiler conforms to this convention so if you are writing application purely in C then this is of no concern. Care must be taken however if any hand written assembly code is used to ensure that that too conforms to the same convention.Shadow registersThe interrupt shadow registers are not used and are therefore available for use by the host application. Shadow registers should not be used within an interrupt service routine that causes a context switch.Software interruptsThe RTOS kernel makes use of the MIPS software interrupt 0. This interrupt is therefore not available for use by the application.Switching between the pre-emptive and co-operative RTOS kernelsSet the definition configUSE_PREEMPTION within FreeRTOS/Demo/PIC32MX_MPLAB/FreeRTOSConfig.h to 1 to use pre-emption or 0 to use co-operative. The demo application will only execute correctly with configUSE_PREEMPTION set to 0 if configIDLE_SHOULD_YIELD is set to 1.Compiler optionsAs 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.Memory allocationSource/Portable/MemMang/heap_4.c is included in the PIC32 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.Serial port driverIt should also be noted that the serial drivers are written to test some of the real time kernel features - and they are not intended to represent an optimized solution. In particular, they make heavy use of the queue mechanism and do not use the available FIFO or DMA.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.
|
Latest News
NXP tweet showing LPC5500 (ARMv8-M Cortex-M33) running FreeRTOS. Meet Richard Barry and learn about running FreeRTOS on RISC-V at FOSDEM 2019 Version 10.1.1 of the FreeRTOS kernel is available for immediate download. MIT licensed. View a recording of the "OTA Update Security and Reliability" webinar, presented by TI and AWS. Careers
FreeRTOS and other embedded software careers at AWS. FreeRTOS Partners
|