1. Overview

1.1 Prerequisites

The following items are required in order to be able to fully exercise the Zephyr RTOS in the Nios V processor:

• Intel FPGA development kit that supports Nios V processor
• Host PC with
• Linux - Ubuntu 22.04 was used to create this design example, other versions, and distributions may work too
• Intel Quartus Prime Pro Edition
• v23.1 was used for the binary release
• v23.1 was used for rebuilding
• Zephyr SDK v0.15.2
• optionally, Ashling RiscFree IDE for Intel FPGA v23.1 (Cross-compiler). More information about the installation can be found here.

Note that the Zephyr build flow is supported in Ubuntu, macOS, and Windows. Please refer to Zephyr - Getting Started Guide for more info.

1.2 Release Contents

1.2.1 Boot from On-Chip Memory

The release files are developed based on 2. Design Architecture. If the exact design architecture is met, they are compatible with any Nios V/g processor system.
For example, the steps in 4. Building Nios V Zephyr Design below is based on Intel Arria 10 SoC Development Kit.
They are accessible at https://releases.rocketboards.org/2023.03/zephyr/niosv_zephyr/niosv_g/hello_world/ and consist of the following:

Item	Description
zephyr.bin	Final Zephyr binary in BIN format
zephyr.dts	Final Zephyr devicetree
zephyr.dts.d	Directory list of DTS and DTSI
zephyr.dts.pre	Pre-processed Zephyr DTS source
zephyr.elf	Final Zephyr binary in ELF format
zephyr.lst	Disassembly file of the final Zephyr binary
zephyr.map	Final Zephyr binary partitions map
zephyr_pre0.elf	Unfixed size Zephyr binary in ELF format
zephyr_pre0.map	Unfixed size Zephyr binary partitions map
zephyr_pre1.elf	Zephyr binary in ELF format
zephyr_pre1.map	Zephyr binary partition map
zephyr_final.map	Final Zephyr binary partitions map
zephyr.stat	Zephyr statistics for maintenance and troubleshooting

1.3 Release Branches and Commit IDs

Component: Zephyr Kernel
Location: github.com/altera-opensource/zephyr-socfpga

Kernel Version	Processor IP Version	Software Version	Branch	Commit ID/Tag
3.2.0	22.4.3	Intel Quartus Prime Pro Edition: 23.1 Ashling RiscFree IDE for Intel FPGA: 23.1 Zephyr SDK: 0.15.2	socfgpa_v3.2	abdef073269bd25c7c6617c37154a5d5a79d9cdb

2. Design Architecture

2.1 Hardware Architecture

The Nios V processor system consists of the following components:

• Nios V/g Processor FPGA IP
• On-Chip Memory (RAM) Intel FPGA IP
• JTAG UART Intel FPGA IP

2.1.1 Nios V/g Processor Address Maps

This section presents the processor system address maps.

Peripheral	Address Offset	Size (Bytes)	Attribute
ram	0x0	256 KB	256KB of FPGA On-Chip RAM
cpu.dm_agent	0x80000	64 KB	Processor Debug Module
cpu.timer_sw_agent	0x90000	64 B	Processor Timer and Software Interrupt Module
jtag_uart	0x90078	8 B	JTAG UART IP

3. Running Design with Pre-Built Binaries

3.1 Board Configuration

The SOF image contains the FPGA configuration bitstream.

1. Configure MSEL[2:0] pins of the development kit to JTAG. (For Intel Arria 10 SoC Development Kit, MSEL[2:0] is SW4[4:2]. And set it as JTAG [OFF-OFF-OFF].)

2. Power cycle the board.

3. Navigate to the folder that contains top.sof.

4. Configure the image using the following commands:

~/intelFPGA_pro/23.1/niosv/bin/niosv-shell
quartus_pgm -c 1 -m JTAG -o p\;top.sof@1

3.2 Download Zephyr Application

The ELF file contains the Zephyr application.

1. Navigate to the folder that contains toggle_issp.tcl (if using the Intel Design Store example design).
2. Reset the Nios V processor system after the configuration is completed (if using the Intel Design Store example design).

quartus_stp -t toggle_issp.tcl

3. Navigate to the folder that contains zephyr.elf.
4. Download the ELF file using the niosv-download command. Alternatively, you can use the Ashling RiscFree IDE or Zephyr SDK.

~/intelFPGA_pro/23.1/niosv/bin/niosv-shell
niosv-download -c 1 zephyr.elf

3.3 Display Hello World Message

1. Navigate to the folder that contains toggle_issp.tcl (if using the Intel Design Store example design).
2. Reset the Nios V processor system after the configuration is completed (if using the Intel Design Store example design).

quartus_stp -t toggle_issp.tcl

3. Run juart-terminal to display the Hello World message on the console.

juart-terminal -c 1

3.4 Running The Application using Ashling RiscFree IDE (Optional)

An alternative method of running zephyr.elf application can be achieved by using the Ashling RiscFree IDE tool. You can follow the steps below:

1. Make sure to configure the FPGA as mentioned in step 3.1.
2. Once the IDE is open, go to the Run menu tab, and Select Run Configuration.

3. From Run Configuration, select Ashling RISC-V (auto-detect) Hardware Debugging, a New_Configuration tab will be created.

4. In the Main tab, choose your C/C++ Application by browsing to the location where you store the zephyr.elf file.

5. In the Debugger tab, make sure your board is selected, and Nios V is seen in the Core selection.

6. Click Apply to save the run configuration, then click Run.
7. In IDE Console view, you should see the debugger information as seen in the snapshot below.

