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

Introduction

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
* DS-5
* Boot Process
* Qsys - hardware system integration tool
* System console
* The memory Map
* sopc_create_header_files
* 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.

Quartus II

( 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

• 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.

Install UsbBlaster Driver

http://www.altera.com/literature/ug/ug_usb_blstr_II_cable.pdf

An SOC Kit

• One of the following kits is required:

1. 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
2. Macnica Helio Board http://www.rocketboards.org/foswiki/Documentation/MacnicaHelioSoCEvaluationKit, http://www.macnica-na.com/heliokit
3. Altera Cyclone V dev kit http://www.rocketboards.org/foswiki/Documentation/AlteraSoCDevelopmentBoard, http://www.altera.com/products/devkits/altera/kit-cyclone-v-soc.html
4. 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:

Arrow SoCKIT: ARROW_SOCKIT-14.1--05-14-2015.img.tar.gz

Uncompress the image.

If using windows Please follow these steps:

• • Download Win32DiskImager from http://sourceforge.net/projects/win32diskimager/
  • Insert an micro-SD card in a microSD→USB adapter
  • a new drive letter will show up, assuming F:
  • run Win32DiskImager
  • select the GSRD sd_image for you board
  • click 'write'and confirm 'yes'
  • wait for the completion
  • eject the micro-SD card

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

1. Place the SDcard into you PC.
2. Create a working folder for the lab on your local hard drive.
3. Copy the WS1-IntroToSoC folder from the FAT partition (partition 1) on the SDcard into the lab project folder on your local hard drive.
4. 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.)
5. 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 settings

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

Test

If everything worked correctly you should be able to

1. Install lthe SD card
2. install the uart/serial USB cable
3. install the USB-blasterII cable
4. Power the board on
5. Start Putty
   1. -N-1 115200 no hardware handshaking.
6. Watch linux boot

LAB 1 Creating the Preloader

Procedure

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):

a- Linux

$ ~/altera/14.1/embedded/embedded_command_shell.sh
$ cd ~/<LAB project> 

b- Windows

Start→Altera→SoCEDS→Embedded Shell
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

$ bsp-editor& 

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

File	Description
generated	Folder containing source code that was generated based on the information from the handoff folder
settings.bsp	Preloader settings file, that contains the settings from the Preloader Generator
Makefile	Makefile used to build the Preloader
preloader.ds	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

$ make

The Makefile (also created by the Preloader Generator) performs the following steps:

1. Extract the fixed part of the Preloader source code
2. Build the Preloader executable using the fixed and the generated parts of the Preloader source code
3. 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/ folder:

File	Description
uboot-socfpga/spl/u-boot-spl	Preloader ELF file
uboot-socfpga/spl/u-boot-spl.bin	Preloader binary file
preloader-mkpimage.bin	Preloader image with the BootROM required header

For full details see

http://www.rocketboards.org/foswiki/Documentation/GSRD1402Preloader

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

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

https://www.altera.com/en_US/pdfs/literature/hb/qts/qts_qii53028.pdf

1. 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.
2. Open an embedded system-console ( Start→ Altera menu) or run the embedded_command_shell script from the embedded directory.
3. In the embedded command shell type

note: system-console is located at <pathToQuartus>/sopc_builder/bin

$ system-console &

1. This will bring up System Console GUI.
2. 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
3. In the System Explorer panel open "devices" . This shows all the jtag connection on the device.
4. Then open 5CS... ( the FPGA this may vary depending on the board you have )
5. Then open (link)
6. Then open JTAG
7. Then open sldfabric.node_0 ( if you have more than one you may want to explore all of them)
8. 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
/devices/5CSE(BA4|MA4)|5CSXFC4C6@2#3-2#DE-SoC/(link)/JTAG/sldfabric.node_0/phy_0/fpga_only_master.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

1. From the File menu choose "Execute Scripts ..." and if a message about Missing user script folder appears, select Don't create.
2. Browse to the <LAB project>/System_Console and choose the fft.tcl file.
3. The script runs and creates a fft demo tab.
4. Select the FFT Length of 512
5. 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.

1. 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.
2. cd to the <LAB project>/software/BareMetal_fft subdirectory.
3. type

   $ make

4. This will create a file called fft.bin
5. Insert SDcard into your PC
6. 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
7. Eject the sdcard
8. Insert the sdcard into the soc board
9. Restart the board by hitting the cold reset button or cycling power.
10. launch putty with ( or any other terminal program )
    • 8 databits
    • 1 stop bits
    • no parity
    • no hardware handshaking
    • 115200 baud rate
11. When prompted, type "stop" to interrupt the uboot process ( if it is already booting linux hit the warm reset button and try again)
12. 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
i.e.
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

run bridge_enable_handoff

Load the code into memory

fatload mmc_spi 0 0x100040 fft.bin

executes the code

go 0x100040

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

1. Start an embedded_command_shell
   • ~/altera/14.1/embedded/embedded_command_shell.sh
   • Start→Altera→...→embedded_command_shell
2. cd to the <LAB project directory>/software/Linux_fft_app
3. type "make"to build the files

   $ make

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

1. Power down the soc board and eject the SDcard.
2. Insert the SDcard into your pc and open the fat32 partition. (on Windows it is the only one you will see)
3. Copy fpga_fft from your software area to the SDcard.
4. Eject the SDcard and install in the SOC kit
5. Power on the board and allow linux to boot normally (you may need to restart your terminal program -- ie. putty)
6. Login as "root" if needed
7. 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
8. Insert the SDcard into the board, turn on the power, connect with your terminal emulator, and wait for the linux command prompt
9. 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 )

cd /home
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

1. log into linux on the dev board if needed -- User name is root
2. Find the IP address of the soc dev board
   • ifconfig from a Linux prompt in putty will give the ip address
3. (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

Usage

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 root@192.168.1.207:/home

Noted  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null - may be need on some PCs

Running the fpga_fft application

1. 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.
2. Try the square wave./fpga_fft 0 128
3. Try the sine wave./fpga_fft 1 256
4. You should see the 2 tables of numbers fly by. The source and the fft values.
5. If you are adventurous try adding a different wave form to the code.
6. To receive your reward for doing the lab you must do the following

   ./fpga_fft 0 128 | tee outputFile.txt

7. insmod /lib/modules/3.10.31-ltsi/extra/validator_module.ko

8. /examples/validator/sign_file.sh /examples/validator/validator_sign.sh outputFile.txt

9. Send in outputFile.txt.sign
10. 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.
11. • ifconfig from the target's Linux prompt in your serial terminal will give the ip address
    • <ip address>/fft.sh