Implementing the DPU on a SD card image

After finishing the Vivado project, it's time to implement the designed Hardware (the DPU) on a SD card image. To do that we will use a Xilinx software called Petalinux. It allows to create a SD card image with the Linux Operating System and the packages and libraries we want, and it also holds the DPU hardware information to be sent to the Zynq-7020 chip. This image will be flashed on an actual Micro SD card and later to be inserted on the PYNQ-Z2.

To use Petalinux we will resort to a Virtual Machine (VM) because it allows to make configurations without damaging the native OS. If you don't know what a VM is, it basically represents a computer running on your computer. In other words, you can have a different OS running on your computer. On this case you have a Windows OS on the computer (That is called the Host machine) and you will need to run a Ubuntu OS on as a program on the host computer (this is the Guest Machine).

Virtual Machine Set up

VirtualBox installation

For this project we are going to use the Virtual Machine Software VirtualBox. To install VirtualBox follow this steps:

Go to VirtualBox website here.
Click the link that says "Windows hosts".
After the download is complete, run the execution file.
Proceed with the installation.

Now you have the VirtualBox icon on the Desktop and you are able to create multiple virtual machines on your computer.

Of course you could use other program for the Virtual Machine! I just used this one for convenience but VMware could be another option. Should be interesting to explore other options which enable all instruction sets from the CPU so we could also use DNNDK on a VM.

Creating the virtual machine

We now need to create the virtual machine running the Ubuntu OS. To do that, first we need to download the Ubuntu 18.04.2 disk image from the old releases website. You want to select the "ubuntu-18.04.2-desktop-amd64.iso". In alternative, just use the link on the box:

The .iso file is almost 2GB in size so it will take time to download. But, after the download, you can now open VirtualBox and click "New" to create a new virtual machine.

Next step, we are going to give a name for the Virtual Machine, for example, "Petalinux" because that's what we will be working with. Then we select the folder where the files will be stored (you can leave the default option). Before proceeding, we have to select the .iso file we just downloaded so the system knows it is Ubuntu 18.04.

Next, we want to set the username and it can be whatever you like, for example your name. Then the password you can set it to something simple as security here is not something very important. The Hostname you can leave as Ubuntu or Petalinux or whatever you desire.

Next we need to select the resources. My computer is not very powerful so I have more limitations. You can play here a little bit but I would recommend half the resources on the CPU and memory to be safe.

Next we need to allocate some disk space for the Ubuntu Desktop on the host PC. You should be fine to select 60GB but to be on the safe side I allocated 70GB.

Now the window shows the summary and you can check every setting. Then we only need to press "Finish" to effectively create the Virtual Machine.

From here I am pretty sure the VM will start automatically an you will be asked to proceed with the Ubuntu installation. All you need to do is to perform the normal installation (do not select minimal installation) and after that you just need to log in to the username you set with the respective password.

Every time you need to use the Ubuntu VM you just open VirtualBox, select Petalinux and click on "Start".

If you ever run out of Disk Space on the Virtual Machine, you can go to "Tools" -> "Properties" -> select the new disk space on the bottom.

Ubuntu Setup

Ubuntu is now available on a virtual machine on your computer. Good job!

Beaware when there is a warning recommending the OS update you have to refuse it! The Ubuntu version should not be changed. Click "Don't upgrade" and then "Cancel".

The next step is to install "Guest Additions" on the Operating System. This package is from VirtualBox and it enables some very important features like the ability to use the same clipboard and to maximize the window size. The clipboard will be shared by the Host OS (Windows) and the Guest OS (Ubuntu), enabling you to copy and paste text, images and files between them.

To install guest additions you open Ubuntu, log in and then click on "Devices" on the top bar, and after that click the screwdriver icon.

Note that the image was taken after installing Guest Additions. On the first time it should display the screwdriver without any text associated.

You need to authorize the program to run on the Terminal. It will install all the necessary stuff and after that I would recommend to restart the VM.

After restating the VM, you can enable the maximization of the Ubuntu screen by clicking on "view" on the top bar and then "Auto-resize Guest Display".

The next step is to set the user as the administrator of operating system.

The Ubuntu administrators are called "Suddoers", resembling the command "sudo" which enables to run programs as the admin.

