Hello World

Embedded Linux hello world projects examples

This chapter covers the basics of C/C++ embedded Linux projects, including create/build/run/debug embedded Linux applications. The project referred to by this chapter is called “Hello World.” This application prints “Hello World” text and runs a simple for-loop for simple demonstration. The application can also be built and run on QEMU emulator.

Note: To build, run and debug Embedded Linux applications with QEMU emulator, please install the xplor-studio-linux blueprint first. Please refer to Guidelines for more information.

Create a new project

Select File > New > C Project choose RISC-V Embedded Linux Project > Helloworld project and select Embedded Linux XploR Toolchain for RISC-V in the Toolchains box

example image

As the image above, there is no option as Embedded Linux XploR Toolchain for RISC-V because this XploR Studio does not contain Embedded Linux toolchain.

To use this toolchain, please install Embedded Linux toolchain blueprint first. There are 4 different blueprints:

  • RISC-V Embedded Linux toolchain 32-bit: riscv32-xplor-linux
  • RISC-V Embedded Linux toolchain 32-bit (Double): riscv32-xplord-linux
  • RISC-V Embedded Linux toolchain 64-bit: riscv64-xplor-linux
  • RISC-V Embedded Linux toolchain 64-bit (Double): riscv64-xplord-linux

example image

Each blueprint can be downloaded separately depending on the purpose.

Please refer to Guidelines for more information.

After installation and restarting the IDE, you can see the creating-project widget like:

example image

On Ubuntu, LLVM Embedded Linux toolchain is packaged inside the Embedded Linux toolchain that supports Double extension (riscv32-xplord-linux and riscv64-xplord-linux). LLVM Embedded Linux toolchain has not been supported on Windows yet.

For using LLVM Embedded Linux toolchain, please make sure that the RISC-V Embedded Linux toolchain (Double) are installed and select LLVM Embedded Linux Toolchain for RISC-V in the Toolchains box:

example image

Update build settings

The build setting is the same as the quick-start project’s settings. Please refer to Update build settings for more information.

Please make sure that the toolchain used to build is installed, otherwise errors as in the following image will appear:

example image

Build project

The build step is the same as the quick-start project’s step. Please refer to Build project for more information.

To run and debug Embedded Linux applications with QEMU emulator, please install the rootfs blueprint and qemu blueprint (if QEMU is not installed). Please refer to Guidelines for more information.

example image

Running and Debugging project with QEMU emulator

Run project on QEMU emulator

XploR Studio offers several ways to debug applications:

  • Select the project entry in the Project Explorer then open the Run Configuration Dialog. Doing so will enable Eclipse to automatically fill out the necessary run configuration information.

    example image

    On the Run Configuration Dialog, create new run configuration by double clicking on RISC-V Runging:

    example image

    On the Main tab, choose option QEMU in Virtual Platforms. Click Apply then Click Debug.

    example image

  • Select the desired project in the Project Explorer window, then click Run As/RISC-V application with QEMU

    example image

  • Right-click on current project > Run As > RISV-C application with QEMU

    example image

After selecting Run As RISC-V application with QEMU, Console view will print as below image:

example image

Debug project on QEMU Emulator

XploR Studio offers several ways to debug applications:

  • Select the project entry in the Project Explorer then open the Debug Configuration Dialog. Doing so will enable Eclipse to automatically fill out the necessary debug configuration information.

    example image

    On the Debug Configuration Dialog, create new configuration by double clicking on RISC-V Debugging:

    example image

    On tab Debugger, choose option QEMU in Virtual Platforms. Click Apply then Click Debug.

    example image

  • Select the desired project in the Project Explorer window, then click Debug As/RISC-V application with QEMU

    example image

  • Right-click on current project > Debug As > RISV-C application with QEMU

    example image

After selecting Debug As RISC-V application with QEMU, the IDE changes to the debug perspective and automatically sets a breakpoint in the first line of code in the main() function.

example image

Other functions of debugging (such as Resume, Step Into, Step Over, Step Return, Terminate, …) are the same as the quick-start project’s. Please refer to Running and Debugging project with QEMU emulator for more information.

