Skip to content

Instantly share code, notes, and snippets.

@addisonElliott
Last active July 18, 2024 10:50
Show Gist options
  • Save addisonElliott/8c229e47184a724d1a00328110dc094c to your computer and use it in GitHub Desktop.
Save addisonElliott/8c229e47184a724d1a00328110dc094c to your computer and use it in GitHub Desktop.
This is a basic guide for building a program on the DE10 Nano SoC. This walks through using Quartus Prime, Qsys, and EDS from start to finish. The program counts up four LEDs on the HPS

I successfully created a project instantiating the HPS in Qsys. I added a parallel I/O in Qsys to allow the HPS to communicate with the LEDs via the HPS-to-FPGA lightweight bus. From there, I generated a preloader and U-boot along with the SOF file. I also wrote a simple C program that counts from 0-15 and sets the LEDs to that value every second. This encompasses about every step required to be able to communicate between the FPGA and HPS, so this is definitely a first step. I'm going to document what I did and how you guys can get this running.

I did this on Windows since that is my primary OS. Things are different on Linux, so you will have to figure them out if you try to do this on Linux.

File Structure

DE10NanoUART-FPGA

  • Project containing everything necessary to get exactly what I have running
  • HPS_FPGA_LED - Source code and makefile for the C program to blink LEDs
  • hps_isw_handoff - ISW stands for Initial SoftWare so it is the first thing to be ran AFTER the hardcoded bootrom is loaded. This is considered the second stage bootloader (SSBL) because it comes right after the primary bootloader which is hardcoded in the HPS (in transistors and such). The primary bootloader just basically checks the MSEL switches to see how it should boot and then looks for the SSBL. This is generated by Quartus Prime when you compile the project. Contains information about the HPS based on Qsys settings
  • output_files - Directory containing output files. The two important ones are SOF and RBF. SOF is if you are going to program it directly via JTAG and RBF if you are going to load it via a filesystem
  • soc_system - This is the directory that contains the generated files from the Qsys project. The Qsys compiles it into HDL files and then that is linked in Quartus Prime
  • software - This file is generated when using the bsp-editor. BSP stands for Board Support Package. It basically takes the hps_isw_handoff and makes a preloader and U-boot image to put on a SD card
  • generate_hps_qsys_header.sh - This file takes a .sopcinfo file and converts it into a header file (.h) that can be included in your C program. This was used to generate the hps_0.h file contains in HPS_FPGA_LED
  • If I didn't mention it, then it probably means it wasn't that important, I assume you know what it is already, or it is a intermediate output file that isn't necessary for our purposes

Testing my work without building

So, since I've done the hard work of building all this, you can follow these instructions to put it on your board and it should work fine.

  1. Extract DE10NanoUART-FPGA.zip somewhere sensible
  2. Download Altera EDS (Embedded Development Suite) here: http://dl.altera.com/soceds/
    • This is used to create baremetal software, build U-boot and the preloader and to put it on the SD card
    • You want the lite edition
  3. Open SoC EDS Command Shell. For Windows, this is a version of Cygwin that comes with EDS and sets up the PATH variable for you. Not sure what it does on Linux.
    • Note: For Windows, you must run this as an Administrator or you'll have problems down the road. I suggest you open the properties on the shortcut and make it run as administrator automatically
  4. In the shell, navigate to the project folder you extracted from 1. Navigate further into software/spl_bsp
    • This is the easy version because everything has already been built. EDS is needed to get it on the SD card however.
  5. Take the micro SD card from the DE10 Nano and put it in your computer. I have a micro SD to SD card thing that I'm using. Take a note of the drive that it gets mounted as. In my case it was G:
    • There are four partitions on the drive.
      1. 1MB preloader, sets up HPS pin configuration and then moves to Uboot
      2. ~1GB FAT32, contains Uboot and also other files since this is what can be seen when you plug into Windows
      3. ~1GB EXT4, contains the Linux filesystem.
      4. ~4GB unallocated.
    • We need to update the preloader and U-boot image
  6. Load the preloader on the disk by running the following. Change the drive from G to your drive
    alt-boot-disk-util.exe -p preloader-mkpimage.bin -a write -d g
    
  7. Next, we want to copy some files to the FAT32 partition of the drive. Run the following three commands and make sure to change the drive from G to your drive.
    cp uboot-socfpga/u-boot.img /cygdrive/g
    cp ../../HPS_FPGA_LED/HPS_FPGA_LED /cygdrive/g
    cp ../../output_files/output_file.rbf /cygdrive/g/soc_system.rbf
    
  8. Run sync to flush changes to the SD card. Remove it and put the micro SD card in the DE10 Nano.
  9. On the board, set all the switches to ON. This boots the FPGA from the HPS using FPP x16. This is just a special way of reading the RBF file to boot the FPGA.
  10. Plug the UART into your computer and open a serial console BEFORE powering on the device. Baud rate is 115200, 8 data bits, 1 stop bit, pretty much all standard. Find your COM port.
  11. Plug in the DE10 Nano and you should see it boot Linux. Don't press a key for the first 5 seconds so it will autoboot from the SD card! The username login is root and no password.
  12. If the FPGA is successfully configured, you should see the fourth LED on and the rest on. If you see them all at like a half on/off state, then something messed up. Look at the top of your UART console to see if an error message was reported.
  13. Now we need to get the HPS_FPGA_LED program off the FAT32 partition and then we can run it and it should work. Do the following:
    mkdir /mnt/FAT
    mount /dev/mmcblk0p1 /mnt/FAT
    cp /mnt/FAT/HPS_FPGA_LED /home/root/
    /home/root/HPS_FPGA_LED
    
  14. You should see the first four LEDs counting. There are printf's that should be showing on the screen too. This is it, you did it.