First you need to open the Terminal (it's like the console on Windows). I recommend you add the Terminal to the favorites as it will be used a lot.

On the Terminal, you have to first access the root directory that contains some important files of the OS. To do that you run the command su root. It will ask for your user password and you write it (it's the one you use on log in) and then press ENTER.

Then you need to access the "suddoers" file and open it:

nano /etc/sudoers

The file will be open and now you need to move the cursor bellow "User privilege specification" and insert your username as well as all the permissions. You can do it like this:

# User privilege specification
root    ALL=(ALL:ALL) ALL
<user> ALL=(ALL:ALL) ALL

Don't forget to change the name "<user>" to you user name!

After defining the user as admin, now we need to save the modifications to the file. You can do it by following this steps:

CNTRL + O (To save content);
ENTER (To confirm save);
CNTRL + X (To leave editing);
Write "exit" on the terminal to leave the root directory and get back to normal;

Congratulations! You are now a suddoer!

Petalinux Installation

The installation process of this specific Petalinux version is well documented on the respective User guide from Xilinx. You can consult it if you want to get more details.

Now comes the part where we have to install Petalinux on the OS. Before starting, you have to download Petalinux 2019.2 from the website (Version compatible with the Vivado files). The following link leads you to the download:

You have to create an AMD account to download this and other software! In case you are wondering, yes, Xilinx is part of AMD now.

You will have to select the version 2019.2 installer that is 7,92GB. Download the file and meanwhile we will complete other requirements.

First you need to update the Operating System using these two commands:

sudo apt update
sudo apt upgrade

Then you have to install a set of required packages as said on the user manual:

sudo apt install htop vim openssh-server iproute2 gcc g++ net-tools libncurses5-dev zlib1g:i386 libssl-dev flex bison libselinux1 xterm autoconf libtool texinfo zlib1g-dev gcc-multilib build-essential screen pax gawk python3 python3-pexpect python3-pip python3-git python3-jinja2 xz-utils debianutils iputils-ping libegl1-mesa libsdl1.2-dev pylint3 cpio chrpath socat python -y

After that, it's needed to upgrade PIP (Python manager for Python Packages):

pip3 install --upgrade pip

Then we will create a directory to store the Petalinux files using the command mkdir:

sudo mkdir -p /opt/petalinux/

We defined the directory as opt/petalinux but you can create it anywhere else like on the "tmp" directory.

Now we need to give permissions to access the newly created folder using the chmod command:

sudo chmod 755 /opt/petalinux/

Next we give permissions to the user about that directory so we can view and edit it:

sudo chown -R <user> /opt/petalinux/

Don't forget to change "<user>" with your Ubuntu username.

Next, we wait for the Petalinux download. When it is ready, we can proceed and enter it's directory using the cd command (I will assume it is on the Downloads directory):

cd Downloads

Now we give permissions to the newly installed file using the chmod command:

sudo chmod 755 petalinux-v2019.2-final-installer.run

Then you execute the installer on the petalinux directory created earlier:

./petalinux-v2019.2-final-installer.run /opt/petalinux/

Next, we have to change the system from dash to bash. This simply means that the Terminal goes to a new mode where there are more commands as the Petalinux might use some of them. To do this, you first write this line:

chsh -s /bin/bash

Now you RESTART your Virtual Machine. You simply do it as you would restart the Ubuntu on the top right corner.

Now, to effectively reconfigure the system to bash, we do the following command and then press "NO".

sudo dpkg-reconfigure dash

Now everything is ready and you have successfully installed Petalinux, congratulations! Now, every time you want to start Petalinux, you have to do this command:

source /opt/petalinux/settings.sh

Don't forget to use this command to start Petalinux in the future! I know you will forget, trust me ;)

Petalinux Project

This part of the project was pretty much based on the Jin-Chen's tutorial on Petalinux that you can find here. I would also recommend to check the Petalinux 2019.2 Use Guide if you want to get more details.

For this part you should copy the repository files under the DPU implementation folder or the files you just created on vivado to the Ubuntu virtual machine desktop. They will be needed here.

Project configuration

Now comes the part where we create a Petalinux project that will contain all configurations and files for the SD card image. To start, we need to create a folder to store all the necessary project files. You can create a folder on the Desktop directory with the "mkdir" command on the terminal or using the Ubuntu interface. As you might expect you can directly create a folder by right clicking on the Desktop and then "new folder". The name of the folder is arbitrary but I called it "DPU_integration".

After that I need you to go to that newly created directory using the "cd" command.

cd Desktop/dpu_integration

Before doing the next steps, make sure you start Petalinux using the command:

source /opt/petalinux/settings.sh

Now we create the Petalinux project on which we will call "pynqz2_dpu" based on the Zynq template:

petalinux-create --type project --template zynq --name pynqz2_dpu

Next, we need to go to the Petalinux project directory. It's here where all the important stuff will be done.

cd pynqz2_dpu/

Now, I need you to copy and paste the Vivado project with all the files to the Ubuntu VM. As we installed Guest Additions earlier, you can do it directly. We will be needing the ".xsa" file.

After you have the Vivado project on the VM (you can place it on the Desktop for convenience), we can now base the Petalinux project according to the DPU Hardware. On the final part, you have to place the path to the ".xsa" file.

petalinux-config --get-hw-description=/home/andre/Desktop/VivadoDPU/pynqz2_dpu

You will be presented on a nice little menu. Here is how you can work on this configuration interface:

Here you can navigate the options using the up and down arrows;
To change between "select", "exit", "save" and "load" you can use the left and right arrows;
To select sub-menus you can press ENTER;
To enable things you press "y" and to disable things you press "n";

Now I need you to access this settings and disable the option:

DTG Settings->Kernel Bootargs->disable generate boot args automatically

On "user set kernel bootargs", paste the following:

console=ttyPS0,115200 root=/dev/mmcblk0p2 rw earlyprintk quiet rootfstype=ext4 rootwait cma=256M

Next thing you need to change the image to EXT4 type because that is the Linux type. To do that you go to this menus and put "y" to enable EXT4:

Image Packaging Configuration->Root filesystem type (EXT4 (SD card))

After that, you exit the configuration and save changes.

Then, we need to change the content of a file. To access it you use the command gedit:

gedit project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi

On this blank file I need you to paste the following code:

/include/ "system-conf.dtsi"
&amba {
xlnk {
compatible = "xlnx,xlnk-1.0";
};
};
&amba{
dpu{
#address-cells = <1>;
#size-cells = <1>;
compatible = "xilinx,dpu";
base-addr = <0x4f000000>; //CHANGE THIS ACCORDING TO YOUR DESIGN
dpucore {
compatible = "xilinx,dpucore";
interrupt-parent = <&intc>;
interrupts = <0 29 4>; //CHANGE THIS ACCORDING TO YOUR DESIGN
core-num = <0x1>; //CHANGE THIS ACCORDING TO YOUR DESIGN
};
};
};
//usb device tree
/{ 
usb_phy0: usb_phy@0 {
compatible = "ulpi-phy";
#phy-cells = <0>;
reg = <0xe0002000 0x1000>;
view-port = <0x0170>;
drv-vbus;
};
};
&usb0 {
dr_mode = "host";
usb-phy = <&usb_phy0>;
};

Don't forget to save what you pasted on the file using the save button on the top right.

Now I need you to download the following file, containing some important content to the DPU.

https://www.xilinx.com/member/forms/download/design-license-xef.html?filename=zcu102-dpu-trd-2019-1-190809.zipwww.xilinx.com

We need to copy some of the files from the downloaded package, specifically some stored on a ".bsp" file. To open that specific file we will need to download a program called "7-Zip". It easier than it seems, you go to this path on the downloaded file:

/zcu102-dpu-trd-2019-1-timer/apu/dpu_petalinux_bsp/xilinx dpu-trd-zcu102-v2019.1.bsp

Now, right click on the file and click "Open With Other Application", then click "Find New Applications". You may now write "P7zip" on the search bar and install the right application.

After the installation is complete, you can close the "Ubuntu Software" window and you can go right click on the ".bsp" file again and click on "Open With Other Application" and now select the newly installed application: P7Zip - Desktop.

You want to access the directory that contains the folder "recipes-modules" and to do that you go here:

xilinx-dpu-trd-zcu102-v2019.1/zcu102-dpu-trd-2019-1/project-spec/meta-user/

Then we need to extract the "recipes-modules" file to the home directory (or other you desire). To do it you press on the file, and then on the top bar "extract". You will be presented with the following window where you can select the destination path to /home or the /Desktop, for example:

We want to copy the file "recipes-modules" from the home directory to the "project-spec/meta-user/" directory on the Petalinux project. You can copy by hand using the interface or you can use the following command:

cp -rv ~/recipes-modules/ project-spec/meta-user/

Next step, you need to add echo "CONFIG_dpu" on the last line of the file on the following folder: project-spec/meta-user/conf/user-rootfsconfig.

Then you also need to add this line echo 'IMAGE_INSTALL_append = "dpu"' on the file project-spec/meta-user/conf/petalinuxbsp.conf.

We need to configure the Root filesystem now. This is where we will define the packages that will be on the SD card image OS from the start. This are some important packages that will be important to do some applications later. To do the configuration, you place the following command on the Terminal:

petalinux-config -c rootfs

The fancy menu will appear again but this time we need to activate some packages. You know how this works so I will give you the list and you press "y" to enable them. When you finish, you save the changes and exit.

modules -> dpu
Filesystem Packages -> admin -> sudo, sudo-dev
Petalinux Package Groups → packagegroup-petalinux-python-modules, -dev
Petalinux Package Groups → packagegroup-petalinux-x11, -dev
Filesystem Packages -> console -> utils -> pkgconfig -> pkgconfig, pkgconfig dev
Filesystem Packages -> libs -> gtk+3 -> gtk+3, gtk+3-demo, gtk+3-dev, gtk+3-dbg
Petalinux Package Groups -> petalinuxgroup-petalinux-opencv -> opencv, opencv-dev

Then is time to configure the Kernel. The only thing we need to do here is to activate the USB driver. To access the configuration you write on the terminal:

petalinux-config -c kernel

And then you enable: Device Drivers -> USB support -> [*]USB announce new devices

To finish kernel configuration you write this to the Terminal:

petalinux-build -c kernel -x finish

The final configuration to be done will be to a single file. I need you to access it and clear anything that is written on it. First you do this:

gedit project-spec/meta-user/recipes-kernel/linux/linux-xlnx/devtool-fragment.cfg

Then you clear the text and paste this:

CONFIG_USB_OTG=y
# CONFIG_USB_OTG_FSM is not set
# CONFIG_USB_ZERO_HNPTEST is not set
CONFIG_MEDIA_USB_SUPPORT=y
CONFIG_USB_VIDEO_CLASS=y
CONFIG_USB_VIDEO_CLASS_INPUT_EVDEV=y
CONFIG_USB_GSPCA=m
CONFIG_V4L_PLATFORM_DRIVERS=y
CONFIG_VIDEO_ADV7604=y
CONFIG_USB_HID=y
CONFIG_USB_OHCI_LITTLE_ENDIAN=y
CONFIG_USB_SUPPORT=y
CONFIG_USB_COMMON=y
CONFIG_USB_ARCH_HAS_HCD=y
CONFIG_USB=y
CONFIG_USB_ANNOUNCE_NEW_DEVICES=y
CONFIG_USB_DEFAULT_PERSIST=y
CONFIG_USB_EHCI_HCD=y
CONFIG_USB_EHCI_ROOT_HUB_TT=y
CONFIG_USB_EHCI_PCI=y
CONFIG_USB_EHCI_HCD_PLATFORM=y
CONFIG_USB_ACM=m
CONFIG_USB_PRINTER=m
CONFIG_USB_WDM=m
CONFIG_USB_TMC=m
CONFIG_USB_STORAGE=y
CONFIG_USB_CHIPIDEA=y
CONFIG_USB_CHIPIDEA_OF=y
CONFIG_USB_CHIPIDEA_PCI=y
CONFIG_USB_CHIPIDEA_HOST=y
CONFIG_USB_PHY=y
CONFIG_NOP_USB_XCEIV=y
CONFIG_AM335X_CONTROL_USB=y
CONFIG_AM335X_PHY_USB=y
CONFIG_USB_GPIO_VBUS=y
CONFIG_USB_ULPI=y
CONFIG_USB_ULPI_VIEWPORT=y

All configurations are done and we will build the project. The process can take 30 minutes with my VM resources configuration but according to your computer specs it can take less. Just paste this command on the Terminal:

petalinux-build

After the build process is complete, we need to make the Petalinux software generate the files to be written on the SD card. The next command will do that job:

petalinux-package --boot --force --fsbl images/linux/zynq_fsbl.elf --fpga images/linux/*.bit --u-boot

You can then save a bsp file with all the configurations you done using the next command. This works like a commit, so any changes you do you can save on this files. You can name the file whatever you like but here I called it "pynq-z2-dpu.bsp".

petalinux-package --bsp -p ./ -o pynq-z2-dpu.bsp

SD card image

Now we will need to pass the files we created on Petalinux to the SD car but first we will need to configure it properly. For this, we will use a program called "AOMEI Partition Assistant" and it will run on Windows before moving again to the Ubuntu VM.

https://www.diskpart.com/ss/download/pa/PAssist_Std.exewww.diskpart.com

With the program downloaded you will need to proceed with the installation by clicking the executable and following along. It will be pretty easy, don't worry!

Now, you will need to insert you micro SD card on the adapter and the whole unit on you SD card reader. Most laptops and computers now have an embedded SD card reader but if you don't have one you can buy one for cheap and plug to the USB or USB C port.

Once you got that sorted out, we will open the newly installed application AOMEI Partition Assistant. There will be some disks, normally the computer disk where the Windows OS is stored and also, there should appear the SD card inserted on the SD card reader. In general, on this situation, the disk 0 represents the computer storage and disk 1 is the external storage device (SD card, PEN drive, ...). So, in my case, disk 1 represented the SD card and I could confirm it by looking at the drive letter and storage space. When I insert the card on Windows, it shows it has the driver letter D and as advertised, it has close to 128GB of storage space.

This SD card is just for demonstration purposes. You can use one with this much storage space but it's not needed. For this application a 8GB is more than enough.

Now that you located your SD card on the program, you should right click on the disk and "Delete all partitions". After that you need to go on the top left corner and click "Apply" and confirm so it does the job.

Then we need to create two partitions with different specifications:

128MB partition called "BOOT" with file system FAT32;
Partition called "rootfs" with the rest of the storage space and with file system EXT4;

The process described on the image above is the same for the second partition but with other specific configurations. Don't forget to apply the changes! The process might take some time to finish depending on the SD card size.

When the SD card is ready with two partitions (BOOT and rootfs), we can now go back to the Petalinux project.

With the SD card still inserted on the reader, what we want to do now is make it recognizable by the Ubuntu OS. To do that, you need to open the VM and on the top bar go to "devices", then "USB" and look for a Flash card reader. Note that normally, the SD car readers on Laptops are embedded USB card readers but it could be a smart card reader for example and accessing it on the VM might be a different process.

After clicking the Flash card reader option, the micro SD card will be recognized by Ubuntu and will appear a little icon on the Desktop for each partition. To determine the directory of each partition we right click on the icon and press "Open In New Window". Then we right click on the window and "properties". In parent folder we can see the directory "/media/andre". Generally the SD card will be here so for BOOT we can access trough /media/<user>/BOOT/ and for rootfs /media/<user>/rootfs.

Now, let's go back to the Petalinux project. We want to transfer the configuration files to the BOOT partition so the embedded OS will have the necessary information to start on the desired way. To pass those files you use these commands, where you have to change "andre" with your username:

cp ./images/linux/BOOT.BIN /media/<user>/BOOT/
cp ./images/linux/image.ub /media/<user>/BOOT/

The Linux OS will be presented on the EXT4 format partition. So, we will move and uncompress the necessary folder to that partitions in a similar way to the BOOT partition:

sudo tar xzf ./images/linux/rootfs.tar.gz -C /media/<user>/rootfs/

Lastly, we need to include on the Linux OS the DNNDK files so there can be communication with the DPU later on. To do it you transfer the file "zynq7020_dnndk_v3.1" from the github repo and put them in the VM. Specifically, you should put them on the project directory, namely the "DPU integration" folder.

The file "zynq7020_dnndk_v3.1" came directly from the DNNDK download that we will talk about on the next topic. It included the tools and the drivers to communicate with the DPU. For the PYNQ-Z2 we stole the files dedicated to the ZedBoard as they share the same FPGA.

sudo cp -r ../zynq7020_dnndk_v3.1/* /media/<user>/rootfs/home/root/

To end the process you execute the command syncon the Terminal so you clear the system cache.

Congratulations, you have the micro SD card with a Linux Operating System and the required tools and packages to use the DPU! You may now remove the SD card from the slot and store it somewhere safe.

PreviousCreating the DPU 3.0 NextModel optimization and compilation

Last updated 7 months ago