From 491350a321bf9bb2feb379c8285e5db0056dbce3 Mon Sep 17 00:00:00 2001
From: Sarunas Kalade <sarunask@xilinx.com>
Date: Fri, 19 Apr 2024 20:43:42 +0100
Subject: [PATCH] Sdbuild readme update (#1406)

* update sdbuild readme with new api

* quick start update
---
 sdbuild/README.md | 62 +++++++++++++++++++++++++----------------------
 1 file changed, 33 insertions(+), 29 deletions(-)

diff --git a/sdbuild/README.md b/sdbuild/README.md
index 6fa8041f8e..8d76ea64d6 100644
--- a/sdbuild/README.md
+++ b/sdbuild/README.md
@@ -17,8 +17,9 @@ require different or additional packages. The build process is optimised for
  * Ensure that sudo is configured for passwordless use and that proxy settings
    and other environment variables are forwarded correctly.
  * Run `scripts/setup_host.sh`
- * Install Petalinux (e.g. 2017.4)
+ * Install Petalinux (e.g. 2022.1)
  * Ensure that Petalinux is on the PATH
+ * Ensure that the prebuilt pynq sdist and rootfs tarballs are in the sdbuild/prebuilt folder
  * Run `make BOARDDIR=<boards_directory>` to recreate all board images
  * Wait for a couple of hours
 
@@ -156,62 +157,65 @@ Custom packages can be placed in a `packages` subfolder of the and will be
 picked up automatically if referenced. This is a convenient way of installing
 custom notebooks or Python packages if desired for your board.
 
-### Step 3: Run `make`
+### Step 3: Build the image
 
-With all the files prepared, the SD card image can be built:
+#### (1) Collect a prebuilt board-agnostic root filesystem tarball and a prebuilt PYNQ source distribution.
 
-```Makefile
-make BOARDDIR=<absolute_path>/myboards
+Starting in PYNQ v3.0, by default the SD card build flow expects a prebuilt root filesystem and a PYNQ source distribution to speedup and simplify user rebuilds of SD card images. These binaries can be found at [the PYNQ boards page](http://www.pynq.io/board.html/) and copied into the sdbuild prebuilt folder
+
+```bash
+# For rebuilding all SD cards, both arm and aarch64 root filesystems
+# may be required depending on boards being targetted.
+cp pynq_rootfs.<arm|aarch64>.tar.gz <PYNQ repository>/sdbuild/prebuilt/pynq_rootfs.<arm|aarch64>.tar.gz
+cp pynq-<version>.tar.gz            <PYNQ repository>/sdbuild/prebuilt/pynq_sdist.tar.gz
 ```
 
-### Step 4 (Optional): Useful byproducts
+#### (2) Run `make`
 
-All boot files are created using Petalinux based on a provided BSP. To generate
-the boot files only:
+With all the files prepared, the SD card image can be built by navigating to the following directory and running make:
 
-```Makefile
-make boot_files BOARDDIR=<absolute_path>/myboards
+```bash
+cd <PYNQ repository>/sdbuild/
+make
 ```
 
-To generate the software components for SDx platform:
+### Step 4 (Optional): Useful byproducts
 
-```Makefile
-make sdx_sw BOARDDIR=<absolute_path>/myboards
+You can force a PYNQ source distribution rebuild by setting the REBUILD_PYNQ_SDIST variable when invoking make
+
+```bash
+make REBUILD_PYNQ_SDIST=True
 ```
 
-To generate sysroot:
+You can force a root filesystem build by setting the REBUILD_PYNQ_ROOTFS variable when invoking make:
 
-```Makefile
-make sysroot BOARDDIR=<absolute_path>/myboards
+```bash
+make REBUILD_PYNQ_ROOTFS=True
 ```
 
-To generate the Petalinux BSP for future use:
+All boot files are created using Petalinux based on a provided BSP. To generate
+the boot files only:
 
 ```Makefile
-make bsp BOARDDIR=<absolute_path>/myboards
+make boot_files BOARDDIR=<absolute_path>/myboards
 ```
 
-To build the board-agnostic images and sysroot you can pass the `ARCH_ONLY`
-variable to make. This will cause the `images` target to build the architecture
-image.
+To generate sysroot:
 
 ```Makefile
-make images ARCH_ONLY=arm
+make sysroot BOARDDIR=<absolute_path>/myboards
 ```
 
-To use a board-agnostic image to build a board-specific image you can pass the
-`PREBUILT` variable:
+To generate the Petalinux BSP for future use:
 
 ```Makefile
-make PREBUILT=<image path> BOARDS=<board>
+make bsp BOARDDIR=<absolute_path>/myboards
 ```
 
-To use a previously built PYNQ source distribution tarball you can pass the 
-`PYNQ_SDIST` variable. This will also avoid having to rebuild bitstreams 
-(except for external boards) and MicroBlazes' bsps and binaries.
+To use a previously built PYNQ source distribution tarball and/or rootfs, instead of moving the files into the prebuilt folder, you can specify the `PYNQ_SDIST` and `PYNQ_ROOTFS` environment variables
 
 ```Makefile
-make PYNQ_SDIST=<sdist tarball path>
+make PYNQ_SDIST=<sdist tarball path> PYNQ_ROOTFS=<rootfs tarball path>
 ```
 
 ## Custom Ubuntu Repository