Skip to contentSkip to conversation

docs/LoongArch: Add English and Chinese versions of booting

PATCH Superseded Yanteng Si 3 participants 7 messages Nov 29, 2022 – Dec 5, 2022 1 message not in the archive

Subsystems (3)

v4 of 5 Superseded Latest is v5 →

lore
Share & tools
lore

Yanteng Si

author
#0 lore raw

v4 cover docs/LoongArch: Add English and Chinese versions of booting

v4:
LoongArch supports ACPI and FDT, so let's add the description of fdt.

v3:
* Add a description about boot parameters (a0=efi_boot a1=cmdline a2=systemtable), and then rename the file to booting.rst.
* remove some blank line.

v2:
* Fix magic start address.
* res14 -> res4.

v1:
* Add boot image header.
* Translate boot-image-header into Chinese.

Yanteng Si (2):
docs/LoongArch: Add booting
docs/zh_CN: Add booting Chinese translation

 Documentation/loongarch/booting.rst           | 89 +++++++++++++++++++
 Documentation/loongarch/index.rst             |  1 +
 .../translations/zh_CN/loongarch/booting.rst  | 86 ++++++++++++++++++
 .../translations/zh_CN/loongarch/index.rst    |  1 +
 4 files changed, 177 insertions(+)
 create mode 100644 Documentation/loongarch/booting.rst
 create mode 100644 Documentation/translations/zh_CN/loongarch/booting.rst
Signature · 1 line
2.31.1
author
#1 lore raw

PATCH v4 1/2 docs/LoongArch: Add booting

Describes the meaning and value of the image header field.

---
 Documentation/loongarch/booting.rst | 89 +++++++++++++++++++++++++++++
 Documentation/loongarch/index.rst   |  1 +
 2 files changed, 90 insertions(+)
 create mode 100644 Documentation/loongarch/booting.rst
Documentation/loongarch/booting.rst new file +89 -0
new file mode 100644
index 000000000000..90456f713c48
@@ -0,0 +1,89 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+启动 LoongArch Linux
+====================
+
+:Author: Yanteng Si <[email protected]>
+:Date:   18 Nov 2022
+
+BootLoader passing parameters to the kernel
+===========================================
+
+LoongArch supports ACPI and FDT. The information that needs to be
+passed to the kernel are memmap, initrd, cmdline, fdt, etc.
+On LoongArch machines, the BootLoader (EFISTUB/Grub) will pass three
+valid parameters to the kernel, which are::
+
+      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.
+
+Boot image header in LoongArch Linux
+====================================
+
+The following 64-byte header is present in decompressed Linux
+kernel image::
+
+	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
+============
+
+Currently, LoongArch has removed the "magic" field.
+
+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       |
+          +-----------------------------------------------+
+
+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;
+
+    - 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.
Documentation/loongarch/index.rst +1 -0
index aaba648db907..df0174d6d227 100644
@@ -10,6 +10,7 @@ LoongArch Architecture
 
    introduction
    irq-chip-model
+   booting
 
    features
 
Signature · 1 line
2.31.1
reviewer
#2 lore raw

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

Quoted 16 lines · Yanteng Si

Describes the meaning and value of the image header field.

---
  Documentation/loongarch/booting.rst | 89 +++++++++++++++++++++++++++++
  Documentation/loongarch/index.rst   |  1 +
  2 files changed, 90 insertions(+)

create mode 100644 Documentation/loongarch/booting.rst

Documentation/loongarch/booting.rst new file +0 -0
new file mode 100644
index 000000000000..90456f713c48

Documentation/loongarch/booting.rst line 4

Quoted 4 lines
Documentation/loongarch/booting.rst new file +4 -0
@@ -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.)

Documentation/loongarch/booting.rst line 10

Quoted 6 lines
Documentation/loongarch/booting.rst new file +6 -0
+====================
+
+:Author: Yanteng Si <[email protected]>
+:Date:   18 Nov 2022
+
+BootLoader passing parameters to the kernel

"Bootloader" or "Boot loader", but not "BootLoader".

Documentation/loongarch/booting.rst line 14

Quoted 4 lines
Documentation/loongarch/booting.rst new file +4 -0
+===========================================
+
+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?

Documentation/loongarch/booting.rst line 16

Quoted 2 lines
Documentation/loongarch/booting.rst new file +2 -0
+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::"

Documentation/loongarch/booting.rst line 23

Quoted 7 lines
Documentation/loongarch/booting.rst new file +7 -0
+
+      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."

Documentation/loongarch/booting.rst line 25

Quoted 2 lines
Documentation/loongarch/booting.rst new file +2 -0
+
+Boot image header in LoongArch Linux