Building the project

If you want to build it from scratch so you know you can do it, then follow these steps.

  1. Extract DE10NanoUART-FPGA.zip somewhere sensible
  2. Open project in Quartus Prime
  3. Open Qsys and open the soc_system.qsys file in the project
    • This is where you make changes to the Qsys file as necessary
  4. Click generate HDL and the defaults should be fine
  5. In Quartus Prime, click Drop-down in Project panel in left and select Files. You should see the soc_system.qip file added. If not, add it to the project
  6. Maybe Optional: This is required if you make changes to the Qsys project. You have to run some TCL scripts to set the timing constraints on the HPS pins. Go to Tools->TCL Scripts. In soc_system/submodules, run hps_sdram_p0_parameters.tcl and hps_sdram_p0_pin_assignments.tcl
    • These TCL files are generated when you generate the HDL from Qsys
  7. Compile the design. It should compile fine
  8. If you want to load the FPGA from HPS, then you need to convert the SOF to RBF now. If you just want to upload the SOF via USB blaster, then skip this step. Select File->Convert Programming Files
    • For programming type, select Raw Binary File (.rbf)
    • Mode: Set Passive Parallel x16. This is why we set the MSEL to what it is. I don't know how to set compression or fast/standard but this is where it all happens
    • In input files to convert section at bottom, add the SOF file generated
    • Click generate and it will create the RBF file
  9. Follow steps 2-4 from above section to get EDS going. You don't need to navigate further into software/spl_bsp since it won't exist yet. When you are in the project directory, type: bsp-editor
    • This creates the software folder based off the hps_isw_handoff
  10. Select File->New HPS BSP.
  11. Navigate to the hps_isw_handoff/soc_system_hps_0 for the preloader settings directory. Keep everything else the same and select OK
  12. This configures how to setup the preloader and Uboot. You can choose how you want to boot after the preloader here. Keep all the defaults but check FAT_SUPPORT for our u-boot.img.
  13. Click Generate to create the software/spl_bsp folder.
    • Note: If you want to open an existing HPS BSP, then do File->Open and select the settings.bsp file in software/spl_bsp folder.
  14. Navigate into software/spl_bsp. Run make and make uboot
  15. Now we need to make our C program to run on the HPS. Go into HPS_FPGA_LED and run make
  16. Everything is built, follow steps 5-15 from the above section to put the data on the SD card and run it

Tips

Tip 1

When making your project for the DE10 Nano SoC, the device MUST be set to 5CSEBA6U23I7 and NOT 5CSEBA6U23I7DK.

When you generate your qsys file with 5CSEBA6U23I7DK, there are some things (such as PLL counter settings) that will not be recognized. This results in the hps_isw_handoff folder having an incorrect hps.xml file which essentially means the preloader will not work correctly.

In my case, my issue was that nothing was showing on the UART console. This was because the preloader was messing things up and so there was nothing to show.

@Phi-Ho
Copy link

Phi-Ho commented Jan 5, 2021

Happy New Year.

It looks like this link is broken:

http://addielli.com/DE10NanoUART-FPGA.zip

