Nios Ii Embedded Design Suite Legacy Tools

KERNEL

WHAT'S NEW

FreeRTOS:

November 2021 release includes Cellular Interface library and improved MPU support, see blog post

FreeRTOS LTS:

LTS libraries are now included in our partner toolchains, see blog post

FreeRTOS:

FreeRTOS adds reference implementations for SMP, see blog post

FreeRTOS:

July 2021 release now includes the SNTP library, see blog post.

AWS Reference Integrations:

See our latest 202107.00 release's blog post.

Altera Nios II FreeRTOS Demo
Running on a Cyclone III FPGA
[RTOS Ports]

This demo was developed on a DBC3C40 reference design from EBV Elektronik - based on an Altera Cyclone III FPGA.

The FPGA and software can be configured and compiled using the free web edition of Quartus II and the Nios II Embedded Design Suite.

Note that this port was originally written using a pre-version 9 version of the design tools. Calvin Ruben has been good enough to keep the project up to date, and posted a version to the FreeRTOS Interactive pages that is compatible with both version 9.1 and version 10 of the Altera tools. On behalf of the FreeRTOS community I would like to thank Calvin for his contribution.

IMPORTANT! Notes on using the Altera Nios II Demo

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

Source Code Organisation
The Demo Application
RTOS Configuration and Usage Details

See also the FAQ My application does not run, what could be wrong?

Source Code Organisation

The Nios II IDE project file is located in the FreeRTOS/Demo/NiosII_CycloneIII_DBC3C40_GCC directory. This is the directory to select when importing the project into your IDE workspace.

The FreeRTOS zip file download contains the files for all the ports and demo application projects. It therefore contains many more files than 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 Demo Application

Creating the project directory structure

The Nios II IDE is a customised version of Eclipse. The easiest way to use an Eclipse managed make build is to locate the required build files (C source files, header files and linker scripts) under the directory that contains the Eclipse project file. The FreeRTOS download contains a batch file called CreateProjectDirectoryStructure.bat that will copy all the required build files from their normal locations within the FreeRTOS directory structure to sub directories under the Eclipse project directory. The batch file is located in the FreeRTOS/Demo/NiosII_CycloneIII_DBC3C40_GCC directory and must be executed prior to importing the project into the Nios II IDE.

Execute CreateProjectDirectoryStructure.bat from either a command prompt or Windows explorer. It cannot be executed successfully from within the Eclipse environment itself.

Note! CreateProjectDirectoryStructure.bat must be executed before the demo project is imported into the Nios II IDE, otherwise the include paths stored within the project will be destroyed.

Importing the project into the Nios II IDE workspace

Note! CreateProjectDirectoryStructure.bat must be executed before the demo project is imported into the Nios II IDE. Instructions are provided above.
Start the Nios II IDE. As it starts up you may be prompted for a workspace location. You can use your existing workspace or create a new one in a convenient directory.
Within the Nios II IDE, select 'Import...' from the 'File' menu.
A dialog box will appear. Select 'Existing Projects Into Workspace', then click 'Next'.
Browse to and select the FreeRTOS/Demo/NiosII_CycloneIII_DBC3C40_GCC directory. The directory contains two projects - one called RTOSDemo and the other called RTOSDemo_syslib.
Ensure both projects are selected and that the 'Copy projects into workspace' check box is not selected before completing the import process.

Importing the FreeRTOS projects into the Nios II IDE workspace

Demo Application Hardware Setup

The CD that accompanies the DBC3C40 reference design includes a selection of .sof files that implement various different Nios II configurations. The demo presented on this page was developed using TFT.sof.

The demo uses the LEDs built onto the DBC3C40 itself. The functions that control the LEDs are implemented within FreeRTOS/Demo/NiosII_CycloneIII_DBC3C40_GCC/RTOSDemo/ParTest/ParTest.c These functions may require modification if a hardware platform with a different IO configuration is being used.

The demo includes the 'ComTest' tasks where one task transmits characters on a UART that are then received by another task. An error is latched if any characters are received out of sequence or are simply missing. A loopback connector must be fitted to the UART for the mechanism to work - simply connect the UART Rx pin to the UART Tx pin.

