1.1. Prerequisites

You need the following devices.

  • Training server

    • Ubuntu Linux 16.04 (x86_64)
    • NVIDIA GPU with Architecture > Fermi (2.1)
    • NVIDIA drivers >= 367.48
    • Docker >=1.12 (or >=17.03.0)
    • nvidia-docker >= 2.0


    Training by Blueoil is run on docker container with original docker image based on NVIDIA’s CUDA images (cuda:8.0-cudnn6-devel).

    The machine running the CUDA container only requires the NVIDIA driver, the CUDA toolkit doesn’t have to be installed.

    Please see the detail in the nvidia-docker’s prerequisites.

  • Your PC

    • MicroSD card reader
    • Installed xterm program


    When you create Linux system on microSD card, you need a host system (Your PC). Also if you run inferences on the FPGA and you need to display inference results, you should connect the host and the FPGA over the LAN.

  • FPGA Board
    For runtime board, we support the following

1.2. Install / Uninstall Blueoil

This section describes how to setup an environment to train a neural network and convert to FPGA ready format by Blueoil.

1.2.1. Install (On server)

Note: Install nvidia-docker before installing Blueoil.

1.2.1.1. Download Blueoil source code from github

Clone the Blueoil repository with recursive option.

$ git clone --recursive [this repository]

You should run below to update some submodules if cloned without recursive option.

$ git submodule update --init --recursive

1.2.1.2. Build the docker image including Blueoil libraries

$ cd blueoil
$ ./docker_build.sh

After the build has succeeded, you can use the docker image named [User ID]_blueoil:local_build

1.2.2. Uninstall (On server)

Remove docker image, container and the blueoil directory.


1.3. Setup an FPGA Board

This section describes how to setup an environment to run the library generated by Blueoil on a DE10-Nano (SoC FPGA) board. You need a PC which has microSD card reader. All example commands are in case you use Linux or macOS. If you use other system, commands will have some differences.

1.3.1. Download Linux system image (On your PC)

You can download the Linux system image updated for Blueoil from the following.

$ wget https://s3-ap-northeast-1.amazonaws.com/leapmind-public-storage/os_images/de10nano_ubuntu.img.gz

Downloaded file contains the “de10nano_ubuntu.img”. Please set the empty microSD card (8GB+) into your PC and write the downloaded image to microSD card as below.

$ cat de10nano_ubuntu.img.gz | gunzip | sudo dd of=/dev/mmcblk0 bs=4M

Caution & Note:

  • In Linux
    • Please unmount the microSD with umount command before writing
    • /dev/xxx might have a different name, so please confirm the name in the target microSD
  • In macOS
    • Please unmount the microSD with diskutil command before writing
    • /dev/xxx might have a different name, so please confirm the name in the target microSD
    • bs option of dd command should be changed to bs=4m

Please unset the microSD from your host system after dd && sync operation has been finished.

You can also create a Linux system from Terasic’s official web site image. If you need, please see ‘Create Linux system on microSD card’.

1.3.2. Connect to the FPGA board (On your PC)

Connect the board to your host system using the mini-b USB cable. Login to the board with serial communication.

$ sudo cu -l  /dev/ttyUSB0  -s 115200

Connected.

Ubuntu 16.04.1 LTS DE10_NANO ttyS0

You can login by below user.

  • User name: root
  • Password: (nothing)

Once the user boots the board with this image, around 300 MB will be available. But if the user wants to expand the root partition to fill the whole free space available they can do this on the FPGA board:

root@DE10_NANO:~# cd ~
root@DE10_NANO:~# ./expand_rootfs.sh
root@DE10_NANO:~# partprobe /dev/mmcblk0
root@DE10_NANO:~# ./resize2fs_once

1.4. [OPTIONAL] Create your own Linux image on microSD card

NOTE: if you have already used the provided OS image per ‘Setup an FPGA Board’, there is no need to go through this section. This is only for someone who wants to build from the original OS image.

1.4.1. Download Terasic’s official system image (On your PC)

The original image is available from the Terasic’s official web site. please follow the link as below:

  1. Go to Terasic’s official web site
  2. Select “Products”
  3. Select “DE10-Nano Kit”
  4. Select “Resources”
  5. Select “Linux BSP (Board Support Package): MicroSD Card Image”
  6. Select “Linux LXDE Desktop (kernel 4.5)”

Note: A user registration is required to download the image.

Downloaded file contains the “DE10_Nano_LXDE.img”. Please set the empty microSD card into your system and write the downloaded image to microSD card as below.

$ sudo dd if=DE10_Nano_LXDE.img of=/dev/mmcblk0 bs=4M && sync

Please unset the microSD from your host system after dd && sync operation has been finished. And please set the microSD again for further operations.

1.4.2. Update some files for Blueoil (On your PC)

We need to update some files on the microSD. To update it, we need to perform some copy operations.

REQUIRED_FILES are shown in the following list. These files are necessary in later step.

{Blueoil directory}/dlk/hw/intel/de10_nano/
 ├── linux_kernel/zImage
 ├── linux_kernel/kernel_modules.tar.gz
 ├── qconv_with_kn2row/soc_system.dtb
 ├── qconv_with_kn2row/soc_system.rbf
 ├── qconv_with_kn2row/preloader-mkpimage.bin
 └── qconv_with_kn2row/dma/terasic_ubuntu_arm32/udmabuf.ko

Copy the required files to the REQUIRED_FILES directory.

$ cd {Blueoil directory}/hw/intel/de10_nano/
$ cp linux_kernel/zImage linux_kernel/kernel_modules.tar.gz qconv_with_kn2row/soc_system.dtb qconv_with_kn2row/soc_system.rbf qconv_with_kn2row/preloader-mkpimage.bin qconv_with_kn2row/dma/terasic_ubuntu_arm32/udmabuf.ko REQUIRED_FILES/

Note: u-boot.scr does not need updating.

And the actual copy operations should be executed as below. It’s assumed that all required files are put on the REQUIRED_FILES directory.

$ cd REQUIRED_FILES
$ mkdir /media
$ mount -t vfat /dev/mmcblk0p1 /media
$ cp zImage /media
$ cp kernel_modules.tar.gz /media
$ cp soc_system.dtb /media
$ cp soc_system.rbf /media
$ dd if=preloader-mkpimage.bin of=/dev/mmcblk0p3 && sync
$ cp udmabuf.ko /media

Caution & Note:

  • In Linux
    • /dev/xxx might have different name and please make sure the device name of target microSD
  • In macOS
    • /dev/xxx has different name and please make sure the device name of target microSD

1.4.3. Load a kernel module automatically (On FPGA board)

This section is to make linux load udmabuf.ko automatically in boot.

First, login to FPGA board and you should delete old kernel modules and replace it with the old ones:

$ rm -rf /lib/modules/*
$ mount -t vfat /dev/mmcblk0p1 /media
$ tar xvzf /media/kernel_modules.tar.gz -C /lib/modules

Second, we need to put udmabuf.ko into specified directory.

$ cp /media/udmabuf.ko /lib/modules/4.5.0/kernel/drivers/misc/

Third, update kernel modules with:

$ echo "udmabuf" >> /etc/modules
$ depmod
$ reboot

1.5. Install required packages

Login to FPGA board and update required packages.

$ apt-get update
$ apt-get install python-dev python-setuptools python-pip unzip

1.6. Other Information

  • Network of the FPGA board is initially set up as DHCP network.