easyboot/docs/zh/plugins.md

Easyboot 插件

默认情况下，Easyboot 从启动分区启动 ELF 和 PE 格式的 Multiboot2 兼容内核。如果您的内核使用不同的文件格式、 不同的启动协议，或者不在启动分区上，那么您将需要启动分区上的插件。您可以在 src/plugins 目录中找到这些插件。

[[TOC]]

安装

要安装插件，只需将它们复制到 (indir) 参数中指定的目录中，该目录位于 menu.cfg 文件旁边的 easyboot 子目录下。

例如：

bootpart
|-- easyboot
|   |-- linux_x86.plg
|   |-- minix_x86.plg
|   `-- menu.cfg
|-- EFI
|   `-- BOOT
|-- kernel
`-- initrd
$ easyboot bootpart 磁盘.img

汇编

从一开始就很明显，ELF 不适合这项任务。它太臃肿、太复杂了。所以最初我想使用 struct exec（经典的 UNIX a.out 格式），但不幸的是， 现代工具链无法再创建这种格式。所以我决定为插件创建自己的格式和自己的链接器。

您可以使用任何标准 ANSI C 交叉编译器将插件的源代码编译成 ELF 目标文件，但随后您必须使用 plgld 链接器来创建最终的二进制文件。 这是一个与架构无关的交叉链接器，无论插件是为哪种机器代码编译的，它都可以工作。最终的 .plg 大小只是它所生成 .o ELF 的一小部分。

Plugin API

插件的 C 源代码必须包含 src/loader.h 头文件，并且必须包含 EASY_PLUGIN 行。它有一个参数，即插件的类型，后面跟着标识符匹配规范。 加载器使用后者来确定何时使用该特定插件。

例如：

#include "../loader.h"

/* 识别 Linux 内核的魔法字节 */
EASY_PLUGIN(PLG_T_KERNEL) {
   /* 偏移量          大小     匹配类型                 魔法字节 */
    { 0x1fe,     2, PLG_M_CONST, { 0xAA, 0x55, 0, 0 } },
    { 0x202,     4, PLG_M_CONST, { 'H', 'd', 'r', 'S' } }
};

/* 入口点，原型由插件的类型定义 */
PLG_API void _start(uint8_t *buf, uint64_t size);
{
    /* 为 Linux 内核准备环境 */
}

插件可以使用多个变量和函数，这些都是在头文件中定义并运行时链接的。

uint32_t verbose;

详细程度。如果该值不为零，则插件才允许打印任何输出，错误消息除外。该值越大，打印的详细信息就越多。

uint64_t file_size;

打开的文件的总大小（请参阅下面的open和loadfile）。

uint8_t *root_buf;

当文件系统插件初始化时，它包含分区的前 128k（希望包括超级块）。稍后，文件系统插件可以将这 128k 缓冲区重新用于任何目的（FAT 缓存、inode 缓存等）。

uint8_t *tags_buf;

包含 Multiboot2 标签。内核插件可以解析此标记，将启动管理器提供的数据转换为内核所需的任何格式。此指针指向缓冲区的开头。

uint8_t *tags_ptr;

此指针指向 Multiboot2 标签缓冲区的末尾。标签插件可能会在此处添加新标签并调整此指针。

uint8_t *rsdp_ptr;

指向RSDP ACPI指针。

uint8_t *dsdt_ptr;

指向 DSDT（或 GUDT、FDT）硬件描述二进制文件。

efi_system_table_t *ST;

在 UEFI 机器上指向 EFI 系统表，否则为NULL。

void memset(void *dst, uint8_t c, uint32_t n);
void memcpy(void *dst, const void *src, uint32_t n);
int  memcmp(const void *s1, const void *s2, uint32_t n);

强制内存函数（即使没有直接调用，C 编译器也可能会生成对这些函数的调用）。

void *alloc(uint32_t num);

分配 num 页（4k）内存。插件不能分配太多，必须以最小的内存占用为目标。

void free(void *buf, uint32_t num);

释放先前分配的num页内存。

void printf(char *fmt, ...);

将格式化的字符串打印到启动控制台。

uint64_t pb_init(uint64_t size);

启动进度条，size 是其代表的总大小。返回一个像素值多少个字节。

void pb_draw(uint64_t curr);

绘制当前值的进度条。curr 必须介于 0 和总大小之间。

void pb_fini(void);

关闭进度栏，清除其在屏幕上的位置。

void loadsec(uint64_t sec, void *dst);

由文件系统插件使用，将扇区从磁盘加载到内存中。sec 是扇区的编号，相对于根分区。

void sethooks(void *o, void *r, void *c);

由文件系统插件使用，为根分区的文件系统设置open / read / close函数挂钩。

int open(char *fn);

打开根（或启动）分区上的文件进行读取，成功时返回 1。任何给定时间只能打开一个文件。如果事先没有sethooks调用，则它会在启动分区上进行操作。

uint64_t read(uint64_t offs, uint64_t size, void *buf);

从查找位置offs处打开的文件中读取数据到内存中，返回实际读取的字节数。

void close(void);

关闭打开的文件。

uint8_t *loadfile(char *path);

将文件从根（或启动）分区完全加载到新分配的内存缓冲区中，如果找到插件，则透明地解压缩它。大小在file_size中返回。

int loadseg(uint32_t offs, uint32_t filesz, uint64_t vaddr, uint32_t memsz);

从内核缓冲区加载一个段。这将检查内存vaddr是否可用，如果是高半部分，则映射该段。offs是文件偏移量，因此相对于内核缓冲区。如果memsz大于filesz， 则差值用零填充。

void _start(void);

文件系统插件（PLG_T_FS）的入口点。它应该解析root_buf中的超级块并调用sethooks。发生错误时它应该直接返回而不设置其钩子。

void _start(uint8_t *buf, uint64_t size);

内核插件的入口点（PLG_T_KERNEL）。接收内存中的内核映像，它应该重新定位其段，设置适当的环境并转移控制权。当没有错误时，它永远不会返回。

uint8_t *_start(uint8_t *buf);

解压插件的入口点（PLG_T_DECOMP）。接收压缩缓冲区（及其在file_size中的大小），并应返回一个分配的新缓冲区，其中包含未压缩的数据 （并在file_size中设置新缓冲区的大小）。它必须释放旧缓冲区（注意，file_size以字节为单位，但 free() 需要以页为单位的大小）。 出现错误时，file_size不得更改，并且它必须返回未修改的原始缓冲区。

void _start(void);

标签插件的入口点（PLG_T_TAG）。它们可能会在tags_ptr处添加新标签，并将该指针调整到新的 8 字节对齐位置。

本地函数

插件可以使用本地函数，但是由于 CLang 的一个错误，这些函数必须声明为static。（错误在于，CLang 会为这些函数生成 PLT 记录，即使在命令行上传递了 -fno-plt标志。使用static可以解决这个问题）。

低级文件格式规范

如果有人想用非 C 语言（例如汇编语言）编写插件，这里是文件格式的低级描述。

它与 a.out 格式非常相似。该文件由固定大小的标头和随后的长度不等的节组成。没有节头，每​​个节的数据直接跟在前一个节的数据后面，顺序如下：

(标头)
(标识符匹配记录)
(重定位记录)
(机器代码)
(只读数据)
(已初始化的可读写数据)

对于第一个实际部分（机器代码），包含对齐。对于所有其他部分，填充将添加到前一个部分的大小。

提示：如果将插件作为单个参数传递给plgld，那么它会转储文件中的各个部分，输出类似于readelf -a或objdump -xd。

标头

无论架构如何，所有数字都采用小端格式。

偏移	尺寸	描述
0	4	魔法字节EPLG
4	4	文件的总大小
8	4	加载文件时所需的总内存
12	4	代码段的大小
16	4	只读数据部分的大小
20	4	插件的入口点
24	2	架构代码（与 ELF 相同）
26	2	搬迁记录数
28	1	标识符匹配记录数
29	1	最高引用的 GOT 条目
30	1	文件格式修订（目前为 0）
31	1	插件的类型（1=文件系统，2=内核，3=解压缩器，4=标签）

架构代码与 ELF 头中的相同，例如 62 = x86_64、183 = Aarch64 和 243 = RISC-V。

插件的类型指定了入口点的原型，ABI 始终是 SysV。

标识符匹配部分

本节包含与标题的“标识符匹配记录数”字段中指定的数量一样多的以下记录。

偏移	尺寸	描述
0	2	偏移
2	1	尺寸
3	1	类型
4	4	要匹配的魔法字节

首先，将主题的开头加载到缓冲区中。设置一个累加器，初始值为 0。这些记录中的偏移量始终相对于此累加器，并且它们在缓冲区中寻址该字节。

类型字段指示如何解释偏移量。如果是 1，则使用偏移量加上累加器作为值。如果是 2，则在偏移量处取一个 8 位字节值，3 表示取一个 16 位字值，4 表示取一个 32 位双字值。5 表示取一个 8 位字节值并将累加器添加到其中，6 表示取​​一个 16 位字值并将累加器添加到其中，7 相同，但值为 32 位。 8 将从累加器第 1 个字节开始按偏移量步骤搜索到缓冲区末尾的魔法字节，如果找到，则返回匹配的偏移量作为值。

如果大小为零，则将累加器设置为该值。如果大小不为零，则检查该数量的字节是否与给定的魔法字节匹配。

例如，检查 PE 可执行文件是否以 NOP 指令开头：

EASY_PLUGIN(PLG_T_KERNEL) {
   /* 偏移量          大小     匹配类型                 魔法字节 */
    { 0,         2, PLG_M_CONST, { 'M', 'Z', 0, 0 } },      /* 检查魔法字节 */
    { 60,        0, PLG_M_DWORD, { 0, 0, 0, 0 } },          /* 获取 PE 头到累加器的偏移量 */
    { 0,         4, PLG_M_CONST, { 'P', 'E', 0, 0 } },      /* 检查魔法字节 */
    { 40,        1, PLG_M_DWORD, { 0x90, 0, 0, 0 } }        /* 检查入口点的 NOP 指令 */
};

搬迁科

本节包含与标题的“重定位记录数”字段中指定的数量一样多的以下记录。

偏移	尺寸	描述
0	4	偏移
4	4	重定位类型

类型中各位的含义：

从	至	描述
0	7	符号（0 - 255）
8	8	程序计数器相对寻址
9	9	全局偏移表相对间接寻址
10	13	直接掩码索引（0 - 15）
14	19	起始位（0 - 63）
20	25	结束位（0 - 63）
26	31	否定地址标志位位置（0 - 63）

偏移量字段与插件头中的魔法相关，它选择必须执行重定位的内存中的整数。

符号告诉要使用哪个地址。0 表示插件在内存中加载的基地址，也就是内存中标头的魔法地址。其他值从 GOT 中选择一个外部符号地址，在加载器或另一个插件中定义， 查看 plgld.c 源代码中的plg_got数组以查看哪个值对应哪个符号。如果 GOT 相对位为 1，则使用符号的 GOT 条目的地址，而不是符号的实际地址。

如果程序计数器相对位为 1，则首先从地址中减去偏移量（指令指针相对寻址模式）。

立即数掩码索引指示哪些位存储指令中的地址。如果该索引为 0，则地址将按原样写入偏移量，与体系结构无关。对于 x86_64，仅允许索引 0。 对于 ARM Aarch64：0 = 按原样，1 = 0x07ffffe0（向左移位 5 位），2 = 0x07fffc00（向左移位 10 位），3 = 0x60ffffe0（使用 ADR/ADRP 指令， 立即数被移位并拆分为两个位组）。未来的体系结构可能会定义更多不同的立即数位掩码。

使用立即数掩码，从内存中取出结束 - 开始 + 1 位，并进行有符号扩展。该值被添加到地址（加数，如果是内部引用，内部符号的地址也在此处编码）。

如果取反地址标志位不为 0，且地址为正数，则清除该位。如果地址为负数，则设置该位，并将地址取反。

最后，起始位和结束位选择将地址的哪一部分写入所选整数。这也定义了重定位的大小，超出此范围的位和不属于直接掩码的位保持不变。

代码部分

此部分包含标题中指定的体系结构的机器指令，并且具有与代码大小字段相同的字节数。

只读数据部分

这是一个可选部分，可能会缺失。它的长度与标题中的只读部分大小字段所示长度相同。所有常量变量都放在此部分中。

初始化数据部分

这是一个可选部分，可能会丢失。如果文件中的代码部分（或可选的只读数据部分）之后仍有字节，则这些字节都被视为数据部分。如果变量用非零值初始化，则将其放置在此部分中。

BSS 部分

这是一个可选部分，可能会缺失。此部分永远不会存储在文件中。如果内存大小字段大于标头中的文件大小字段，则它们的差值将在内存中用零填充。 如果变量未初始化或初始化为零，则将其放置在此部分中。