README.sdt.bsp.md: Add SDT build instructions

1. Move all SDT build instruction from README.md to README.xsct.bsp.md
2. Add instructions for generating SDT machine configuration files
   for custom board or design sdt files.

Signed-off-by: Sandeep Gundlupet Raju <sandeep.gundlupet-raju@amd.com>
Signed-off-by: Mark Hatle <mark.hatle@amd.com>

1 files changed, 165 insertions, 39 deletions

diff --git a/meta-xilinx-standalone-sdt/README.sdt.bsp.md b/meta-xilinx-standalone-sdt/README.sdt.bsp.md
index 2b2ce4b0..eb1f852f 100644
--- a/meta-xilinx-standalone-sdt/README.sdt.bsp.md
+++ b/meta-xilinx-standalone-sdt/README.sdt.bsp.md
@@ -1,46 +1,172 @@
-# SDT BSP
+# AMD SDT BSP Machines files
 
-This section describes the SDT BSP settings which must be added to the generated
-machine configuration file, following [Build Instructions](README.md) step 4, in
-order to use the runqemu command.
+This section describes the SDT BSP machine files generation.
 
-## SDT BSP settings
+## SDT Build Instructions
 
-The following board settings need to be added in sdt machine configuration file
-to define which QEMU device trees should be used.
+The Yocto Project setup for the System Device Tree (SDT) workflow is as follows.
+Be sure to read everything below.
 
