This page provides information about running Nios II Linux on Stratix IV GX FPGA Development Kit (4SGX230 board).

Please refer to NiosII Linux User Manual on how to download and compile Linux components.

Configure FPGA with a Nios II MMU design

You will need Altera tools to configure the FPGA on the 4SGX230 board. Download and install the tools from Altera .
Download the Nios II MMU design for 4SGX230 board from Nios II with Memory Management Unit (MMU) Design Example

The SOF file is available in niosii-mmu-4sgx230-qsys folder. Configure FPGA with the following command:

nios2-configure-sof ghrd_4sgx230.sof

To boot Nios II Linux from CFI Flash

This flow allows you to boot Linux kernel with root file system, DTB and U-boot from CFI flash.

Go to Linux top directory and configure Linux kernel for Nios II to compile Linux kernel with root file system:

make menuconfig 

Select the option : General setup → Initial RAM filesystem and RAM disk (initramfs/initrd) support.
Next, enter the path "../buildroot/output/images/rootfs.cpio" under General setup → Initramfs source file(s).
Save and exit.

To build:

make vmImage

Output file name : vmImage
Output directory : <Linux_kernel_top_directory>/arch/nios2/boot

You will need Altera tools to program the CFI on the 4SGX230 board. Download and install the tools from Altera.
First, you need to convert the boot images to SREC format(.flash file) before you can use the nios2-flash-programmer to program to CFI flash.
You will also need to determine the location of boot images in the CFI flash address map. Based on the Nios II MMU hardware design, we will use the following address map with CFI base address at 0x0 and CPU reset address at 0x02800000. U-Boot is the first boot image and will need to be program to the CPU reset address.

Offset	Content
0x00200000	DTB
0x00300000	Linux kernel with build in root file system
0x02800000	U-Boot

To convert the following files to SREC format:

bin2flash --input=4sgx230_devboard.dtb --output=4sgx230_devboard.flash --location=0x00200000
bin2flash --input=vmImage --output=vmImage.flash --location=0x00300000
elf2flash --base=0x0 --end=0x03FFFFFF --boot=<Altera_ACDS_installation_path>/ip/altera/nios2_ip/altera_nios2/boot_loader_cfi.srec
--reset=0x02800000 --input=u-boot --output=u-boot.flash

If you are using dual-die flash board, the 2nd CFI flash is located at 0x2000000.
elf2flash --base=0x2000000 --end=0x03FFFFFF --boot=<Altera_ACDS_installation_path>/ip/altera/nios2_ip/altera_nios2/boot_loader_cfi.srec
--reset=0x02800000 --input=u-boot --output=u-boot.flash

To use the nios2-flash-programmer :

nios2-flash-programmer --base=0x0 --mmu 4xgx230_devboard.flash
nios2-flash-programmer --base=0x0 --mmu vmImage.flash
nios2-flash-programmer --base=0x0 --mmu u-boot.flash

If you are using dual-die flash board, the 2nd CFI flash is located at 0x2000000.
nios2-flash-programmer --base=0x2000000 --mmu u-boot.flash

To boot Nios II Linux : Start nios2-terminal and press CPU reset on board.
U-boot will run and load the Linux kernel from CFI flash by default and you can login as root.

$ nios2-terminal
nios2-terminal: connected to hardware target using JTAG UART on cable
nios2-terminal: "USB-Blaster [USB-0]", device 1, instance 0
nios2-terminal: (Use the IDE stop button or Ctrl-C to terminate)

U-Boot 2013.01.01-00042-g42e7b05-dirty (Sep 15 2014 - 12:53:14)

CPU   : Nios-II
SYSID : 00000000, Mon Jun 30 02:24:29 2014
BOARD : 4SGX230
Net:   ALTERA_TSE-0
Hit any key to stop autoboot:  0
## Booting kernel from Legacy Image at d6000000 …
   Image Name:   Linux-3.15.0-00179-g25deacd-dirt
   Image Type:   NIOS II Linux Kernel Image (gzip compressed)
   Data Size:    3240446 Bytes = 3.1 MiB
   Load Address: d0000000
   Entry Point:  d0000000
   Verifying Checksum … OK
## Flattened Device Tree blob at d5000000
   Booting using the fdt blob at 0xd5000000
   Uncompressing Kernel Image … OK
