From e7c13de36952784354a820bc8c2d91eadb284c17 Mon Sep 17 00:00:00 2001
From: Stefano Stabellini
Date: Mon, 21 Oct 2019 16:02:58 -0700
Subject: Improve README

Document how to use uboot-script-gen directly.

Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
Signed-off-by: Brian Woods <brian.woods@xilinx.com>
---
 README.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 87 insertions(+), 6 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 59108cf..9632018 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,87 @@
-# imagebuilder
+# ImageBuilder
 
-## `Dockerfile.image`
+Given a bunch of binaries for Xen, Dom0, and a number of Dom0-less
+DomUs, ImageBuilder generates a u-boot script that can be used to load
+all of the binaries automatically and boot the system. ImageBuilder
+takes care of calculating all loading addresses, editing device tree
+with the necessary information, and even pre-configuring a disk image
+with kernels and rootfses.
+
+ImageBuilder scripts can be used stand-alone, or from an ImageBuilder
+Container.
+
+
+## Stand-alone Usage: scripts/uboot-script-gen
+
+The ImageBuilder script that generates a u-boot script to load all your
+binaries for a Xen Dom0-less setup is `scripts/uboot-script-gen`.
+
+To use it, first write a config file like `config`:
+
+```
+MEMORY_START="0x0"
+MEMORY_END="0x80000000"
+
+DEVICE_TREE="mpsoc.dtb"
+XEN="xen"
+DOM0_KERNEL="Image-dom0"
+DOM0_RAMDISK="dom0-ramdisk.cpio"
+
+NUM_DOMUS=2
+DOMU_KERNEL[0]="zynqmp-dom1/Image-domU"
+DOMU_RAMDISK[0]="zynqmp-dom1/domU-ramdisk.cpio"
+DOMU_PASSTHROUGH_DTB[0]="zynqmp-dom1/passthrough-example-part.dtb"
+DOMU_KERNEL[1]="zynqmp-dom2/Image-domU"
+DOMU_RAMDISK[1]="zynqmp-dom2/domU-ramdisk.cpio"
+
+UBOOT_SOURCE="boot.source"
+UBOOT_SCRIPT="boot.scr"
+```
+
+Where:
+- MEMORY_START and MEMORY_END specify the start and end of RAM.
+
+- DEVICE_TREE specifies the DTB file to load.
+
+- XEN specifies the Xen hypervisor binary to load. Note that it has to
+  be a regular Xen binary, not a u-boot binary.
+
+- DOM0_KERNEL specifies the Dom0 kernel file to load.
+
+- DOM0_RAMDISK specifies the Dom0 ramdisk to use. Note that it should be
+  a regular ramdisk cpio.gz file, not a u-boot binary.
+
+- NUM_DOMUS specifies how many Dom0-less DomUs to load
+
+- DOMU_KERNEL[number] specifies the DomU kernel to use.
+
+- DOMU_RAMDISK[number] specifies the DomU ramdisk to use.
+
+- DOMU_PASSTHROUGH_DTB[number] specifies the device assignment
+  configuration, see xen.git:docs/misc/arm/passthrough.txt
+
+Then you can invoke uboot-script-gen as follows:
+
+```
+$ export LOAD_CMD="tftpb"
+$ bash ./scripts/uboot-script-gen /path/to/config-file
+```
+
+Where LOAD_CMD specifies the u-boot command to load the binaries.
+For tftp, use LOAD_CMD="tftpb".
+For SCSI, use LOAD_CMD="load scsi 0:1".
+
+
+## Container Usage
+
+ImageBuilder comes with a Dockerfile to build a container with all the
+required scripts. The following chapters explain how to build it and use
+it.
+
+
+### `Dockerfile.image`
+
+Build the container.
 
 ```
 $ cd imagebuilder
@@ -8,9 +89,9 @@ $ cd imagebuilder
 $ docker build --force-rm --file Dockerfile.image -t imagebuilder .
 ```
 
-## `/imagebuilder_sd` or `/imagebuilder_tftp`
+### `/imagebuilder_sd` or `/imagebuilder_tftp`
 
-### TFTP
+#### TFTP
 
 Run the following command to generate a uboot script to tftp all the
 necessary binaries automatically:
@@ -32,7 +113,7 @@ Run this command instead:
 setenv serverip 192.168.76.2; tftpb 0xc00000 boot.scr; source 0xc00000
 ```
 
-### SATA
+#### SATA
 
 Run the following command to generate an image to be written on disk:
 
@@ -51,7 +132,7 @@ command:
 scsi scan; load scsi 0:1 0xc00000 boot.scr; source 0xc00000
 ```
 
-## Add additional DomUs
+### Add additional DomUs
 
 Assuming that you have the kernel and ramdisk of another DomU already in
 `PACKAGE.md` format, you can configure Imagebuilder to start it
-- 
cgit v1.2.3