Running and Debugging project with Intel FPGA DE2-115 platform on Ubuntu

Hardware and driver preparations

Please refer to the Hardware and Environment Setup document for more details.

Programming IP core

To program a RISC-V IP core to the board, click on Flash icon example image on the toolbar

example image

  • In the IP Core, select de2115-Vexriscv32.sof or Custom IP core if users use their own RISC-V IP core. In this case, we select de2-115_vexrisc32 for the vexriscv - DE2-115 project.
  • Select JTAG cable (if the user has multiple boards connected to the development machine).
  • Click Finish to flash Vexriscv 32-bit RISC-V core to DE2-115 board.

example image

To view the console output printed from the RISC-V core, open the Terminal view and select COM port (on Windows) or /dev/ttyUSBx port (on Linux) with the following connection settings.

The output message on the serial terminal will look like this:


    _   _           _           ____         ____ 
   | | | |_   _  __| |_ __ __ _/ ___|  ___  / ___|
   | |_| | | | |/ _` | '__/ _` \___ \ / _ \| |    
   |  _  | |_| | (_| | | | (_| |___) | (_) | |___ 
   |_| |_|\__, |\__,_|_|  \__,_|____/ \___/ \____|
          |___/                                   

           Maximize your SoC design!

 (c) Copyright 2020-2023 SoC.One
 (c) Copyright 2012-2023 Enjoy-Digital
 (c) Copyright 2007-2015 M-Labs

 BIOS CRC passed (42b17cce)

 HydraCore git sha1: --------

--=============== SoC ==================--
CPU:            NEORV32 @ 50MHz
BUS:            WISHBONE 32-bit @ 4GiB
CSR:            32-bit data
ROM:            64.0KiB
SRAM:           64.0KiB
SDRAM:          128.0MiB 32-bit @ 50MT/s (CL-2 CWL-2)
MAIN-RAM:       128.0MiB

--========== Initialization ============--
Ethernet init...
Initializing SDRAM @0x40000000...
Switching SDRAM to software control.
Switching SDRAM to hardware control.
Memtest at 0x40000000 (2.0MiB)...
  Write: 0x40000000-0x40200000 2.0MiB     
   Read: 0x40000000-0x40200000 2.0MiB     
Memtest OK
Memspeed at 0x40000000 (Sequential, 2.0MiB)...
  Write speed: 14.4MiB/s
   Read speed: 11.7MiB/s

--============== Boot ==================--
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
             Timeout
Booting from network...
Local IP: 192.168.1.50
Remote IP: 192.168.1.100
Booting from boot.json...
Booting from boot.bin...
Copying boot.bin to 0x40000000... 
Network boot failed.
No boot medium found

--============= Console ================--

litex>
  • The Ethernet connection is needed only for debugging embedded Linux RISC-V applications on the DE2-115 board.
  • There are two built-in SoC SOFs on XploR Studio to flash DE2-115 for embedded Linux applications:
  • One for MII network mode where speed is 10 Mbps
  • One for RGMII network mode where speed is 1000Mps
  • Development PC IP address: 192.168.1.100
  • The TFTP server is running the development PC and serving Linux image

Booting Linux to DE2-115 board

In serial terminal, if you see:

    Booting from network...
    Local IP: 192.168.1.50
    Remote IP: 192.168.1.100
    Booting from boot.json...
    Booting from boot.bin...
    Copying boot.bin to 0x40000000... 
    Network boot failed.
    No boot medium found

That means the Linux kernel cannot be booted correctly.

So, please do the follow steps:

  1. Install rootfs-vexriscv-de2115 blueprint

  2. Start/Restart TFTP server (Linux)

        docker rm -f tftpboot
    cd $HOME/.xplor/blueprints/rootfs-vexriscv-de2115/
    docker run -itd --name=tftpboot --net=host  --restart=always -v ${PWD}:/var/tftpboot  pghalliday/tftp

  3. Configure IP address for DE2-115 board RGMII mode:

    example image

    • Network interface on the host PC connects to ETHERNET0 of DE2-115. The connection could be directly or via router/switches.
    • On the board, set Jumper JP1 to pins 1 and 2. It’s default mode (RGMII mode).
    • Default IP addresses:
      • DE2-115 board: 192.168.1.50
      • TFTP server: 192.168.1.100

    On the PC, the IP address is set to 192.168.1.100. If users want to use a different subnet, please update the IP of the board. To update the IP of the board, after flashing FPGA bitstream, open the /dev/ttyUSB* or COM* port console to the board and set the IP as:

    CommandUsage
    eth_local_ipSet the IP address of the board
    eth_remote_ipSet the expected IP of the TFTP Server to download kernel/rootfs for network booting
    netbootStart booting Linux from the network

    example image

    MII mode:

    example image

    • Network interface on the host PC connects to port 0 of DE2-115.
    • Connection speed is 10 Mpbs.
    • On the board, set Jumper JP1 to pins 2 and 3 (to config Ethernet port 0 to run on MII mode).
    • On the PC, the IP address is set to 192.168.1.100. The network speed and IP can be set with the following command:
    # Assume that the network interface is enxf8e43b5dd64a
NIC=enxf8e43b5dd64a
sudo ethtool -s $NIC speed 10 duplex full autoneg off
# Double check
ethtool $NIC
# IP needs to be fixed as 192.168.1.100
# Make sure that IPv4 method is manual
sudo ifconfig $NIC 192.168.1.100

    example image

    On the PC, the IP address is set to 192.168.1.100. If users want to use a different subnet, please update the IP of the board.

  4. Netboot/Reboot Linux In some case, you cannot type anything to serial terminal, please use litex_term to connect the serial port.

        cd $HOME
    git clone https://github.com/enjoy-digital/litex.git
    python3 -m pip install pyserial 
    python3 -m pip install litex
    sudo chmod -R 777 /dev/ttyUSB0
    cd litex/litex/tools/
    ./litex_term.py /dev/ttyUSB0 --speed 115200

    After that, you can see:

        --============== Boot ==================--
    Booting from serial...
    Press Q or ESC to abort boot completely.
    sL5DdSMmkekro
                Timeout
    Booting from network...
    Local IP: 192.168.1.50
    Remote IP: 192.168.1.100
    Booting from boot.json...
    Booting from boot.bin...
    Copying boot.bin to 0x40000000... 
    Network boot failed.
    No boot medium found

    --============= Console ================--

    litex>

    Then setup IP address (if needed) and run netboot. If output as follows, that means Linux be booted properly:

        Starting Dropbear SSH server: Waiting for kernel randomness to be initialised...
    [   14.144009] random: crng init done
    Generating 1024 bit rsa key, this may take a while...
    Public key portion is:
    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCMeX37iv5Hw5MadvVwd+UIVeSIx1QecoV8OiPOt65obbokDxvaol0PsfCHBi0h23zxhhzUHizKDAu9fJ7gQVLWfHjcGKA4x4XuY8O3TasjnzpAntjXgWcBOpw3zpM46skOl65zfJqq6AIH14IzCqs+VDUE2dKjv+4mRbiX3A5Ovw== root@de2-115-vexriscv32
    Fingerprint: sha1!! 5a:9f:05:35:11:2c:e2:e1:b8:71:a4:8e:f5:a3:8a:1d:76:b6:f2:ff
    dropbear.

    Rvdn 1.0 de2-115-vexriscv32 /dev/console

    de2-115-vexriscv32 login:

  5. Login and setup connection to debug

    • Login by typing root without password
    • Run ifconfig eth0 192.168.1.50 netmask 255.255.255.0
        Rvdn 1.0 de2-115-vexriscv32 /dev/console

    de2-115-vexriscv32 login: root
    login[58]: root login on 'console'
    root@de2-115-vexriscv32:~# ifconfig eth0 192.168.1.50 netmask 255.255.255.0

Debug application

Currently, riscv32-xplor-linux is the only toolchain supported. Please change the project settings to use the correct toolchain

  • Right click on the project then select properties.

  • In project settings, select

    • Architecture: RV32 (-march=rv32i*)
    • Floating point: None
    • Integer ABI: ILP32 (-mabi=ilp32*)
    • Floating point ABI: None

    example image

  • Click Apply and Close

There are some differences when debugging Linux applications, it is necessary to update some config as follows:

On the Debugger tab, select Intel FPGA Board.

example image

On the Configuration, select “Advanced Configuration”.

example image

Click the New button to create a new connection configuration, then select SSH as connection type:

example image

On the “New Connection” dialog.

  • Connection name: The name of connection
  • Host: 192.168.1.50. This is the default IP address of Linux run on board. If you use a different subnet when booting Linux, please update this IP too.
  • User: root
  • Use password-based authentication: No password

example image

Click Finish to create the connection configuration.

In the Connections dropdown, select the newly created connection name and set the destination file path to copy the application to the board.

On the Remote Absolute File Path for C/C++ Application, enter the path of the elf file that is copied to Linux (ex: /tmp/riscv.elf).

example image

Click Debug to start debugging.

Running and Debugging project with Intel FPGA DE2-115 platform on Windows 10

Hardware and driver preparations

Please refer to the Hardware and Environment Setup document for more details.

Setup SolarTFTP server on Windows 10

Prerequisites

  • Administrator permission

  • SolarWinds TFTP Server: To set up a TFTP server, users will have to download the TFTP Server utility such as SolarWinds can be downloaded from https://www.solarwinds.com/free-tools/free-tftp-server. Once the .zip file is downloaded, extract it and go through the straightforward installation.

  • Firewall setup: To allow remote access to the TFTP server, users need to open the firewall for TFTP service.

Start the TFTP Server

Run the SolarWinds TFTP Server utility by going to the Start Menu and searching for TFTP Server.

example image

Once it loads up, copy all the file in rootfs-vexriscv-de2115/ folder to C:\TFTP-Root folder.

example image

Programming IP Core

Similar to Linux

Booting Linux to DE2

Update IP of TFTP server

Go to *Network and Internet settings by click on example image:

example image

As image, there are 2 networks:

- The `Ethernet 3` for connecting to Internet
- The `Ethernet` for connecting to DE2-115 Board

example image

Click on Properties on Ethernet:

example image

Now we need to setup IP manually bt click on Edit button, choose Manual , type as image and Save

example image

After that, restart the SolarTFTP server and programming IP Core again.

example image

If Serial Terminal stills show Network boot failed, please try to turn off your Windows Firewall and reprogram IP core.

Login and setup connection from board to host

After booting Linux successfully,

``` sh
    Starting Dropbear SSH server: Waiting for kernel randomness to be initialised...
    [   14.144009] random: crng init done
    Generating 1024 bit rsa key, this may take a while...
    Public key portion is:
    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCMeX37iv5Hw5MadvVwd+UIVeSIx1QecoV8OiPOt65obbokDxvaol0PsfCHBi0h23zxhhzUHizKDAu9fJ7gQVLWfHjcGKA4x4XuY8O3TasjnzpAntjXgWcBOpw3zpM46skOl65zfJqq6AIH14IzCqs+VDUE2dKjv+4mRbiX3A5Ovw== root@de2-115-vexriscv32
    Fingerprint: sha1!! 5a:9f:05:35:11:2c:e2:e1:b8:71:a4:8e:f5:a3:8a:1d:76:b6:f2:ff
    dropbear.

    Rvdn 1.0 de2-115-vexriscv32 /dev/console

    de2-115-vexriscv32 login: 
```

  • Login by typing root without password

  • Run ifconfig eth0 192.168.1.50 netmask 255.255.255.0

        Rvdn 1.0 de2-115-vexriscv32 /dev/console

    de2-115-vexriscv32 login: root
    login[58]: root login on 'console'
    root@de2-115-vexriscv32:~# ifconfig eth0 192.168.1.50 netmask 255.255.255.0

Now board is ready for debugging application.

Debug application

Create debug configurations and debug are same to Linux.