Is it still available somewhere?

Regards,

phiho

@addisonElliott
Copy link
Author

Bought a different domain. Here's the link: https://addisonelliott.net/DE10NanoUART-FPGA.zip

@Phi-Ho
Copy link

Phi-Ho commented Jan 6, 2021

Hi,

Thank you so much for sharing your experience, it is much appreciated. I will need to spend a lot of time to study what you shared.

I followed your instruction to rebuild the whole project with Quartus Prime Lite Edition 20.1 without errors.

There are only 2 critical warnings:

Critical Warning (169085): No exact pin location assignment(s) for 112 pins of 172 total pins. For the list of pins please refer to the I/O Assignment Warnings table in the fitter report.
Critical Warning (174073): No exact pin location assignment(s) for 1 RUP, RDN, or RZQ pins of 1 total RUP, RDN or RZQ pins

I hope you don't mind if I ask a few newbie questions.

I have been trying to use the Intel FPGA Monitor Program v18.1 in the hope that I can poke around the boot rom in the HPS but have been encountering this error:
"The system has been downloaded onto the board, but some JTAG devices could not be queried. Please check Info & Errors for more details."

I have been searching for a solution without success. Do you have any ideas why I encountered this error. I have been programming the device successfully with JTAG to download the exercises to the board.

Also, would you please tell me where is the boot rom located .

Best regards,

phiho

Uploading DE10NanoUART-FPGA.warnings.zip…

@addisonElliott
Copy link
Author

To be honest, I don't know. It's been a few years since I've worked with this stuff and so I don't remember at this point.

Sorry, wish I could've been more help.

@samalika
Copy link

samalika commented Mar 3, 2021

Hi,
It seems like the following link is broken:
Could you please share a link for this project
https://addisonelliott.net/DE10NanoUART-FPGA.zip

@addisonElliott
Copy link
Author

Link works for me?

@Andy2No
Copy link

Andy2No commented Oct 5, 2023

@addisonElliott That latest link works for me too (https://addisonelliott.net/DE10NanoUART-FPGA.zip) but the first link to it in the document above is broken and still points to http://addielli.com/DE10NanoUART-FPGA.zip

Thanks for writing this guide. I'll work through it. I've found other takes on it, but they tend to be too long to get to grips with easily, yet still somehow leave out details. Yours seems like a more appropriate length :)

I've found recent versions of Quartus aren't able to actually build the IP in Windows, in Platform Designer - they use a WSL Linux subsystem to do it, which needs Win 10 or later. I'm not sure when that started, but Quartus 15.1 (with Qsys, predating Platform Designer) may be the last version that worked fully within Windows; I'm not sure. So, I'm curious to see which version you used here. Hopefully I can work that out.

[ EDIT: It seems that Quartus 18.1.1 was the last version that worked fully within Windows, without using the WSL - "Windows Subsystem for Linux". It can currently still be downloaded from Intel's website ]

@Andy2No
Copy link

Andy2No commented Nov 14, 2023

At step 5 of "Testing my work without building", it says "Take the micro SD card from the DE10 Nano and put it in your computer. ". I don't understand what was meant by that. Is this based on a pre-existing SD card image flashed onto the micro SD card? If so, which one is it based on?

I'm probably just misunderstanding, but this doesn't seem to say how to start from a blank micro SD card. It seems to assume that one has already been prepared to boot the DE10-Nano, but it doesn't appear to say where that card image came from.

@Ravin-git
Copy link

$ make
Applying Patch: C:/intelFPGA/17.0/embedded/host_tools/altera/preloader/uboot-socfpga.patch/cygwin/apply_mingw_support.patch
patch -p1 --directory=uboot-socfpga --input=C:/intelFPGA/17.0/embedded/host_tools/altera/preloader/uboot-socfpga.patch/cygwin/apply_mingw_support.patch
(Patch is indented 1 space.)
(Stripping trailing CRs from patch; use --binary to disable.)
can't find file to patch at input line 4
Perhaps you used the wrong -p or --strip option?
The text leading up to this was:

|diff -rupN uboot-socfpga.orig/tools/mkenvimage.c uboot-socfpga/tools/mkenvimage.c
|--- uboot-socfpga.orig/tools/mkenvimage.c 2014-01-24 16:05:23.570492900 -0800
|+++ uboot-socfpga/tools/mkenvimage.c 2014-01-24 16:05:24.267562600 -0800

File to patch:

I am facing this issue could you support .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment