DE1-SoC: ARM HPS Linux
Cornell ece5760

The programming model I wish to use in ece5760 is LINUX running on the ARM processors, talking to hardware on the FPGA through Qsys.
I would prefer not to use design automation tools, like OpenCL, but stay at the level of the Qsys module interconnect, with custom FPGA hardware.

• To start, you will use the UP LINUX 2016 image. The rest of this page assumes this version of Linux.
  • If you are working with a windows machine, The sections 2.1 and 2.2 Using Linux on the DE1-SoC
    shows how to install Linux on an SDcard.
  • If you are working from a Mac, then you probably want to use ApplePiBaker
• On the bottom of the DE1-SoC is an MSEL switch.
  Do not modify the switch setting unless you cannot program the FPGA from the USB blaster.
  If necesary, set MSEL to 010101 (left to right), see DE1-Soc Users Manual page 12-13
• Once Linux is running on the HPS:
  • Log in using the board serial connection as explained in section 2.3 of Using Linux on the DE1-SoC
    but use PSFTP or MobaXterm to transfer files, not the USB drive explained in section 2.4
    (after you install a SSH client, see below)
  • To configure the FPGA, we will not use the scheme described in Section 3, but rather download
    configuration using the USB blaster interface from Quartus Prime.
  • Compile C code as explained in section 4, 4.1, 4.3 and 4.4 of Using Linux on the DE1-SoC
  • If you have never used Linux, you may want to look at:
    • 40 linux commands.
    • Beginners guide part 1, part 2,
    • Linux tutorial
    • Network

Segfaults and undefined memory accesses

We are going to be accessing the FPGA through a memory map mechanism in C. FPGA real memory addresses are converted to virtual addresses by a mmap Linux utility. If you try to access an FPGA address which has not been mapped to virtual memory, the system will segfault. This requires coordination between Qsys and the C program. A separate kind of failure occurs if you access a memory address for which you have not built hardware on the Qsys bus. In this case, the bus hangs, waiting forever for a response, and LInux crashes. To fix this you have to reboot.

Setting up the UP Linux environment:

• Before doing anything else:
  • Remember: People write malware for Linux! Practice safe computing!
  • Login as root using the serial terminal connection and PuTTY (on Mac use Terminal)
  • Put a strong password on the root account using passwd
  • Disable the linaro account using passwd linaro -l
  • You should not shut down the system by just turning off the power.
    To avoid corrupting the file system use:
    shutdown -h now
  • To reboot use: reboot
• Editing on the HPS
  • Usually you will edit source code on a PC, then transfer the code to the HPS
    using MobaXterm or SFTP
  • But sometimes small edits (e.g. config files) are done on the HPS. Editors:
    • vi -- it is on every linux system. commands.
      You just have to remember the state (command/insert) of the editor.
    • vim -- very much like vi commands, but the state of the editor is indicated.
      To download: apt-get install vim
      
    • GNU nano -- slightly less cryptic than vi, more commands, and users guide
      When mouse support has been configured and enabled, a single mouse click places the cursor at the indicated position. Clicking a second time in the same position toggles the mark to start a selection range. Clicking in the shortcut list executes the selected shortcut. The mouse will work on the console when gpm is running (which seems to be the default). Invoke mouse with nano -m
    • GNU emacs -- bewildering. This is not an editor, it is a way of life.
• In the lab you will connect to the internet using a wired system,
  and we will require you to use a static address for security
• The Cornell 10space system will be used for any FPGA on the internet in the lab.
• The Cornell 10space system is not reachable from wireless devices!
• The MAC address and IP address are locked down and must match.
  You will use a static address assigned to your group. You may not use another group's addresses.
• You will need to specify an MAC address, IP address, and a router address in /etc/network/interfaces
  Add:
  auto eth0
iface eth0 inet static
hwaddress ether 12:34:56:78:90:yy
address 10.253.17.xx
netmask 255.255.255.0
gateway 10.253.17.1
dns-nameservers 132.236.56.250 128.253.180.2 192.35.82.50
  
• With a static address, you may need to add DNS servers.
  Edit /etc/resolv.conf to add the lines:
  nameserver 132.236.56.250
nameserver 128.253.180.2
nameserver 192.35.82.50
  Then execute /etc/init.d/networking restart
If you get a eth0 error, then reboot
  
