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/boot-image-header.rst | 76 +++++++++++++++++++
Documentation/loongarch/index.rst | 1 +
2 files changed, 77 insertions(+)
create mode 100644 Documentation/loongarch/boot-image-header.rst
diff --git a/Documentation/loongarch/boot-image-header.rst b/Documentation/loongarch/boot-image-header.rst
new file mode 100644
index 000000000000..92a953a6f2e6
--- /dev/null
+++ b/Documentation/loongarch/boot-image-header.rst
@@ -0,0 +1,76 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Boot image header in LoongArch Linux
+====================================
+
+:Author: Yanteng Si <siyanteng@xxxxxxxxxxx>
+:Date: 18 Nov 2022
+
+This document only describes the boot image header details for
+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::
+
+ +-----------------------------------------------+
+ 0x0: | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+ +-----------------------------------------------+
+ 0x8: | MZ_MAGIC | res0 |
+ +-----------------------------------------------+
+ 0x10: | kernel_entry |
+ +-----------------------------------------------+
+ 0x18: | _end - _text |
+ +-----------------------------------------------+
+ 0x20: | 0 |
+ +-----------------------------------------------+
+ 0x28: | res1 |
+ +-----------------------------------------------+
+ 0x30: | res2 |
+ +-----------------------------------------------+
+ 0x38: | res3 |
+ +-----------------------------------------------+
+ 0x40: | res14 | 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.
diff --git a/Documentation/loongarch/index.rst b/Documentation/loongarch/index.rst
index aaba648db907..97419821adf9 100644
--- a/Documentation/loongarch/index.rst
+++ b/Documentation/loongarch/index.rst
@@ -10,6 +10,7 @@ LoongArch Architecture
introduction
irq-chip-model
+ boot-image-header
features
--
2.31.1