Linux version 3.15.0-00179-g25deacd-dirty (alterian@localhost.localdomain) (gcc
version 4.7.3 (Sourcery CodeBench Lite 2013.05-43) ) #9 Mon Sep 15 10:01:14 MYT
2014
bootconsole [early0] enabled
early_console initialized at 0xe8004d50
On node 0 totalpages: 32768
free_area_init_node: node 0, pgdat d04d0ca0, node_mem_map d04f35e0
  DMA zone: 256 pages used for memmap
  DMA zone: 0 pages reserved
  DMA zone: 32768 pages, LIFO batch:7
pcpu-alloc: s0 r0 d32768 u32768 alloc=1*32768
pcpu-alloc: [0] 0
Built 1 zonelists in Zone order, mobility grouping on.  Total pages: 32512
Kernel command line: console=ttyJ0,115200 root=/dev/mtdblock0 rootfstype=jffs2 r
w
PID hash table entries: 512 (order: -1, 2048 bytes)
Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)
Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)
Sorting __ex_table...
Memory: 124844K/131072K available (2591K kernel code, 113K rwdata, 520K rodata,
1704K init, 116K bss, 6228K reserved)
NR_IRQS:64
Calibrating delay loop... 74.24 BogoMIPS (lpj=148480)
pid_max: default: 32768 minimum: 301
Mount-cache hash table entries: 1024 (order: 0, 4096 bytes)
Mountpoint-cache hash table entries: 1024 (order: 0, 4096 bytes)
devtmpfs: initialized
NET: Registered protocol family 16
Switched to clocksource timer
NET: Registered protocol family 2
TCP established hash table entries: 1024 (order: 0, 4096 bytes)
TCP bind hash table entries: 1024 (order: 0, 4096 bytes)
TCP: Hash tables configured (established 1024 bind 1024)
TCP: reno registered
UDP hash table entries: 256 (order: 0, 4096 bytes)
UDP-Lite hash table entries: 256 (order: 0, 4096 bytes)
NET: Registered protocol family 1
RPC: Registered named UNIX socket transport module.
RPC: Registered udp transport module.
RPC: Registered tcp transport module.
RPC: Registered tcp NFSv4.1 backchannel transport module.
futex hash table entries: 256 (order: -1, 3072 bytes)
jffs2: version 2.2. (NAND) c 2001-2006 Red Hat, Inc.
msgmni has been set to 243
Block layer SCSI generic (bsg) driver version 0.4 loaded (major 254)
io scheduler noop registered
io scheduler deadline registered
io scheduler cfq registered (default)
ttyAL0 at MMIO 0x8004c80 (irq = 18, base_baud = 9375000) is a Altera UART
ttyJ0 at MMIO 0x8004d50 (irq = 17, base_baud = 0) is a Altera JTAG UART
console [ttyJ0] enabled
console [ttyJ0] enabled
bootconsole [early0] disabled
bootconsole [early0] disabled
loop: module loaded
0.flash: Found 1 x16 devices at 0x0 in 16-bit bank. Manufacturer ID 0x000089 Chi
p ID 0x00891c
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Using buffer write method
Using auto-unlock on power-up/resume
cfi_cmdset_0001: Erase suspend on write enabled
erase region 0: offset=0x0,size=0x8000,blocks=4
erase region 1: offset=0x20000,size=0x20000,blocks=255
2000000.flash: Found 1 x16 devices at 0x0 in 16-bit bank. Manufacturer ID 0x0000
89 Chip ID 0x008919
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Using buffer write method
Using auto-unlock on power-up/resume
cfi_cmdset_0001: Erase suspend on write enabled
erase region 0: offset=0x0,size=0x20000,blocks=255
erase region 1: offset=0x1fe0000,size=0x8000,blocks=4
libphy: altera_tse: probed
altera_tse 8004000.ethernet (unregistered net_device): MDIO bus altera_tse-0: cr
eated
altera_tse 8004000.ethernet: Altera TSE MAC version 14.0 at 0x08004000 irq 4/5
mousedev: PS/2 mouse device common for all mice
TCP: cubic registered
NET: Registered protocol family 17
Freeing unused kernel memory: 1704K (d0289000 - d0433000)
Starting logging: OK
Initializing random number generator... random: dd urandom read with 1 bits of e
ntropy available
done.
Starting network...

