SoC SW WS1: Intro To Altera SoC Devices - Lab 4 - Linux FFT Application

---

LAB 4 Linux FFT app

---

In this lab we will compile a simliar application to the one in Lab 3, but in many ways this is a simpler program because it will be a standard linux application instead of a bare metal application, so we can rely on all the resources that are provided by the linux environment to make this application simpler. We will copy this program over to the linux target and execute it. This program also produces results in such a way that we can view them over a network connection with a web browser, and we will demonstrate that as well.

The linux application requires the same understanding of the memory map as the bare metal application. The linux application can use the same "sopc-create-header-files" utility as the bare metal application. Since we have already seen how to use this utility before, this lab will generate it automatically with the Makefile for this project. NOTE: there are other ways to communicate this inforomation into the linux application, but for the purposes of this lab we will just use the "sopc-create-header-files" method.

Hardware Environment

Jump to Workshop Main Page | Return to Lab Intro | Return to Lab 3: Bare Metal FFT Application | Show All Steps

The image below represents an abstract view of what the hardware environment looks like that we will be interacting with in this lab. The FPGA system on the right side of the image contains an onchip RAM which FFT input samples can be store into. Then the FFT read DMA can read those samples and source them into the FFT hardware component for processing. The results from the FFT hardware are then writen into the onchip RAM by the FFT write DMA. The JTAG master and the LWH2F bridge master can both interact with the onchip RAM and the DMA engines, so we can interact with the FFT hardware from either a system-console session connecting through the JTAG master component, or through software running on the HPS reading and writing through the LWH2F master.

In this lab we will be using the Linux application to interact through the LWH2F master.

Lab Environment

Jump to Workshop Main Page | Return to Lab Intro | Return to Lab 3: Bare Metal FFT Application | Show All Steps

To begin, make sure that you have the environment provided by the Embedded Command Shell which is delivered in the SoC EDS tools installation. There are a number of ways that you might get this environment applied to your development host, one way is to simply execute the "embedded_command_shell.sh" shell script that is provided in the SoC EDS tools, like this:

On Linux:

[~]$ <path-to-soceds-tools>/embedded/embedded_command_shell.sh
[~]$

On Windows:

Start->Altera->SoCEDS->Embedded Shell

Then from the embedded command shell, change into the "WS1-IntroToSoC/software/BareMetal_fft" directory that you should have previously copied onto the local hard drive of your development host.

[~]$ cd <path-to-lab-work>/WS1-IntroToSoC/software/Linux_fft_app
[Linux_fft_app]$

Lab Procedure

Jump to Workshop Main Page | Return to Lab Intro | Return to Lab 3: Bare Metal FFT Application | Show All Steps

Now compile the linux application by running "make":

[Linux_fft_app]$ make
[Linux_fft_app]$

You should now see the linux application "fpga_fft" in the directory:

[Linux_fft_app]$ ls
alt_types.h  fpga_fft.c  fpga_fft.map  Makefile  qsys_headers
fpga_fft     fpga_fft.d  fpga_fft.o    msgdma
[Linux_fft_app]$

Now we need to copy the "fpga_fft" application over to the target development board running linux. We want to place the "fpga_fft" application in the "/root" directory on the target development board. There are three ways that this can be accomplished:

• OPTION 1 - Mount the SD card from your target board running the USB mass storage gadget driver. If your target board is booted into linux and you have the USB OTG cable connected from your target development board to your host development machine then you should be able to mount the FAT partition of the SD card as a removable media device on your host development machine. Then you can copy the "fpga_fft application onto the FAT partition of the SD card. For more information on how to accomplish this refer to this page "Interacting with the USB gadget mass storage interface." Once you have copied the application over to the FAT partition of the SD card, you need to move it into the "/root" directory of the target linux system. So "eject" the USB mass storage device from your host development machine, and mount the FAT partition in you target linux system and copy the application from the FAT partition over to the "/root" directory. For more information on how to accomplish this refer to this page "Interacting with the target file systems." Ultimately this all looks something like this:
  
  
  • First on the host:
    

    [Linux_fft_app]$ mkdir fat_mnt
    [Linux_fft_app]$ sudo mount <SD card FAT parition> fat_mnt/
    [Linux_fft_app]$ cp fpga_fft fat_mnt/
    [Linux_fft_app]$ ls fat_mnt/
    ALTERA_AV_SOC                fft.bin           u-boot.scr
    ALTERA_CV_SOC                fpga_fft          WS1-IntroToSoC
    ARROW_SOCKIT                 hdl_src           WS2-IntroToLinux
    board_info                   ip                WS3-DevelopingDrivers
    boot.script                  MACNICA_HELIO_14  zImage.socfpga-3.10-ltsi
    CRITICALLINK_MITYSOM_DEVKIT  patches
    DE0_NANO_SOC                 rootfs.img
    [Linux_fft_app]$ sudo umount fat_mnt/
    [Linux_fft_app]$ sudo eject -s <SD card FAT parition>
    [Linux_fft_app]$ rm -rf fat_mnt/
    [Linux_fft_app]$

    
    
  • Then on the target:
    

    # mkdir /mnt/fat
    # mount /dev/mmcblk0p1 /mnt/fat/
    # cp /mnt/fat/fpga_fft /root
    # ls /root
    fpga_fft
    # umount /mnt/fat
    # rm -rf /mnt/fat/
    #

    
    
