[RFC,v3] doc: arch: Add document for RISC-V architecture

This patch adds a brief introduction to the RISC-V architecture and
the typical boot process used on a variety of RISC-V platforms.

Signed-off-by: Yu Chien Peter Lin <peterlin@andestech.com>
Reviewed-by: Samuel Holland <samuel@sholland.org>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
Changes v1 -> v2
- Use 'boot phases' rather than 'boot stages'
- Pick up Samuel and Simon's RB tags
Changes v2 -> v3
- Follow the suggestion by Heinrich [1]
- Add the document as an entry of Andes maintainer in MAINTAINERS
- Add some pointers to OpenSBI document

[1] https://patchwork.ozlabs.org/project/uboot/patch/20230212070053.14800-1-peterlin@andestech.com/
---
 MAINTAINERS        |  1 +
 doc/arch/index.rst |  1 +
 doc/arch/riscv.rst | 74 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 doc/arch/riscv.rst

> From: Peter Yu-Chien Lin(林宇謙) <peterlin@andestech.com>
> Sent: Tuesday, February 14, 2023 6:19 PM
> To: u-boot@lists.denx.de
> Cc: Leo Yu-Chi Liang(梁育齊) <ycliang@andestech.com>; Rick Jian-Zhi Chen(陳建志) <rick@andestech.com>; sjg@chromium.org; xypron.glpk@gmx.de; Peter Yu-Chien Lin(林宇謙) <peterlin@andestech.com>; Samuel Holland <samuel@sholland.org>
> Subject: [RFC PATCH v3] doc: arch: Add document for RISC-V architecture
>
> This patch adds a brief introduction to the RISC-V architecture and the typical boot process used on a variety of RISC-V platforms.
>
> Signed-off-by: Yu Chien Peter Lin <peterlin@andestech.com>
> Reviewed-by: Samuel Holland <samuel@sholland.org>
> Reviewed-by: Simon Glass <sjg@chromium.org>
> ---
> Changes v1 -> v2
> - Use 'boot phases' rather than 'boot stages'
> - Pick up Samuel and Simon's RB tags
> Changes v2 -> v3
> - Follow the suggestion by Heinrich [1]
> - Add the document as an entry of Andes maintainer in MAINTAINERS
> - Add some pointers to OpenSBI document
>
> [1] https://patchwork.ozlabs.org/project/uboot/patch/20230212070053.14800-1-peterlin@andestech.com/
> ---
>  MAINTAINERS        |  1 +
>  doc/arch/index.rst |  1 +
>  doc/arch/riscv.rst | 74 ++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 76 insertions(+)
>  create mode 100644 doc/arch/riscv.rst

Reviewed-by: Rick Chen <rick@andestech.com>