-> **Variable usage examples:**
+> **Pre-requisites:**
+> * Follow [System Device Tree Instructions](https://github.com/Xilinx/system-device-tree-xlnx/blob/master/README.md)
+>   to generate the SDT output.
+> * To use the SDT version of the embedded software (firmware) as well as system
+>   configuration, you must build through gen-machineconf tool. This tool is passed
+>   a output of system device tree directory.
+
+> **Note:** SDT builds for following devices are not supported in 2024.2 release.
+> * MicroBlaze
+
+1. Follow [Building Instructions](../README.building.md) upto step 6.
+
+2. Clone the meta-openamp repository.
+```
+$ cd ../sources
+$ git clone -b <rel-version> https://github.com/Xilinx/meta-openamp
+$ cd -
+```
+3. Add meta-openamp layer.
+```
+$ bitbake-layers add-layer ./<path-to-layer>/meta-openamp
+```
+
+4. Export gen-machineconf tool.
+```
+$ export PATH=$PATH:<ABSOLUTE_PATH>/gen-machine-conf
+```
+
+5. Run the script from the build or ${TOPDIR} directory. This step describes
+   System Device Tree (SDT) with and without pl overlays. Configruations are same
+   for both SDT with and without pl overlays except for linux dts content.
+
+> **Note:**
+> 1. The -c option should point either <path-to-machine-bsp-layer>/conf or <path-to-build-directory>/build/conf
+>    directory.
+> 2. The -l option will automatically add the necessary parameters to the
+   local.conf file.  If you need to re-run this comment, you just clear the
+   parameters from the end of the file.  Without the -l option the items are
+   printed to the screen and must be manually added to your conf/local.conf
+> 3. The --soc-family argument is an optional argument and user can skip this.
+> 4. By default minimal set of multiconfigs are generated by gen-machineconf tool.
+>    To enable full multiconfig(APU/RPU baremetal or FreeRTOS) then use
+>    `--multiconfigfull` option.
+
+> **Recommended SDT Machine nomenclature:**
 >
-> QEMU Device tree deploy directory: `QEMU_HW_DTB_PATH = "${DEPLOY_DIR_IMAGE}/qemu-hw-devicetrees/multiarch"`
-> 
-> QEMU PMU Device tree: `QEMU_HW_DTB_PMU = "${QEMU_HW_DTB_PATH}/zynqmp-pmu.dtb"`
-> 
-> QEMU PS Device tree: `QEMU_HW_DTB_PS = "${QEMU_HW_DTB_PATH}/board-versal-ps-vck190.dtb"`
+> 1. Machine Configuration file nomenclature: `<soc-family>-<board-name>-sdt-<design-name>`
+> * Example: `MACHINE = "versal-vek280-sdt-seg"`
 >
-> QEMU PMC Board Device tree: `QEMU_HW_DTB_PMC = "${QEMU_HW_DTB_PATH}/board-versal-pmc-virt.dtb"`
+> 2. BSP Reference design name:
+> * `full` - Zynq-7000/ZynqMP full bitstream loading Vivado design.
+> * `dfx` - ZynqMP/Versal full bitstream loading Vivado design.
+> * `seg` - Versal Segmented Configuration Vivado design.
+>
+> **Note:** In machine file nomencalutre `<soc-family>-<board-name>-sdt-<design-name>`
+> If design-name suffix is not set or defined then it is treated as flat design
+> without dynamic PL configuration.
+
+   a. Without SDT pl overlay:
+```
+ $ gen-machineconf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name>
+```
+
+   b. With SDT pl overlay:
+      To generate SDT pl overlay run gen-machineconf command with
+      `-g {full|dfx}` option. Once SDT pl overlay command is executed successfully
+      pl.dtsi will be generated under <conf-directory>/dts/${MACHINE}/pl-overlay-{full|dfx}
+      directory. User can use this pl.dtsi as input to full or dfx static firmware
+      recipes. See https://github.com/Xilinx/meta-xilinx/blob/master/docs/README.dfx.user.dts.md
+          for more details.
+
+> **Note:** DFx partial dtsi is not processed by gen-machineconf(lopper) tool, User
+>          needs to use the *_partial.dtsi and *_partial.pdi/bit from sdtgen output
+>          artifacts to DFx partial firmware recipes.
+
+   * Zynq-700 or ZynqMP Full bitstream or Versal Segmented Configuration:
+```
+ $ gen-machineconf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name> -g full
+```
+
+   * ZynqMP or Versal DFx:
+```
+ $ gen-machineconf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name> -g dfx
+```
+
+For example, Zynq-7000:
+```
+$ gen-machineconf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name>
+```
+The following will be written to the end of the <path-to-build-directory>/build/conf/local.conf file:
+
+```
+# Use the newly generated MACHINE
+MACHINE = "zynq-zc702-sdt"
+
+# Avoid errors in some baremetal configs as these layers may be present
+# but are not used.  Note the following lines are optional and can be
+# safetly disabled.
+SKIP_META_VIRT_SANITY_CHECK = "1"
+SKIP_META_SECURITY_SANITY_CHECK = "1"
+SKIP_META_TPM_SANITY_CHECK = "1"
+```
+
+For example, ZynqMP:
+```
+$ gen-machineconf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name>
+```
+The following will be written to the end of the <path-to-build-directory>/conf/local.conf file:
+
+```
+# Use the newly generated MACHINE
+MACHINE = "zynqmp-zcu102-sdt"
+
+# Avoid errors in some baremetal configs as these layers may be present
+# but are not used.  Note the following lines are optional and can be
+# safetly disabled.
+SKIP_META_VIRT_SANITY_CHECK = "1"
+SKIP_META_SECURITY_SANITY_CHECK = "1"
+SKIP_META_TPM_SANITY_CHECK = "1"
+```
+
+For example, Versal:
+```
+$ gen-machineconf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name>
+```
+
+The following will be written to the end of the <path-to-build-directory>/conf/local.conf file:
+
+```
+# Use the newly generated MACHINE
+MACHINE = "versal-vmk180-sdt"
+
+# Avoid errors in some baremetal configs as these layers may be present
+# but are not used.  Note the following lines are optional and can be
+# safetly disabled.
+SKIP_META_VIRT_SANITY_CHECK = "1"
+SKIP_META_SECURITY_SANITY_CHECK = "1"
+SKIP_META_TPM_SANITY_CHECK = "1"
+```
+
+> **Bitbake Performance Note:**
+Each BBMULTICONFIG value requires all of the recipes to be parsed for that
+configuration.  Thus each multiconfig will add more parsing time.  A long list
+can lead to a very slow parse (many minutes).  To speed up parsing, it is
+suggested that you trim this down to only the configurations you require.
+A minimum configuration is included with the generated configuration.
+
+6. Build your project, You should now be able to build your project normally.
+   See the Yocto Project documentation if you have questions on how to work with
+   the multiconfig recipes. The following is a simple build for testing.
+
+7. Continue [Building Instructions](https://github.com/Xilinx/meta-xilinx/blob/master/README.building.md)
+   from step 8.
+
+>**Note:** Only AMD eval boards have the dtsi in System Device Tree repo, for custom
+> board user has to follow one of the following methods.
+> 1. Patch System Device Tree to include the custom board dtsi and include the
+> custom board dtsi during sdtgen build step.
+> `% sdtgen set_dt_param -board_dts <custom-board-dtsi-name>`
 >
-> QEMU Memory: Some boards for example VEK280 and VH158 memory configurations are
-> different, Hence we need to adjust the same in QB_MEM to match board dtsi files.
-> Below are some examples.
-> * ZynqMP `QB_MEM = "-m 4096"`
-> * Versal VEK280 `QB_MEM = "-m 12G"`
-
-
-| Devices | Evaluation Board                                                              |   QEMU PMC or PMU DTB file  |        QEMU PS DTB file       | QB Mem |
-|---------|-------------------------------------------------------------------------------|-----------------------------|-------------------------------|--------|
-| ZynqMP  | [ZCU102](https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html) | `zynqmp-pmu.dtb`            | `zcu102-arm.dtb`              |  4096  |
-|         | [ZCU104](https://www.xilinx.com/products/boards-and-kits/zcu104.html)         | `zynqmp-pmu.dtb`            | `zcu102-arm.dtb`              |  4096  |
-|         | [ZCU106](https://www.xilinx.com/products/boards-and-kits/zcu106.html)         | `zynqmp-pmu.dtb`            | `zcu102-arm.dtb`              |  4096  |
-|         | [ZCU111](https://www.xilinx.com/products/boards-and-kits/zcu111.html)         | `zynqmp-pmu.dtb`            | `zcu102-arm.dtb`              |  4096  |
-|         | [ZCU208](https://www.xilinx.com/products/boards-and-kits/zcu208.html)         | `zynqmp-pmu.dtb`            | `zcu102-arm.dtb`              |  4096  |
-|         | [ZCU216](https://www.xilinx.com/products/boards-and-kits/zcu216.html)         | `zynqmp-pmu.dtb`            | `zcu102-arm.dtb`              |  4096  |
-|         | [ZCU670](https://www.xilinx.com/products/boards-and-kits/zcu670.html)         | `zynqmp-pmu.dtb`            | `zcu102-arm.dtb`              |  4096  |
-| Versal  | [VCK190](https://www.xilinx.com/products/boards-and-kits/vck190.html)         | `board-versal-pmc-virt.dtb` | `board-versal-ps-vck190.dtb`  |   8G   |
-|         | [VMK180](https://www.xilinx.com/products/boards-and-kits/vmk180.html)         | `board-versal-pmc-virt.dtb` | `board-versal-ps-vmk180.dtb`  |   8G   |
-|         | [VPK120](https://www.xilinx.com/products/boards-and-kits/vpk120.html)         | `board-versal-pmc-virt.dtb` | `board-versal-ps-vpk120.dtb`  |   8G   |
-|         | [VPK180](https://www.xilinx.com/products/boards-and-kits/vpk180.html)         | `board-versal-pmc-virt.dtb` | `board-versal-ps-vpk180.dtb`  |   8G   |
-|         | [VEK280](https://www.xilinx.com/products/boards-and-kits/vek280.html)         | `board-versal-pmc-virt.dtb` | `board-versal-ps-vek280.dtb`  |  12G   |
-|         | [VHK158](https://www.xilinx.com/products/boards-and-kits/vhk158.html)         | `board-versal-pmc-virt.dtb` | `board-versal-ps-vhk158.dtb`  |  32G   |
-
-> **Note:** Additional information on Xilinx architectures can be found at:
-        https://www.xilinx.com/products/silicon-devices.html
+> 2. Create a custom board dtsi file and use EXTRA_DT_INCLUDE_FILES variable to
+> include the custom board dtsi to final dtb. Here is the example usage.
+> `EXTRA_DT_INCLUDE_FILES:append = " <path-to-directory>/<custom-board>.dtsi"`