Note: This page has been superseded by a new version at the URL below. If you are starting this lab, please use the updated lab page at the URL below:
WS1 Altera SoC Devices Introduction for SW Developers
This workshop is designed to familiarize the participant with the Altera SOC families of FPGA that include ARM Cortex-A9 processors. Specifically, how to create peripherals that become part of the memory map of the processors but reside in the FPGA and how software can interact with them. Bare Metal as well as simple Linux drivers (/dev/mem) will be discussed.
Basic workshop outline ( subject to change)
* Introduction to the Altera SOC architecture
* HW Features
* Software Features
* Supported OS
* Boot Process
* Qsys - hardware system integration tool
* System console
* The memory Map
* HWLIBS /SOCAL
* Bare Metal Apps talking to FPGA
* Linux Memory/Driver Model
* User Space driver /dev/mem
* Web Server
The slides from the classroom presentation are available here: WS_1_Intro_To_SoC_SW_Workshop.pdf
Set Up for Labs
- A Windows/linux machine with the following installed.
( web edition is fine), version 14.1 http://www.altera.com/products/software/sfw-index.jsp
This lab is built for and tested against Quartus 14.1. It is recommended that this version of Quartus be used for the lab.
- SOCEDS, version 14.1 is also required for the lab. Having a license for DS-5 is not required but useful if you wish to debug code.
An SOC Kit
- One of the following kits is required:
- Arrow SoCKit Board, https://www.arrow.com/en/products/sockit/arrow-development-tools Good doc for whole setup http://www.rocketboards.org/pub/Documentation/ArrowSoCKitEvaluationBoard/SoCKit_Getting_Started_Guide.pdf
- Macnica Helio Board http://www.rocketboards.org/foswiki/Documentation/MacnicaHelioSoCEvaluationKit, http://www.macnica-na.com/heliokit
- Altera Cyclone V dev kit http://www.rocketboards.org/foswiki/Documentation/AlteraSoCDevelopmentBoard, http://www.altera.com/products/devkits/altera/kit-cyclone-v-soc.html
- TODO other kits
Other kits will work, but are not supported directly with this lab
Putty or some terminal program
- A terminal program capable of interfacing to the SoCKit 's built-in USB serial port.PuTTY is a common terminal program supported for both Linux and Windows which works well.Downlod PSCP.exe as well.
A microSD card with the lab image
Now burn the microSD card with the Lab image.
First, download the SD card image for your board:
Uncompress the image.
If using windows Please follow these steps:
If using Linux use the dd command
- Determine the device associated with the SD card on the host by running the following command before and after inserting the card in the reader:
$ cat /proc/partitions
Let's assume it is /dev/sdx
. ( it will be something like sdb, sdc, or mmcblk0)
*CAUTION: be absolutely certain that you have the correct device, as dd to the wrong device can destroy your system.*
- Use dd utility to write the SD image to the SD card:
$ sudo dd if=ARROW_SOCKIT-14.1--05-14-2015.img of=/dev/sd%RED%x%ENDCOLOR% bs=1M
Note we are using sudo to be able to write to the card.
- Use sync utility to flush the changes to the SD card:
$ sudo sync
Copy the lab files to the PC
All the files you need for hte labs are on the SD card's fat partition
- Place the SDcard into you PC.
- Create a working folder for the lab on your local hard drive.
- Copy the WS1-IntroToSoC folder from the FAT partition (partition 1) on the SDcard into the lab project folder on your local hard drive.
- Each development board has its own folder on the SD card FAT partition. Find the folder for the development board you are using (ALTERA_CV_SOC, DE0_NANO_SOC, etc.)
- Copy soc_system.sopcinfo, output_files/<board name>.sof and the hps_isw_handoff folder from the folder for your board on the SDCard FAT partition into the WS1-IntroToSoC folder on your local hard drive. The results should look like directory below.
Connect the board to your PC
The lab uses two USB interfaces. The first is a USB interface to the stdio serial port on the SoC
device. Find the mini or micro USB connector (depending on your board) labeled "UART". Connect this USB port to your host PC with the appropriate cable.
The second USB interface is used for networking the board to your host PC and to mount the SD card FAT filesystem. The web server part of the lab uses USBNet to communicate to the board. Look for the micro or mini USB connector labeled "USB OTG", "HPS USB", or something similar. Connect this USB port to your host PC with the appropriate cable.
Configure the Board for running linux
msel 0-4 should be set for compression and 32 bit configuration
up-dn-up-dn-up-up => 010100
Each board needs to have the proper settings so the board will boot and run linux
If everything worked correctly you should be able to
- Install lthe SD card
- install the uart/serial USB cable
- install the USB-blasterII cable
- Power the board on
- Start Putty
- -N-1 115200 no hardware handshaking.
- Watch linux boot
LAB 1 Creating the Preloader
Generating the Preloader
1. Anytime an SOC design is generated with qsys and compiled in Quartus an hps_isw_handoff folder will be generated. This folder contains configuration information which is needed by the preloader to configure clocks, IO, and the sdram controller. For these labs this handoff folder has already been created for you so you don't have to run Quartus.
2. Start an Embedded Command Shell and go to LAB project folder (assumed here to be saved in the home folder):
$ cd ~/<LAB project>
In the embedded shell cd to the path of the project.
$ cd ~/<LAB project>
3. Start the Preloader Generator aka BSP Editor
in the embedded command shell
4. In the BSP Editor
, select File -> New BSP ...
5. In the New BSP
window, click the ...
browse button to browse to the handoff folder
6. Select the <project folder>/hps_isw_handoff/soc_system_hps_0
folder and Click Open
7. The New BSP
window will have all the settings populated, based on the handoff folder. Accept the default settings and click OK
. This will close the window.
8. In the BSP Editor
window, edit any settings if necessary, then click Generate
9. The message panel on the bottom will indicate the status of the generation. Click Exit
to close the BSP Editor
The following items are generated in the <LAB project>/software/spl_bsp/
|| Folder containing source code that was generated based on the information from the handoff folder
|| Preloader settings file, that contains the settings from the Preloader Generator
|| Makefile used to build the Preloader
|| ARM DS-5 AE that can be used to load the Preloader
Compiling the Preloader
1. In an Embedded Command Shell and go to the generated Preloader folder:
$ cd ~/<LAB project>/software/spl_bsp
2. Run the make
command to build the Preloader image
The Makefile (also created by the Preloader Generator) performs the following steps:
- Extract the fixed part of the Preloader source code
- Build the Preloader executable using the fixed and the generated parts of the Preloader source code
- Convert the executable to binary, then add the bootROM required header on top of it
The following files are built in the <LAB project>/software/spl_bsp/
|| Preloader ELF file
|| Preloader binary file
|| Preloader image with the BootROM required header
For full details see
At this point the preloader could be loaded into the SDcard and used. However we have already generated one and it is preinstalled on the SDCard.
LAB 2 Verifying Hardware with System Console
System console is a utility that allow you to poke and peek to peripherals in the HPS and FPGA. It also has the ability to support Dashboards composed of widgets that present a GUI to the user. It is tcl driven scripts can be used.In this LAB a script called <LAB project>/systemconsole/fft.tcl will be used. Feel free to open and examine the contents of this file.
For more system console documentation
- Start a terminal program such as Putty and then power on SOC board. In the terminal you should see U-boot wait for 5 seconds and then see Linux begin to boot. After a few seconds Linux should finish booting and leave you at a prompt.
- Open an embedded system-console ( Start-> Altera menu) or run the embedded_command_shell script from the embedded directory.
- In the embedded command shell type
note: system-console is located at <pathToQuartus>/sopc_builder/bin
$ system-console &
- This will bring up System Console GUI.
- With system console up and running go to the File -> Load Design ... menu and choose the LAB project directory and choose the <board name>.sof file. This loads up all the information about your project into system-console
- In the System Explorer panel open "devices" . This shows all the jtag connection on the device.
- Then open 5CS... ( the FPGA this may vary depending on the board you have )
- Then open (link)
- Then open JTAG
- Then open sldfabric.node_0 ( if you have more than one you may want to explore all of them)
- Then open phy_0.Under phy_0 it should say fpga_only_master.master. If it does not you may need to explore other sldfabric.nodes.
The JTAG master we will be using is call fpga_only_master.jtag, open it. It should under a folerder call phy_X ( Quartus assigns the phy numbers) In this case it is phy_0. In this design there is only one JTAG master. On the phy_X for the fpga_only_master notice green square wave. This indicates that the clock attached to the fpga_only_jtag_master is running and the reset has been de-asserted. This is a very handy indicator for board bring up.
Notice: that when you open the fpga_only_master.master you can see all the peripherals attached to fpga_only_master.
Now in the Tcl Console window type
% get_service_paths master
You should get and output similar to this. In this simple case there is only one master interface.
% get_service_paths master
Notice that phy_0/fpga_only_master shows up as the first device. Which is index "0" (phy_0). When we open a channel for communicating with the the fpga_only_master we need to know the position of the phy in the list. If it is any place other that the first item, the 12th line of the <LAB project>systemconsole/fft.tcl script will have to be changed to the correct index.
puts [set m [lindex [ get_service_paths master ] 0]]
Running the fft.tcl script
- From the File menu choose "Execute Scripts ..." and if a message about Missing user script folder appears, select Don't create.
- Browse to the <LAB project>/System_Console and choose the fft.tcl file.
- The script runs and creates a fft demo tab.
- Select the FFT Length of 512
- Select the square wave button and you should see a screen like this.
Note: The right side of the image may be clipped but you can view the entire picture by right clicking on it and selecting view attachment.
The three graphs show you the FFT real Input ( Imaginary is zero) and the Real and Imaginary FFT transforms. Go ahead play with buttons and look at the wave forms. The "Input Raw Data" tab shows the raw data going to and from the FFT. Column "Code" is the Hex value and last column is the sign extended version.
Feel free to play around and try different settings.
LAB 3 Bare Metal FFT app
Creating a Bare metal Application for FFT
In this lab we will compile some bare metal code based upon the BareMetalHelloWorldExample
code that ships with the soceds. We will place the resultant executable on the fat32 partition of the sd-card and Modify uboot to launch it.
- Open an Embedded console by choosing it from the start menu or running the embedded_command_shell.sh(bat) script in the embedded install directory.
- cd to the <LAB project>/software/BareMetal_fft subdirectory.
- This will create a file called fft.bin
- Insert SDcard into your PC
- Copy the <LAB project>/software/BareMetal_fft/fft.bin file to the sdcard (fat32 partition). i.e. the same directory as the boot.script file
- Eject the sdcard
- Insert the sdcard into the soc board
- Restart the board by hitting the cold reset button or cycling power.
- launch putty with ( or any other terminal program )
- 8 databits
- 1 stop bits
- no parity
- no hardware handshaking
- 115200 baud rate
- When prompted, type "stop" to interrupt the uboot process ( if it is already booting linux hit the warm reset button and try again)
- at the UBOOT prompt type or copy each of these lines
This loads the system.rbf into memory (don't use with Helio Board)
fatload mmc 0:1 $fpgadata <boardname>/output_files/<boardname>.rbf
fatload mmc 0:1 $fpgadata DE0_NANO_SOC/output_files/DE0_NANO_soc.rbf
The configures the fpga with the .rbf (don't use with Helio Board)
fpga load 0 $fpgadata $filesize
Turns the bridges on
Load the code into memory
fatload mmc_spi 0 0x100040 fft.bin
executes the code
On the terminal you should see input to the fft and real and imaginary parts of the fft output displayed. The default is 128 samples but you can recompile the code and change the value to any power of 2 less than or equal to 4096. Edit file fft.c line 70 and change the #define for the DATA_LENGTH.
// ***************** feel free to change this value ****************
// 128 256 512 1024 2048 4096
#define DATA_LENGTH 128
In hello.c you change change the output from square wave to sine wave by changing fft_main(0) to fft_main(1)
LAB 4 Creating a Linux Application for FFT
- Start an embedded_command_shell
- cd to the <LAB project directory>/software/Linux_fft_app
- type "make"to build the files
Move the fpga_fft app to the sdcard
You have 2 options you can use pscp ( scp) to move the file over or you can move the file using by ejecting the SDcard and placing it in your PC.
Moving the fpga_fft app by manually copying to the sdcard
- Power down the soc board and eject the SDcard.
- Insert the SDcard into your pc and open the fat32 partition. (on Windows it is the only one you will see)
- Copy fpga_fft from your software area to the SDcard.
- Eject the SDcard and install in the SOC kit
- Power on the board and allow linux to boot normally (you may need to restart your terminal program -- ie. putty)
- Login as "root" if needed
- Now we need to mount fat partition as a regular folder on the SOC linux file system so we can get to the files we just place on the card
- Insert the SDcard into the board, turn on the power, connect with your terminal emulator, and wait for the linux command prompt
- At the Linux prompt in the terminal emulator, ype the following commands ( if you have scp on your machine you can just transfer the files with that )
mkdir -p sdcard
mount /dev/mmcblk0p1 sdcard
cp sdcard/fpga_fft /home
Moving fpga_app files using scp
you need to have the soc dev board connect to the same ethernet subnet as your PC. If you are running on windows you need to have an scp utility. If you downloaded the full putty it is included. the putty version is called "pscp" and has the identical syntax as scp except the command is pscp Here is what you want to do
- log into linux on the dev board if needed -- User name is root
- Find the IP address of the soc dev board
- ifconfig from a Linux prompt in putty will give the ip address
- (p)scp has the following command structur
- (p)scp <source file name> <destination file name>
- the trick is when the file is on the remote soc system for the fjile name you use
- pscp [options] [user@]host:source targetpscp [options] source [source...] [user@]host:targetpscp [options] -ls [user@]host:filespecso in our case it will be
(p)scp fpga_fft root@<ipaddress>:/home/root/
(p)scp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null fpga_fft email@example.com:/home
Noted -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null - may be need on some PCs
Running the fpga_fft application
- Now it is time to run the fpga_fft application. It takes two parameters. The first is the wave form 0= square, 1=sine. The second parameter is the number of samples that must be a power of 2 between 128 and 4096.
- Try the square wave./fpga_fft 0 128
- Try the sine wave./fpga_fft 1 256
- You should see the 2 tables of numbers fly by. The source and the fft values.
- If you are adventurous try adding a different wave form to the code.
- To receive your reward for doing the lab you must do the following
./fpga_fft 0 128 | tee outputFile.txt
/examples/validator/sign_file.sh /examples/validator/validator_sign.sh outputFile.txt
- Send in outputFile.txt.sign
- If your board is connected to a network you can see the graph of the fft with a webserver.In the web browser on a machine on the same network type the <ipaddress of the board>/fft.sh. This lab is set up to use USBNet networking to the host.
- ifconfig from the target's Linux prompt in your serial terminal will give the ip address
- <ip address>/fft.sh