On 2/14/23 11:18, Yu Chien Peter Lin wrote:
> This patch adds a brief introduction to the RISC-V architecture and
> the typical boot process used on a variety of RISC-V platforms.
>
> Signed-off-by: Yu Chien Peter Lin <peterlin@andestech.com>
> Reviewed-by: Samuel Holland <samuel@sholland.org>
> Reviewed-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Rick Chen <rick@andestech.com>
> ---
> Changes v1 -> v2
> - Use 'boot phases' rather than 'boot stages'
> - Pick up Samuel and Simon's RB tags
> Changes v2 -> v3
> - Follow the suggestion by Heinrich [1]
> - Add the document as an entry of Andes maintainer in MAINTAINERS
> - Add some pointers to OpenSBI document
>
> [1] https://patchwork.ozlabs.org/project/uboot/patch/20230212070053.14800-1-peterlin@andestech.com/
> ---
>   MAINTAINERS        |  1 +
>   doc/arch/index.rst |  1 +
>   doc/arch/riscv.rst | 74 ++++++++++++++++++++++++++++++++++++++++++++++
>   3 files changed, 76 insertions(+)
>   create mode 100644 doc/arch/riscv.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index b9c505d5fa..5eb79faf29 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1292,6 +1292,7 @@ S:	Maintained
>   T:	git https://source.denx.de/u-boot/custodians/u-boot-riscv.git
>   F:	arch/riscv/
>   F:	cmd/riscv/
> +F:	doc/arch/riscv.rst
>   F:	doc/usage/sbi.rst
>   F:	drivers/sysreset/sysreset_sbi.c
>   F:	drivers/timer/andes_plmt_timer.c
> diff --git a/doc/arch/index.rst b/doc/arch/index.rst
> index b3e85f9bf3..b8da4b8c8e 100644
> --- a/doc/arch/index.rst
> +++ b/doc/arch/index.rst
> @@ -11,6 +11,7 @@ Architecture-specific doc
>      m68k
>      mips
>      nios2
> +   riscv
>      sandbox/index
>      sh
>      x86
> diff --git a/doc/arch/riscv.rst b/doc/arch/riscv.rst
> new file mode 100644
> index 0000000000..10bf3e6849
> --- /dev/null
> +++ b/doc/arch/riscv.rst
> @@ -0,0 +1,74 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (C) 2023, Yu Chien Peter Lin <peterlin@andestech.com>
> +
> +RISC-V
> +======
> +
> +Overview
> +--------
> +
> +This document outlines the U-Boot boot process for the RISC-V architecture.
> +RISC-V is an open-source instruction set architecture (ISA) based on the
> +principles of reduced instruction set computing (RISC). It has been designed
> +to be flexible and customizable, allowing it to be adapted to different use
> +cases, from embedded systems to high performance servers.
> +
> +Typical Boot Process
> +--------------------
> +
> +U-Boot can run in either M-mode or S-mode, depending on whether it runs before
> +the initialization of the firmware providing SBI (Supervisor Binary Interface).
> +The firmware is necessary in the RISC-V boot process as it serves as a SEE
> +(Supervisor Execution Environment) to handle exceptions for the S-mode U-Boot
> +or Operating System.
> +
> +In between the boot phases, the hartid is passed through the a0 register, and
> +the start address of the devicetree is passed through the a1 register.
> +
> +As a reference, OpenSBI is an SBI implementation that can be used with U-Boot
> +in different modes, see the `OpenSBI firmware document <https://github.com/riscv-software-src/opensbi/tree/master/docs/firmware>`_ for more details.
> +
> +M-mode U-Boot
> +^^^^^^^^^^^^^
> +
> +When running in M-mode U-Boot, it will load the payload image (e.g. `fw_payload <https://github.com/riscv-software-src/opensbi/blob/master/docs/firmware/fw_payload.md>`_)
> +which contains the firmware and the S-mode Operating System; in this case, you
> +can use mkimage to package the payload image into an uImage format, and boot it
> +using the bootm command.
> +
> +The following diagram illustrates the boot process::
> +
> +	<-----------( M-mode )----------><--( S-mode )-->
> +	+----------+   +--------------+    +------------+
> +	|  U-Boot  |-->| SBI firmware |--->|     OS     |
> +	+----------+   +--------------+    +------------+
> +
> +To examine the boot process with the QEMU virt machine, you can follow the
> +steps in the "Building U-Boot" section of the following document:
> +:doc:`../board/emulation/qemu-riscv.rst`

This patch does not build. '.rst' has to removed here.

doc/arch/riscv.rst:46:unknown document: ../board/emulation/qemu-riscv.rst
make[1]: *** [doc/Makefile:70: htmldocs] Error 2
make: *** [Makefile:2348: htmldocs] Error 2

Please, execute the build process as described in

https://u-boot.readthedocs.io/en/latest/build/documentation.html#html-documentation

for testing your documentation patches.

I will fix this issue when merging. Thank you for the contribution.

Best regards

Heinrich

> +
> +S-mode U-Boot
> +^^^^^^^^^^^^^
> +
> +RISC-V production boot images may include a U-Boot SPL for platform-specific
> +initialization. The U-Boot SPL then loads a FIT image (u-boot.itb), which
> +contains a firmware (e.g. `fw_dynamic <https://github.com/riscv-software-src/opensbi/blob/master/docs/firmware/fw_dynamic.md>`_) providing the SBI, as well as a regular
> +U-Boot (or U-Boot proper) running in S-mode. Finally, the S-mode Operating
> +System is loaded.
> +
> +The following diagram illustrates the boot process::
> +
> +	<-------------( M-mode )----------><----------( S-mode )------->
> +	+------------+   +--------------+    +----------+   +----------+
> +	| U-Boot SPL |-->| SBI firmware |--->|  U-Boot  |-->|    OS    |
> +	+------------+   +--------------+    +----------+   +----------+
> +
> +To examine the boot process with the QEMU virt machine, you can follow the
> +steps in the "Running U-Boot SPL" section of the following document:
> +:doc:`../board/emulation/qemu-riscv.rst`
> +
> +Toolchain
> +---------
> +
> +You can build the `RISC-V GNU toolchain <https://github.com/riscv-collab/riscv-gnu-toolchain>`_ from scratch, or download a
> +pre-built toolchain from the `releases page <https://github.com/riscv-collab/riscv-gnu-toolchain/releases>`_.

