soc

The repository contains:

• A Linux driver which supports:
  • mmap: map a memory between user space and kernel space
  • ioctl:
    • copy a memory between kernel space (PS's storage) and a peripheral's storage (PL's storage)
    • write neural network accelerators' registers to drive it to process
• A Linux application which will be started automatically when OS booted.
  • communicate with center board to download images
  • call driver to process images to get the processed bit streams
  • entropy encode the bit streams
  • communicate with center board to upload the bit streams

Linux driver and Linux application share axitangxi_ioctl.h.

The repository doesn't contain:

• the code to build FPGA's *.bit
• the code to train neural network and generate weight.bin and quantify.bin, please see https://gitlab.com/iWave/iwave

Build for Local Machine

Dependencies:

• modules
  • make
  • linux-headers
• apps
  • meson
  • pkg-config
  • google test: optional, for unit test

Some required binary files *.bin can be seen here.

# modules
make
# apps
meson setup project-spec/meta-user/recipes-apps/autostart/build project-spec/meta-user/recipes-apps/autostart
meson compile -Cproject-spec/meta-user/recipes-apps/autostart/build

Cross Compile for Develop Board

Dependencies:

• vitis: contains vivado.
  • source /opt/xilinx/vitis/settings.sh
• petalinux
  • source /opt/petalinux/settings.sh
• minicom or picocom: optional, serial debug

Create a Project

petalinux-create -tproject -nsoc --template zynqMP
cd soc
# download source code to `soc/`
git clone --depth=1 --bare https://github.com/ustc-ivclab/soc .git
git config core.bare false
git reset --hard

You can create a new project from the old project:

scripts/copy-project.sh ../soc

Then refer Configure to run scripts/config.sh.

Configure

Binary files

Before building, some required binary files can be downloaded from Release:

• system.xsa: a zip file compressing FPGA's *.bit and some generated tcl/c files, which is called as hardware description file
• weight.bin: weight factors of neural network
• exp.bin: gauss function factors for speeding up entropy encoding
• cdf.bin: cdf function factors for speeding up entropy encoding

Currently, system.xsa has hard encoded some coefficiences, so the following files are unnecessary temporally:

• quantify.bin: quantification coefficiences

Third-party Files

To speed up building, you need to download:

• u-boot-xlnx
• linux-xlnx
• https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html:
  • downloads
  • aarch64 sstate-cache

Then extract them to some paths. Refer assets/configs/example/config to modify these paths.

install -Dm644 /the/path/of/system.xsa -t project-spec/hw-description
install -Dm644 /the/path/of/{weight,cdf,exp}.bin -t project-spec/meta-user/recipes-apps/autostart/assets/bin
# wait > 60 seconds
# for initramfs
scripts/config.sh assets/configs/config assets/configs/example/config
# for SD
scripts/config.sh assets/configs/config assets/configs/example/config assets/configs/sd/config
# for eMMC
scripts/config.sh assets/configs/config assets/configs/example/config assets/configs/emmc/config

Build

Every time source code is modified, you need to rerun:

# on the first time it costs about 1 hour while it costs 2.5 minutes later
scripts/build.sh

Burn

You need a parted SD card:

sudo scripts/part-disk.sh /dev/sdb assets/sfdisk/example.yaml

Dependencies:

• util-linux
• dosfstools
• e2fsprogs

Insert the SD card to your PC. For eMMC, make sure the SD card has been burn.

Run:

# wait > 10 seconds
scripts/burn.sh

Then:

1. insert the SD card to your board
2. set the switch to ↓↑↓↑ for xzcu7ev1517 or ↑↓↑↓ for xzcu7ev1156
3. reset the board. The next steps are for eMMC:
4. run post-burn-emmc.sh
5. set the switch to ↑↓↓↑
6. reset the board
7. pull out the SD card

Usage

PC

# run the following commands in different ttys
# create two connected fake serials
socat pty,rawer,link=/tmp/ttyS0 pty,rawer,link=/tmp/ttyS1
main -dt/tmp/ttyS0
master -t/tmp/ttyS1 /the/path/of/test.yuv
# display log
journalctl -tslave0 -tmaster -fn0

Embedded

# run the following commands in different ttys
# open serial debug helper to see information
# assume your COM port is /dev/ttyUSB0
minicom -D/dev/ttyUSB0
# assume your COM port is /dev/ttyUSB1
master /the/path/of/test.yuv
# display log
journalctl -tmaster -fn0

Debug

App

Add example kconfig to kconfig.

Add the following code to rootfs_config:

CONFIG_autostart-dbg=y

Rebuild and reburn it.

Connect board and PC by a WLAN, then add IP address in board and PC, such as:

Board:

ip a add 192.168.151.112/24 dev eth0
gdbserver 192.168.151.112:6666 main

PC:

cgdb -darm-none-eabi-gdb

Hardware description file

You can generate an example system.xsa which doesn't contain the code of neural network.

Make sure vivado and xsct in your $PATH.

# wait about 4 minutes
hw/generate-xsa.tcl
# test, it can be skipped
hw/test-xsa.tcl
cp hw/build/project/system.xsa project-spec/hw-description

Documents

• 图像压缩软件设计报告大纲: written by Cheng Ran
• 搭载板图像加速处理软件与中心机的串口传输协议: written by Li Yunfei
• 基于 linux 系统上与 tangxi 芯片通信的 AXI 驱动: written by Wang Yang
• 数据格式: written by Tao Jie

References

• Vivado
  • vivado system level design entry
  • vivado tcl commands
• Vitis
  • vitis embedded
• PetaLinux
  • petalinux-tools-reference-guide
  • Embedded-Design-Tutorials
  • PetaLinux Yocto Tips
• Linux Driver
  • Linux-Device-Driver
  • Linux 设备驱动程序
• Device Tree
  • devicetree specification
  • Device Tree Usage