[PATCH v6 17/17] doc: update FU540 RISC-V documentation

[Bin Meng]

Hi Pragnesh,

On Mon, Mar 30, 2020 at 1:07 AM Pragnesh Patel
<pragnesh.patel at sifive.com> wrote:
>
> Add descriptions about U-Boot SPL feature and how to build and run.
>
> Signed-off-by: Pragnesh Patel <pragnesh.patel at sifive.com>
> ---
>  doc/board/sifive/fu540.rst | 409 ++++++++++++++++++++++++++++++++++---
>  1 file changed, 385 insertions(+), 24 deletions(-)
>
> diff --git a/doc/board/sifive/fu540.rst b/doc/board/sifive/fu540.rst
> index 3937222c6c..cf76b88ebc 100644
> --- a/doc/board/sifive/fu540.rst
> +++ b/doc/board/sifive/fu540.rst
> @@ -42,8 +42,60 @@ Building
>     export ARCH=riscv
>     export CROSS_COMPILE=<riscv64 toolchain prefix>
>
> -3. make sifive_fu540_defconfig
> -4. make
> +User can use FSBL or u-boot-spl as the 1st stage bootloader.
> +
> +1) Use FSBL as the 1st stage bootloader
> +
> +.. code-block:: console
> +
> +       git clone https://github.com/sifive/freedom-u540-c000-bootloader.git
> +       cd freedom-u540-c000-bootloader
> +       make
> +
> +       cd <u-boot-dir>
> +       make sifive_fu540_defconfig
> +       make
> +
> +       git clone https://github.com/riscv/opensbi.git
> +       cd opensbi
> +       make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=<path to u-boot-dtb.bin>
> +
> +This will generate a fw_payload.bin (build/platform/sifive/fu540/firmware/fw_payload.bin)
> +
> +u-boot-dtb.bin is used as a payload of the OpenSBI FW_PAYLOAD firmware.
> +
> +More detailed description of steps required to build FW_PAYLOAD firmware
> +is beyond the scope of this document. Please refer OpenSBI documenation.
> +(Note: OpenSBI git repo is at https://github.com/riscv/opensbi.git)
> +
> +2) Use u-boot-spl as the 1st stage bootloader
> +
> +Before building U-Boot SPL, OpenSBI must be built first. OpenSBI can be
> +cloned and built for FU540 as below:
> +
> +.. code-block:: console
> +
> +       git clone https://github.com/riscv/opensbi.git
> +       cd opensbi
> +       make PLATFORM=sifive/fu540
> +
> +Copy OpenSBI FW_DYNAMIC image (build/platform/sifive/fu540/firmware/fw_dynamic.bin)
> +into U-Boot root directory
> +
> +.. code-block:: console
> +
> +       cp build/platform/sifive/fu540/firmware/fw_dynamic.bin <u-boot-dir>
> +
> +Now build the u-boot-spl and U-Boot proper
> +
> +.. code-block:: console
> +
> +       cd <u-boot-dir>
> +       make sifive_fu540_defconfig
> +       make
> +
> +This will generate spl/u-boot-spl.bin and FIT image (u-boot.itb)
> +
>
>  Flashing
>  --------
> @@ -53,28 +105,55 @@ The current U-Boot port is supported in S-mode only and loaded from DRAM.
>  A prior stage M-mode firmware/bootloader (e.g OpenSBI) is required to
>  boot the u-boot.bin in S-mode and provide M-mode runtime services.
>
> -Currently, the u-boot.bin is used as a payload of the OpenSBI FW_PAYLOAD
> -firmware. We need to compile OpenSBI with below command:
> +1) Use FSBL as the 1st stage bootloader
> +
> +ZSBL loads the FSBL (fsbl.bin) from a partition with GUID type
> +5B193300-FC78-40CD-8002-E86C45580B47
> +
> +FSBL loads the fw_payload.bin from a partition with GUID type
> +2E54B353-1271-4842-806F-E436D6AF6985
> +
> +Once the prior stage firmware/bootloader binary is generated, it should be
> +copied to the first partition of the sdcard.
>
>  .. code-block:: none
>
> -make PLATFORM=sifive/fu540 FW_PAYLOAD_PATH=<path to u-boot-dtb.bin>
> +     sudo dd if=fsbl.bin of=/dev/disk2s4 bs=1024
> +     sudo dd if=fw_payload.bin of=/dev/disk2s1 bs=1024
>
> -More detailed description of steps required to build FW_PAYLOAD firmware
> -is beyond the scope of this document. Please refer OpenSBI documenation.
> -(Note: OpenSBI git repo is at https://github.com/riscv/opensbi.git)
> +Assuming that /dev/disk2s4 partition is of GUID type
> +5B193300-FC78-40CD-8002-E86C45580B47 and /dev/disk2s1 partition
> +is of GUID type 2E54B353-1271-4842-806F-E436D6AF6985
> +
> +2) Use u-boot-spl as the 1st stage bootloader
> +
> +ZSBL loads the U-Boot SPL (u-boot-spl.bin) from a partition with GUID type
> +5B193300-FC78-40CD-8002-E86C45580B47
> +
> +U-boot SPL expects a U-Boot FIT image (u-boot.itb) from 1st partition (/dev/sdc1)

nits: U-Boot SPL

> +of SD card irrespective of GUID
> +
> +FIT image (u-boot.itb) is a combination of fw_dynamic.bin, u-boot-nodtb.bin and
> +device tree blob (hifive-unleashed-a00.dtb)
>
>  Once the prior stage firmware/bootloader binary is generated, it should be
>  copied to the first partition of the sdcard.
>
>  .. code-block:: none
>
> -    sudo dd if=<prior_stage_firmware_binary> of=/dev/disk2s1 bs=1024
> +    sudo dd if=spl/u-boot-spl.bin of=/dev/disk2s4 bs=1024
> +    sudo dd if=u-boot.itb of=/dev/disk2s1 bs=1024
> +
> +Assuming that /dev/disk2s4 partition is of GUID type
> +5B193300-FC78-40CD-8002-E86C45580B47 and /dev/disk2s1 is of
> +any GUID type raw partition.
>

Other than above,

Reviewed-by: Bin Meng <bmeng.cn at gmail.com>

Regards,
Bin