From patchwork Tue Feb 14 10:18:51 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Yu Chien Peter Lin X-Patchwork-Id: 1742229 X-Patchwork-Delegate: xypron.glpk@gmx.de Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Received: from phobos.denx.de (phobos.denx.de [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4PGHJC6Ptnz23r4 for ; Tue, 14 Feb 2023 21:19:38 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 7B0C2858CC; Tue, 14 Feb 2023 11:19:24 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=none (p=none dis=none) header.from=andestech.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Received: by phobos.denx.de (Postfix, from userid 109) id 2964E858BF; Tue, 14 Feb 2023 11:19:21 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-0.9 required=5.0 tests=BAYES_00, PDS_RDNS_DYNAMIC_FP, RDNS_DYNAMIC,SPF_HELO_NONE,SPF_PASS autolearn=no autolearn_force=no version=3.4.2 Received: from Atcsqr.andestech.com (60-248-80-70.hinet-ip.hinet.net [60.248.80.70]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 86623858A8 for ; Tue, 14 Feb 2023 11:19:11 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=none (p=none dis=none) header.from=andestech.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=peterlin@andestech.com Received: from mail.andestech.com (ATCPCS16.andestech.com [10.0.1.222]) by Atcsqr.andestech.com with ESMTP id 31EAIvPs023447; Tue, 14 Feb 2023 18:18:57 +0800 (+08) (envelope-from peterlin@andestech.com) Received: from atcfdc88.andestech.com (10.0.15.158) by ATCPCS16.andestech.com (10.0.1.222) with Microsoft SMTP Server id 14.3.498.0; Tue, 14 Feb 2023 18:18:55 +0800 From: Yu Chien Peter Lin To: CC: , , , , Yu Chien Peter Lin , "Samuel Holland" Subject: [RFC PATCH v3] doc: arch: Add document for RISC-V architecture Date: Tue, 14 Feb 2023 18:18:51 +0800 Message-ID: <20230214101851.11648-1-peterlin@andestech.com> X-Mailer: git-send-email 2.38.0.68.ge85701b4af.dirty MIME-Version: 1.0 X-Originating-IP: [10.0.15.158] X-DNSRBL: X-MAIL: Atcsqr.andestech.com 31EAIvPs023447 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.6 at phobos.denx.de X-Virus-Status: Clean 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 Reviewed-by: Samuel Holland Reviewed-by: Simon Glass Reviewed-by: Rick Chen --- 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 + +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 `_ for more details. + +M-mode U-Boot +^^^^^^^^^^^^^ + +When running in M-mode U-Boot, it will load the payload image (e.g. `fw_payload `_) +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` + +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 `_) 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 `_ from scratch, or download a +pre-built toolchain from the `releases page `_.