On Tue, Jun 20, 2023 at 9:18 AM Sunil V L <sunilvl@xxxxxxxxxxxxxxxx> wrote: > > Hey Alex, > > Many thanks for writing this up! > > On Mon, Jun 19, 2023 at 11:49:13AM +0200, Alexandre Ghiti wrote: > > @Sunil V L Something about ACPI is more than welcome :) > > > > And thanks to @Björn Töpel and @Atish Kumar Patra for helping in > > writing this document! > > > > On Mon, Jun 19, 2023 at 11:47 AM Alexandre Ghiti <alexghiti@xxxxxxxxxxxx> wrote: > > > > > > This document describes the constraints and requirements of the early > > > boot process in a RISC-V kernel. > > > > > > Szigned-off-by: Alexandre Ghiti <alexghiti@xxxxxxxxxxxx> > > > --- > > > Documentation/riscv/boot-image-header.rst | 3 - > > > Documentation/riscv/boot.rst | 181 ++++++++++++++++++++++ > > > Documentation/riscv/index.rst | 1 + > > > 3 files changed, 182 insertions(+), 3 deletions(-) > > > create mode 100644 Documentation/riscv/boot.rst > > > > > > diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/riscv/boot-image-header.rst > > > index d7752533865f..a4a45310c4c4 100644 > > > --- a/Documentation/riscv/boot-image-header.rst > > > +++ b/Documentation/riscv/boot-image-header.rst > > > @@ -7,9 +7,6 @@ Boot image header in RISC-V Linux > > > > > > This document only describes the boot image header details for RISC-V Linux. > > > > > > -TODO: > > > - Write a complete booting guide. > > > - > > > The following 64-byte header is present in decompressed Linux kernel image:: > > > > > > u32 code0; /* Executable code */ > > > diff --git a/Documentation/riscv/boot.rst b/Documentation/riscv/boot.rst > > > new file mode 100644 > > > index 000000000000..b02230818b79 > > > --- /dev/null > > > +++ b/Documentation/riscv/boot.rst > > > @@ -0,0 +1,181 @@ > > > +.. SPDX-License-Identifier: GPL-2.0 > > > + > > > +============================================= > > > +Early boot requirements/constraints on RISC-V > > > +============================================= > > > + > > > +:Author: Alexandre Ghiti <alexghiti@xxxxxxxxxxxx> > > > +:Date: 23 May 2023 > > > + > > > +This document describes what the RISC-V kernel expects from the previous stages > > > +and the firmware, but also the constraints that any developer must have in mind > > > +when touching the early boot process, e.g. before the final virtual mapping is > > > +setup. > > > + > > > +Pre-kernel boot (Expectations from firmware) > > > +============================================ > > > + > > > +Registers state > > > +--------------- > > > + > > > +The RISC-V kernel expects: > > > + > > > + * `$a0` to contain the hartid of the current core. > > > + * `$a1` to contain the address of the device tree in memory. > > > + > > > +CSR state > > > +--------- > > > + > > > +The RISC-V kernel expects: > > > + > > > + * `$satp = 0`: the MMU must be disabled. > > > + > > > +Reserved memory for resident firmware > > > +------------------------------------- > > > + > > > +The RISC-V kernel expects the firmware to mark any resident memory with the > > > +`no-map` flag, thus the kernel won't map those regions in the direct mapping > > > +(avoiding issues with hibernation, speculative accesses and probably other > > > +subsystems). > > > + > > > +Kernel location > > > +--------------- > > > + > > > +The RISC-V kernel expects to be placed at a PMD boundary (2MB for rv64 and 4MB > > > +for rv32). Note though that the EFI stub will physically relocate the kernel if > > > +that's not the case. > > > + > > > +Device-tree > > > +----------- > > > + > > > +The RISC-V kernel always expects a device tree, it is: > > > + > In general, the firmware can pass either DT or ACPI (not both at the > same time) to the OS. So, I think the statement that kernel always > expects DT probably causes confusion. Can we mention some thing like > below? > > The firmware can pass either DeviceTree or ACPI tables to the RISC-V > kernel. > > The DeviceTree is either passed directly to the kernel from the > previous stage using the `$a1` register, or when booting with UEFI, it > can be passed using the EFI configuration table. > > The ACPI tables are passed to the kernel using the EFI configuration > table. In this case, a tiny DeviceTree is still created by the EFI > stub. Please refer to "EFI stub and device" tree section below for > details of the tiny DeviceTree. > Great, this is way better so I'll go with that: Hardware description -------------------- The firmware can pass either a devicetree or ACPI tables to the RISC-V kernel. The devicetree is either passed directly to the kernel from the previous stage using the `$a1` register, or when booting with UEFI, it can be passed using the EFI configuration table. The ACPI tables are passed to the kernel using the EFI configuration table. In this case, a tiny devicetree is still created by the EFI stub. Please refer to "EFI stub and devicetree" tree section below for details about this devicetree. Thanks! > Thanks, > Sunil
