Exercising FPGA programming using fpgautil

Linux Drivers
Release Date
2023-07-22

Source code for the fpgautil is available in below meta layers.

Note: In 2022.1 release fpgautil source code is moved from meta-xilinx-tools to meta-xilinx/meta-xilinx-core layer.

2022.1 and later release: https://github.com/Xilinx/meta-xilinx/blob/master/meta-xilinx-core/recipes-bsp/fpga-manager-script/files/fpgautil.c

2021.2 and earlier release: https://github.com/Xilinx/meta-xilinx-tools/blob/rel-v2021.2/recipes-bsp/fpga-manager-script/files/fpgautil.c 

root@xilinx-zcu102-2018_3:~# fpgautil -h

fpgautil: FPGA Utility for Loading/reading PL Configuration in zynqMP

Usage:  fpgautil -b <bin file path> -o <dtbo file path>

Options: -b <binfile>           (Bin file path)
         -o <dtbofile>          (DTBO file path)
         -f <flags>             Optional: <Bitstream type flags>
                                   f := <Full | Partial > 
                                Default: <Full>
          -s <secure flags>     Optional: <Secure flags>
                                   s := <AuthDDR | AuthOCM | EnUsrKey | EnDevKey | AuthEnUsrKeyDDR | AuthEnUsrK>
          -k <AesKey>           Optional: <AES User Key>
          -r <Readback>         Optional: <file name>
                                Default: By default Read back contents will be stored in readback.bin file
          -t                    Optional: <Readback Type>
                                   0 - Configuration Register readback
                                   1 - Configuration Data Frames readback
                                Default: 0 (Configuration register readback)
          -R                    Optional: Remove overlay from a live tree
 
Examples:
(Load Full Bitstream using Overlay)
fpgautil -b top.bit.bin -o can.dtbo
(Load Partial Bitstream through the sysfs interface)
fpgautil -b top.bit.bin -f Partial 
(Load Authenticated Bitstream through the sysfs interface)
fpgautil -b top.bit.bin -f Full -s AuthDDR 
(Load Parital Encrypted Userkey Bitstream using Overlay)
fpgautil -b top.bit.bin -o pl.dtbo -f Partial -s EnUsrKey -k <32byte key value>
(Read PL Configuration Registers)
fpgautil -b top.bit.bin -r

Fpgautil usage for DFx (aka PR/RP)use cases

Typical topology: FPGA has the base FPGA Region(static) with two PR/DFx regions (Each PR region has two RMs).  The relevant files can be looked as below. 