"Header of Linux/LoongArch kernel images"

Documentation/loongarch/booting.rst line 29

Quoted 4 lines
Documentation/loongarch/booting.rst new file +4 -0
+====================================
+
+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::"

Quoted 4 lines
Documentation/loongarch/booting.rst new file +4 -0
+
+	u32	MZ_MAGIC		/* "MZ", MS-DOS header */
+	u32	res0 = 0		/* reserved */
+	u64	kernel_entry		/* Kernel entry point */

Documentation/loongarch/booting.rst line 43

Quoted 10 lines
Documentation/loongarch/booting.rst new file +10 -0
+	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.

Documentation/loongarch/booting.rst line 45

Quoted 2 lines
Documentation/loongarch/booting.rst new file +2 -0
+
+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.

Quoted 17 lines
Documentation/loongarch/booting.rst new file +17 -0
+
+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                 |
+          +-----------------------------------------------+

Documentation/loongarch/booting.rst line 72

Quoted 10 lines
Documentation/loongarch/booting.rst new file +10 -0
+    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.

Documentation/loongarch/booting.rst line 83

Quoted 11 lines
Documentation/loongarch/booting.rst new file +11 -0
+
+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.)

Documentation/loongarch/booting.rst line 89

Quoted 6 lines
Documentation/loongarch/booting.rst new file +6 -0
+
+    - 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.

Quoted 12 lines
Documentation/loongarch/index.rst +1 -0
index aaba648db907..df0174d6d227 100644
@@ -10,6 +10,7 @@ LoongArch Architecture
 
     introduction
     irq-chip-model
+   booting
 
     features
 
Signature · 3 lines
WANG "xen0n" Xuerui

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

A message that is not in the archive (sent off-list or not yet received): [email protected]

#4 lore raw

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

Quoted 227 lines · Yanteng Si <[email protected]> 于2022年11月29日周二 21:04写道:

On 11/29/22 10:40, WANG Xuerui wrote:

On 11/29/22 09:52, Yanteng Si wrote:

Describes the meaning and value of the image header field.

---
  Documentation/loongarch/booting.rst | 89 +++++++++++++++++++++++++++++
  Documentation/loongarch/index.rst   |  1 +
  2 files changed, 90 insertions(+)

create mode 100644 Documentation/loongarch/booting.rst

Documentation/loongarch/booting.rst new file +4 -0
new file mode 100644
index 000000000000..90456f713c48
@@ -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.)

OK!

Booting Linux/LoongArch

+====================

Documentation/loongarch/booting.rst new file +5 -0
+
+:Author: Yanteng Si <[email protected]>
+:Date:   18 Nov 2022
+
+BootLoader passing parameters to the kernel

"Bootloader" or "Boot loader", but not "BootLoader".

Ok!

Bootloader

+===========================================

Documentation/loongarch/booting.rst new file +3 -0
+
+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?

Great!

The information that needs to be passed to the kernel includes the memmap, the initrd, the command line, optionally the FDT, and so on.

Documentation/loongarch/booting.rst new file +2 -0
+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::"

OK!

Documentation/loongarch/booting.rst new file +7 -0
+
+      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."

OK, thanks!

Documentation/loongarch/booting.rst new file +2 -0
+
+Boot image header in LoongArch Linux

"Header of Linux/LoongArch kernel images"

OK!

+====================================

Documentation/loongarch/booting.rst new file +3 -0
+
+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::"

OK!

Documentation/loongarch/booting.rst new file +14 -0
+
+    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.

OK!

Documentation/loongarch/booting.rst new file +2 -0
+
+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.

OK!

Documentation/loongarch/booting.rst new file +27 -0
+
+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.

I don't think so.

The above corresponds to the struct in grub, this diagram is much more readable.

Documentation/loongarch/booting.rst new file +11 -0
+
+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.)

I wrote this article with partial reference to riscv.

See Documentation/riscv/boot-image-header.rst line 61:

- Image size is mandatory for boot loader to load kernel image. Booting will fail otherwise.

Documentation/loongarch/booting.rst new file +6 -0
+
+    - 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.

Here's just a simple description of the header bit fields, which is a prerequisite for understanding the boot image header.

Thanks,

Yanteng

Documentation/loongarch/index.rst +0 -0
index aaba648db907..df0174d6d227 100644

Documentation/loongarch/index.rst LoongArch Architecture · line 16

Quoted 7 lines
Documentation/loongarch/index.rst +1 -0
@@ -10,6 +10,7 @@ LoongArch Architecture
       introduction
     irq-chip-model
+   booting
       features
 
 
 

Sorry.

I don't know why my email client sent the html part, which caused the email to be rejected by the list, so I re-copied it to the list.

