Help understanding output files from sdbuild/make


I’m struggling to understand what output files from make can be used in what groups and where they reside.

I’ve run make and have (I think) a working BOOT.bin and image.ub. My understanding is that these two files both go in the FAT partition on the sdcard. These files are located here:

I am having a hard time locating the filesystem and I can find no mention of this in any of the Pynq documentation.

  1. What is the file system file name?
  2. What is the extensions? tar.gz?
  3. Where in the PYNQ repo is the file system located?
  4. Should this file merely be placed in the second ext4 partition or does it need to be unzipped?

additional questions
5. Does a .img file get produced from the sdbuild/make process?
6. If so where does this reside?
7. Is the intention to write this image to the sdcard and you are good to go?

If the build process runs successfully all of the images (with an .img extension) should be produced in the output folder. If that’s not happening something is going wrong with the build process. If you post the console output from the build that would be helpful in diagnosing what’s going on.

The image files produced are the same as the ones we offer for download and are intentended to be burnt as is. We separate out the boot files separately because when bringing up a new board it is often easier to start with an existing image and just replace the files on the boot partition.


Ok - in going back through my console output it looks like the ZC104 bsp is missing and the build is failing. I’m running the make sysroot with BOARDDIR=my_board_dir_abs_path and BOARDS=Pynq-Z1 which is my board. If I understand things correctly this produces two “.img” files. The first img file is for the fat partition? The second image file is the filesystem?

From your reply - so is the idea that you can make new overlay (or new board) you keep the filesystem and just replace the boot partition files?

ZCU104 bsp can be downloaded from Xilinx website.

Only one img file will be produced from the make process, which consists of both the boot partition and the rootfs. You only need to burn that img onto your SD card. You will not able to see the rootfs in your windows machine easily, but your board should boot up properly.

For new overlay you don’t need to replace the boot partition, just bitstream and its metadata (hwh file) are needed to reprogram FPGA.

Ok - I thought I saw today there were two image files being produce. A stage 1 and stage2 something. I will double check this.

As for the new overlays - how does the bitstream relate to u-boot if the boot.bin doesn’t have to be rebuilt? Previously you would integrate the bitstream (i should say maybe you would do this often) into u-boot.

Is there any more detailed documentation than the online readthedocs pages? That is good for an overview, but for an new hardware guy this is very vague.

That is the beauty of PYNQ - you don’t have to rely on the bitstream in the boot.bin. You can use pynq package (essentially fpga manager) to reprogram the FPGA during runtime.

1 Like

What is the purpose of the *.state1.img and *.state2.img files?

I’m building the Pynq-Z1 image with make BOARDS=PynqZ1 command and see these two files that are both 7 gigs each. Are these combined into the single sdcard image?

The stage 1 and stage 2 files act as checkpoints for the build system so that the entire process doesn’t need to be repeated when files get updated. Stage 1 occurs after the initial bootstrap of the system by the Debian multistrap tool and stage 2 is after most of the PYNQ-specific packages are installed. This means, for example, when we are creating new release candidates of images where the only thing that has changed is the PYNQ python repository we don’t need to re-run the whole process from scratch - make will instead start from the stage 2 checkpoint.

One thing to note is that all of our images are sparse files so they aren’t necessarily taking up the full 7 GB - you can use du *.img to find out how much space is actually in use. For a recent build I did both ended up being about 4 GB which is still pretty large but not as bad as it first looks.


Thank you for the great response Peter!

Regarding the build process, I notice that during the sdbuild make process I’m running there are two images mounted in linux and then there are many many ubuntu packages downloaded. I’ve attached a screenshot showing the two mounted partitions. I’m assuming these are the two partitions on the sdcard.

I’m curious about what happens in what order…once these two (soon to be) sd card partitions are mounted do we then download all the packages and build the root file system on one of the mount points then turn that into an image? What exactly is going on here?

The basic flow goes as follows

  1. Create the image file and use fdisk to partition it into the boot and root partitions
  2. Mount the newly created image using kpartx - this will create entries for each partition in /dev/mapper
  3. Create the filesystems on each partition
  4. Mount the filesystems in the build directory
  5. Use multistrap to download the Ubuntu packages and unpack them into the mounted space
  6. Use QEMU to run the post install scripts of the Ubuntu packages
  7. Install the non-Ubuntu packages (those in the packages directory of the sdbuild folder)
  8. Use PetaLinux to build the boot partition for the board
  9. Unmount everything
  10. Resize the image to be slightly bigger than the installed size for distribution

Some of the steps in the middle have multiple sub-steps. We also check-point after steps 6 and 7 to speed the creation of images. The board-agnostic image you can download from our website is the output of stage 7 as by that point nothing specific to a board has been done and all that’s necessary is to add your own boot files.

One thing to be aware of is that if make fails for some reason it’s likely that the partitions don’t get unmounted. In this instance it’s necessary to manually unmount them before running make again or it can get confused. We’ve added a check to prevent this from happening but it’s possible there are circumstances we’ve missed.


1 Like

i got build error as in image pls help me to sort out this .

here is make file line 57
git clone …/ $@

as in fig

Maybe it is not a git clone repo. Make sure you clone it from our repo, instead of downloading the tar file from our github website.