• OPTION 2 - If you cannot or choose not to mount the SD card from your target board directly as a mass storage device, then you can always power off your target board, remove the SD card and insert it into your development host machine using whatever SD card adapter you used to program the SD card image initially. Then copy the "fpga_fft" application over to the FAT partition of the SD card, remove the SD card from your host development machine and insert it back into your target development board and boot the target back into linux. Once you get the target back to a linux prompt you can follow the advice given in the option above to move the "fpga_fft" application from the FAT partition over to the "/root" directory.
  
  
• OPTION 3 - If you would prefer to use "scp" to copy the "fpga_fft" application over to the target "/root" directory over the network connection, you can do this as well. For more information on how to accomplish this refer to this page for general netwoking information "Interacting with the USB gadget networking interface." And refer to this page for "scp" specific information "SCP file copy to target." Ultimately this looks something like this:
  
  
  • On the host:
    

    [Linux_fft_app]$ scp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null fpga_fft root@192.168.7.1:/root/
    Warning: Permanently added '192.168.7.1' (ECDSA) to the list of known hosts.
    
    ********************************************************************
    Welcome to the SoC Workshop
    
    The rootfs is a ram based filesystem built using Buildroot, no changes will survive a reboot
    
    A good place to start is /readme.txt which provides some basic instructions and notes.  To read it, do the following:
    
    less /readme.txt
    
    'q' will quit from the above command
    
    The root password is "password"
    ********************************************************************
    root@192.168.7.1's password: 
    fpga_fft                                      100%   23KB  23.3KB/s   00:00    
    [Linux_fft_app]$

Now we can run the linux application on the target development board. The application takes two parameters when it is started, the first parameter specifies the waveform type, pass in 0 for square waves and pass in 1 for sine waves. The second parameter is the number of samples that are passed through the FFT hardware, this number must be a power of 2 between 128 and 4096.

To run the progam, on the target you should change directory into the "/root" directory that the application was copied into.

# cd /root
#

Then we can run the program like this, we will try square waves with 128 samples first:

# ./fpga_fft 0 128

As the program runs, it prints out all the sample input data and the real and imaginary results from the FFT computation to the console as text, it is also possible for us to view this data graphically if we can connect a web browser to the target development board and point it to the /fft.sh script. This looks something like this:

Now lets try the program with sine waves and 256 samples:

# ./fpga_fft 1 256

And in our browser if we click the reload sample values button, we should see the new data appear:

If you need some advice on getting your target board connected to your host development machine over the network so that you can view the webpage results, you may refer to this page "Interacting with the USB gadget networking interface." Or this page "Interacting with the RJ-45 Ethernet network interface.".

Workshop Lab Validation

Jump to Workshop Main Page | Return to Lab Intro | Return to Lab 3: Bare Metal FFT Application | Show All Steps

If you would like to prove to your Altera representative that you have successfully completed the Workshop 1 lab work, please do the following.

An application is provided on the target linux environment called "/examples/fft/ws1_lab_validator". This program is expected to be invoked from a directory containing the "fft.bin" and "fpga_fft" applications that you created during the lab work. If you have successfully worked through the 4 labs in Workshop 1, then you should have "fpga_fft" in the "/root" directory of your target already, and you should have "fft.bin" on the FAT partition of the target SD card. So move the "fft.bin" file over to the "/root" directory and run the "/examples/fft/ws1_lab_validator" program from the "/root" directory. This would look something like this:

# ls /root
fpga_fft
# mkdir /mnt/fat
# mount /dev/mmcblk0p1 /mnt/fat/
FAT-fs (mmcblk0p1): Volume was not properly unmounted. Some data may be corrupt. Please run fsck.
# cp /mnt/fat/fft.bin /root/
# umount /mnt/fat/
# rm -rf /mnt/fat
# ls /root
fft.bin   fpga_fft
# cd /root
# /examples/fft/ws1_lab_validator
Validation Complete
Please forward these validation files to prove that you completed the lab work:
validation_archive.tar.gz
validation_archive.tar.gz.sign
#

The "/examples/fft/ws1_lab_validator" program attempts to run your "fpga_fft" application and verify the results expected from the default implementation of the program, and then it collects a number of statistics about the environment and creates an archive of the information and cryptographically signs the archive. When it is complete you should see the two files "validation_archive.tar.gz" and "validation_archive.tar.gz.sign" in your "/root" directory if that is where you invoked "/examples/fft/ws1_lab_validator" from.

Email the two files "validation_archive.tar.gz" and "validation_archive.tar.gz.sign" to your Altera representative for verification.