Skip to contentSkip to conversation

docs/LoongArch: Add English and Chinese versions of boot image header

PATCH Superseded Yanteng Si 2 participants 4 messages Nov 24, 2022 – Nov 25, 2022

Subsystems (3)

v2 of 5 Superseded Latest is v5 →

lore
Share & tools
lore

Yanteng Si

author
#0 lore raw

v2 cover docs/LoongArch: Add English and Chinese versions of boot image header

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

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

Yanteng Si (2):
docs/LoongArch: Add boot image header docs/zh_CN: Add boot-image-header Chinese translation

 Documentation/loongarch/boot-image-header.rst | 76 ++++++++++++++++++
 Documentation/loongarch/index.rst             |  1 +
 .../zh_CN/loongarch/boot-image-header.rst     | 77 +++++++++++++++++++
 .../translations/zh_CN/loongarch/index.rst    |  1 +
 4 files changed, 155 insertions(+)
 create mode 100644 Documentation/loongarch/boot-image-header.rst
 create mode 100644 Documentation/translations/zh_CN/loongarch/boot-image-header.rst
Signature · 1 line
2.31.1
author
#1 lore raw

PATCH v2 1/2 docs/LoongArch: Add boot image header

Describes the meaning and value of the image header field.

---
 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
Documentation/loongarch/boot-image-header.rst new file +76 -0
new file mode 100644
index 000000000000..9fd8f3538175
@@ -0,0 +1,76 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Boot image header in LoongArch Linux
+====================================
+
+:Author: Yanteng Si <[email protected]>
+: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::
+
+          +-----------------------------------------------+
+          |  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..97419821adf9 100644
@@ -10,6 +10,7 @@ LoongArch Architecture
 
    introduction
    irq-chip-model
+   boot-image-header
 
    features
 
Signature · 1 line
2.31.1
author
#2 lore raw

PATCH v2 2/2 docs/zh_CN: Add boot-image-header Chinese translation

In reply to Yanteng Si

Translate ../loongarch/boot-image-header.rst into Chinese.

---
 .../zh_CN/loongarch/boot-image-header.rst     | 77 +++++++++++++++++++
 .../translations/zh_CN/loongarch/index.rst    |  1 +
 2 files changed, 78 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/loongarch/boot-image-header.rst
Documentation/translations/zh_CN/loongarch/boot-image-header.rst new file +77 -0
new file mode 100644
index 000000000000..e40889d4cb63
@@ -0,0 +1,77 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/loongarch/boot-image-header.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <[email protected]>
+
+=============================
+LoongArch Linux启动镜像文件头
+=============================
+
+:作者: 司延腾 <[email protected]>
+:日期: 18 Nov 2022
+
+此文档仅描述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..625597792fd9 100644
@@ -15,6 +15,7 @@ LoongArch体系结构
 
    introduction
    irq-chip-model
+   boot-image-header
 
    features
 
Signature · 1 line
2.31.1
maintainer
#3 lore raw
In reply to Yanteng Si

Hi, Yanteng,

I hope you can add a description about boot parameters (a0=efi_boot a1=cmdline a2=systemtable), and then rename the file to booting.rst.

Huacai

Quoted 25 lines · Yanteng Si

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

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

Yanteng Si (2):
docs/LoongArch: Add boot image header docs/zh_CN: Add boot-image-header Chinese translation

 Documentation/loongarch/boot-image-header.rst | 76 ++++++++++++++++++
 Documentation/loongarch/index.rst             |  1 +
 .../zh_CN/loongarch/boot-image-header.rst     | 77 +++++++++++++++++++
 .../translations/zh_CN/loongarch/index.rst    |  1 +
 4 files changed, 155 insertions(+)
 create mode 100644 Documentation/loongarch/boot-image-header.rst
 create mode 100644 Documentation/translations/zh_CN/loongarch/boot-image-header.rst

--
2.31.1