Thanks,
Yanteng

reviewer
#5 lore raw

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

In reply to a message not in the archive
Quoted 53 lines · Yanteng Si
Quoted 42 lines · WANG Xuerui
Quoted 41 lines · Yanteng Si

Describes the meaning and value of the image header field.

---
  Documentation/loongarch/booting.rst | 89
+++++++++++++++++++++++++++++
  Documentation/loongarch/index.rst   |  1 +

  2 files changed, 90 insertions(+)

  create mode 100644 Documentation/loongarch/booting.rst

Documentation/loongarch/booting.rst new file +0 -0
new file mode 100644
index 000000000000..90456f713c48
 
[snip]
Quoted 23 lines
Documentation/loongarch/booting.rst new file +4 -0
+
+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

Documentation/loongarch/booting.rst new file +17 -0
+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                     |
+          +-----------------------------------------------+
Quoted 8 lines
Quoted 8 lines
Quoted 6 lines

+    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.

Quoted 3 lines

I don't think so.

The above corresponds to the struct in grub, this diagram is much more readable.

How is an EFI stub image's header different in grub than somewhere else?

Quoted 18 lines
Quoted 16 lines

Documentation/loongarch/booting.rst line 83

Quoted 13 lines
Documentation/loongarch/booting.rst new file +11 -0
+
+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.)

Quoted 1 line

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.)

Quoted 7 lines

I wrote this article with partial reference to riscv.

See Documentation/riscv/boot-image-header.rst line 61:

- Image size is mandatory for boot loader to load kernel image. Booting will
  fail otherwise.

No, the LoongArch EFI boot protocol is not the same as that of RISC-V, we've taken lessons and I believe the LoongArch GRUB2 simply chain-loads the image without any of the extra Linux-specific checking. Please read the previous EFI boot patch threads carefully, and you can also ask Xiaotian or Huacai for details (they're both CC'd on this thread so they should have the context).

Quoted 11 lines
Quoted 9 lines

Documentation/loongarch/booting.rst line 89

Quoted 8 lines
Documentation/loongarch/booting.rst new file +6 -0
+
+    - 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.

Here's just a simple description of the header bit fields, which is a prerequisite for understanding the boot image header.

Since the boot image is just a PE file, and it's clearly mandated in the UEFI spec, I think some knowledge of the PE format should be necessary after all? In which case the reader could be pointed to the PE spec for the parts not related to Linux or LoongArch, and this document can stay focused on its main topic.

Quoted 16 lines

Thanks,

Yanteng

Quoted 10 lines
Quoted 9 lines
Documentation/loongarch/index.rst +0 -0
index aaba648db907..df0174d6d227 100644
@@ -10,6 +10,7 @@ LoongArch Architecture

       introduction
     irq-chip-model
+   booting
       features

Signature · 3 lines
WANG "xen0n" Xuerui

Linux/LoongArch mailing list: https://lore.kernel.org/loongarch/
author
#6 lore raw

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

Quoted 54 lines · WANG Xuerui
Quoted 53 lines · Yanteng Si
Quoted 50 lines · WANG Xuerui
Quoted 49 lines · Yanteng Si

Describes the meaning and value of the image header field.

---
  Documentation/loongarch/booting.rst | 89
+++++++++++++++++++++++++++++
  Documentation/loongarch/index.rst   |  1 +

  2 files changed, 90 insertions(+)

  create mode 100644 Documentation/loongarch/booting.rst

Documentation/loongarch/booting.rst new file +0 -0
new file mode 100644
index 000000000000..90456f713c48
 
[snip]
Quoted 19 lines
Documentation/loongarch/booting.rst new file +4 -0
+
+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

Documentation/loongarch/booting.rst new file +13 -0
+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 |
+ +-----------------------------------------------+

Documentation/loongarch/booting.rst line 72

Quoted 10 lines
Documentation/loongarch/booting.rst new file +10 -0
+    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.

Quoted 4 lines
Quoted 3 lines

I don't think so.

The above corresponds to the struct in grub, this diagram is much more readable.

How is an EFI stub image's header different in grub than somewhere else?

OK, remove it.

Quoted 18 lines
Quoted 18 lines
Quoted 17 lines

Documentation/loongarch/booting.rst line 83

Quoted 13 lines
Documentation/loongarch/booting.rst new file +11 -0
+
+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.)

Quoted 8 lines
Quoted 7 lines

I wrote this article with partial reference to riscv.

See Documentation/riscv/boot-image-header.rst line 61:

- Image size is mandatory for boot loader to load kernel image. Booting will
  fail otherwise.