• Secure Shell login
  • When networking is up, then at the Linux prompt do
    sudo apt-get install openssh-server
  • You may need to do sudo apt-get update before installing any packages
  • Use passwd to add a password to root if you have not already done this!
  • Make sure that PuTTY and PSFTP are installed on the Windows machine (on Mac use Terminal)
  • Use PuTTY to SSH to the ARM.
    -- Open the IP address assigned by DHCP (Find address using ifconfig)
    -- OR use the static address assigned to you
  • Use PSFTP to move files to/from the ARM (use help command)
  • The Cornell 10space system is not reachable from wireless devices!
• GCC
  • The ARM cpus are completely capable of running GCC to communicate with either native HPS peripherials or with the FPGA.
    You compile from the command line with the usual Linux syntax. Some projects require compile flags which are noted below.
  • man page
  • Compile code as explained in section 4, 4.1, 4.3 and 4.4 of Using Linux on the DE1-SoC
  • Minumum compile command is gcc source.c -o executable_file_name
  • To use math library include -lm option on the command line and <math.h> in the code
  • To use pThreads include the -pthread option on the command line <pthread.h> in the code
• Utilities
  • taskset allows you to place a process on either ARM processor.
    However, Linux attempts to migrate processes to load balance if you do nothing.
  • htop (sudo apt-get install htop) shows you what is running and on which processor.
  • clamav is an antivirus program you might install using apt-get install clamav
    Then you can update the virus database by using freshclam
    and scan the file system using clamscan (options)
    • But if the update fails with a locked database then
      sudo /etc/init.d/clamav-freshclam stop
sudo freshclam -v
sudo /etc/init.d/clamav-freshclam start
      
  • ntp sets network time. get it with apt-get install ntp
    You need to edit /etc/ntp.conf to include the line
    server ntp0.cornell.edu
    Service starts up after a minute or so.
    Occasionally I need to restart sudo service ntp restart
  • apt-get sometimes fails with the error "Problem with MergeList ..."
    Apparently this is due to a correpted database so
    sudo rm -vf /var/lib/apt/lists/*
sudo apt-get update
    Then try again
• Mount a USB flash drive
  • Plug it in, then look for something like sda1 in /dev
  • cd to /mnt
  • mkdir sda1
  • mount /dev/sda1 /mnt/sda1
  • To eject the drive: umount /dev/sda1
• Backup
  • SD cards fail. Backup your good image, or you will do all the work again.
  • On windows, Win32 disk imager can be used to READ an image from the SD card.
  • On Mac, use ApplePiBaker
• General
  • 40 linux commands
  • Python2.7 is installed in this distribution.
    Python supports mmap, so you should be able to get to the FPGA, but is probably slow.
• Do not use this networking method in the lab.
  If you connect to internet using Cornell DHCP, then Cornell requires a fixed, registered MAC address in order to use DHCP.
  Since the board boots with a different MAC address every time you, have to fix the MAC address.
  Note that if you get hit with malware, Cornell will throw you off the net!
  Do not use this in the lab. Use this only if you buy your own board and use in your own facility.
  To set this up:
  • At the Linux prompt do ifconfig and copy the MAC address to
    https://dnsdb.cit.cornell.edu/dnsdb-cgi/mycomputers.cgi
  • Every time you start the board you must execute
    ifconfig eth0 down
ifconfig eth0 hw ether <mac addr>
ifconfig eth0 up
/etc/init.d/networking restart
    Where <mac addr> the the address you registered
    put these commands in /etc/rc.local so that they are executed on startup
  • The DHCP server should then assign you an IP address
  • If networking does not start then execute dhclient eth0
    

References:

DE1-SOC literature list

Using the DE1-SOC FPGA by Ahmed Kamel

Stereoscopic Depth on an FPGA via OpenCL by Ahmed Kamel and Aashish Agarwal

Running Linux on DE1-SOC by MANISH PATEL and SYED TAHMID MAHBUB

OpenCL on DE1-SOC Sahil P Potnis (spp66@cornell.edu) Aashish Agarwal (aa2264@cornell.edu) Ahmed Kamel (ayk33@cornell.edu)

Audio Core (Qsys University Program 15.1) local copy

Video Core (Qsys University Program 15.1) local copy

External to Avalon Bus Master (external here means in the FPGA, but not in the Qsys bus structure)

Avalon to External Bus Slave (external here means in the FPGA, but not in the Qsys bus structure)

(old LINUX image)

Copyright Cornell University October 29, 2020