The bootargs node is also added by the EFI stub in the function
update_fdt(), so add it to the table.
Signed-off-by: Alexandre Ghiti <[email protected]>
---
Documentation/arm/uefi.rst | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/arm/uefi.rst b/Documentation/arm/uefi.rst
index baebe688a006..2b7ad9bd7cd2 100644
--- a/Documentation/arm/uefi.rst
+++ b/Documentation/arm/uefi.rst
@@ -50,7 +50,7 @@ The stub populates the FDT /chosen node with (and the kernel scans for) the
following parameters:
========================== ====== ===========================================
-Name Size Description
+Name Type Description
========================== ====== ===========================================
linux,uefi-system-table 64-bit Physical address of the UEFI System Table.
@@ -67,4 +67,6 @@ linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format.
kaslr-seed 64-bit Entropy used to randomize the kernel image
base address location.
+
+bootargs String Kernel command line
========================== ====== ===========================================
--
2.39.2
The EFI stub is supported on RISC-V so update the documentation that
explains how the boot image header was reused to support it.
Signed-off-by: Alexandre Ghiti <[email protected]>
Reviewed-by: Atish Patra <[email protected]>
Reviewed-by: Palmer Dabbelt <[email protected]>
Acked-by: Palmer Dabbelt <[email protected]>
---
Documentation/riscv/boot-image-header.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/riscv/boot-image-header.rst
index a4a45310c4c4..df2ffc173e80 100644
--- a/Documentation/riscv/boot-image-header.rst
+++ b/Documentation/riscv/boot-image-header.rst
@@ -28,11 +28,11 @@ header in future.
Notes
=====
-- This header can also be reused to support EFI stub for RISC-V in future. EFI
- specification needs PE/COFF image header in the beginning of the kernel image
- in order to load it as an EFI application. In order to support EFI stub,
- code0 should be replaced with "MZ" magic string and res3(at offset 0x3c) should
- point to the rest of the PE/COFF header.
+- This header is also reused to support EFI stub for RISC-V. EFI specification
+ needs PE/COFF image header in the beginning of the kernel image in order to
+ load it as an EFI application. In order to support EFI stub, code0 is replaced
+ with "MZ" magic string and res3(at offset 0x3c) points to the rest of the
+ PE/COFF header.
- version field indicate header version number
--
2.39.2
This document describes the constraints and requirements of the early
boot process in a RISC-V kernel.
Signed-off-by: Alexandre Ghiti <[email protected]>
Reviewed-by: Björn Töpel <[email protected]>
Reviewed-by: Conor Dooley <[email protected]>
Reviewed-by: Sunil V L <[email protected]>
Reviewed-by: Andrew Jones <[email protected]>
Reviewed-by: Palmer Dabbelt <[email protected]>
Acked-by: Palmer Dabbelt <[email protected]>
---
Documentation/riscv/boot-image-header.rst | 3 -
Documentation/riscv/boot.rst | 170 ++++++++++++++++++++++
Documentation/riscv/index.rst | 1 +
3 files changed, 171 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..09997bbe1b52
--- /dev/null
+++ b/Documentation/riscv/boot.rst
@@ -0,0 +1,170 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================================
+RISC-V Kernel Boot Requirements and Constraints
+===============================================
+
+:Author: Alexandre Ghiti <[email protected]>
+:Date: 23 May 2023
+
+This document describes what the RISC-V kernel expects from bootloaders and
+firmware, but also the constraints that any developer must have in mind when
+touching the early boot process. For the purposes of this document, the
+'early boot process' refers to any code that runs before the final virtual
+mapping is set up.
+
+Pre-kernel Requirements and Constraints
+=======================================
+
+The RISC-V kernel expects the following of bootloaders and platform firmware:
+
+Register state
+--------------
+
+The RISC-V kernel expects:
+
+ * `$a0` to contain the hartid of the current core.
+ * `$a1` to contain the address of the devicetree in memory.
+
+CSR state
+---------
+
+The RISC-V kernel expects:
+
+ * `$satp = 0`: the MMU, if present, must be disabled.
+
+Reserved memory for resident firmware
+-------------------------------------
+
+The RISC-V kernel must not map any resident memory, or memory protected with
+PMPs, in the direct mapping, so the firmware must correctly mark those regions
+as per the devicetree specification and/or the UEFI specification.
+
+Kernel location
+---------------
+
+The RISC-V kernel expects to be placed at a PMD boundary (2MB aligned for rv64
+and 4MB aligned for rv32). Note that the EFI stub will physically relocate the
+kernel if that's not the case.
+
+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" section below for details about this devicetree.
+
+Kernel entrance
+---------------
+
+On SMP systems, there are 2 methods to enter the kernel:
+
+- `RISCV_BOOT_SPINWAIT`: the firmware releases all harts in the kernel, one hart
+ wins a lottery and executes the early boot code while the other harts are
+ parked waiting for the initialization to finish. This method is mostly used to
+ support older firmwares without SBI HSM extension and M-mode RISC-V kernel.
+- `Ordered booting`: the firmware releases only one hart that will execute the
+ initialization phase and then will start all other harts using the SBI HSM
+ extension. The ordered booting method is the preferred booting method for
+ booting the RISC-V kernel because it can support cpu hotplug and kexec.
+
+UEFI
+----
+
+UEFI memory map
+~~~~~~~~~~~~~~~
+
+When booting with UEFI, the RISC-V kernel will use only the EFI memory map to
+populate the system memory.
+
+The UEFI firmware must parse the subnodes of the `/reserved-memory` devicetree
+node and abide by the devicetree specification to convert the attributes of
+those subnodes (`no-map` and `reusable`) into their correct EFI equivalent
+(refer to section "3.5.4 /reserved-memory and UEFI" of the devicetree
+specification v0.4-rc1).
+
+RISCV_EFI_BOOT_PROTOCOL
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When booting with UEFI, the EFI stub requires the boot hartid in order to pass
+it to the RISC-V kernel in `$a1`. The EFI stub retrieves the boot hartid using
+one of the following methods:
+
+- `RISCV_EFI_BOOT_PROTOCOL` (**preferred**).
+- `boot-hartid` devicetree subnode (**deprecated**).
+
+Any new firmware must implement `RISCV_EFI_BOOT_PROTOCOL` as the devicetree
+based approach is deprecated now.
+
+Early Boot Requirements and Constraints
+=======================================
+
+The RISC-V kernel's early boot process operates under the following constraints:
+
+EFI stub and devicetree
+-----------------------
+
+When booting with UEFI, the devicetree is supplemented (or created) by the EFI
+stub with the same parameters as arm64 which are described at the paragraph
+"UEFI kernel support on ARM" in Documentation/arm/uefi.rst.
+
+Virtual mapping installation
+----------------------------
+
+The installation of the virtual mapping is done in 2 steps in the RISC-V kernel:
+
+1. :c:func:`setup_vm` installs a temporary kernel mapping in
+ :c:var:`early_pg_dir` which allows discovery of the system memory. Only the
+ kernel text/data are mapped at this point. When establishing this mapping, no
+ allocation can be done (since the system memory is not known yet), so
+ :c:var:`early_pg_dir` page table is statically allocated (using only one
+ table for each level).
+
+2. :c:func:`setup_vm_final` creates the final kernel mapping in
+ :c:var:`swapper_pg_dir` and takes advantage of the discovered system memory
+ to create the linear mapping. When establishing this mapping, the kernel
+ can allocate memory but cannot access it directly (since the direct mapping
+ is not present yet), so it uses temporary mappings in the fixmap region to
+ be able to access the newly allocated page table levels.
+
+For :c:func:`virt_to_phys` and :c:func:`phys_to_virt` to be able to correctly
+convert direct mapping addresses to physical addresses, they need to know the
+start of the DRAM. This happens after step 1, right before step 2 installs the
+direct mapping (see :c:func:`setup_bootmem` function in arch/riscv/mm/init.c).
+Any usage of those macros before the final virtual mapping is installed must
+be carefully examined.
+
+Devicetree mapping via fixmap
+-----------------------------
+
+As the :c:var:`reserved_mem` array is initialized with virtual addresses
+established by :c:func:`setup_vm`, and used with the mapping established by
+:c:func:`setup_vm_final`, the RISC-V kernel uses the fixmap region to map the
+devicetree. This ensures that the devicetree remains accessible by both virtual
+mappings.
+
+Pre-MMU execution
+-----------------
+
+A few pieces of code need to run before even the first virtual mapping is
+established. These are the installation of the first virtual mapping itself,
+patching of early alternatives and the early parsing of the kernel command line.
+That code must be very carefully compiled as:
+
+- `-fno-pie`: This is needed for relocatable kernels which use `-fPIE`, since
+ otherwise, any access to a global symbol would go through the GOT which is
+ only relocated virtually.
+- `-mcmodel=medany`: Any access to a global symbol must be PC-relative to avoid
+ any relocations to happen before the MMU is setup.
+- *all* instrumentation must also be disabled (that includes KASAN, ftrace and
+ others).
+
+As using a symbol from a different compilation unit requires this unit to be
+compiled with those flags, we advise, as much as possible, not to use external
+symbols.
diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
index 175a91db0200..1f66062def6d 100644
--- a/Documentation/riscv/index.rst
+++ b/Documentation/riscv/index.rst
@@ -5,6 +5,7 @@ RISC-V architecture
.. toctree::
:maxdepth: 1
+ boot
boot-image-header
vm-layout
hwprobe
--
2.39.2
Alexandre Ghiti <[email protected]> writes:
> This document describes the constraints and requirements of the early
> boot process in a RISC-V kernel.
Some quick comments...
> +The RISC-V kernel expects:
> +
> + * `$a0` to contain the hartid of the current core.
> + * `$a1` to contain the address of the devicetree in memory.
Single `backtick` quotes are probably not doing what you want. If
you're looking for it to render in a monospace font, use ``double``
quotes instead. But I'd also encourage you to keep that to a minimum to
avoid overly cluttering the plain-text document.
[...]
> +Virtual mapping installation
> +----------------------------
> +
> +The installation of the virtual mapping is done in 2 steps in the RISC-V kernel:
> +
> +1. :c:func:`setup_vm` installs a temporary kernel mapping in
Please don't use :c:func:. If you just write setup_vm(), all the right
magic will happen.
> + :c:var:`early_pg_dir` which allows discovery of the system memory. Only the
We also really just don't use :c:var: at all. Kerneldoc doesn't
currently know about global variables...perhaps it should but that's not
the way of things now.
Thanks,
jon
On Fri, Jun 23, 2023 at 2:56 AM Alexandre Ghiti <[email protected]> wrote:
>
> The bootargs node is also added by the EFI stub in the function
> update_fdt(), so add it to the table.
>
> Signed-off-by: Alexandre Ghiti <[email protected]>
> ---
> Documentation/arm/uefi.rst | 4 +++-
> 1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/arm/uefi.rst b/Documentation/arm/uefi.rst
> index baebe688a006..2b7ad9bd7cd2 100644
> --- a/Documentation/arm/uefi.rst
> +++ b/Documentation/arm/uefi.rst
> @@ -50,7 +50,7 @@ The stub populates the FDT /chosen node with (and the kernel scans for) the
> following parameters:
>
> ========================== ====== ===========================================
> -Name Size Description
> +Name Type Description
> ========================== ====== ===========================================
> linux,uefi-system-table 64-bit Physical address of the UEFI System Table.
>
> @@ -67,4 +67,6 @@ linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format.
>
> kaslr-seed 64-bit Entropy used to randomize the kernel image
> base address location.
> +
> +bootargs String Kernel command line
> ========================== ====== ===========================================
> --
> 2.39.2
>
>
> _______________________________________________
> linux-riscv mailing list
> [email protected]
> http://lists.infradead.org/mailman/listinfo/linux-riscv
Reviewed-by: Atish Patra <[email protected]>
--
Regards,
Atish
On Fri, Jun 23, 2023 at 2:57 AM Alexandre Ghiti <[email protected]> wrote:
>
> This document describes the constraints and requirements of the early
> boot process in a RISC-V kernel.
>
> Signed-off-by: Alexandre Ghiti <[email protected]>
> Reviewed-by: Björn Töpel <[email protected]>
> Reviewed-by: Conor Dooley <[email protected]>
> Reviewed-by: Sunil V L <[email protected]>
> Reviewed-by: Andrew Jones <[email protected]>
> Reviewed-by: Palmer Dabbelt <[email protected]>
> Acked-by: Palmer Dabbelt <[email protected]>
> ---
> Documentation/riscv/boot-image-header.rst | 3 -
> Documentation/riscv/boot.rst | 170 ++++++++++++++++++++++
> Documentation/riscv/index.rst | 1 +
> 3 files changed, 171 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..09997bbe1b52
> --- /dev/null
> +++ b/Documentation/riscv/boot.rst
> @@ -0,0 +1,170 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================================
> +RISC-V Kernel Boot Requirements and Constraints
> +===============================================
> +
> +:Author: Alexandre Ghiti <[email protected]>
> +:Date: 23 May 2023
> +
> +This document describes what the RISC-V kernel expects from bootloaders and
> +firmware, but also the constraints that any developer must have in mind when
> +touching the early boot process. For the purposes of this document, the
> +'early boot process' refers to any code that runs before the final virtual
> +mapping is set up.
> +
> +Pre-kernel Requirements and Constraints
> +=======================================
> +
> +The RISC-V kernel expects the following of bootloaders and platform firmware:
> +
> +Register state
> +--------------
> +
> +The RISC-V kernel expects:
> +
> + * `$a0` to contain the hartid of the current core.
> + * `$a1` to contain the address of the devicetree in memory.
> +
> +CSR state
> +---------
> +
> +The RISC-V kernel expects:
> +
> + * `$satp = 0`: the MMU, if present, must be disabled.
> +
> +Reserved memory for resident firmware
> +-------------------------------------
> +
> +The RISC-V kernel must not map any resident memory, or memory protected with
> +PMPs, in the direct mapping, so the firmware must correctly mark those regions
> +as per the devicetree specification and/or the UEFI specification.
> +
> +Kernel location
> +---------------
> +
> +The RISC-V kernel expects to be placed at a PMD boundary (2MB aligned for rv64
> +and 4MB aligned for rv32). Note that the EFI stub will physically relocate the
> +kernel if that's not the case.
> +
> +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" section below for details about this devicetree.
> +
> +Kernel entrance
> +---------------
> +
> +On SMP systems, there are 2 methods to enter the kernel:
> +
> +- `RISCV_BOOT_SPINWAIT`: the firmware releases all harts in the kernel, one hart
> + wins a lottery and executes the early boot code while the other harts are
> + parked waiting for the initialization to finish. This method is mostly used to
> + support older firmwares without SBI HSM extension and M-mode RISC-V kernel.
> +- `Ordered booting`: the firmware releases only one hart that will execute the
> + initialization phase and then will start all other harts using the SBI HSM
> + extension. The ordered booting method is the preferred booting method for
> + booting the RISC-V kernel because it can support cpu hotplug and kexec.
> +
> +UEFI
> +----
> +
> +UEFI memory map
> +~~~~~~~~~~~~~~~
> +
> +When booting with UEFI, the RISC-V kernel will use only the EFI memory map to
> +populate the system memory.
> +
> +The UEFI firmware must parse the subnodes of the `/reserved-memory` devicetree
> +node and abide by the devicetree specification to convert the attributes of
> +those subnodes (`no-map` and `reusable`) into their correct EFI equivalent
> +(refer to section "3.5.4 /reserved-memory and UEFI" of the devicetree
> +specification v0.4-rc1).
> +
> +RISCV_EFI_BOOT_PROTOCOL
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +When booting with UEFI, the EFI stub requires the boot hartid in order to pass
> +it to the RISC-V kernel in `$a1`. The EFI stub retrieves the boot hartid using
> +one of the following methods:
> +
> +- `RISCV_EFI_BOOT_PROTOCOL` (**preferred**).
> +- `boot-hartid` devicetree subnode (**deprecated**).
> +
> +Any new firmware must implement `RISCV_EFI_BOOT_PROTOCOL` as the devicetree
> +based approach is deprecated now.
> +
> +Early Boot Requirements and Constraints
> +=======================================
> +
> +The RISC-V kernel's early boot process operates under the following constraints:
> +
> +EFI stub and devicetree
> +-----------------------
> +
> +When booting with UEFI, the devicetree is supplemented (or created) by the EFI
> +stub with the same parameters as arm64 which are described at the paragraph
> +"UEFI kernel support on ARM" in Documentation/arm/uefi.rst.
> +
> +Virtual mapping installation
> +----------------------------
> +
> +The installation of the virtual mapping is done in 2 steps in the RISC-V kernel:
> +
> +1. :c:func:`setup_vm` installs a temporary kernel mapping in
> + :c:var:`early_pg_dir` which allows discovery of the system memory. Only the
> + kernel text/data are mapped at this point. When establishing this mapping, no
> + allocation can be done (since the system memory is not known yet), so
> + :c:var:`early_pg_dir` page table is statically allocated (using only one
> + table for each level).
> +
> +2. :c:func:`setup_vm_final` creates the final kernel mapping in
> + :c:var:`swapper_pg_dir` and takes advantage of the discovered system memory
> + to create the linear mapping. When establishing this mapping, the kernel
> + can allocate memory but cannot access it directly (since the direct mapping
> + is not present yet), so it uses temporary mappings in the fixmap region to
> + be able to access the newly allocated page table levels.
> +
> +For :c:func:`virt_to_phys` and :c:func:`phys_to_virt` to be able to correctly
> +convert direct mapping addresses to physical addresses, they need to know the
> +start of the DRAM. This happens after step 1, right before step 2 installs the
> +direct mapping (see :c:func:`setup_bootmem` function in arch/riscv/mm/init.c).
> +Any usage of those macros before the final virtual mapping is installed must
> +be carefully examined.
> +
> +Devicetree mapping via fixmap
> +-----------------------------
> +
> +As the :c:var:`reserved_mem` array is initialized with virtual addresses
> +established by :c:func:`setup_vm`, and used with the mapping established by
> +:c:func:`setup_vm_final`, the RISC-V kernel uses the fixmap region to map the
> +devicetree. This ensures that the devicetree remains accessible by both virtual
> +mappings.
> +
> +Pre-MMU execution
> +-----------------
> +
> +A few pieces of code need to run before even the first virtual mapping is
> +established. These are the installation of the first virtual mapping itself,
> +patching of early alternatives and the early parsing of the kernel command line.
> +That code must be very carefully compiled as:
> +
> +- `-fno-pie`: This is needed for relocatable kernels which use `-fPIE`, since
> + otherwise, any access to a global symbol would go through the GOT which is
> + only relocated virtually.
> +- `-mcmodel=medany`: Any access to a global symbol must be PC-relative to avoid
> + any relocations to happen before the MMU is setup.
> +- *all* instrumentation must also be disabled (that includes KASAN, ftrace and
> + others).
> +
> +As using a symbol from a different compilation unit requires this unit to be
> +compiled with those flags, we advise, as much as possible, not to use external
> +symbols.
> diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
> index 175a91db0200..1f66062def6d 100644
> --- a/Documentation/riscv/index.rst
> +++ b/Documentation/riscv/index.rst
> @@ -5,6 +5,7 @@ RISC-V architecture
> .. toctree::
> :maxdepth: 1
>
> + boot
> boot-image-header
> vm-layout
> hwprobe
> --
> 2.39.2
>
>
> _______________________________________________
> linux-riscv mailing list
> [email protected]
> http://lists.infradead.org/mailman/listinfo/linux-riscv
Reviewed-by: Atish Patra <[email protected]>
--
Regards,
Atish
Hi Alexandre,
kernel test robot noticed the following build warnings:
[auto build test WARNING on v6.4-rc7]
[also build test WARNING on linus/master next-20230623]
[cannot apply to lwn/docs-next]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Alexandre-Ghiti/Documentation-riscv-Add-early-boot-document/20230623-175814
base: v6.4-rc7
patch link: https://lore.kernel.org/r/20230623095547.51881-2-alexghiti%40rivosinc.com
patch subject: [PATCH v3 2/3] Documentation: riscv: Add early boot document
reproduce: (https://download.01.org/0day-ci/archive/20230624/[email protected]/reproduce)
If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <[email protected]>
| Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
All warnings (new ones prefixed by >>):
>> Documentation/riscv/boot.rst:122: WARNING: Unknown interpreted text role "c:var".
vim +122 Documentation/riscv/boot.rst
121
> 122 1. :c:func:`setup_vm` installs a temporary kernel mapping in
123 :c:var:`early_pg_dir` which allows discovery of the system memory. Only the
124 kernel text/data are mapped at this point. When establishing this mapping, no
125 allocation can be done (since the system memory is not known yet), so
126 :c:var:`early_pg_dir` page table is statically allocated (using only one
127 table for each level).
128
--
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki
在 2023/6/23 17:55, Alexandre Ghiti 写道:
> The bootargs node is also added by the EFI stub in the function
> update_fdt(), so add it to the table.
>
> Signed-off-by: Alexandre Ghiti <[email protected]>
> ---
> Documentation/arm/uefi.rst | 4 +++-
> 1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/arm/uefi.rst b/Documentation/arm/uefi.rst
> index baebe688a006..2b7ad9bd7cd2 100644
> --- a/Documentation/arm/uefi.rst
> +++ b/Documentation/arm/uefi.rst
> @@ -50,7 +50,7 @@ The stub populates the FDT /chosen node with (and the kernel scans for) the
> following parameters:
>
> ========================== ====== ===========================================
> -Name Size Description
> +Name Type Description
> ========================== ====== ===========================================
> linux,uefi-system-table 64-bit Physical address of the UEFI System Table.
>
> @@ -67,4 +67,6 @@ linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format.
>
> kaslr-seed 64-bit Entropy used to randomize the kernel image
> base address location.
> +
> +bootargs String Kernel command line
> ========================== ====== ===========================================
Reviewed-by: Song Shuai <[email protected]>
--
Thanks
Song Shuai
在 2023/6/23 17:55, Alexandre Ghiti 写道:
> This document describes the constraints and requirements of the early
> boot process in a RISC-V kernel.
>
> Signed-off-by: Alexandre Ghiti <[email protected]>
> Reviewed-by: Björn Töpel <[email protected]>
> Reviewed-by: Conor Dooley <[email protected]>
> Reviewed-by: Sunil V L <[email protected]>
> Reviewed-by: Andrew Jones <[email protected]>
> Reviewed-by: Palmer Dabbelt <[email protected]>
> Acked-by: Palmer Dabbelt <[email protected]>
> ---
> Documentation/riscv/boot-image-header.rst | 3 -
> Documentation/riscv/boot.rst | 170 ++++++++++++++++++++++
> Documentation/riscv/index.rst | 1 +
> 3 files changed, 171 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..09997bbe1b52
> --- /dev/null
> +++ b/Documentation/riscv/boot.rst
> @@ -0,0 +1,170 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================================
> +RISC-V Kernel Boot Requirements and Constraints
> +===============================================
> +
> +:Author: Alexandre Ghiti <[email protected]>
> +:Date: 23 May 2023
> +
> +This document describes what the RISC-V kernel expects from bootloaders and
> +firmware, but also the constraints that any developer must have in mind when
> +touching the early boot process. For the purposes of this document, the
> +'early boot process' refers to any code that runs before the final virtual
> +mapping is set up.
> +
> +Pre-kernel Requirements and Constraints
> +=======================================
> +
> +The RISC-V kernel expects the following of bootloaders and platform firmware:
> +
> +Register state
> +--------------
> +
> +The RISC-V kernel expects:
> +
> + * `$a0` to contain the hartid of the current core.
> + * `$a1` to contain the address of the devicetree in memory.
> +
> +CSR state
> +---------
> +
> +The RISC-V kernel expects:
> +
> + * `$satp = 0`: the MMU, if present, must be disabled.
> +
> +Reserved memory for resident firmware
> +-------------------------------------
> +
> +The RISC-V kernel must not map any resident memory, or memory protected with
> +PMPs, in the direct mapping, so the firmware must correctly mark those regions
> +as per the devicetree specification and/or the UEFI specification.
> +
> +Kernel location
> +---------------
> +
> +The RISC-V kernel expects to be placed at a PMD boundary (2MB aligned for rv64
> +and 4MB aligned for rv32). Note that the EFI stub will physically relocate the
> +kernel if that's not the case.
> +
> +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" section below for details about this devicetree.
> +
> +Kernel entrance
> +---------------
> +
> +On SMP systems, there are 2 methods to enter the kernel:
> +
> +- `RISCV_BOOT_SPINWAIT`: the firmware releases all harts in the kernel, one hart
> + wins a lottery and executes the early boot code while the other harts are
> + parked waiting for the initialization to finish. This method is mostly used to
> + support older firmwares without SBI HSM extension and M-mode RISC-V kernel.
> +- `Ordered booting`: the firmware releases only one hart that will execute the
> + initialization phase and then will start all other harts using the SBI HSM
> + extension. The ordered booting method is the preferred booting method for
> + booting the RISC-V kernel because it can support cpu hotplug and kexec.
> +
> +UEFI
> +----
> +
> +UEFI memory map
> +~~~~~~~~~~~~~~~
> +
> +When booting with UEFI, the RISC-V kernel will use only the EFI memory map to
> +populate the system memory.
> +
> +The UEFI firmware must parse the subnodes of the `/reserved-memory` devicetree
> +node and abide by the devicetree specification to convert the attributes of
> +those subnodes (`no-map` and `reusable`) into their correct EFI equivalent
> +(refer to section "3.5.4 /reserved-memory and UEFI" of the devicetree
> +specification v0.4-rc1).
> +
> +RISCV_EFI_BOOT_PROTOCOL
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +When booting with UEFI, the EFI stub requires the boot hartid in order to pass
> +it to the RISC-V kernel in `$a1`. The EFI stub retrieves the boot hartid using
> +one of the following methods:
> +
> +- `RISCV_EFI_BOOT_PROTOCOL` (**preferred**).
> +- `boot-hartid` devicetree subnode (**deprecated**).
> +
> +Any new firmware must implement `RISCV_EFI_BOOT_PROTOCOL` as the devicetree
> +based approach is deprecated now.
> +
> +Early Boot Requirements and Constraints
> +=======================================
> +
> +The RISC-V kernel's early boot process operates under the following constraints:
> +
> +EFI stub and devicetree
> +-----------------------
> +
> +When booting with UEFI, the devicetree is supplemented (or created) by the EFI
> +stub with the same parameters as arm64 which are described at the paragraph
> +"UEFI kernel support on ARM" in Documentation/arm/uefi.rst.
> +
> +Virtual mapping installation
> +----------------------------
> +
> +The installation of the virtual mapping is done in 2 steps in the RISC-V kernel:
> +
> +1. :c:func:`setup_vm` installs a temporary kernel mapping in
> + :c:var:`early_pg_dir` which allows discovery of the system memory. Only the
> + kernel text/data are mapped at this point. When establishing this mapping, no
> + allocation can be done (since the system memory is not known yet), so
> + :c:var:`early_pg_dir` page table is statically allocated (using only one
> + table for each level).
> +
> +2. :c:func:`setup_vm_final` creates the final kernel mapping in
> + :c:var:`swapper_pg_dir` and takes advantage of the discovered system memory
> + to create the linear mapping. When establishing this mapping, the kernel
> + can allocate memory but cannot access it directly (since the direct mapping
> + is not present yet), so it uses temporary mappings in the fixmap region to
> + be able to access the newly allocated page table levels.
> +
> +For :c:func:`virt_to_phys` and :c:func:`phys_to_virt` to be able to correctly
> +convert direct mapping addresses to physical addresses, they need to know the
> +start of the DRAM. This happens after step 1, right before step 2 installs the
> +direct mapping (see :c:func:`setup_bootmem` function in arch/riscv/mm/init.c).
> +Any usage of those macros before the final virtual mapping is installed must
> +be carefully examined.
> +
> +Devicetree mapping via fixmap
> +-----------------------------
> +
> +As the :c:var:`reserved_mem` array is initialized with virtual addresses
> +established by :c:func:`setup_vm`, and used with the mapping established by
> +:c:func:`setup_vm_final`, the RISC-V kernel uses the fixmap region to map the
> +devicetree. This ensures that the devicetree remains accessible by both virtual
> +mappings.
> +
> +Pre-MMU execution
> +-----------------
> +
> +A few pieces of code need to run before even the first virtual mapping is
> +established. These are the installation of the first virtual mapping itself,
> +patching of early alternatives and the early parsing of the kernel command line.
> +That code must be very carefully compiled as:
> +
> +- `-fno-pie`: This is needed for relocatable kernels which use `-fPIE`, since
> + otherwise, any access to a global symbol would go through the GOT which is
> + only relocated virtually.
> +- `-mcmodel=medany`: Any access to a global symbol must be PC-relative to avoid
> + any relocations to happen before the MMU is setup.
> +- *all* instrumentation must also be disabled (that includes KASAN, ftrace and
> + others).
> +
> +As using a symbol from a different compilation unit requires this unit to be
> +compiled with those flags, we advise, as much as possible, not to use external
> +symbols.
> diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
> index 175a91db0200..1f66062def6d 100644
> --- a/Documentation/riscv/index.rst
> +++ b/Documentation/riscv/index.rst
> @@ -5,6 +5,7 @@ RISC-V architecture
> .. toctree::
> :maxdepth: 1
>
> + boot
> boot-image-header
> vm-layout
> hwprobe
Reviewed-by: Song Shuai <[email protected]>
--
Thanks
Song Shuai
Hi Jonathan,
On Fri, Jun 23, 2023 at 3:44 PM Jonathan Corbet <[email protected]> wrote:
>
> Alexandre Ghiti <[email protected]> writes:
>
> > This document describes the constraints and requirements of the early
> > boot process in a RISC-V kernel.
>
> Some quick comments...
>
> > +The RISC-V kernel expects:
> > +
> > + * `$a0` to contain the hartid of the current core.
> > + * `$a1` to contain the address of the devicetree in memory.
>
> Single `backtick` quotes are probably not doing what you want. If
> you're looking for it to render in a monospace font, use ``double``
> quotes instead. But I'd also encourage you to keep that to a minimum to
> avoid overly cluttering the plain-text document.
Indeed, the rendering is better with double quotes, thanks.
>
> [...]
>
> > +Virtual mapping installation
> > +----------------------------
> > +
> > +The installation of the virtual mapping is done in 2 steps in the RISC-V kernel:
> > +
> > +1. :c:func:`setup_vm` installs a temporary kernel mapping in
>
> Please don't use :c:func:. If you just write setup_vm(), all the right
> magic will happen.
The magic indeed happens with virt_to_phys()/phys_to_virt(), but not
with setup_vm(): is there something we should do when declaring those
functions?
>
> > + :c:var:`early_pg_dir` which allows discovery of the system memory. Only the
>
> We also really just don't use :c:var: at all. Kerneldoc doesn't
> currently know about global variables...perhaps it should but that's not
> the way of things now.
Ok, noted, I remove those "c:XXX".
Thanks
>
> Thanks,
>
> jon
>
Alexandre Ghiti <[email protected]> writes:
>> Please don't use :c:func:. If you just write setup_vm(), all the right
>> magic will happen.
>
> The magic indeed happens with virt_to_phys()/phys_to_virt(), but not
> with setup_vm(): is there something we should do when declaring those
> functions?
If the function in question has no kerneldoc comment, there will be
nothing to make the magic link to. In other words, if you want it to
link to the documentation, the documentation needs to actually exist :)
Thanks,
jon
On Sun, Jun 25, 2023 at 10:39 PM Jonathan Corbet <[email protected]> wrote:
>
> Alexandre Ghiti <[email protected]> writes:
>
> >> Please don't use :c:func:. If you just write setup_vm(), all the right
> >> magic will happen.
> >
> > The magic indeed happens with virt_to_phys()/phys_to_virt(), but not
> > with setup_vm(): is there something we should do when declaring those
> > functions?
>
> If the function in question has no kerneldoc comment, there will be
> nothing to make the magic link to. In other words, if you want it to
> link to the documentation, the documentation needs to actually exist :)
Ok, that's for another patchset then, thanks for your help!
>
> Thanks,
>
> jon