Xilinx Zynq-7000 (dual core ARM Cortex-A9) SoC Port
Demonstrated on a ZC702 evaluation kit
[RTOS Ports]

Also see the FreeRTOS-Plus-TCP and FreeRTOS-Plus-FAT examples running on a Zynq

This page documents a FreeRTOS demo application for the Xilinx Zynq-7000 SoC, which incorporates a dual core ARM Cortex-A9 processor.

The demo is pre-configured to build with the Xilinx SDK tools (version 2016.1 at the time of writing) and execute on the ZC702 evaluation board.

The project uses the default hardware design and board support package (BSP) shipped with the SDK, and builds FreeRTOS and lwIP as part of the application (rather than part of the BSP).

IMPORTANT! Notes on using the FreeRTOS ARM Cortex-A9 port on the Xilinx Zynq-7000 SoC

1. Source Code Organisation
2. The Demo Application Functionality
3. Build Instructions
4. RTOS Configuration and Usage Details

Source Code Organization

The directory structure used by the demo application is shown and described below. The root CORTEX_A9_Zynq_ZC702 directory is itself located in FreeRTOS/Demo.

CORTEX_A9_Zynq_ZC702
    |
    +-RTOSDemo           Contains the SDK project and C files specific to the demo.
    |
    +-RTOSDemo_bsp       Contains the hardware BSP.
    |
    +-ZC702_hw_platform  The hardware description.

	

• The projects contained in the ZC702_hw_platform and RTOSDemo_bsp directories are the defaults generated by the SDK when the ZC702 is selected as the target hardware for a new project.

• The RTOSDemo directory only contains the source files that are specific to the Zynq demo. The FreeRTOS source files, and the source files that implement tasks that are common to all demo applications, are located elsewhere in the directory tree. Therefore the project will only build when the default directory structure is unchanged. Also see the page that describes how to use virtual and linked paths in the Eclipse project explorer.

The Zynq-7000 SoC Demo Application

Functionality

Functionality with mainSELECTED_APPLICATION set to 0

main_blinky() creates a very simple demo that includes two tasks and one queue. One task repeatedly sends the value 100 to the other task through the queue. The receiving task toggles an LED each time it receives the message. The message is sent every 200 milliseconds, so the LED toggles every 200 milliseconds.

Functionality with mainSELECTED_APPLICATION set to 1

main_full() creates a comprehensive test and demo application that demonstrates:

• The FreeRTOS-Plus-CLI command line interface.
• RTOS objects being created using both statically allocated and dynamically allocated RAM.
• Direct to task notifications.
• Event groups.
• Software timers.
• Queues.
• Semaphores.
• Mutexes.

Most of the tasks created by the demo are from the set of standard demo tasks. These are used by all FreeRTOS demo applications, and have no specific functionality or purpose other than to demonstrate the FreeRTOS API being used and test the RTOS kernel port.

The following tasks are created in addition to the standard demo tasks:

• Register test tasks

  These two tasks test the RTOS kernel context switch mechanism by first filling each Cortex-A9 register (including the floating point registers) with a known and unique value, then repeatedly checking that the value originally written to the register is maintained in the register, for the lifetime of the task. The tasks execute at the lowest possible priority (the idle priority), so are preempted frequently. The nature of these tasks necessitates that they are written in assembly.

• Interrupt nesting test tasks

  Two timers are used to test FreeRTOS queues being used from interrupts that nest to a depth of 3 (including the RTOS tick interrupt). A third timer is configured to generate a 20KHz interrupt at a priority above the maximum system call interrupt priority (the maximum system call interrupt priority is explained on the "Running FreeRTOS on a Cortex-A9" page) - giving a total tested interrupt nesting depth of 4.

  The high frequency timer is also used as a convenient time source for the collection of run-time statistics. The collected statistics can be viewed using the CLI.

• A 'check' task

  The check task periodically queries the standard demo tasks and the register test tasks to ensure they are functioning as intended. The check task also toggles an LED to give a visual indication of the system status. If the LED toggles every 3 seconds then the check task has not discovered any problems with the executing demo. If the LED toggles every 200 milliseconds then the check task has discovered a problem in at least one task..

Functionality with mainSELECTED_APPLICATION set to 2

The lwIP example can be configured to use either a static or dynamic IP address:

• To use a dynamically allocated IP address set LWIP_DHCP to 1 in lwipopts.h and connect the target to a network that includes a DHCP server. The obtained IP address is printed to the UART console.

• To use a static IP address set LWIP_DHCP to 0 in lwipopts.h and set the static IP address using the configIP_ADDR0 to configIP_ADDR3 constants at the bottom of FreeRTOSConfig.h. Constants used to define a netmask are also located at the bottom of FreeRTOSConfig.h. The selected IP address and netmask must be compatible with the network to which the embedded target is to be connected. This can normally be achieved by setting the first three octects of the target's IP address and netmask to match the first three octects of the host computer's IP address and netmask respectively. The chosen IP address must be unique on the network.