Building and executing the demo application

Open main.c and search for a line that starts "#error". Delete the line (it provides instructions on setting up the directory structure for those using the project without first reading these instructions).
Connect the target hardware to the host computer using a programming and debug interface - an Altera USB Blaster is suitable for this purpose.
To build the project, simply select 'Build All' from the 'Project' menu. The application should build with no errors or warnings (assuming the #error statement has been removed and CreateProjectDirectoryStructure.bat has been executed). The initial build will take some time as it generates the entire system library.
A launch configuration needs to be created before a debug session can be started. This only needs to be done once, after it has been created debug sessions can be started simply by clicking the 'Debug' speed button. To create a launch configuration, first select the 'RTOSDemo' project within the IDE Projects window, then select 'Debug...' from the 'Run' menu.
In the dialog box that opens, double click where it says 'Nios II hardware' to create a new configuration. The configuration parameters will be set automatically.
Finally click 'Debug' to program the MCU and start a debug session.

The first download attempt will cause the Nios II IDE to automatically open the Quartus II programmer, from where a .sof file can be opened and programmed into the FPGA. Once the .sof file has been downloaded the debug speed button can be clicked to re-run the debug launch configuration. This is only necessary the first time after the FPGA has been powered up.

Setting up the launch configuration

Functionality

The demo application creates 43 tasks prior to starting the RTOS scheduler. These tasks consist mainly of the standard demo application tasks (see the demo application section for details of the individual tasks). Their only purpose is to test the RTOS kernel port and provide a demonstration of how to use the various API functions.

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

Check task
This only executes every five seconds. Its main function is to check that all the standard demo tasks are still operational. The Check task will toggle LED 7 every 5 seconds provided all the tasks in the system are executing without error. The toggle rate increasing to 500ms is indicative of an error being reported in at least one task - the name of the offending task will be written to the Nios II IDE terminal. This mechanism can be tested by removing the loop back connector from the UART and in so doing deliberately introducing an error.
Reg Test tasks
The reg test tasks fill the Nios II registers with known values before checking each register contains the value expected. A register containing an unexpected value is indicative of an error in the context switch mechanism. Two reg test tasks are created, with each using a different set of register values.

When executing correctly the demo application will behave as follows:

LEDs 0, 1 and 2 are under the control of the standard 'flash' tasks. Each will toggle at a different but fixed frequency.
LEDs 4 and 5 are under the control of the ComTest tasks - one will toggle each time a character is transmitted and the other each time a character is correctly received.
LED 7 is under the control of the Check task (as described above). It will toggle every 5 seconds.

RTOS Configuration and Usage Details

RTOS port specific configuration

Configuration items specific to these demos are contained in FreeRTOS/Demo/NiosII_CycloneIII_DBC3C40_GCC/RTOSDemo/FreeRTOSConfig.h. The constants defined in this file can be edited to suit your application. In particular configTICK_RATE_HZ which 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.

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 routines

The interrupt entry point is contained within the RTOS kernel port layer itself (within FreeRTOS/Source/portable/GCC/Nios II/port_asm.S) and is written to be compatible with the Altera HAL. This means interrupt service routines can be written in accordance with the Altera HAL documentation, and can be registered using the standard HAL alt_irq_register() function.

Sometimes it is desirable for an interrupt service routine to interrupt one task, but return to another. This would be the case if the interrupt service routine caused a task to unblock, and the unblocked task had a priority higher than the currently executing task. The macro portEND_SWITCHING_ISR() is provided to allow an interrupt service routine to request a context switch - pass zero to portEND_SWITCHING_ISR() if a context switch is not required, or a non-zero value if a context switch is required.

See FreeRTOS/Demo/NiosII_CycloneIII_DBC3C40_GCC/RTOSDemo/serial.c for an example interrupt service routine and an example use of portEND_SWITCHING_ISR().

Memory allocation

Source/Portable/MemMang/heap_2.c is included in the 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.