Re: [PATCH v4 1/2] docs/LoongArch: Add booting

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On 11/29/22 09:52, Yanteng Si wrote:
Describes the meaning and value of the image header field.

Suggested-by: Xiaotian Wu <wuxiaotian@xxxxxxxxxxx>
Signed-off-by: Yanteng Si <siyanteng@xxxxxxxxxxx>
---
  Documentation/loongarch/booting.rst | 89 +++++++++++++++++++++++++++++
  Documentation/loongarch/index.rst   |  1 +
  2 files changed, 90 insertions(+)
  create mode 100644 Documentation/loongarch/booting.rst

diff --git a/Documentation/loongarch/booting.rst b/Documentation/loongarch/booting.rst
new file mode 100644
index 000000000000..90456f713c48
--- /dev/null
+++ b/Documentation/loongarch/booting.rst
@@ -0,0 +1,89 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+启动 LoongArch Linux

Forgot to translate this? ;-)

Also it's probably more idiomatic to use the "Linux/LoongArch" convention throughout, as can be seen from similar previous usages such as "Linux/Alpha", "Linux/IA64", "Linux/PA-RISC" or "Linux/MIPS". (Of course it's "RISC-V Linux" according to my grep result but it's probably better to stick to traditions here IMO.)

+====================
+
+:Author: Yanteng Si <siyanteng@xxxxxxxxxxx>
+:Date:   18 Nov 2022
+
+BootLoader passing parameters to the kernel
"Bootloader" or "Boot loader", but not "BootLoader".
+===========================================
+
+LoongArch supports ACPI and FDT. The information that needs to be
+passed to the kernel are memmap, initrd, cmdline, fdt, etc.
Perhaps "... includes the memmap, the initrd, the command line, optionally the FDT, and so on." could be better?
+On LoongArch machines, the BootLoader (EFISTUB/Grub) will pass three
+valid parameters to the kernel, which are::

The "on LoongArch machines" seems redundant, we're a LoongArch document so it's kinda implied information. Also drop "valid" as it's quite obvious too.

And it's not the bootloader that provides the kernel with those 3 arguments, kernel_entry isn't directly called by firmware but rather by the EFI stub. And I doubt the FDT boot flow invokes kernel_entry either. Let's clarify things then, make the whole paragraph something like this:

"The kernel is passed the following arguments on `kernel_entry`::"

+
+      a0 = efi_boot
+      a1 = cmdline
+      a2 = systemtable
+
+where a1 is a pointer to cmdline, a2 contains the memmap, initrd,
+fdt(opt) and other information that needs to be passed to the kernel.

Please use a list for enumerating the 3 arguments.

Also the list belongs to the previous sentence, so you shouldn't start this paragraph with "where" but rather please use a new sentence. And the fact that a0 is a flag indicating whether full UEFI capabilities are present needs mentioning too.

"`efi_boot` is a flag indicating whether this boot environment is fully UEFI-compliant. `cmdline` is a pointer to the kernel command line. `systemtable` points to the EFI system table. All pointers involved at this stage are in physical addresses."

+
+Boot image header in LoongArch Linux
"Header of Linux/LoongArch kernel images"
+====================================
+
+The following 64-byte header is present in decompressed Linux
+kernel image::

Everything becomes crystal clear when you somehow indicate it's just the DOS header of the EFI stub. Also AFAIK no LoongArch bootloader decompress the kernel image themselves, so it's not like there exists any "compressed Linux kernel image".

"Linux/LoongArch kernel images are EFI images. Being PE files, they have a 64-byte header structured like::"

+
+	u32	MZ_MAGIC		/* "MZ", MS-DOS header */
+	u32	res0 = 0		/* reserved */
+	u64	kernel_entry		/* Kernel entry point */
+	u64	_end - _text		/* Kernel image effective size */
+	u64	0			/* Kernel image load offset from start of RAM */
+	u64	res1 = 0		/* reserved */
+	u64	res2 = 0		/* reserved */
+	u64	res3 = 0		/* reserved */
+	u32	res4 = 0		/* reserved */
+	u32	pe_header - _head	/* Offset to the PE header */
+
+Header notes
+============
No need for a new section: the rest are all explanations to the structure mentioned above.
+
+Currently, LoongArch has removed the "magic" field.

Needs more background information, and (IMO) unnatural topicalization.

"LoongArch has abolished the use of a magic number for identifying the boot image as one for the LoongArch, because ..."

Right now, unfortunately I don't have enough time for providing all the details for the justification of removal of magic number, but you can refer to previous (long) threads where the earlier versions of the arch EFI boot code were reviewed. Pay attention especially to ardb's very detailed and in-depth explanation, you want to "transplant" the info here.

+
+According to the EFI specification, the PE/COFF image file header is
+required at the beginning of the kernel image; the LoongArch kernel
+supports the EFI stub, so the first two bytes of the kernel image header
+are "MZ" magic characters, and 0x3c should point to the rest of the
+PE/COFF file header, between which The kernel entry point, image
+effectivesize, and image load offset layout are as follows::
+
+          +-----------------------------------------------+
+          |  0  |  1  |  2  |  3  |  4  |  5  |  6  |  7  |
+          +-----------------------------------------------+
+    0x00: |       MZ_MAGIC        |          res0         |
+          +-----------------------------------------------+
+    0x08: |                 kernel_entry                  |
+          +-----------------------------------------------+
+    0x10: |                  _end - _text                 |
+          +-----------------------------------------------+
+    0x18: |                       0                       |
+          +-----------------------------------------------+
+    0x20: |                      res1                     |
+          +-----------------------------------------------+
+    0x28: |                      res2                     |
+          +-----------------------------------------------+
+    0x30: |                      res3                     |
+          +-----------------------------------------------+
+    0x38: |          res4         |       PE header       |
+          +-----------------------------------------------+

This is repeating the structure described above, only in a pictorial form. I think only one needs to be kept.

+
+All bit fields are in little endian:
+
+    - MZ: Effective length of 2 bytes;
+
+    - kernel entry point: leaving 6 bytes blank in front, starting
+      from 0x8, with a effective length of 8 bytes;
+
+    - kernel image effective size: Immediately following the kernel
+      entry point, with a effective length of 8 bytes, this field is
+      required for the bootloader;

The boot loader probably doesn't care. GRUB2 just chain-loads after recognizing the image as valid EFI application, and the firmware most certainly just do its routine EFI application launch too without looking at the contents here that are all in fact just reserved space. (IIUC only the MZ signature and the PE header offset matter here; everything in between is actually part of the DOS stub which is ignored on all modern platforms.)

So, please clarify which component requires this info; is it the EFI stub instead? (I haven't checked myself though due to limited review time. Sorry for that.)

+
+    - kernel image load offset: Immediately following the kernel
+      image effective size, with a effective length of 8 bytes;
+
+    - Offset to the PE header: leaving 28 bytes blank in front,
+      starting from 0x3c, with a effective length of 4 bytes.
Drop explanation for trivial things like MZ or the PE header offset, they're just common PE format thing, and totally unrelated to Linux.
diff --git a/Documentation/loongarch/index.rst b/Documentation/loongarch/index.rst
index aaba648db907..df0174d6d227 100644
--- a/Documentation/loongarch/index.rst
+++ b/Documentation/loongarch/index.rst
@@ -10,6 +10,7 @@ LoongArch Architecture
introduction
     irq-chip-model
+   booting
features

--
WANG "xen0n" Xuerui

Linux/LoongArch mailing list: https://lore.kernel.org/loongarch/




[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux