docs: Update unleashed platform guide.

Following updates to fu540 platform guide.

1. Update a section about flashing the firmware binary
to sdcard with correct partition identifier.
2. Refer the individual payload section.
3. Update uboot booting section.

Signed-off-by: Atish Patra <atish.patra@wdc.com>

diff --git a/docs/platform/sifive_fu540.md b/docs/platform/sifive_fu540.md
index bb4d69b..95a4326 100644 (file)
--- a/docs/platform/sifive_fu540.md
+++ b/docs/platform/sifive_fu540.md
@@ -13,58 +13,46 @@ Platform Options
 As hart0 in the FU540 doesn't have an MMU, only harts 1-4 boot by default.
 A hart mask i.e. *FU540_ENABLED_HART_MASK* compile time option is provided to
 select any other hart for booting. Please keep in mind that this is not
-platform wide option. It can only be specificd for FU540 platform in following way.
+platform wide option. It can only be specified for FU540 platform in following way.
 
 ```
 make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=Image FU540_ENABLED_HART_MASK=0x02
 ```
 This will let the board boot only hart1 instead of default 1-4.
 
-Booting SiFive Fu540 Platform
+Building SiFive Fu540 Platform
 -----------------------------
 
-**Linux Kernel Payload**
+As of this writing, the required Linux kernel and U-Boot patches are not
+accepted in mainline. Please follow the below instructions to cherry-pick
+them into your repository.
 
-Build:
+[U-Boot patches](../firmware/payload_uboot.md)
 
-```
-make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=<linux_build_directory>/arch/riscv/boot/Image
-```
+[Linux kernel patches](../firmware/payload_linux.md)
+
+**Linux Kernel Payload**
 
-Flash:
-The generated firmware binary should be copied to the first partition of the sdcard.
 
 ```
-dd if=build/platform/sifive/fu540/firmware/fw_payload.bin of=/dev/disk2s1 bs=1024
+make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=<linux_build_directory>/arch/riscv/boot/Image
 ```
 
 **U-Boot Payload**
 
-Note: U-Boot doesn't have SMP support. So you can only boot single cpu with non-smp
-kernel configuration using U-Boot.
 
-Build:
+The command-line example here assumes that U-Boot was compiled using sifive_fu540_defconfig configuration.
+
+With SMP support enabled in U-Boot:
 
-The commandline example here assumes that U-Boot was compiled using sifive_fu540_defconfig configuration.
 ```
-make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=<u-boot_build_dir>/u-boot.bin FU540_ENABLED_HART_MASK=0x02
+make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=<u-boot_build_dir>/u-boot.bin
 ```
 
-Flash:
-The generated firmware binary should be copied to the first partition of the sdcard.
-
+Without SMP support enabled in U-Boot:
 ```
-dd if=build/platform/sifive/fu540/firmware/fw_payload.bin of=/dev/disk2s1 bs=1024
+make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=<u-boot_build_dir>/u-boot.bin FU540_ENABLED_HART_MASK=0x02
 ```
-U-Boot tftp boot method can be used to load kernel image in U-Boot prompt.
-
-Note: As the U-Boot & Linux kernel patches are not in upstream it, you can cherry-pick from here.
-
-U-Boot patchset:
-https://lists.denx.de/pipermail/u-boot/2019-January/355941.html
-
-Linux kernel patchset:
-https://lkml.org/lkml/2019/1/8/192
 
 **U-Boot & Linux Kernel as a single payload**
 
@@ -78,8 +66,9 @@ mkimage -A riscv -O linux -T kernel -C none -a 0x80200000 -e 0x80200000 -n Linux
                <linux_build_directory>/arch/riscv/boot/uImage
 ```
 
-2. Create a temporary image with u-boot.bin as the first payload. The commandline example here assumes
-that U-Boot was compiled using sifive_fu540_defconfig configuration.
+2. Create a temporary image with u-boot.bin as the first payload. The command-line
+example here assumes that U-Boot was compiled using sifive_fu540_defconfig
+configuration.
 ```
 dd if=~/workspace/u-boot-riscv/u-boot.bin of=/tmp/temp.bin bs=1M
 ```
@@ -87,20 +76,112 @@ dd if=~/workspace/u-boot-riscv/u-boot.bin of=/tmp/temp.bin bs=1M
 ```
 dd if=<linux_build_directory>/arch/riscv/boot/uImage of=/tmp/temp.bin bs=1M seek=4
 ```
-4. Compile OpenSBI with temp.bin (generated in step 3) as payload and single hart enabled.
+4. Compile OpenSBI with temp.bin (generated in step 3) as payload.
 ```
