arch/riscv/boot.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 RISC-V Kernel Boot Requirements and Constraints
10 This document describes what the RISC-V kernel expects from bootloaders and
12 touching the early boot process. For the purposes of this document, the
16 Pre-kernel Requirements and Constraints
19 The RISC-V kernel expects the following of bootloaders and platform firmware:
22 --------------
24 The RISC-V kernel expects:
26   * ``$a0`` to contain the hartid of the current core.
27   * ``$a1`` to contain the address of the devicetree in memory.
30 ---------
32 The RISC-V kernel expects:
37 -------------------------------------
39 The RISC-V kernel must not map any resident memory, or memory protected with
44 ---------------
46 The RISC-V kernel expects to be placed at a PMD boundary (2MB aligned for rv64
51 --------------------
53 The firmware can pass either a devicetree or ACPI tables to the RISC-V kernel.
56 using the ``$a1`` register, or when booting with UEFI, it can be passed using the
64 ------------
68 - ``RISCV_BOOT_SPINWAIT``: the firmware releases all harts in the kernel, one hart
71   support older firmwares without SBI HSM extension and M-mode RISC-V kernel.
72 - ``Ordered booting``: the firmware releases only one hart that will execute the
74   extension. The ordered booting method is the preferred booting method for
75   booting the RISC-V kernel because it can support CPU hotplug and kexec.
78 ----
83 When booting with UEFI, the RISC-V kernel will use only the EFI memory map to
86 The UEFI firmware must parse the subnodes of the ``/reserved-memory`` devicetree
87 node and abide by the devicetree specification to convert the attributes of
88 those subnodes (``no-map`` and ``reusable``) into their correct EFI equivalent
89 (refer to section "3.5.4 /reserved-memory and UEFI" of the devicetree
90 specification v0.4-rc1).
95 When booting with UEFI, the EFI stub requires the boot hartid in order to pass
96 it to the RISC-V kernel in ``$a1``. The EFI stub retrieves the boot hartid using
97 one of the following methods:
99 - ``RISCV_EFI_BOOT_PROTOCOL`` (**preferred**).
100 - ``boot-hartid`` devicetree subnode (**deprecated**).
108 The RISC-V kernel's early boot process operates under the following constraints:
111 -----------------------
113 When booting with UEFI, the devicetree is supplemented (or created) by the EFI
118 ----------------------------
120 The installation of the virtual mapping is done in 2 steps in the RISC-V kernel:
123    allows discovery of the system memory. Only the kernel text/data are mapped
129    and takes advantage of the discovered system memory to create the linear
136 direct mapping addresses to physical addresses, they need to know the start of
138 mapping (see ``setup_bootmem()`` function in arch/riscv/mm/init.c). Any usage of
143 -----------------------------
147 ``setup_vm_final()``, the RISC-V kernel uses the fixmap region to map the
151 Pre-MMU execution
152 -----------------
154 A few pieces of code need to run before even the first virtual mapping is
155 established. These are the installation of the first virtual mapping itself,
156 patching of early alternatives and the early parsing of the kernel command line.
159 - ``-fno-pie``: This is needed for relocatable kernels which use ``-fPIE``,
162 - ``-mcmodel=medany``: Any access to a global symbol must be PC-relative to
164 - *all* instrumentation must also be disabled (that includes KASAN, ftrace and