7. Open Nios V Command Shell, and run juart-terminal command, Nios V should print the "Hello World" message.

3.5 Debugging Hello World Application

Refer to Zephyr - Application Debugging and Zephyr - Debug with Eclipse for more info.

4. Building Nios V Zephyr Design

4.1 Hardware Build Flow

There are available design examples in the Intel FPGA Design Store.
For this guide, we will use the Intel® Arria® 10 FPGA - Nios® V/g Processor based Hello World.
You may download the following design examples for different development kits. They are also compatible with the pre-built zephyr.elf.

• Intel® Stratix® 10 FPGA - Nios® V/g Processor based Hello World
• Intel Agilex® 7 FPGA - Nios® V/g Processor based Hello World

4.1.1 Nios V Processor Hello World Example Design

1. Download Intel® Arria® 10 FPGA - Nios® V/g Processor based Hello World for version 23.1.0 Pro.
2. Open the provided project PAR file.

The relevant files from the project PAR file are:

File	Description
script/toggle_issp.tcl	TCL script to reset the design via In-System Sources and Probes
hw/sys.qsys	Platform Designer system file for Nios V Hello World example design
ready_to_test/top.sof	Intel FPGA configuration file

4.1.2 Building a New Processor System

Alternatively, the hardware system can be built from scratch to understand the development process. Using Intel Arria 10 SoC development kit:

1. Start a new project as "top".
2. Select the Device Name "10AS066N3F40E2SG".
3. Construct the Platform Designer system as below, and name it "top.qsys".

4. Configure each IP accordingly,

IP Block	Settings
Clock Bridge Intel FPGA IP	Input clock frequency of 50MHz
Reset Bridge Intel FPGA IP	"Active low reset" option is ON
Nios V/g Processor FPGA IP	- "Enable Debug" option is ON - On-Chip Memory Intel FPGA IP as Reset Agent
On-Chip Memory (RAM) Intel FPGA IP	256KB of FPGA on-chip RAM
JTAG UART Intel FPGA IP	Interrupt number 0

5. You will need to perform ONLY ONE of the following options,

• Modify the processor system to have the exact address mapping shown below (recommended), or
• Reflected the new address mapping to the board DTS file (boards/riscv/niosv_g/niosv_g.dts) after cloning zephyr-socfoga-dev repo.

Peripheral	Address Offset	Size (Bytes)	Attribute
ram	0x0	256 KB	256KB of FPGA On-Chip RAM
cpu.dm_agent	0x80000	64 KB	Processor Debug Module
cpu.timer_sw_agent	0x90000	64 B	Processor Timer and Software Interrupt Module
jtag_uart	0x90078	8 B	JTAG UART IP

6. After generating HDL files, assign the exported pins:

• clk as PIN_AN18 (50MHz clock source)
• reset_n as PIN_AV21 (Active low reset input)

Note: With reset_n as PIN_AV21, "quartus_stp -t toggle_issp.tcl" is not needed to reset the processor system.

7. Define the SDC file with the constraint below, and named it "top.sdc".

create_clock -name clk -period 20.0 [get_ports clk]

8. Compile the project to get the design SOF file.

The relevant files created are:

File	Description
top.qsys	Platform Designer system file for Nios V Hello World example design
output_files/top.sof	FPGA configuration file

4.2 Software Build Flow

The following Zephyr RTOS build commands are for Ubuntu OS.
Refer to Zephyr - Getting Started Guide for a how-to guide on generating the Zephyr RTOS in macOS or Windows OS.

4.2.1 Tools Installation and Setup

To set up the Zephyr development environment on Ubuntu, please perform the installation accordingly.

1. Refer to Zephyr - Select and Update OS to update your operating system.
2. Refer to Zephyr - Install Dependencies to install host dependencies.
3. Setup the Zephyr project, and clone zephyr-socfpga repo.

$ sudo apt install python3-venv
$ python3 -m venv ~/zephyrproject/ .venv
$ source ~/zephyrproject/.venv/bin/activate
$ pip install west
$ git clone https://github.com/altera-opensource/zephyr-socfpga.git ~/zephyrproject/zephyr
$ west init -l ~/zephyrproject/zephyr
$ cd ~/zephyrproject
$ west update
$ west zephyr-export
$ pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

4. Refer to Zephyr - Install Zephyr SDK to install Zephyr SDK. Note that, please change the SDK version to 0.15.2.

4.2.2 Setup Environment Variables

$ export ZEPHYR_BASE=$HOME/zephyrproject/zephyr
$ export ZEPHYR_SDK_INSTALL_DIR= <Zephyr SDK installation path or $HOME>/zephyr-sdk-0.15.2

Note: The default toolchain is based on the riscv64-zephyr-elf binaries in Zephyr SDK.
For cross-compilers such as Ashling RiscFree IDE for Intel FPGA, please run the commands below.

$ export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
$ export CROSS_COMPILE=<RiscFree IDE installation path>/riscfree/toolchain/riscv32-unknown-elf/bin/riscv32-unknown-elf-

For more information, please refer to Zephyr - Other Cross Compile.

4.2.3 Application Build Flow

$ cd $HOME
$ cd zephyrproject/zephyr/samples/hello_world
$ mkdir build && cd build
$ cmake -DBOARD=niosv_g ..
$ make

For custom applications, please refer to Zephyr - Application Development.

The relevant files created in the samples/hello_world/build/zephyr folder are:

File	Description
zephyr.elf	Final Zephyr binary in ELF format