Homepage  

Microchip PIC32 RTOS port
with a MIPS M4K core
[RTOS Ports]



This page presents the FreeRTOS.org port and demo application for the PIC32, a MIPS based 32bit microcontroller offerings from Microchip.

The port and demo are preconfigured to use:

Thanks to Darren Wenn for his contributions during the development of this port.

IMPORTANT! Notes on using the PIC32 RTOS port

Please read all the following points before using this RTOS port.

  1. Source Code Organization
  2. The Demo Application
  3. Configuration and Usage Details
See also the FAQ My application does not run, what could be wrong?

Source Code Organization

 The FreeRTOS download contains the source code for all the FreeRTOS ports so contains many more files that used by this demo. See the Source Code Organization section for a description of the downloaded files and information on creating a new project.

The MPLAB demo application workspace for the PIC32 / MIPS port is called RTOSDemo.mcw and can be located in the FreeRTOS/Demo/PIC32MX_MPLAB directory.

The Demo Application


Demo application hardware setup

All 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 should any characters be missed or received out of order. A loopback connector is required on the Explorer16 9way D socket for this mechanism to operation (pins 2 and 3 the socket should be connected together). The internal loopback mode of the UART itself is not used by default.

The demo application uses the LEDs built onto the prototyping board so no other hardware setup is required.


Functionality

The demo application creates twenty five tasks (including the idle task), and a high frequency interrupt test. When executing correctly the demo will behave as follows:


Building and executing the demo application

These instructions assume you have MPLAB and the MPLAB C32 compiler correctly installed on your host computer.


Configuration and Usage Details


RTOS Port specific configuration

Configuration items specific to this port are contained in FreeRTOS/Demo/PIC32_MPLAB/FreeRTOSConfig.h. The constants defined in this file can be edited to suit your application. In particular -

Each port #defines 'portBASE_TYPE' to equal the most efficient data type for that processor. This port defines portBASE_TYPE to be of type long.

Note that vPortEndScheduler() has not been implemented.


Interrupt service routines

Interrupt service routines that cannot cause a context switch have no special requirements and can be written as per the compiler documentation. The high frequency timer interrupt within the PIC32 demo can be used as an example, an outline of which is shown in Listing 1.

        void __attribute__( (interrupt(ipl2), vector(_TIMER_2_VECTOR))) vT2InterruptHandler( void );
        void vT2InterruptHandler( void )
        {
            /* Perform interrupt processing here. */
        
            /* Clear the timer interrupt. */
            IFS0bits.T2IF = 0;
        }
Listing 1: An ISR that does not cause a context switch written as per the compiler documentation

Interrupts service routines that can cause a context switch do have have a few special requirements:

  1. The interrupt entry must be via an assembly wrapper.
  2. The interrupt handler C function must only use the portEXIT_SWITCHING_ISR() macro to perform the context switch, if one is required.
  3. The interrupt must be assigned the same priority as the tick interrupt - defined by portKERNEL_INTERRUPT_PRIORITY within FreeRTOSConfig.h.
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 2, and an outline of the corresponding C function handler is shown in Listing 3:


        /* Prototype to be included in a C file to ensure the vector is 
        correctly installed. */
        void __attribute__( (interrupt(ipl1), vector(_UART2_VECTOR))) vU2InterruptWrapper( void );


        /* Header file in which portSAVE_CONTEXT and portRESTORE_CONTEXT are defined. */
        #include "ISR_Support.h"

        /* 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 2: 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 portBASE_TYPE 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 3: The C portion of an ISR that can cause a context switch

Some notes on the C function:

See the full UART interrupt handler within the PIC32 demo application for a complete example - note however that, as downloaded, the UART driver is intended to generate lots of interrupts (with the intention of testing the robustness of the MIPS port) and should therefore not be regarded as an optimal solution.


Critical sections

Exiting 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.org API functions themselves will use critical sections.


Execution context

Inline with the conventions documented in the C32 manual, the RTOS kernel assumes all access to the K0 and K1 registers will be atomic. Code generated by the C32 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 this too conforms to the same convention.


Shadow registers

The 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.


Switching between the pre-emptive and co-operative real time kernels

Set the definition configUSE_PREEMPTION within FreeRTOS/Demo/PIC32_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 options

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.


Memory allocation

Source/Portable/MemMang/heap_2.c is included in the PIC32 demo application project to provide the memory allocation required by the real time kernel. Please refer to the Memory Management section of the API documentation for full information.


Serial port driver

It 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.


Buy PIC32 starter kits from the FreeRTOS.org shop!




Copyright (C) 2003 - 2008 Richard Barry
Any and all data, files, source code, html content and documentation included in the FreeRTOS distribution or available on this site are the exclusive property of Richard Barry. See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Richard Barry.