yunqu/pynq-boot.md

## pynq-boot.md

      
    Raw
  

              pynq-boot.md
            
          
    Quick Steps to Modify Device Tree

This document covers the simple steps to modify an existing device tree
in a Petalinux-generated boot partition. For detailed information, you can
refer to
the steps on Xilinx Wiki page.
Note starting from image v2.3, the customized boot steps are no longer supported
by the PYNQ SD build flow. Instead, Petalinux will be used to generate the boot
partition. Petalinux has certain requirements on the boot files; the resulting
boot files needed are only:

BOOT.BIN, which contains the FSBL, the boot bitstream, and the u-boot.
image.ub, which contains the linux kernel (zImage) and device tree (system.dtb)

To change the device tree for boot, you will have to recompile
system.dtb and then image.ub. Fortunately, this does not take too much time,
and you can do this on your PYNQ image (e.g. Pynq-Z2 board) pretty quickly.
Step 1: Get file from PYNQ SD build flow

We only need to take two files from the host machine:

image.its
zImage

There files can be found in the PYNQ build folder after building the PYNQ image
boot partition. For instance, after running
cd /opt/builds/PYNQ_rock/sdbuild
make boot_files /opt/builds/PYNQ_rock/boards

The 2 files can be located at /opt/builds/PYNQ_rock/sdbuild/build/Pynq-Z2.
You can find other relevant files, but I will ignore the discussion.
Step 2: Install proper tools

You will need to install those tools on your board.
sudo apt-get install -y u-boot-tools device-tree-compiler

After installation you should be able to check the running device tree on
your OS:
cd /home/xilinx
dtc -I fs /proc/device-tree > device-tree0.dts

Step 3: Mount boot parition

Let's examine the binaries in your boot partition. To access those files easily,
let's mount the boot parition. Make sure you are running the following as root.
mount /dev/mmcblk0p1 /mnt
cd /mnt

You will see BOOT.BIN and image.ub.
Step 4: Look into image.ub

We can check what are wrapped in image.ub.
dumpimage -l image.ub

An example output:
FIT description: U-Boot fitImage for PYNQ arm kernel
Created:         Tue Apr 23 22:40:28 2019
 Image 0 (kernel@0)
  Description:  Linux Kernel
  Created:      Tue Apr 23 22:40:28 2019
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    4470640 Bytes = 4365.86 kB = 4.26 MB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x00080000
  Entry Point:  0x00080000
  Hash algo:    sha1
  Hash value:   8b126520622019db23bc61b0d3fdae2cda2f04cb
 Image 1 (fdt@0)
  Description:  Flattened Device Tree blob
  Created:      Tue Apr 23 22:40:28 2019
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    14785 Bytes = 14.44 kB = 0.01 MB
  Architecture: ARM
  Hash algo:    sha1
  Hash value:   49d239bf7175c14cb2b5d7b6210370e41c212bfd
 Default Configuration: 'conf@1'
 Configuration 0 (conf@1)
  Description:  Boot Linux kernel with FDT blob
  Kernel:       kernel@0
  FDT:          fdt@0

As you can see, Image 0 is the kernel while Image 1 is the flattend device tree (fdt).
Step 5: Extract device tree

You can extract the flattend device tree (use -p 1 since it is Image 1).
dumpimage -T flat_dt -p 1 -i image.ub device-tree1.dtb

Use dtc to de-compile it into user-readable format:
dtc -I dtb -O dts -o device-tree1.dts device-tree1.dtb

Now you should be able to read the content in device-tree1.dts.
Step 6: Modify device tree

Before we modify the device tree, maybe it is a good idea to backup the original
files such as BOOT.BIN and image.ub. Make sure you have these 2 files
backed up in your host machine.
Now let's change the system.dts, which is to be baked into image.ub.
cp device-tree1.dts system.dts

Make changes to system.dts. For example, I added
	status="disabled";

for a specific entry.
Step 7: Recompile device tree

After the change, you are able to recompile the device tree.
dtc -I dts -O dtb -o system.dtb system.dts

Now you can use image.its to package up image.ub. Make sure you have
the following files in the same folder: image.its (copied from host machine),
system.dtb (just recompiled), and zImage (copied from host machine).
You can check the contents of image.its to better understand the flow.
mkimage -f image.its image.ub

This command will make a new image.ub.
If all the above command are run in /mnt, your boot parition will get an updated
image.ub. You should be able to reboot using it:
reboot

Step 8: Check results

After boot, check the new device tree:
cd /home/xilinx
dtc -I fs /proc/device-tree > device-tree2.dts

You will be able to see your changes in the running device tree.
diff device-tree0.dts device-tree2.dts

Summary

For the above steps, if you are playing with the device tree and bitstream
repeatedly, you will notice that steps 1, 2, 4, and 8 are not required all
the time. You can adjust this flow for faster debugging purpose.