Welcome to Nios II
nios2 login:

To boot Nios II Linux from RAM

This flow allows Nios II Linux to boot from RAM without flashing kernel image and DTB to flash.
It doesn't require U-boot hence is useful for debugging or development phase.

Follow these steps in " Building Nios II Linux kernel" section to build your kernel image.

In Linux top directory, launch menuconfig:

make menuconfig

Select the option : Platform options → Compile and link device tree into kernel image.

Enter the path : Platform options → Device tree source file.
Note:

• Example path: arch/nios2/boot/dts/4sgx230_devboard.dts

Save and exit menuconfig.

To build:

make 

Output file name : vmIinux
Output directory : <Linux_kernel_top_directory>

Download kernel image, launch Nios II terminal and boot kernel.

nios2-download -g vmlinux && nios2-terminal

Login as user "root" in Nios II kernel console.

$ nios2-download -g vmlinux && nios2-terminal
Using cable "USB-Blaster [USB-0]", device 1, instance 0x00
Pausing target processor: OK
Initializing CPU cache (if present)
OK
Downloaded 4933KB in 85.1s (57.9KB/s)
Verified OK
Starting processor at address 0xD0000000
nios2-terminal: connected to hardware target using JTAG UART on cable
nios2-terminal: "USB-Blaster [USB-0]", device 1, instance 0
nios2-terminal: (Use the IDE stop button or Ctrl-C to terminate)

Linux version 3.15.0-00179-g25deacd-dirty (alterian@localhost.localdomain) (gcc
version 4.7.3 (Sourcery CodeBench Lite 2013.05-43) ) #10 Mon Sep 15 17:38:32 MYT
 2014
bootconsole [early0] enabled
early_console initialized at 0xe8004d50
On node 0 totalpages: 32768
free_area_init_node: node 0, pgdat d04d0ca0, node_mem_map d04f35e0
  DMA zone: 256 pages used for memmap
  DMA zone: 0 pages reserved
  DMA zone: 32768 pages, LIFO batch:7
pcpu-alloc: s0 r0 d32768 u32768 alloc=1*32768
pcpu-alloc: [0] 0
Built 1 zonelists in Zone order, mobility grouping on.  Total pages: 32512
Kernel command line: debug console=ttyJ0,115200
PID hash table entries: 512 (order: -1, 2048 bytes)
Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)
Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)
Sorting __ex_table...
Memory: 124844K/131072K available (2591K kernel code, 109K rwdata, 520K rodata,
1708K init, 116K bss, 6228K reserved)
NR_IRQS:64
Calibrating delay loop... 74.24 BogoMIPS (lpj=148480)
pid_max: default: 32768 minimum: 301
Mount-cache hash table entries: 1024 (order: 0, 4096 bytes)
Mountpoint-cache hash table entries: 1024 (order: 0, 4096 bytes)
devtmpfs: initialized
NET: Registered protocol family 16
Switched to clocksource timer
NET: Registered protocol family 2
TCP established hash table entries: 1024 (order: 0, 4096 bytes)
TCP bind hash table entries: 1024 (order: 0, 4096 bytes)
TCP: Hash tables configured (established 1024 bind 1024)
TCP: reno registered
UDP hash table entries: 256 (order: 0, 4096 bytes)
UDP-Lite hash table entries: 256 (order: 0, 4096 bytes)
NET: Registered protocol family 1
RPC: Registered named UNIX socket transport module.
RPC: Registered udp transport module.
RPC: Registered tcp transport module.
RPC: Registered tcp NFSv4.1 backchannel transport module.
futex hash table entries: 256 (order: -1, 3072 bytes)
jffs2: version 2.2. (NAND) c 2001-2006 Red Hat, Inc.
msgmni has been set to 243
Block layer SCSI generic (bsg) driver version 0.4 loaded (major 254)
io scheduler noop registered
io scheduler deadline registered
io scheduler cfq registered (default)
ttyAL0 at MMIO 0x8004c80 (irq = 18, base_baud = 9375000) is a Altera UART
ttyJ0 at MMIO 0x8004d50 (irq = 17, base_baud = 0) is a Altera JTAG UART
console [ttyJ0] enabled
console [ttyJ0] enabled
bootconsole [early0] disabled
bootconsole [early0] disabled
loop: module loaded
0.flash: Found 1 x16 devices at 0x0 in 16-bit bank. Manufacturer ID 0x000089 Chi
p ID 0x00891c
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Using buffer write method
Using auto-unlock on power-up/resume
cfi_cmdset_0001: Erase suspend on write enabled
erase region 0: offset=0x0,size=0x8000,blocks=4
erase region 1: offset=0x20000,size=0x20000,blocks=255
2000000.flash: Found 1 x16 devices at 0x0 in 16-bit bank. Manufacturer ID 0x0000
89 Chip ID 0x008919
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Intel/Sharp Extended Query Table at 0x010A
Using buffer write method
Using auto-unlock on power-up/resume
cfi_cmdset_0001: Erase suspend on write enabled
erase region 0: offset=0x0,size=0x20000,blocks=255
erase region 1: offset=0x1fe0000,size=0x8000,blocks=4
libphy: altera_tse: probed
altera_tse 8004000.ethernet (unregistered net_device): MDIO bus altera_tse-0: cr
eated
altera_tse 8004000.ethernet: Altera TSE MAC version 14.0 at 0x08004000 irq 4/5
mousedev: PS/2 mouse device common for all mice
TCP: cubic registered
NET: Registered protocol family 17
Freeing unused kernel memory: 1708K (d0289000 - d0434000)
Starting logging: OK
Initializing random number generator... random: dd urandom read with 1 bits of e
ntropy available
done.
Starting network...