No, the LoongArch EFI boot protocol is not the same as that of RISC-V, we've taken lessons and I believe the LoongArch GRUB2 simply chain-loads the image without any of the extra Linux-specific checking. Please read the previous EFI boot patch threads carefully, and you can also ask Xiaotian or Huacai for details (they're both CC'd on this thread so they should have the context).

Now, MAGIC is back.

Quoted 10 lines
Quoted 10 lines
Quoted 9 lines

Documentation/loongarch/booting.rst line 89

Quoted 8 lines
Documentation/loongarch/booting.rst new file +6 -0
+
+    - 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.

Quoted 2 lines
Quoted 1 line

Here's just a simple description of the header bit fields, which is a prerequisite for understanding the boot image header.

Since the boot image is just a PE file, and it's clearly mandated in the UEFI spec, I think some knowledge of the PE format should be necessary after all? In which case the reader could be pointed to the PE spec for the parts not related to Linux or LoongArch, and this document can stay focused on its main topic.

OK.

Thanks,

Yanteng

Quoted 16 lines
Quoted 16 lines

Thanks,

Yanteng

Quoted 10 lines
Quoted 9 lines
Documentation/loongarch/index.rst +0 -0
index aaba648db907..df0174d6d227 100644
@@ -10,6 +10,7 @@ LoongArch Architecture

       introduction
     irq-chip-model
+   booting
       features

author
#7 lore raw

PATCH v4 2/2 docs/zh_CN: Add booting Chinese translation

In reply to Yanteng Si

Translate ../loongarch/booting.rst into Chinese.

---
 .../translations/zh_CN/loongarch/booting.rst  | 86 +++++++++++++++++++
 .../translations/zh_CN/loongarch/index.rst    |  1 +
 2 files changed, 87 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/loongarch/booting.rst
Documentation/translations/zh_CN/loongarch/booting.rst new file +86 -0
new file mode 100644
index 000000000000..a78d5390f6d9
@@ -0,0 +1,86 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/loongarch/booting.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <[email protected]>
+
+====================
+启动 LoongArch Linux
+====================
+
+:作者: 司延腾 <[email protected]>
+:日期: 2022年11月18日
+
+BootLoader传递给内核的信息
+==========================
+
+LoongArch兼容ACPI和FDT,需要传递给内核的信息有memmap、initrd、cmdline、fdt等。
+而在LoongArch机器上,BootLoader(EFISTUB/Grub)会给内核传递三个有效参数,
+它们分别是::
+
+      a0 = efi_boot
+      a1 = cmdline
+      a2 = systemtable
+
+其中a1是指向cmdline的指针,a2则包含了需要传递给内核的memmap、initrd、fdt(可选的)……
+
+LoongArch Linux启动镜像文件头
+=============================
+
+在非压缩的Linux内核镜像中存在以下64字节的文件头::
+
+	u32	MZ_MAGIC		/* "MZ", MS-DOS 头 */
+	u32	res0 = 0		/* 保留 */
+	u64	kernel_entry		/* 内核入口点 */
+	u64	_end - _text		/* 内核镜像有效大小 */
+	u64	0			/* 从RAM开始的加载内核镜像的偏移量 */
+	u64	res1 = 0		/* 保留 */
+	u64	res2 = 0		/* 保留 */
+	u64	res3 = 0		/* 保留 */
+	u32	res4 = 0		/* 保留 */
+	u32	pe_header - _head	/* 到PE头的偏移量 */
+
+镜像头注释
+==========
+
+目前LoongArch已经移除“magic”结构体成员。
+
+按照EFI规范的规定,在内核镜像的开始需要PE/COFF镜像文件头。当前LoongArch内核支持
+EFI stub,故内核镜像头最开始两字节为“MZ”魔术字符,且0x3c处应指向PE/COFF文件头的
+其余部分,在此之间,内核的入口点、有效镜像大小、镜像加载偏移布局如下::
+
+          +-----------------------------------------------+
+          |  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       |
+          +-----------------------------------------------+
+
+所有的位域都是小端序:
+
+    - MZ:有效长度为2字节;
+
+    - 内核入口点:前留空6个字节,自0x8开始,有效长度为8字节;
+
+    - 内核镜像有效大小:紧接内核入口点,有效长度为8字节,该成员对于引导器来说是必须的;
+
+    - 内核镜像加载偏移:紧接内核镜像有效大小,有效长度为8字节;
+
+    - 到PE头的偏移量:前留空28字节,自0x3c开始,有效长度为4字节。
Documentation/translations/zh_CN/loongarch/index.rst +1 -0
index 7d23eb78379d..8609ade41981 100644
@@ -15,6 +15,7 @@ LoongArch体系结构
 
    introduction
    irq-chip-model
+   booting
 
    features
 
Signature · 1 line
2.31.1