-- xilinx
    `-- static
        |-- static.dtbo
        |-- static.bin
        |---PR0        |   `-- PR0-RM0         |        |-- pr0-rm0.dtsi
        |        |-- pr0-rm0.dtbo
        |        |-- pr0-rm0.bin        |    `-- PR0-RM1        |        |-- pr0-rm1.dtsi        |        |-- pr0-rm1.dtbo        |        |-- pr0-rm1.bin        |---PR1        |   `-- PR1-RM0        |       |-- pr1-rm0.dtsi        |       |-- pr1-rm0.dtbo        |       |-- pr1-rm0.bin        |   `-- PR0-RM1        |       |-- pr1-rm1.dtsi        |       |-- pr1-rm1.dtbo        |       |-- pr1-rm1.bin
  • Configure/Reconfigure Static region using fpgautil: fpgautil -b <full/static bitstream image> -o <Full/static dtbo file> -f Full -n <Fpga region info>
    • Usage example: fpgautil -b static.bin -o static.dtbo -f Full -n Full
  • PR0 region configuration/Reconfigure using fpgautil:
    • Command to configure the PR0-RM0 Image: fpgautil -b <PR0-RM0 Bitstream image> -o <PR0-RM0 dtbo file> -f Partial -n <Fpga region info>
      • Usage example: fpgautil PR0-RM0.bin -o PR0-RM0.dtbo -f Partial -n PR0
    • Command to Remove Images(PR0-RM0) from the PR0 region: fpgautil -R -n  -n <Fpga region info> (Note: Before Reconfiguring the same region with a different Bitstream user needs to remove the existing dtbo relevant to it)
      • Usage example: fpgautil -R -n PR0
    • Command to configure the PR0-RM1 Image: : fpgautil -b <PR0-RM1 Bitstream image> -o <PR0-RM1 dtbo file> -f Partial -n <Fpga region info>
      • Usage example: fpgautil PR0-RM1.bin -o PR0-RM1.dtbo -f Partial -n PR0
    • Command to Remove Images(PR0-RM1) from the PR0 region: fpgautil -R -n <Fpga region info>
      • Usage example: fpgautil -R -n PR0
  • PR1 region configuration/reconfiguration using fpgautil:
    • Command to configure the PR0-RM0 Image: fpgautil -b <PR1-RM0 Bitstream image> -o <PR1-RM0 dtbo file> -f Partial -n <Fpga region info>
      • Usage example: fpgautil PR1-RM0.bin -o PR1-RM0.dtbo -f Partial -n PR1
    • Command to Remove Images(PR1-RM0) from the PR1 region: fpgautil -R -n <Fpga region info> (Note: Before Reconfiguring the same region with a different Bitstream user needs to remove the existing dtbo relevant to it)
      • Usage example: fpgautil -R -n PR1
    • Command to configure the PR1-RM1 Image: : fpgautil -b <PR1-RM1 Bitstream image> -o <PR1-RM1 dtbo file> -f Partial -n <Fpga region info>
      • Usage example: fpgautil PR1-RM1.bin -o PR1-RM1.dtbo -f Partial -n PR0
    • Command to Remove Images(PR0-RM1) from the PR0 region: fpgautil -R -n <Fpga region info>
      • Usage example: fpgautil -R -n PR1

  • Command to remove the images from the static region: fpgautil -R -n <Fpga region info>
    • Usage example: fpgautil -R -n Full

Notes:

  • Before Reconfiguring the same region(whether it is a static/ partial region) with a different Bitstream user needs to remove the existing dtbo relevant to it

  • Fpgautil -R is responsible for only removing the dtbo file from the livetree. it will not remove the PL logic from the FPGA region. If the user wants to remove the complete configuration logic from the FPGA region he should reconfigure the target configuration region with grey-box logic.

Loading an overlay along with it's Bitstream

Usage: fpgautil -b <bin file path> -o <overlay file path> 

root@xilinx-zcu102-2018_3:~#
root@xilinx-zcu102-2018_3:~# fpgautil -b /lib/firmware/design_1_wrapper/design_1_wrapper.bit.bin -o /lib/firmwaree/design_1_wrapper/design_1_wrapper.dtbo 
[   43.642776] fpga_manager fpga0: writing design_1_wrapper.bit.bin to Xilinx ZynqMP FPGA Manager
[   43.871149] XGpio: /amba/gpio@a0000000: registered, base is 298
[   43.877420] XGpio: /amba/gpio@a0000000: dual channel registered, base is 290
Time taken to load DTBO is 244.000000 Milli Seconds
DTBO loaded through zynqMP FPGA manager successfully
root@xilinx-zcu102-2018_3:~# 
root@xilinx-zcu102-2018_3:/sys/class/gpio# dmesg |grep gpio
[    5.399518] input: gpio-keys as /devices/platform/gpio-keys/input/input0
[   43.871149] XGpio: /amba/gpio@a0000000: registered, base is 298
[   43.877420] XGpio: /amba/gpio@a0000000: dual channel registered, base is 290
root@xilinx-zcu102-2018_3:/sys/class/gpio# dmesg |grep gpio
[    5.399518] input: gpio-keys as /devices/platform/gpio-keys/input/input0
[   43.871149] XGpio: /amba/gpio@a0000000: registered, base is 298
[   43.877420] XGpio: /amba/gpio@a0000000: dual channel registered, base is 290
root@xilinx-zcu102-2018_3:/sys/class/gpio# echo 290 > export 
root@xilinx-zcu102-2018_3:/sys/class/gpio# cd gpio290
root@xilinx-zcu102-2018_3:/sys/class/gpio/gpio290# ls
active_low  device      direction   edge        power       subsystem   uevent      value
root@xilinx-zcu102-2018_3:/sys/class/gpio/gpio290# echo 1 out > direction 
root@xilinx-zcu102-2018_3:/sys/class/gpio/gpio290# echo 0 > value 
root@xilinx-zcu102-2018_3:/sys/class/gpio/gpio290# echo 1 > value 
root@xilinx-zcu102-2018_3:/sys/class/gpio/gpio290#

Removing an overlay

Usage: fpgautil -R 

root@xilinx-zcu102-2018_3:~# fpgautil -R 
root@xilinx-zcu102-2018_3:~#

Loading Bitstream only

Usage: fpgautil -b <bit/bin file absolute path> 

root@xilinx-zcu102-2018_3:~# fpgautil  -b /mnt/design_1_wrapper.bit
Time taken to load BIN is 213.000000 Milli Seconds
BIN FILE loaded through zynqMP FPGA manager successfully

Loading Partial Bitstream that doesn't require PL drivers

Usage: fpgautil -b <bit/bin file full path> -f Partial 

root@xilinx-zcu102-2018_3:~# fpgautil -b pr1rm1.bit.bin -f Partial
Flags : 0x1
Time taken to load BIN is 56.000000 Milli Seconds
BIN FILE loaded through zynqMP FPGA manager successfully

Loading Secure Authenticated Bitstream

Usage: fpgautil -b <bit/bin file full path> -f <flags> -s AuthDDR 

root@xilinx-zcu102-2018_3:~# fpgautil -b Authentication_system_wrapper.bin -f Full -s AuthDDR
Flags : 0x0
Flags : 0x2
[  467.885628] fpga_manager fpga0: writing Authentication_system_wrapper.bin to Xilinx ZynqMP FPGA Manager
Time taken to load BIN FILE is 263.000000 Milli Seconds
BIN FILE loaded through zynqMP FPGA manager successfully

Read back of FPGA Configuration Registers

Usage: fpgautil -r 

root@xilinx-zcu102-2018_3:~#fpgautil -r
Readback contents are stored in the file readback.bin
root@xilinx-zcu102-2018_3:~# vi readback.bin 
zynqMP FPGA Configuration register contents are
CRC --> 	 0 	
FAR --> 	 7fc0000 	
FDRI --> 	 0 	
FDRO --> 	 effffffe 	
CMD --> 	 d 	
CTRL0 --> 	 101 	
MASK --> 	 0 	
STAT --> 	 16907ffc 	
LOUT --> 	 0 	
COR0 --> 	 38003fe5 	
MFWR --> 	 0 	
CBC --> 	 0 	
IDCODE --> 	 1484a093 	
AXSS --> 	 0 	
COR1 --> 	 400000 	
WBSTR --> 	 0 	
TIMER --> 	 0 	
BOOTSTS --> 	 1 	
CTRL1 --> 	 0

Read back of FPGA Configuration Data (Frames)

Usage: fpgautil -r <filename> -t 1 

root@xilinx-zcu102-2018_3:~# fpgautil -r readbackdata -t 1
root@xilinx-zcu102-2018_3:~# hexdump readbackdata.bin > data.txt
Verification of Read-back Data

  • To verify the readback data stream, compare it to the RBD golden readback file and masking readback bits with the MSD file. This approach is simple because there is a 1:1 correspondence between the start of the readback data stream and the start of the RBD and MSD files, making the task of aligning readback, mask, and expected data easier.

  • The RBD and MSD files contain an ASCII representation of the readback and mask data along with a file header that lists the file name, etc. This header information should be ignored or deleted. The ASCII 1s and 0s in the RBD and MSD files correspond to the binary readback data from the device.

  • For generating RBD and MSD refer UG908 (Vivado Design Suite User Guide)

    By compiling the below utility(verify_readback.c file) user can verify the read back contents. Source code: verify_readback

Note:

utility compares the readback with the RBD golden file, by masking readback bits with the MSD file. It is expected from user to remove/strip the header in the msd and rdb files and also remove the print statement in the readback contents file(readback.bin).

Example 

$./verify_readback -msd design_1_wrapper.msd -rbd design_1_wrapper.rbd -data reabackdata_2.bin 
=============================================
Starting verification of readback data...
 
>>>> Readback data is correct! <<<<
=============================================