When connected correctly the demo uses the lwIP sockets API to create a FreeRTOS-Plus-CLI command console, and the lwIP raw API to create a basic HTTP web server. Server side includes (SSI) are used to generate dynamic data in the served web pages. To connect to the http server simply type the IP address of the target into the address bar of a web browser.

To connect to FreeRTOS-Plus-CLI, open a command prompt and enter "telnet <ipaddr>" where <ipaddr> is the IP address of the target. Once connected type "help" to see a list of registered commands. Note this example does not implement a real telnet server, it just uses the telnet port number to allow easy connection using telnet tools.

Hardware setup

All of the 5-way boot selection switches must be switched to the right hand side when the board is viewed with the integrated Digilent JTAG module on the lower edge. This enables booting via JTAG.

Build Instructions

Importing the demo application project into the SDK Eclipse workspace

1. Select "Import" from the SDK "File" menu. The dialogue box shown below will appear. Select General->Existing Project into Workspace, as shown in the image.
   
   The dialogue box that appears when "Import" is first clicked

   
   

2. In the next dialogue box, select FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702 as the root directory. Then, make sure the RTOSDemo, RTOSDemo_bsp and ZC702_hw_platform projects are 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 all three projects are checked, and "Copy projects into workspace" is not checked

   
   

3. Once all three projects have been imported, the project explorer window of the SDK IDE will appear as below.

   The ZC702_hw_platform and RTOSDemo_bsp projects are dependencies of the RTOSDemo project, so only the RTOSDemo project needs to be built explicitly.

   
   All three projects imported into the workspace

Building the demo application

1. Open the project's main.c file, and set mainSELECTED_APPLICATION to generate the simple blinky demo, the full test and demo application, or the lwIP Ethernet example, as required.

2. Select 'Rebuild All' from the IDE 'Project' menu. The application should build without any errors or warnings.

Starting a debug session

1. Ensure the ZC702 evaluation board is powered up and connected via its on-board Digilent JTAG port to the host computer.

2. Select 'Debug Configurations...' from the IDE's 'Run' menu. The Debug Configurations dialogue box will appear. Double click 'Xilinx C/C++ application (System Debugger)' to create a new debug configuration.

3. Configure the 'Target Setup' tab as shown in the image below.
   
   The required settings on the Target Setup tab

   
   

4. Configure the 'Application' tab as shown in the image below.
   
   The required settings on the Application tab

   
   All the other tabs in the 'Debug Configurations' dialogue can be left with their default settings.

5. Click the "Debug" button to commence debugging. The application will be downloaded to RAM and the debugger will break on entry to main().

RTOS Configuration and Usage Details

FreeRTOS ARM Cortex-A port specific configuration

Configuration items specific to this demo are contained in /FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo/src/FreeRTOSConfig.h. The constants defined in this file can be edited to suit your application.

Interrupt vector table

The vector table defined in FreeRTOS_asm_vectors.S is placed in a linker segment called .freertos_vectors, and the linker script lscript.ld places the .freertos_vectors segment at the beginning of the .text region.

[Application Defined] Interrupt service routines

The Xilinx drivers require interrupt service routines (ISRs) to accept a void * parameter, although the parameter is not always used. The required ISR prototype is therefore:

    void Interrupt_Handler( void *pvUnusedParameter );

If an ISR causes a task of equal or higher priority than the currently executing task to leave the Blocked state then the ISR must request a context switch before the ISR exits. When this is done the interrupt will interrupt one RTOS task, but return to a different RTOS task.

The macros portYIELD_FROM_ISR() (or portEND_SWITCHING_ISR()) can be used to request a context switch from within an ISR. The following source code snippet is provided as an example. The example ISR uses a semaphore to synchronise with a task (not shown), and calls portYIELD_FROM_ISR() to ensure the interrupt returns directly to the task. The prvUART_Handler() and prvTimerhandler() functions already referenced provide further examples.

void Dummy_IRQHandler( void *pvUnusedInThisExample )
{
long lHigherPriorityTaskWoken = pdFALSE;

    /* The parameter is not used in this case. */
    ( void ) pvUnusedInThisExample;

    /* Clear the interrupt if necessary. */
    Dummy_ClearITPendingBit();

    /* This interrupt does nothing more than demonstrate how to synchronise a
    task with an interrupt.  A semaphore is used for this purpose.  Note
    lHigherPriorityTaskWoken is initialised to pdFALSE. */
    xSemaphoreGiveFromISR( xTestSemaphore, &lHigherPriorityTaskWoken );

    /* If there was a task that was blocked on the semaphore, and giving the
    semaphore caused the task to unblock, and the unblocked task has a priority
    higher than or equal to the currently Running task (the task that this
    interrupt interrupted), then lHigherPriorityTaskWoken will have been set to
    pdTRUE internally within xSemaphoreGiveFromISR().  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 );
}

Only FreeRTOS API functions that end in "FromISR" can be called from an interrupt service routine - and then only if the priority of the interrupt is less than or equal to that set by the configMAX_API_CALL_INTERRUPT_PRIORITY configuration constant (meaning a numerically higher value).

Resources used by FreeRTOS

Memory allocation

Miscellaneous