docs/LoongArch: Add English and Chinese versions of booting
Subsystems (3)
v3 cover docs/LoongArch: Add English and Chinese versions of booting
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
PATCH v3 1/2 docs/LoongArch: Add booting
Describes the meaning and value of the image header field.
Suggested-by Xiaotian Wu <[email protected]>
Signed-off-by Yanteng Si <[email protected]>
--- 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
@@ -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 is an ACPI system and the information that needs to be passed +to the kernel are memmap, initrd, cmdline, 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, +cmdline 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
@@ -10,6 +10,7 @@ LoongArch Architecture introduction irq-chip-model + booting features
Signature · 1 line
2.31.1
PATCH v3 2/2 docs/zh_CN: Add booting Chinese translation
In reply to Yanteng SiTranslate ../loongarch/booting.rst into Chinese.
Suggested-by Xiaotian Wu <[email protected]>
Signed-off-by Yanteng Si <[email protected]>
--- .../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
@@ -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系统,需要传递给内核的信息有memmap、initrd、cmdline等。 +而在LoongArch机器上,BootLoader(EFISTUB/Grub)会给内核传递三个有效参数, +它们分别是:: + + a0 = efi_boot + a1 = cmdline + a2 = systemtable + +其中a1是指向cmdline的指针,a2则包含了需要传递给内核的memmap、initrd、cmdline…… + +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
@@ -15,6 +15,7 @@ LoongArch体系结构 introduction irq-chip-model + booting features
Signature · 1 line
2.31.1