企业官网建设流程全解析

这个系列写到第七篇，终于要碰整个 ACPI 体系里我最喜欢的一张表：MADT（Multiple APIC Description Table）。前面几篇我们聊过怎么定位 RSDP、怎么遍历 XSDT、怎么从 FADT 里拿到 DSDT，但真要在一个空空如也的内核里把多核跑起来、把外设中断接上去，光有那些还不够。你还需要知道 CPU 的中断控制器长什么样、I/O 中断从哪里进来、每个 CPU 的 APIC ID 是多少——这些答案全藏在这张签名只有四个字母“APIC”的表里。

这篇文章适合正在写内核、写 hypervisor、或者单纯想搞懂“为什么我的 IRQ 0 会变成 GSI 2”的开发者。MADT 在 ACPI 表家族里不算复杂，结构非常规整，但它背后牵扯的中断模型、历史兼容逻辑和固件怪癖一点都不少。搞懂它之后，你再去看 /proc/interrupts 和 IOAPIC 的寄存器，会有一种豁然开朗的感觉。

1. 先搞清楚 MADT 在 ACPI 体系里的位置

1.1 一张表解决三个问题

MADT 的职责可以浓缩成三件事：告诉 OS 本地 APIC 在哪里、I/O APIC 有哪些、系统里有多少个 CPU 以及它们各自的中断配置。对于任何要在 x86 上做多核调度和中断管理的软件来说，这三件事缺一不可。

为什么需要单独一张表来做这件事？因为 APIC 这套中断基础设施虽然是硬件标准，但具体平台怎么接、接在哪、有多少个 I/O APIC，完全由固件决定。同一个处理器型号，在不同主板上 I/O APIC 的数量和地址都可能不同，更不用说那些 legacy 中断的映射差异。ACPI 的作用就是把这种“硬件拓扑”用统一的表格式语言描述出来，让 OS 不必为每种主板写死一套配置。

换句话说，MADT 是固件和 OS 之间关于中断拓扑的一份“书面合同”。OS 不需要去猜测，只需要照单执行。

1.2 从 RSDP 到 MADT 的寻表路径

按照 ACPI 规范，所有系统描述表都要通过 RSDT 或 XSDT 来定位。相比 FADT 这种机器必须有的表，MADT 在 x86 平台上几乎也是必然存在的，它的签名是APIC，而不是你直觉里可能猜的MADT。这一点特别容易踩坑，我第一次解析时就在签名上卡了十分钟。

寻表流程非常简单：先从 RSDP 拿到 RSDT/XSDT 的物理地址，遍历其中的表指针数组，逐个比较表头前四个字节是否等于APIC，命中后把整张表按长度读入内存即可。ACPI 2.0 之后建议走 XSDT，因为表地址是 64 位，MADT 里的 Local APIC Address 字段虽然有 32 位版本，但实际物理地址也可能超过 4G，优先遵循 XSDT。

拿到表之后，第一步永远是校验表头和 checksum。ACPI 的校验规则是整张表（从签名到最后一个字节）所有字节相加，低 8 位必须为 0。固件在这方面出错率不高，但我在某些国产主板上见过 checksum 错误的 MADT，属于稀有但真实存在的坑。

1.3 MADT 头部：37 字节之后的真正信息

MADT 的结构分两段：前 36 字节是标准的 ACPI 表头，后面跟着一张“记录流”。表头字段和所有 ACPI 表一致：签名、长度、修订号、checksum、OEM ID 等等，这里不展开。关键是表头之后紧跟的三个字段：

struct acpi_madt { struct acpi_sdt_header header; uint32_t local_apic_address; uint32_t flags; /* 后面紧跟一系列 type/length 记录 */ } __attribute__((packed));

第一个字段local_apic_address是本地 APIC 的 32 位物理基址，x86 上几乎永远是0xFEE00000。第二个字段flags比较有意思，只有 bit0 有意义：为 1 表示系统里有 PC-AT 兼容的 dual 8259 PIC，OS 需要为 legacy 中断处理做一些兼容性映射；为 0 表示纯 APIC 环境，没有传统 PIC。这个标志直接关系到后面说到的中断源覆盖。

