Philips LPC2129 (ARM7) RTOS Port
for the Keil Development Tools
[RTOS Ports]

Buy NXP prototyping boards from
the FreeRTOS.org shop!

There are currently four FreeRTOS ports for the Philips LPC2000 ARM7 based embedded microcontroller. This page relates only to the Keil port. Both ARM and THUMB modes are supported.

Please note: The port requires the Keil DKARM compiler version 1.5 or later. This port has not yet been updated for the new ARM owned version of the Keil tools and will therefore not compile with the latest uVision tools. Contact me if you are interested in receiving a port that uses the new tools.

The port was developed on an MCB2100 development/prototyping board (instructions are provided should you wish to use an alternative development board) using a ULINK USB JTAG adapter. The Keil simulator also proved very useful. A complete development kit can be obtained from Hitex Development Tools.

The MCB2100 is a fully featured and comprehensive prototyping board that allows easy access to the LPC2129 peripherals and includes 8 built in LEDs which are utilised by the FreeRTOS demo application.

The development tools include a compiler, assembler and linker tool chain along with an IDE and excellent device specific simulator. The simulator includes a 'logic analyzer' feature that can be used to monitor the microcontroller IO - providing the same visual feedback in the simulated environment that the LEDs do on the real target hardware.

The demo applications can be built and simulated using the generous and non time limited Keil development tools evaluation version [V1.5 or higher required].

As downloaded this demo application does not demonstrate the use of co-routines. See the co-routine documentation page for information on how co-routine functionality can be quickly added to this demonstration.

IMPORTANT! Notes on using the Keil LPC2129 RTOS port

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

Source Code Organisation
The Demo Application
Configuration and Usage Details

Source Code Organisation

The FreeRTOS download contains the source code for all the FreeRTOS ports. See the Source Code Organization section for a description of the downloaded files and information on creating a new project.

Two sample projects are included for the Keil ARM7 port. Both are contained in the Demo/ARM7_LPC2129_Keil directory.

The 'rtosdemo_ARM' project operates in ARM mode only.
The 'rtosdemo_THUMB' project demonstrates ARM / THUMB interworking.

The Demo Application

The FreeRTOS source code download includes a fully preemptive multitasking demo application for the Keil LPC2000 RTOS port.

Functionality

The demo applications can be built using the Keil development tools evaluation version - which has a file size limit of 16K bytes. ARM code generates larger executables than THUMB code, so consequently the ARM mode demo creates fewer tasks in order to fit within this size limit.

For the purpose of test coverage the THUMB mode demo is supplied with full optimisation, and the ARM mode demo with minimal optimisation. Increasing the optimisation level of the ARM mode demo decreases the generated executable size, allowing more tasks to be added.

The THUMB demo generates 25 tasks.
The ARM demo generates 8 tasks.

When executing correctly the demo application will behave as follows:

LEDs P1.16, P1.17 and P1.18 are under control of the 'flash' tasks. Each will flash at a constant frequency, with LED P1.16 being the slowest and LED P1.18 being the fastest (see the logic analyzer screen capture below).
LED P1.19 will flash each time a character is transmitted on the serial port.
LED P1.20 will flash each time a character is received on the serial port.
Not all the tasks update an LED so have no visible indication that they are operating correctly. Therefore a 'Check' task is created whose job it is to ensure that no errors have been detected in any of the other tasks.
LED P1.23 is under control of the 'Check' task. Every three seconds the 'Check' task examines all the tasks in the system to ensure they are executing without error. It then toggles LED P1.23. If LED P1.23 is toggling every three seconds then no errors have ever been detected. The toggle rate increasing to 500ms indicates that the 'Check' task has discovered at least one error. This mechanism can be checked by removing the loopback connector from the serial port (described below), and in doing so deliberately generating an error.

See the demo application section for details of the individual tasks.

Demo application hardware setup

The demo application includes tasks that send and receive characters over the serial port. The characters sent by one task need to be received by another - if any character is missed or received out of sequence an error condition is flagged. A loopback connector is required on the serial port for this mechanism to operate (simply connect pins 2 and 3 together on the P2 serial port connector of COM 0).

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

Building the demo application

Simply open the required project file from within the Keil IDE (uVision3) then select 'Built Target' from the IDE 'Project' menu. The application should build with no errors or warnings.

Running the demo application

The demo application can be executed in the simulator or on the target hardware. To switch between the simulator and JTAG debugger:

Right click on the FreeRTOS target within the 'Project Workspace' pane - depicted below.
From the resultant pop up menu select 'Options for Target FreeRTOS'.
A pop up window will appear. Select the 'Debug' tab.
Use the radio buttons to switch between the simulator and JTAG debugger - depicted below.

Using the simulator and logic analyzer