-make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=/tmp/temp.bin FU540_ENABLED_HART_MASK=0x02
+make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=/tmp/temp.bin
 ```
-5. The generated firmware binary should be copied to the first partition of the sdcard.
+
+Flashing the OpenSBI firmware binary to storage media:
+-----------------------------------------------------
+The first stage boot loader([FSBL](https://github.com/sifive/freedom-u540-c000-bootloader))
+expects the storage media to have a GPT partition table. It tries to look for a
+partition with following GUID to load the next stage boot loader (OpenSBI in this case).
+
+```
+2E54B353-1271-4842-806F-E436D6AF6985
+``` 
+
+That's why the generated firmware binary in above steps should be copied to the
+partition of the sdcard with above GUID.
 
 ```
 dd if=build/platform/sifive/fu540/firmware/fw_payload.bin of=/dev/disk2s1 bs=1024
 ```
-6. At U-Boot prompt execute following boot command to boot non-SMP linux.
+
+In my case, it is the first partition is **disk2s1** that has been formatted with the
+above specified GUID.
+
+In case of a brand new sdcard, it should be formatted with below partition
+tables as described here.
+
+```
+sgdisk --clear                                                               \
+       --new=1:2048:67583  --change-name=1:bootloader --typecode=1:2E54B353-1271-4842-806F-E436D6AF6985   \
+       --new=2:264192:     --change-name=2:root       --typecode=2:0FC63DAF-8483-4772-8E79-3D69D8477DE4 \
+       $(DISK)
+```
+
+Booting SiFive Fu540 Platform
+-----------------------------
+
+**Linux Kernel Payload**
+
+As Linux kernel image is embedded in the OpenSBI firmware binary, HiFive Unleashed will directly
+boot into Linux directly after powered on.
+
+**U-Boot Payload**
+
+As U-Boot image is used as payload, HiFive Unleashed will boot into a U-Boot prompt.
+U-Boot tftp boot method can be used to load kernel image in U-Boot prompt.
+Here are the steps do a tftpboot.
+
+1. Set the mac address of the board.
+
+```
+setenv ethaddr <mac address of the board>
+```
+2. Set the ip address of the board.
+
+```
+setenv ipaddr <ipaddr of the board>
+```
+3. Set the tftpboot server IP.
+
 ```
-bootm 0x80600000 - 0x82200000
+setenv serverip <ipaddr of the tftp server>
 ```
+4. Set the network gateway address.
 
+```
+setenv gatewayip <ipaddress of the network gateway>
+```
+5. Load the Linux kernel image from the tftp server.
+
+```
+tftpboot ${kernel_addr_r} /sifive/fu540/uImage
+```
+
+6. Load the ramdisk image from the tftp server. This is only required if ramdisk
+   is loaded from tftp server. This step is optional, if rootfs is already part
+   of the kernel or loaded from an external storage by kernel.
+
+```
+tftpboot ${ramdisk_addr_r} /sifive/fu540/uRamdisk
+```
+7. Set the boot command-line arguments.
+
+```
+setenv bootargs "root=/dev/ram rw console=ttySIF0 earlycon=sbi"
+```
+
+8. Now boot into Linux.
+
+```
+bootm ${kernel_addr_r} ${ramdisk_addr_r} ${fdtcontroladdr}
+
+```
+or (if ramdisk is not loaded from network)
+```
+bootm ${kernel_addr_r} - ${fdtcontroladdr}
+```
+
+**U-Boot & Linux Kernel as a single payload**
+
+At U-Boot prompt execute the following boot command to boot Linux.
+
+```
+bootm ${kernel_addr_r} - ${fdtcontroladdr}
+```
 Booting SiFive Fu540 Platform with Microsemi Expansion board
 ------------------------------------------------------------