On Fri, Feb 17, 2023 at 02:26:17PM +0100, Heinrich Schuchardt wrote:
> On 2/14/23 11:18, Yu Chien Peter Lin wrote:
> > This patch adds a brief introduction to the RISC-V architecture and
> > the typical boot process used on a variety of RISC-V platforms.
> > 
> > Signed-off-by: Yu Chien Peter Lin <peterlin@andestech.com>
> > Reviewed-by: Samuel Holland <samuel@sholland.org>
> > Reviewed-by: Simon Glass <sjg@chromium.org>
> > Reviewed-by: Rick Chen <rick@andestech.com>
> > ---
> > Changes v1 -> v2
> > - Use 'boot phases' rather than 'boot stages'
> > - Pick up Samuel and Simon's RB tags
> > Changes v2 -> v3
> > - Follow the suggestion by Heinrich [1]
> > - Add the document as an entry of Andes maintainer in MAINTAINERS
> > - Add some pointers to OpenSBI document
> > 
> > [1] https://patchwork.ozlabs.org/project/uboot/patch/20230212070053.14800-1-peterlin@andestech.com/
> > ---
> >   MAINTAINERS        |  1 +
> >   doc/arch/index.rst |  1 +
> >   doc/arch/riscv.rst | 74 ++++++++++++++++++++++++++++++++++++++++++++++
> >   3 files changed, 76 insertions(+)
> >   create mode 100644 doc/arch/riscv.rst
> > 
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index b9c505d5fa..5eb79faf29 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -1292,6 +1292,7 @@ S:	Maintained
> >   T:	git https://source.denx.de/u-boot/custodians/u-boot-riscv.git
> >   F:	arch/riscv/
> >   F:	cmd/riscv/
> > +F:	doc/arch/riscv.rst
> >   F:	doc/usage/sbi.rst
> >   F:	drivers/sysreset/sysreset_sbi.c
> >   F:	drivers/timer/andes_plmt_timer.c
> > diff --git a/doc/arch/index.rst b/doc/arch/index.rst
> > index b3e85f9bf3..b8da4b8c8e 100644
> > --- a/doc/arch/index.rst
> > +++ b/doc/arch/index.rst
> > @@ -11,6 +11,7 @@ Architecture-specific doc
> >      m68k
> >      mips
> >      nios2
> > +   riscv
> >      sandbox/index
> >      sh
> >      x86
> > diff --git a/doc/arch/riscv.rst b/doc/arch/riscv.rst
> > new file mode 100644
> > index 0000000000..10bf3e6849
> > --- /dev/null
> > +++ b/doc/arch/riscv.rst
> > @@ -0,0 +1,74 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +.. Copyright (C) 2023, Yu Chien Peter Lin <peterlin@andestech.com>
> > +
> > +RISC-V
> > +======
> > +
> > +Overview
> > +--------
> > +
> > +This document outlines the U-Boot boot process for the RISC-V architecture.
> > +RISC-V is an open-source instruction set architecture (ISA) based on the
> > +principles of reduced instruction set computing (RISC). It has been designed
> > +to be flexible and customizable, allowing it to be adapted to different use
> > +cases, from embedded systems to high performance servers.
> > +
> > +Typical Boot Process
> > +--------------------
> > +
> > +U-Boot can run in either M-mode or S-mode, depending on whether it runs before
> > +the initialization of the firmware providing SBI (Supervisor Binary Interface).
> > +The firmware is necessary in the RISC-V boot process as it serves as a SEE
> > +(Supervisor Execution Environment) to handle exceptions for the S-mode U-Boot
> > +or Operating System.
> > +
> > +In between the boot phases, the hartid is passed through the a0 register, and
> > +the start address of the devicetree is passed through the a1 register.
> > +
> > +As a reference, OpenSBI is an SBI implementation that can be used with U-Boot
> > +in different modes, see the `OpenSBI firmware document <https://github.com/riscv-software-src/opensbi/tree/master/docs/firmware>`_ for more details.
> > +
> > +M-mode U-Boot
> > +^^^^^^^^^^^^^
> > +
> > +When running in M-mode U-Boot, it will load the payload image (e.g. `fw_payload <https://github.com/riscv-software-src/opensbi/blob/master/docs/firmware/fw_payload.md>`_)
> > +which contains the firmware and the S-mode Operating System; in this case, you
> > +can use mkimage to package the payload image into an uImage format, and boot it
> > +using the bootm command.
> > +
> > +The following diagram illustrates the boot process::
> > +
> > +	<-----------( M-mode )----------><--( S-mode )-->
> > +	+----------+   +--------------+    +------------+
> > +	|  U-Boot  |-->| SBI firmware |--->|     OS     |
> > +	+----------+   +--------------+    +------------+
> > +
> > +To examine the boot process with the QEMU virt machine, you can follow the
> > +steps in the "Building U-Boot" section of the following document:
> > +:doc:`../board/emulation/qemu-riscv.rst`
> 
> This patch does not build. '.rst' has to removed here.
> 
> doc/arch/riscv.rst:46:unknown document: ../board/emulation/qemu-riscv.rst
> make[1]: *** [doc/Makefile:70: htmldocs] Error 2
> make: *** [Makefile:2348: htmldocs] Error 2
> 
> Please, execute the build process as described in
> 
> https://u-boot.readthedocs.io/en/latest/build/documentation.html#html-documentation
> 
> for testing your documentation patches.
> 
> I will fix this issue when merging. Thank you for the contribution.

Hi Heinrich,

Thanks for the pointer, I will make sure it builds on my local next time.

Best regards,
Peter Lin

> Best regards
> 
> Heinrich