从第 40 字节（如果是 32 位地址与 flags 各 4 字节，其实从 36+4+4=44？等等）开始就是真正的核心资产——类型化记录流。每条记录的第一个字节是类型，第二个字节是本条记录的总长度（包含类型和长度这两个字节），后面跟着该类型独有的数据。遍历时不需要关心总表里有哪些类型，只需要从头走到表尾即可。

注意：MADT 记录流的长度不由表头单独给出，而是根据 header.length 减去表头长度推算出来。遍历时务必以header.length为硬边界，有些固件会在最后塞几个填充字节，不能一条记录越界读出去。

2. 逐条拆解 MADT 记录：从 Local APIC 到 MP Wakeup

2.1 记录类型速查表

MADT 的记录类型随着 ACPI 规范演进越来越多，从最初的几种发展到今天的十余种。对于 x86 平台的 OS 开发，真正需要亲手解析的集中在下面这张表里：

剩下的 Type 6/7/8 是 SAPIC 和平台中断源，x86 上基本见不到；Type 11 到 15 是 ARM GIC 相关，写 ARM 固件或 hypervisor 时会用到，本文聚焦 x86，不展开。

2.2 Local APIC 条目：不只是“标记 CPU 存在”

Type 0 记录总共 8 字节，结构如下：

struct madt_local_apic { uint8_t type; // 0 uint8_t length; // 8 uint8_t acpi_uid; // 匹配 _MAT/_PRS 等 ACPI 对象的处理器 ID uint8_t apic_id; // 本地 APIC ID uint32_t flags; // bit0=Enabled, bit1=Online Capable } __attribute__((packed));

绝大部分人解析这条记录时只关心 apic_id 和 flags。flags 的 bit0 为 1 表示这个处理器在系统里是启用的，OS 可以把它纳入调度；为 0 表示逻辑上不存在或者禁用，OS 启动时不应该去碰它。ACPI 规范特别强调，OS 只能启动 MADT 里 Enabled 的处理器——这是多核启动时最容易被忽略的一条铁律。

我自己踩过这样一个坑：某台机器上_MAT返回了 4 个处理器，但 MADT 里只有一个 Enabled 位被置位，其余全部是 0。如果当时有代码按 UID 去轮询启动，后果就是 INIT-SIPI 发出去之后 CPU 永远不响应。正确做法是先过滤 flags，只有 Enabled 或 Online Capable 的处理器才进入后续启动流程。

另外请注意 apic_id 与 acpi_uid 是两个完全不同的概念。acpi_uid 是 ACPI 命名空间里的逻辑编号，apic_id 是硬件中断控制器里的物理编号。在 x2APIC 时代，apic_id 扩展到 32 位，而 acpi_uid 仍然是 32 位整数，二者靠 MADT 条目一一对应，不能混用。

2.3 I/O APIC 条目与 GSI Base：多个 I/O APIC 如何拼接

Type 1 记录是 12 字节，结构如下：

struct madt_io_apic { uint8_t type; // 1 uint8_t length; // 12 uint8_t ioapic_id; uint8_t reserved; uint32_t address; // I/O APIC 的 MMIO 物理地址 uint32_t gsi_base; // 这个 I/O APIC 负责的 GSI 起始编号 } __attribute__((packed));

一台机器可能有好几个 I/O APIC，每个负责一段连续的 GSI 区间。GSI 的编号空间就是这样通过每个 I/O APIC 的gsi_base拼接出来的。比如第一个 I/O APIC 的 gsi_base 是 0，第二个是 24，那么 GSI 0~23 属于第一个，GSI 24~47 属于第二个。注意这只是约定俗成的“连续拼接”，规范并没有强制要求每段都正好覆盖 24 个中断引脚，具体每个 I/O APIC 有多少引脚，OS 需要去读 I/O APIC 的版本寄存器才能确定。

读取方法后面在实操章节会给出代码。这里先记住一个关键概念：一个 I/O APIC 能服务的 GSI 范围是[gsi_base, gsi_base + pin_count - 1]，pin_count 来自硬件，不是 MADT 直接给出的。这也是新手经常困惑的地方：明明 MADT 里写了 gsi_base，为什么还要再去访问 MMIO 寄存器？因为 pin 数量确实是 I/O APIC 自身的硬件属性，MADT 不负责描述它。

2.4 你一定会遇到的两个条目：Interrupt Source Override 和 Local APIC NMI

Type 2 的 Interrupt Source Override 是本文后半段的另一个主角，这里先给结构：

struct madt_iso { uint8_t type; // 2 uint8_t length; // 10 uint8_t bus; // 0 表示 ISA 总线 uint8_t source; // 源 IRQ 号（ISA IRQ 编号） uint32_t gsi; // 被覆盖到的 GSI uint16_t flags; // bit0-1 极性, bit2-3 触发方式 } __attribute__((packed));

Type 4 的 Local APIC NMI 记录则是 6 字节：

struct madt_lapic_nmi { uint8_t type; // 4 uint8_t length; // 6 uint8_t acpi_uid; // 0xFF 表示应用到所有处理器 uint16_t flags; // bit0-1 选择 LINT0/LINT1 uint8_t lint; // 0=LINT0, 1=LINT1 } __attribute__((packed));

如果你读过 APIC 手册，会知道每个本地 APIC 有两条外部中断线 LINT0/LINT1，通常一条用来接 NMI，一条接外部中断。MADT 的 Type 4 就是告诉 OS 该把 NMI 接到哪条线上、用什么样的触发方式。几乎所有 x86 平台都会有至少一条这样的记录，如果没有，OS 就不应该给 LINT 引脚配置 NMI，而是走系统 NMI 通道（Type 3）。

3. 全局系统中断：GSI 是怎么来的

3.1 为什么会有 GSI 这个概念

传统 PC 上用 8259 PIC，只有 16 个 IRQ，IRQ 编号本身就是硬件的“中断编号”，OS 直接用 IRQ 0 对应定时器、IRQ 1 对应键盘。到了 APIC 时代，I/O APIC 的引脚数量远远超过 16 个，而且一个系统可能有多个 I/O APIC，光靠 “IRQ 号” 这个一维编号已经无法表达完整的中断拓扑了。

ACPI 引入 GSI 的目的就是做一个“全局中断编号”抽象：把所有 I/O APIC 的物理引脚统一编成一个大空间，每个设备中断最终都映射到某个 GSI 上。PCI 设备的 INTx 中断路由表（_PRT）里给出的也是 GSI，而不是 IRQ。OS 的中断子系统拿到 GSI 后，再去找到对应的 I/O APIC 和引脚号，写入重定向表项。

可以说，GSI 是软件层面看到的中断编号，而 I/O APIC 引脚是硬件层面的物理入口，MADT 负责在两者之间搭桥。

3.2 GSI 与 ISA IRQ 的映射规则

理想情况下，中断编号空间应该自洽：ISA IRQ 0 就对应 GSI 0，IRQ 1 对应 GSI 1，以此类推。这种一一对应关系被称为 identity 映射，在纯 APIC 环境（MADT flags bit0=0）下通常是成立的。

但在 PC-AT 兼容的系统里，情况就没那么美好。原因在于：I/O APIC 引脚的实际接线并不一定遵循 “引脚 0 接定时器、引脚 1 接键盘” 的传统布排。现代芯片组往往把 legacy 设备接到不同的物理引脚上，为了不破坏 OS 对 ISA IRQ 的既有认知，固件通过 Interrupt Source Override 记录来纠正映射。

映射规则可以概括成一句话：对于 ISA 总线上的 IRQ 0~15，如果 MADT 里有对应的 Type 2 覆盖记录，就按覆盖记录把它映射到指定的 GSI；如果没有，就默认采用 identity 映射（IRQn → GSIn）。OS 在处理 legacy 设备中断时，必须先从这张映射表里走一遍。

这里有个最常见的反直觉案例：IRQ 0 定时器中断。x86 平台几乎都会在 MADT 里给出source=0, gsi=2的覆盖记录，意思是 ISA IRQ 0 被重映射到了 GSI 2。如果你忽略覆盖逻辑直接按 IRQ 0 处理定时器中断，会发现在 I/O APIC 那边根本没有任何设备在 GSI 0 上产生中断，然后陷入“定时器不工作”的困惑。

3.3 经典案例：IRQ0 为什么会变成 GSI 2

这个问题可能是 MADT 系列里被问得最多的问题。要理解它，得从 8259 的级联说起。老式 PC 用两片 8259 串联，从片通过主片的 IRQ2 输入接入，所以 ISA IRQ2 对应的实际上是从片 8259 的级联入口，真正暴露给设备的 IRQ 编号从 IRQ8 开始往下排。也就是说，在 PIC 时代，IRQ2 这个编号只是“名义上”存在，不直接连接任何设备。

到了 APIC 时代，芯片组设计者想把 PIT 定时器接到 I/O APIC 的某个引脚上，选来选去选了物理引脚 2。但在 ACPI 的世界里，设备仍然按传统 IRQ 0 来标识自己。为了让 OS 用 IRQ 0 编程却最终驱动 I/O APIC 引脚 2，固件就写下一条 override：source=0 → gsi=2。

所以 IRQ0 变成 GSI2 不是什么神秘魔法，纯粹是固件在描述“逻辑 IRQ 和物理引脚之间的接线差异”。这个差异没有任何硬件上的必然性，不同芯片组完全可能选择不同的引脚，这也是为什么 override 记录必须由固件显式提供，而不能由 OS 硬编码假设。

3.4 中断源覆盖的 Flags：极性/触发方式

Type 2 记录里的 flags 字段容易被忽略，但它直接影响中断是否会被正确识别。低两位表示极性（Polarity），bit0=1 且 bit1=0 表示 Active High，bit0=1 且 bit1=1 表示 Active Low，全 0 表示 conforms（即遵从总线默认约定，ISA 默认 Active High）。bit2-3 表示触发方式，全 0 表示 conforms（ISA 默认 Edge），0b01 表示 Level，0b11 表示 Edge。

在写中断控制器时，这些标志最终会被转换到 I/O APIC 重定向表项的极性位和触发模式位。ISA 设备大多走边沿触发，但像 ACPI 事件中断、PCI INTx 中断这类走电平触发，极性默认是 Active Low。如果你在代码里只解析 GSI 编号而丢掉 flags，后面配中断路由时很容易出现“中断来了但一直挂着不响应”或“一进中断就疯狂触发”的诡异症状。

我建议在解析 MADT 时，把 override 的 flags 原封不动地和 GSI 映射一起存下来，建立一个结构体而不是单纯一个编号数组。中断子系统的路由逻辑迟早会用到这些信息。

4. 实操：如何在自己的 OS/内核里解析 MADT

4.1 获取原始二进制

在真实硬件上调试时，最快的方式是从 /sys 虚拟文件系统里导出二进制表。第一步是确认你的环境里 MADT 真的存在：

ls /sys/firmware/acpi/tables/

如果看到名为MADT的文件，直接读出来：

cat /sys/firmware/acpi/tables/MADT > madt.dat xxd madt.dat

输出会是一段带APIC签名的二进制。另一种方式是使用 acpidump 工具导出全部表，然后从导出的文件里按签名提取。对开发调试来说，手工xxd查看头部和几条记录就够了，完全可以验证后续解析逻辑是否正确。

在虚拟化环境里调试时，MADT 通常由虚拟固件生成，不同虚拟机管理程序生成的 MADT 内容差异很大，这反而是一个绝佳的兼容性测试场。建议至少准备两个不同虚拟机环境，或者一台真实机器 + 一台虚拟机配合测试，因为真实硬件上的覆盖记录和虚拟机里的往往不一样，解析器必须能同时处理这两种情况。

4.2 C 语言解析代码

下面这段是我在自己写的内核里用的简化版解析逻辑，去掉了日志和错误处理的冗余，保留核心遍历和建表过程。结构体定义假设标准 ACPI 表头已经解析完毕：

struct acpi_madt_header { struct acpi_sdt_header sdt; uint32_t lapic_addr; uint32_t flags; } __attribute__((packed)); struct madt_record { uint8_t type; uint8_t length; } __attribute__((packed)); #define LAPIC_ENTRY_TYPE 0 #define IOAPIC_ENTRY_TYPE 1 #define ISO_ENTRY_TYPE 2 #define LAPIC_NMI_ENTRY_TYPE 4 #define X2APIC_ENTRY_TYPE 9 #define MP_WAKEUP_ENTRY_TYPE 16 #define ISA_IRQ_COUNT 16 void parse_madt(void *madt_base, size_t len) { struct acpi_madt_header *madt = (struct acpi_madt_header *)madt_base; uintptr_t p = (uintptr_t)(madt + 1); uintptr_t end = (uintptr_t)madt + len; gsi_identity_init(); // 先把 ISA IRQ 0~15 映射到自身 GSI ioapic_count = 0; while (p + sizeof(struct madt_record) <= end) { struct madt_record *rec = (struct madt_record *)p; if (rec->length < 2) break; if (p + rec->length > end) break; switch (rec->type) { case LAPIC_ENTRY_TYPE: if (rec->length >= 8) { uint8_t apic_id = *(uint8_t *)(p + 2); uint32_t flags = *(uint32_t *)(p + 4); if (flags & 0x1) { lapic_table[apic_id].apic_id = apic_id; lapic_table[apic_id].acpi_uid = *(uint8_t *)(p + 2); lapic_count++; } } break; case IOAPIC_ENTRY_TYPE: if (rec->length >= 12) { ioapic[ioapic_count].id = *(uint8_t *)(p + 2); ioapic[ioapic_count].addr = *(uint32_t *)(p + 4); ioapic[ioapic_count].gsi_base = *(uint32_t *)(p + 8); ioapic_count++; } break; case ISO_ENTRY_TYPE: if (rec->length >= 10) { uint8_t bus = *(uint8_t *)(p + 2); uint8_t source = *(uint8_t *)(p + 3); uint32_t gsi = *(uint32_t *)(p + 4); uint16_t flags = *(uint16_t *)(p + 8); if (bus == 0 && source < ISA_IRQ_COUNT) { irq_source_to_gsi[source] = gsi; irq_source_flags[source] = flags; } } break; } p += rec->length; } }

解析时有一个易错点：madt + 1这样的指针运算依赖struct acpi_madt_header的大小等于 40 字节，因为标准表头 36 字节、加两个 4 字节字段。如果不确定，用(uintptr_t)madt_base + sizeof(struct acpi_sdt_header)更稳妥。另外对于 2 字节以上的字段，在 x86_64 上直接解引用没问题，如果代码将来要跑在严格对齐的架构上，记得用 memcpy 取出字段。

4.3 从 MADT 到中断路由：建立 GSI 映射表与 IOAPIC 编程

解析完 MADT 之后，下一步是把 GSI 落到具体的 I/O APIC 引脚上。这需要知道每个 I/O APIC 实际有多少个引脚，所以要先读硬件寄存器。I/O APIC 有两个 MMIO 寄存器，一个索引一个数据，地址就放在 MADT 的 Type 1 记录里：

#define IOAPIC_IOREGSEL 0x00 #define IOAPIC_IOWIN 0x10 uint32_t ioapic_read(uintptr_t base, uint8_t reg) { *(volatile uint32_t *)(base + IOAPIC_IOREGSEL) = reg; return *(volatile uint32_t *)(base + IOAPIC_IOWIN); }

版本寄存器是 0x01，读回来之后低 8 位是最大重定向表项号，从 0 开始数，所以引脚数量是这个值加 1。有了每个 I/O APIC 的 gsi_base 和引脚数量，就能写一个把 GSI 翻译成ioapic_id + pin的函数：

int gsi_to_pin(uint32_t gsi, int *ioapic_idx, uint32_t *pin) { for (int i = 0; i < ioapic_count; i++) { uint32_t max_pin = ioapic_read(ioapic[i].addr, 0x01) & 0xff; if (gsi >= ioapic[i].gsi_base && gsi < ioapic[i].gsi_base + max_pin + 1) { *ioapic_idx = i; *pin = gsi - ioapic[i].gsi_base; return 0; } } return -1; }

拿到引脚号之后，把 vector、触发方式、极性写入重定向表项即可。I/O APIC 重定向表项从寄存器 0x10 开始，每项占两个 32 位寄存器。这里先不展开完整的中断控制器驱动，因为那是另一个大话题；只要理解了 GSI → I/O APIC → pin 这条链路，后续所有中断路由都是水到渠成的事。

4.4 Linux 下验证解析结果

如果不想直接写内核代码，也可以用现成工具交叉验证。最直观的是/proc/interrupts，每一行对应一个 IRQ 号，右侧能看到IO-APIC的 GSI 编号和引脚。观察一下定时器那一行，十有八九会看到类似IR-IO-APIC 2-fasteoi的表现，这就是 IRQ0 被映射到 GSI2 的现场证据。

还可以对比/sys/firmware/acpi/tables/MADT的原始内容和内核日志里ACPI: MADT ...的打印。内核启动早期会打印每个处理器的 APIC ID、I/O APIC 地址以及 override 记录，这些信息和我上面那段解析代码读出来的应该完全一致。如果哪一项对不上，优先怀疑自己解析的字段偏移，而不是怀疑内核有问题。

5. 常见问题与排查实录

MADT 表面上看只是一堆记录，但解析和使用的过程中坑相当密集。下面把我实际遇到过的几类问题整理成一张速查表，按“现象 → 根因 → 处理”的顺序展开：

这里挑两个展开说。

第一，多核启动问题。我见过不止一次解析逻辑完全正确、但 AP 就是不起来的场景，最后发现原因出在 BSP 的 APIC ID 不是 0。因为 MADT 里的 LAPIC 条目只告诉你“有哪些 CPU”，不会告诉你“谁是 BSP”。BSP 的 APIC ID 要从IA32_APIC_BASEMSR 之外的 Local APIC ID 寄存器（偏移 0x20）现场读取。如果启动代码里写死 APIC ID 0 就是 BSP，遇到 BSP 是 1 或更大的平台就容易出错。正确流程应该是：先用当前 CPU 的 APIC ID 锁定 BSP，其余 Enabled 的条目才是需要发送 INIT-SIPI 的目标。

第二，x2APIC 条目并存问题。ACPI 5.0 之后，支持 x2APIC 的平台可以在 MADT 里同时给出 Type 0 和 Type 9 条目。OS 在启用 x2APIC 模式时，应以 Type 9 为准，因为传统 LAPIC 条目的 APIC ID 字段只有 8 位，装不下 x2APIC 的 32 位 ID。如果固件只给了 Type 0 条目、没有 Type 9，说明固件认为你仍然工作在传统 APIC 模式，强行开 x2APIC 可能造成 ID 错配。

第三，关于 ACPI 6.5 新加的 MP Wakeup（Type 16）。我最近在虚拟化实验里开始认真看这条记录，因为它提供了一种不依赖 INIT-SIPI-SIPI 的 AP 启动方式，在 TrustDomain 这类环境下特别有用。结构里包含一个信箱地址（Mailbox Address），OS 把 AP 的启动代码入口写到信箱，然后通过一条特殊的硬件唤醒机制触发 AP 上线。如果你的目标平台同时提供 Type 0 和 Type 16，优先用 Type 16 的启动协议，比传统 SIPI 循环要简洁得多。

最后说一个通用排查思路：当 MADT 解析结果和预期不一致时，先把原始二进制用十六进制工具完整读一遍，自己去数每条记录的类型和长度。不要急着怀疑代码算法，先用肉眼确认固件给的数据长什么样。我排查过的“诡异问题”里，至少三分之一最后都归因于固件给出了一条非标准记录，而解析器没有做好未知类型跳过——所以遍历时遇到不认识的类型，直接按 length 跳过就好，不需要报错。

6. 一些个人体会

写内核或者搞底层固件这几年，MADT 是我见过“看起来最简单、实际细节最多”的 ACPI 表之一。它没有 AML 那种复杂的字节码，也没有 FADT 那种一堆布尔标志的晦涩语义，但在它上面翻车的人一点不少。核心原因在于：MADT 描述的是硬件拓扑，而硬件拓扑恰恰是固件自由度最高的地方。每一台机器都可能给你一点“小惊喜”，比如来源不明的覆盖记录、多出来的保留填充字节、或者一个让你哭笑不得的 checksum 错误。

我个人在写解析器时，会刻意把它写得比规范要求的更宽容：未知类型一律跳过，条目长度以字段为准，所有表项边界都用header.length严格约束。这种冗余的健壮性在前期的 90% 平台上看不出价值，但到了那 10% 有怪癖的平台上，它能帮你省下好几个通宵。

如果你正在做自己的内核，我建议下一步直接拿一个最简单的定时器中断做实验：解析 MADT，找到 IRQ0 对应的 GSI，配置 I/O APIC 重定向表项，然后观察中断是否按预期频率触发。这一条链路跑通之后，整个中断子系统的骨架也就立住了。后面再扩展 PCI 中断路由、多 I/O APIC、x2APIC 模式，都会在这个底盘上顺理成章地展开。