1.1. Prerequisites

You need the following devices.

  • Training server

    • Ubuntu Linux 18.04 (x86_64)

    • NVIDIA GPU with Architecture >= 3.0 (Kepler)

    • NVIDIA drivers >= 410.48

    • Docker >= 19.03

    • nvidia-container-runtime >= 3.2

    Training by Blueoil is run on docker container with original docker image based on NVIDIA’s CUDA images (cuda:10.0-cudnn7-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-container-runtime’s document.

  • Your PC

    • MicroSD card reader

    • xterm program installed

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

  • FPGA Board
    We currently support the following

    • DE10-Nano Kit (Base Ubuntu 16.04, distributed by Terasic, Ubuntu 18.04 as customized)

1.2. Install / Uninstall Blueoil

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

1.2.1. Install (On server)

Note: Install nvidia-docker before installing Blueoil. Download Blueoil source code from github

Clone the Blueoil repository with recursive option.

$ git clone --recursive [Blueoil repository]

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

$ make deps Build the docker image including Blueoil libraries

$ cd blueoil
$ make build

After the build has succeeded, you can use the docker image named blueoil_[User ID]:[TAG based on commit tag]

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 a microSD card reader. All example commands should work if you use Linux or macOS. If you are using a different system, the necessary commands may be different.

1.3.1. Download Linux system image (On your PC)

You can download an up-to-date-for-Blueoil Linux system image by:

$ wget https://storage.googleapis.com/blueoil-asia-northeast1/os-images/de10nano/ubuntu1804/v0.3/de10nano_ubuntu_1804.img.gz

The downloaded file should contain the image “de10nano_ubuntu_1804.img”. Insert an empty microSD card (8GB+) into your PC and write the downloaded image to it.

  • Using Etcher [Recommended]

    • We recommend using the open source software Etcher to help you write the image on any platform.

  • Using Linux terminal

    • Make sure to unmount the microSD with umount command before writing.

    • Confirm the path name of the target microSD. It should be /dev/[your_target_name].

    • Type the following command:

$ cat de10nano_ubuntu_1804.img.gz | gunzip | sudo dd of=/dev/[your_target_name] bs=4M
  • Using macOS terminal

    • Make sure to unmount the microSD with diskutil command before writing.

    • Confirm the path name of the target microSD. It should be /dev/[your_target_name].

    • To make the process faster, append an r in front of [your_target_name].

    • Type the following command:

$ cat de10nano_ubuntu_1804.img.gz | gunzip | sudo dd of=/dev/r[your_target_name] bs=4m

Remove the microSD from your host system after the operation have finished.

You can also create a Linux system using an image from Terasic’s official website. Please refer to ‘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 a mini-b USB cable. Login to the board via serial.

  • On Linux

    • The path name of your FPGA board should look similar to /dev/ttyUSB0.

  • On macOS

    • The path name of your FPGA board should look similar to /dev/tty.usbserial-A106I1IY.

First, change the permission of your board to 666.

$ sudo chmod 666 /dev/[your_fpga_board]

On Linux, if you don’t want to change it every time, you can also do the following. You can use the lsusb command to check the vendor id and product id of your board(like XXXX:YYYY). Then edit /etc/udev/rule.d/50=usb=serial.rules like below.

SUBSYSTEM=="tty", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0666"

After you change the permission of your board, you can connect via serial.

$ sudo cu -l  /dev/[your_fpga_board]  -s 115200


Hit enter, and you can login using the following information:

  • User name: ubuntu

  • Password: ubuntu

When the board is booted with the above image, around 300 MB will be available. But if one wants to expand the root partition to fill the whole free space available they can do this by running the following commands:

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 Terasic’s official web site.

  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: User registration is required to download the image.

Downloaded file contains “DE10_Nano_LXDE.img”. Please insert an empty microSD card into your system and write the downloaded image to it.

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

Please remove 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 them, we need to perform a few copy operations. Please download sample files.

$ wget https://storage.googleapis.com/blueoil-asia-northeast1/de10_nano_sample.tar.gz
$ tar xzvf de10_nano_sample.tar.gz

REQUIRED_FILES are shown below. These files are necessary for a later step.

{Working directory}/de10_nano_sample/
 ├── linux_kernel/zImage
 ├── linux_kernel/kernel_modules.tar.gz
 └── dma/terasic_ubuntu_arm32/udmabuf.ko

{Blueoil directory}/output_files/fpga/
 ├── preloader-mkpimage.bin
 ├── soc_system.rbf
 └── soc_system.dtb

Create and copy the required files to the REQUIRED_FILES directory.

$ cd {Working directory}/de10_nano_sample/
$ cp linux_kernel/zImage linux_kernel/kernel_modules.tar.gz dma/terasic_ubuntu_arm32/udmabuf.ko REQUIRED_FILES/
$ cd {Blueoil directory}/output_files/fpga/
$ cp soc_system.dtb soc_system.rbf preloader-mkpimage.bin 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 in the REQUIRED_FILES directory.

$ 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


  • /dev/xxx might have different name, so one should confirm 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 during boot.

First, login to the FPGA board, delete old kernel modules and replace them with new 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 the correct 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 the FPGA board and update required packages.

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

1.6. Other Information

  • Initially, networking on the FPGA board is set-up for use with DHCP.