The microcontroller IO ports can be monitored using the simulators 'logic analyzer' feature. Below is a screen capture of the logic analyzer being used to monitor certain output pins while the demo application is being simulated.

The red green and blue lines show pins P1.16, P1.17 and P1.18 respectively under control of the 'Flash' tasks. The black line shows pin P1.19 which is toggled each time a character is transmitted. You would need to zoom much closer in to see the line being toggled for each individual transmitted character.

When being simulated the 'Check' task will find an error in the 'ComTest' tasks. This is because the 'ComTest' tasks require a loopback connector as described previously.

Programming the flash

The demo application can be programmed into the microcontroller flash from within the Keil IDE using the 'Flash' menu item. The prototyping board must be reset to start the program executing.

The flash must be programmed before the JTAG debugger can be used.

Configuration and Usage Details

RTOS Port specific configuration

Configuration items specific to this port are contained in Demo/ARM7_LPC2129_Keil/FreeRTOSConfig.h. The constants defined in this file can be edited to suit your application. In particular - the definition configTICK_RATE_HZ is used to set the frequency of the RTOS tick. The supplied value of 1000Hz is useful for testing the kernel functionality but is faster than most applications require. Lowering this value will improve efficiency.

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

An interrupt service routine that does not cause a context switch has no special requirements and can be written as per the normal Keil syntax. For example:

    static void vAnISR( void ) __irq
    {
        /* ISR C code goes here. */
    }

Special syntax is required if you wish your interrupt service routine to cause a context switch:

Declare the ISR using the __task key word. This prevent the compiler from generating any function prologue or epilogue code.
The first statement in the ISR must be a call to the portENTER_SWITCHING_ISR() macro. This must be before any local variable declarations.
The last statement in the ISR must be a call to the portEXIT_SWITCHING_ISR( bool ) macro. A boolean is passed to the macro to indicate whether a context switch is required or not.
All function scope variables must be declared static.

For example:

    void vASwitchCompatibleISR( void ) __task
    {
        /* Macro must be called first. */
        portENTER_SWITCHING_ISR();

        /* Variable declarations can come next - must be static. */
        static portLONG lSwitchRequired = 0L;

        /* This variable is static so will only initialise on
        startup so must be initialised explicitly. */
        lSwitchRequired = 0L;
        


        /* ISR code comes here.  If the ISR wakes a task then
           lSwitchRequired should be set to 1. */



        /* Final statement is the closing macro. */
        portEXIT_SWITCHING_ISR( lSwitchRequired );
    }

See vUART_ISR() defined in Demo/ARM7_LPC2129_Keil/serial/serial.c for a full example.

To use a part other than an LPC2129

The LPC2129 uses a standard ARM7 core with processor specific peripherals. The core real time kernel components should be portable across all ARM7 devices - but the peripheral setup and memory requirements will require consideration. Items to consider:

prvSetupTimerInterrupt() in Source/portable/Keil/ARM7/port.c configures the LPC2129 timer 0 to generate the RTOS tick.
Port, memory access and system clock configuration is performed by prvSetupHardware() within Demo/ARM7_LPC2129_Keil/main.c.
The interrupt service routine setup and management assume the existence of the vectored interrupt controller.
The serial port drivers.
Register location definitions are provided the file lpc21xx.h which is included at the top of Demo/ARM7_LPC2129_Keil/FreeRTOSConfig.h.
Startup code, memory map and vector table setup is contained within Demo/ARM7_LPC2129_Keil/Startup.s.
RAM size - see Memory Allocation below.

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

Set the definition configUSE_PREEMPTION within Demo/ARM7_LPC2129_Keil/FreeRTOSConfig.h to 1 to use pre-emption or 0 to use co-operative.

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 project file - as described in the Source Organization section.

Execution Context

The scheduler executes in supervisor mode, tasks execute in system mode.

NOTE! : The processor MUST be in supervisor mode when the scheduler is started (vTaskStartScheduler is called). The demo applications included in the FreeRTOS.org download switch to supervisor mode prior to main being called. If you are not using one of these demo application projects then ensure Supervisor mode is entered before calling vTaskStartScheduler().

Interrupt service routines always run in ARM mode. All other code will run in either ARM or THUMB mode depending on the build. It should be noted that some of the macros defined in portmacro.h can only be called from ARM mode code, and use from THUMB code will result in a compile time error.

Demo/ARM7_LPC2129_Keil/Startup.s configures stacks for system/user, IRQ and SWI modes only.

SWI instructions are used by the real time kernel and can therefore not be used by the application code.

Memory allocation

Source/Portable/MemMang/heap_2.c is included in the ARM7 demo application makefile 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 optimised solution.

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. FreeRTOS^TM and FreeRTOS.org^TM are trade marks of Richard Barry.

Philips LPC2129 (ARM7) RTOS Port for the Keil Development Tools [RTOS Ports]