Welcome to Nios II
nios2 login:

How to debug kernel/drivers with GDB

This section talks about how to debug kernel and drivers with GDB command line.
User will use Linux environment to load Linux kernel object file into target board and start GDB while host PC acts as server and connect to it.

First, launch menuconfig in Nios II Linux kernel directory:

make menuconfig

Select the option : Kernel hacking → Compile-time checks and compiler options → Compile the kernel with debug info.
Then re-make the kernel image.

make

Output file name : vmIinux
Output directory : <Linux_kernel_top_directory>

For Host, open Nios II Command Shell and executes below command to define host port number:

nios2-gdb-server –-tcpport <port number> 

Host will open the service and wait for GDB connection.

$ nios2-gdb-server --tcpport 1234
Using cable "USB-Blaster [USB-0]", device 1, instance 0x00
Processor is already paused
Listening on port 1234 for connection from GDB: 60s

In Linux environment, open terminal and execute below command:

nios2-linux-gnu-gdb vmlinux

This will loads kernel and starts GDB enviroment:

[alterian@localhost linux-nios2]$ nios2-linux-gnu-gdb vmlinux
GNU gdb (Sourcery CodeBench Lite 2012.09-115) 7.4.50.20120716-cvs
Copyright (C) 2012 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=nios2-linux-gnu".
For bug reporting instructions, please see:
<https://support.codesourcery.com/GNUToolchain/>...
Reading symbols from /home/alterian/nios2-linux/linux-nios2/vmlinux...done.

Inside GDB server, connect to host with its IP address and port number:

target remote <host IP>:<port number>

Now you can start to debug any statically compiled kernel code or drivers.

(gdb) target remote 137.57.118.36:1234
Remote debugging using 137.57.118.36:1234
0xd7fd481c in ?? ()
(gdb) 

Note:

• GDB commands reference
• GDB supports script files. User can put a file .gdbinit in the source directory containing the line target remote <host IP>:<port number>. This command will be automatically executed whenever GDB starts in this directory.

Debug with Data Display Debugger - GUI for GDB (Optional)

GNU DDD is a graphical front-end user interface for GDB command-line debuggers.

To install:

yum install ddd

Note:

• Additional repo files might be needed for ddd installation. User can refer here for RHEL EPEL Repo.

To run:

ddd -debugger nios2-linux-gnu-gdb vmlinux

Inside DDD gui, connect to host with its IP address and port number:

target remote <host IP>:<port number>

Once connected, you may start to debug with GUI.

How to build hello world app, TFTP to root filesystem

This section will guide user to create a hello world app from scratch, compile code with GNU toolchain, then use TFTP to transfer file from Host (PC) into client (4SGX230 dev kit).

In Linux environment, create a hello.c file with codes as below:

#include <stdio.h>
int main(void)
{   
    printf("Hello from Linux\n");
    return 0; 
} 

Compile using Altera nios2-linux tool chain with debugging information for use by GDB:

nios2-linux-gnu-gcc -ggdb hello.c -o hello

Output file name: hello
Output directory: <same directory as hello.c>
Note:

• Make sure that toolchain setup is done prior to compilation; you may refer to “ Setting up toolchain” section for more info.

Setup 4SGX230 board with a valid Ethernet connection and follow these steps in " To boot Nios II Linux from CFI flash" section to build your kernel image and boot linux kernel.
After boot into kernel, log in as root and execute below commands to setup Ethernet port:

ifconfig eth0 up
udhcpc eth0

Once the setup is done, you may start TFTP file transfer.

Welcome to Nios II
nios2 login: root
# ifconfig eth0 up
# udhcpc
udhcpc (v1.21.1) started
grep: /etc/resolv.conf: No such file or directory
Sending discover...
Sending select for 137.57.118.128...
Lease of 137.57.118.128 obtained, lease time 86400
deleting routers
route: SIOCDELRT: No such process
adding dns 137.57.116.2
adding dns 137.57.137.2
adding dns 137.57.64.1
#

In your host PC, download TFTP from this link and install.
Set your Linux “shared folder” as TFTP directory then copy hello file into it.
Use below command to transfer your file.

# tftp -g <host IP address> -r hello

Change “hello” file mode to grant permission to run it in client.

# chmod 744 hello
# ./hello
Hello from Linux

Note:

• User may need to disable PC firewall setting for TFTP software.

How to debug user application program

This section describes on GDB remote debug session with user space program through ethernet/tcp. We will use hello world app that was build in previous section " How to build hello world app, TFTP to root filesystem" as an example.

Copy "gdbserver" from toolchain directory (toolchain top directory/nios2-linux-gnu/libc/usr/lib/bin) and TFTP to target board.

In Nios II Linux, run below command to check target board ip address:

ifconfig eth0

Target board address is shown as 192.168.106.175.

# ifconfig eth0
eth0      Link encap:Ethernet  HWaddr 0E:4A:7A:81:69:58
          inet addr:137.57.118.128  Bcast:137.57.118.255  Mask:255.255.255.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:15003 errors:0 dropped:724 overruns:0 frame:0
          TX packets:573 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:1844808 (1.7 MiB)  TX bytes:26964 (26.3 KiB)
          Memory:8004000-80043ff

To run gdbserver on Nios II Linux, execute below command with target board ip address and an unused port:

./gdbserver -–remote-debug <target IP>:<port number> <ELF file> 

Nios II Linux will wait for connection from GDB debugger:

# # ./gdbserver --remote-debug 137.57.118.128:1234 hello
Process hello created; pid = 774
Listening on port 1234

Then, run GDB to debug from your Linux host environment.

nios2-linux-gnu-gdb <ELF file>

In GDB console:

target remote <target IP>:<port number>

Note: Note:

• GDB commands reference
• GDB supports script files. User can put a file .gdbinit in the source directory containing the line target remote <target IP address>:<port number>. This command will be automatically executed whenever GDB starts in this directory.

Use DDD to debug (Optional)

GNU DDD is a graphical front-end user interface for GDB command-line debuggers.

To install:

yum install ddd

Run DDD from your Linux host environment:

ddd –debugger nios2-linux-gnu-gdb <ELF file>

In DDD console:

target remote <target IP>:<port number>

Note:

• Additional repo files might be needed for ddd installation. User can refer here for RHEL EPEL Repo.

U-boot config files

Add the following files containing 4SGX230 board information to the U-boot project:
4sgx230_fpga.h to board/altera/nios2-generic
4sgx230.h to include/configs
boards.cfg to top level directory

Workaround for SIV SGMII TSE

This section describes the workaround needed for SGMII TSE.

1. Set the PCS PHY ID to non-zero in the TSE IP in Qsys.

2. In linux-socfpga/drivers/net/ethernet/altera/altera_tse_main.c, apply the following temporary workaround in altera_tse_mdio_read().

Change &mac→mdio_phy0 to &mac→mdio_phy1

Change &mac→mdio_phy0_addr → &mac→mdio_phy1_addr