Firecracker x86_64 CPUID 归一化（CPUID Normalization）机制全解析：作用于所有微VM的默认访客 CPUID 修正策略

本指南围绕 docs/cpu_templates/cpuid-normalization.md 展开，结合源码 cpuid 归一化实现 及其 Intel / AMD 专属子模块，系统讲解 Firecracker 在 x86_64 平台上对访客 CPUID 的“归一化”处理：无论是否使用 CPU 模板，每条 vCPU 都会按固定规则改写特定的 CPUID 叶子字段。读者读完后，将掌握归一化的执行时机、三类（通用 / Intel / AMD）逐位级修改清单、与 CPU 模板的覆盖次序关系，以及这些规则对应的源码实现与测试证据。

Firecracker 是面向 serverless 负载的安全、快速微VM运行时。在 x86_64 架构下，为了让每个微VM（microVM）的 CPU 视图稳定、可预测，并保证 CPU 拓扑信息与用户配置的 vCPU 数量、SMT 状态自洽，Firecracker 会对写入 KVM 的访客 CPUID 做一批无条件执行的修正，这套修正过程被命名为 CPUID normalization。它独立于 CPU 模板机制，即便完全不指定 CPU 模板也会生效，因此是理解 Firecracker 默认 CPU 行为的基石。

一、归一化是什么，什么时候发生

1.1 概念与适用前提

Firecracker 的 x86_64 实现中，不论用户是否配置 CPU 模板，Firecracker 都会基于 KVM 返回的宿主能力构造访客 CPUID，并对其中若干字段做统一改写，这份改动即“CPUID 归一化”。其目的可从源码注释与字段性质归纳为几点：

• 保证 CPU 拓扑自洽：访客看到的 APIC ID、核心数、每核线程数等必须与 machine_config 中配置的 vcpu_count、smt 严格对应，而不是简单透传宿主值；
• 暴露虚拟化必要特征：如设置 HYPERVISOR 位、使能 TSC_DEADLINE 等，让客户机正确识别自己运行于虚拟化环境；
• 抹平宿主差异与噪音：例如禁用 Turbo Boost、WAITPKG、性能监控等易造成跨宿主不一致或调度干扰的位；
• 收编品牌字符串：统一为默认格式（Intel 保留真实频率、AMD 固定为 AMD EPYC），避免客户机软件依据具体 CPU 型号走宿主绑定路径。

归一化由每个 vCPU 在启动引导配置阶段独立执行一次，可参考 configure_cpuid 入口。

1.2 完整调用链

从 x86_64 架构引导模块 可以看到启动时 CPU 配置的完整阶段：

1. 以 KVM_GET_SUPPORTED_CPUID 得到的宿主 CPUID 为基底，经 Cpuid::try_from 转成内部统一表示（依赖 leaf 0x0 的 vendor ID 判断走 Intel 还是 AMD 分支，仅支持 GenuineIntel / AuthenticAMD，见 mod.rs）；
2. apply_template_to_cpuid(cpuid, cpu_template) 施加用户选定的 CPU 模板修饰；
3. 对每个 vCPU 调用 vcpu.configure_cpuid(...)，其内部执行 cpuid.normalize(...) 并调用 KVM_SET_CPUID2 安装最终 CPUID；
4. 之后才执行 KVM_GET_MSRS 采集 MSR，并依据最终 CPUID 推导快照时需要保存的额外 MSR（见后文第六节）。

关键点在于第 2、3 步的先后：模板先应用，归一化后执行，因此“归一化涉及的位若被模板设置，最终会被归一化覆盖”。这是使用 CPU 模板时最容易踩中的语义，下文第五节将详细展开。

1.3 normalize 的参数模型

归一化是逐 vCPU 的，不同 vCPU 上的结果不同。参考 normalize 定义：

normalize(cpu_index: u8, cpu_count: u8, cpu_bits: u8)

• cpu_index：当前逻辑 CPU 在 [0, cpu_count) 内的序号，直接决定 APIC ID 类字段；
• cpu_count：微VM 的逻辑 vCPU 总数；
• cpu_bits：枚举“每核逻辑 CPU”所需位数。在 vcpu.rs 中由 u8::from(vcpu_count > 1 && smt) 计算，即只有 vCPU 数大于 1 且开启 SMT 时才为 1；
• 内部再推出 cpus_per_core = 1 << cpu_bits（每核逻辑 CPU 数，SMT 关闭时为 1，开启时为 2）。

归一化依次执行：update_vendor_id → update_feature_info_entry → update_extended_topology_entry → update_extended_cache_features，最后按厂商分派到 IntelCpuid::normalize 或 AmdCpuid::normalize。cpu_bits >= 8 与各叶子缺失等情况会返回结构化错误（NormalizeCpuidError 各变体在 normalize.rs 中定义）。

二、x86_64 通用归一化：与厂商无关的修正

下表来自 原文档，列出了对 Intel 与 AMD 主机一律执行的通用修改，实现位于 common 归一化文件：

描述	Leaf	Subleaf	寄存器	Bits
从宿主透传 vendor ID	0x0	-	EBX, ECX, EDX	all
设置 CLFLUSH 行大小	0x1	-	EBX	15:8
设置物理包内可寻址逻辑处理器 ID 的最大数	0x1	-	EBX	23:16
设置初始 APIC ID	0x1	-	EBX	31:24
禁用 PDCM（Perfmon and Debug Capability）	0x1	-	ECX	15
使能 TSC_DEADLINE	0x1	-	ECX	24
使能 HYPERVISOR	0x1	-	ECX	31
当微VM的CPU数量大于1时设置 HTT 值	0x1	-	EDX	28
若不存在则插入 leaf 0xb 的 subleaf 0x1	0xb	0x1	all	all
填充扩展拓扑枚举 leaf	0xb	all	all	all
从宿主透传 L1 缓存与 TLB 信息	0x80000005	-	all	all
从宿主透传 L2 缓存、TLB 与 L3 缓存信息	0x80000006	-	all	all

2.1 Leaf 0x0：vendor ID 透传

实现函数 update_vendor_id（normalize.rs）读取宿主 cpuid(0x0) 的 EBX/ECX/EDX 覆盖访客 leaf 0x0 的对应寄存器。源码注释明确指出：该透传用于防止自定义 CPU 模板篡改 vendor ID——也就是说，即使模板把 leaf 0x0 的 vendor 改成其他值，归一化也会把它拉回宿主真实值。

2.2 Leaf 0x1：feature information

update_feature_info_entry（normalize.rs）逐位改写：

• EBX[15:8] CLFLUSH 行大小：固定写入 8（行大小 = 值 × 8 = 64 字节），保证跨宿主一致；
• EBX[23:16] 每包最大可寻址逻辑处理器数：由 get_max_cpus_per_package(cpu_count) 计算，取“不小于 vCPU 总数的最近 2 的幂”。该辅助函数（normalize.rs）在 cpu_count == 0 时返回 Underflow，在 > 128 时返回 Overflow，边界行为（1→1、3→4、5→8、128→128）有对应单测覆盖（同文件测试 get_max_cpus_per_package_test）；
• EBX[31:24] 初始 APIC ID：写入当前 vCPU 序号 cpu_index；
• ECX[15] PDCM 清零、ECX[24] TSC_DEADLINE 置 1、ECX[31] HYPERVISOR 置 1；
• EDX[28] HTT：当 cpu_count > 1 时置 1，表示 EBX[23:16] 字段有效。

2.3 Leaf 0xB：扩展拓扑枚举

update_extended_topology_entry（normalize.rs）是通用逻辑里最复杂的一块：

• 补全 subleaf 0x1：从 Linux v6.2 起 KVM_GET_SUPPORTED_CPUID 不再返回 CPUID.(EAX=0BH,ECX=1)（源码注释引用内核行为变更），因此 Firecracker 通过 entry(...).or_insert(...) 主动补一个全零的 core domain 项，并在测试中专门验证 Intel/AMD 两侧都能补上（测试 check_leaf_0xb_subleaf_0x1_added）；
• subleaf 0（逻辑处理器域）：EAX[4:0] = cpu_bits（SMT 关闭为 0，开启为 1）；EBX[15:0] = cpus_per_core；ECX[15:8] = 域类型 1；EDX = x2APIC ID（cpu_index）；
• subleaf 1（核心域）：EAX[4:0] 取 MAX_SUPPORTED_VCPUS.next_power_of_two().ilog2()，即满足 2^N ≥ 最大 vCPU 数的最小 N。当前 MAX_SUPPORTED_VCPUS = 32（machine_config.rs），故该字段固定为 5，可覆盖最大 32 个 vCPU；EBX[15:0] = cpu_count；ECX[7:0] = subleaf 序号；ECX[15:8] = 域类型 2（core）；
• 更深的 subleaf（≥2）：受支持内核上不应存在；若出现，Firecracker 仅告警 warn! 并跳过，以免在不支持的内核上直接失败。

2.4 扩展缓存叶子 0x80000005 / 0x80000006

update_extended_cache_features（normalize.rs）把宿主 cpuid(0x80000005)（L1 缓存与 TLB）与 cpuid(0x80000006)（L2/L3 缓存与 TLB）整份透传，并对后者 EDX 屏蔽保留位 [17:16]。源码注释提醒：这两个叶子缺失会以 MissingLeaf0x80000005/06 报错。

三、Intel 专属归一化

下表来自 原文档，实现位于 Intel 归一化文件：

描述	Leaf	Subleaf	寄存器	Bits
更新确定性缓存参数	0x4	all	EAX	31:14
禁用 Intel Turbo Boost 技术	0x6	-	EAX	1
禁用频率选择	0x6	-	ECX	3
设置 FDP_EXCPTN_ONLY 位	0x7	0x0	EBX	6
设置 "Deprecates FPU CS and FPU DS values" 位	0x7	0x0	EBX	13
禁用 WAITPKG（UMONITOR / UMWAIT / TPAUSE）	0x7	0x0	ECX	5
禁用性能监控	0xa	-	all	all
填充 v2 扩展拓扑枚举 leaf	0x1f	all	all	all
用默认格式与真实频率更新品牌字符串	0x80000002, 0x80000003, 0x80000004	-	all	all

3.1 Leaf 0x4：确定性缓存参数

update_deterministic_cache_entry（intel/normalize.rs）遍历所有有效 subleaf（全零寄存器视为无效项并终止），依据 EAX[7:5] 缓存层级改写 EAX[31:14]：

• L1/L2 缓存：最多由每核逻辑 CPU 数共享，写入 cpus_per_core - 1；
• L3 缓存：由全部逻辑线程共享，写入 cpu_count - 1；
• EAX[31:26]（物理包内最大可寻址核心数域）写入 cpu_count / cpus_per_core - 1，即把所有核心视为位于同一 socket。

3.2 Leaf 0x6 与 0xA：电源管理与性能监控

update_power_management_entry（同文件 L163-L181）执行两项清除：

• EAX[1]：清除 Turbo Boost 可用位，避免客户机向虚拟化层索取频率行为；
• ECX[3]：清除 SETBH / 能量性能偏好（EPB）位，源码注释表述为“Clear X86 EPB feature. No frequency selection in the hypervisor”。

update_performance_monitoring_entry（同文件 L242-L254）将 leaf 0xA 的四个寄存器整体清零，即访客不再获得宿主硬件性能监控单元（PMU）的 CPUID 描述。

3.3 Leaf 0x7 / subleaf 0：结构化扩展特性标志

update_extended_feature_flags_entry（同文件 L183-L240）一次性修正三个位：

• EBX[6]（FDP_EXCPTN_ONLY）与 EBX[13]（Deprecates FPU CS/DS）：置 1。源码注释指出这两个位在 AMD 上是保留位，置位依据是内核虚拟化维护者关于 “向访客暴露较新的 x87 FPU 语义” 的推荐补丁，并给出来源内核提交引用；
• ECX[5]（WAITPKG）：清零。原因注释非常清晰：UMONITOR/UMWAIT/TPAUSE 即便运行在客户机里，也会让物理 CPU 进入优化空闲态，Firecracker 出于多租户调度友好性将其关闭；清除 CPUID 位后，KVM 不会在二次 VM-execution 控制中设置 “enable user wait and pause”，访客执行这些指令将得到 #UD。KVM 自 v5.8 起会把该位以 1 返回给 VMM，因此必须显式清掉。

3.4 Leaf 0x1F：v2 扩展拓扑

update_extended_topology_v2_entry（同文件 L256-L277）在 leaf 0x1F 存在时，把 leaf 0xB 的所有 subleaf 原样复制到 leaf 0x1F（0x1F 是 Intel 推荐的、0xB 的超集）。如果宿主 CPUID 中根本没有 0x1F，则直接跳过，测试 test_update_extended_topology_v2_entry_* 对“无 0x1F 时跳过”与“逐 subleaf 复制”两种路径均有覆盖。

3.5 品牌字符串：默认格式 + 真实频率

Intel 侧品牌字符串长度恒为 48 字节（3 个叶子 × 4 个寄存器 × 4 字节，BRAND_STRING_LENGTH 定义在 mod.rs）。归一化并不简单地写死“Xeon”：

1. 用 host_brand_string()（mod.rs）读出宿主三个品牌叶子的原始字节；
2. 由 default_brand_string（intel/normalize.rs）从字符串尾部反向解析出频率数字（如 3.00）及其单位（GHz/MHz/THz）；
3. 重组为 Intel(R) Xeon(R) Processor @ 3.00GHz 样式；若解析失败（缺频率、缺空格分隔、长度溢出）则回退到常量 DEFAULT_BRAND_STRING = Intel(R) Xeon(R) Processor（无频率后缀）。

示例单测 default_brand_string_test：输入 Intel(R) Xeon(R) Platinum 8275CL CPU @ 3.00GHz\0\0，期望输出 Intel(R) Xeon(R) Processor @ 3.00GHz 并零填充至 48 字节。

四、AMD 专属归一化

下表来自 原文档，实现位于 AMD 归一化文件：

描述	Leaf	Subleaf	寄存器	Bits
将 IA32_ARCH_CAPABILITIES MSR 标记为不存在	0x7	-	EDX	29
设置拓扑扩展位	0x80000001	-	ECX	22
用默认 AMD 值更新品牌字符串	0x80000002, 0x80000003, 0x80000004	-	EAX, EBX, ECX, EDX	all
更新物理线程数	0x80000008	-	ECX	7:0
更新 APIC ID 大小	0x80000008	-	ECX	15:12
更新缓存拓扑信息	0x8000001d	all	all	all
更新扩展 APIC ID	0x8000001e	-	EAX, EBX, ECX	all

4.1 Leaf 0x7：清除 IA32_ARCH_CAPABILITIES 枚举

update_structured_extended_entry（amd/normalize.rs）清除 EDX[29]。源码注释解释：AMD64 架构手册中 IA32_ARCH_CAPABILITIES MSR 不可用，而 KVM 无条件置位该枚举位，Firecracker 须显式纠正，否则客户机会以为可以访问并不存在的 MSR。测试 test_update_structured_extended_entry_valid 验证了对置满的 EDX 执行清除后该位确实为 0。

4.2 缓存拓扑透传与拓扑扩展位

passthrough_cache_topology（同文件 L118-L182）是 AMD 分支中最“吃宿主”的步骤：

• 先用 get_vendor_id_from_host() 校验宿主确为 AMD，否则返回 BadVendorId 错误（防止在非 AMD 宿主上进入无限枚举循环）；
• 直接插入宿主 cpuid(0x8000001e) 作为 leaf 0x8000001e（处理器拓扑信息）；
• 以 cache_type = EAX[4:0] 是否为 0 作为终止条件，把宿主 leaf 0x8000001d（缓存拓扑）的各级 subleaf 依次透传并标记 SIGNIFICANT_INDEX。

随后 update_extended_feature_fn_entry（同文件 L185-L195）置位 leaf 0x80000001 ECX[22]（TopologyExtensions），向客户机声明对 Fn8000_001D/001E 的支持——否则上述缓存拓扑叶子会被视为保留。

4.3 Leaf 0x80000008 与 0x8000001D/1E

• 0x80000008（update_amd_feature_entry，同文件 L211-L244）：ECX[7:0]（NC，物理线程数 − 1）写入 cpu_count - 1；ECX[15:12]（APIC ID 大小）固定写入 7（常量 THREAD_ID_MAX_SIZE，可容纳至多 64 逻辑线程）；
• 0x8000001d（update_extended_cache_topology_entry，同文件 L246-L305）：对每个已透传的 subleaf，按 EAX[7:5] 缓存层级改写 EAX[25:14]（共享该缓存的逻辑处理器数 − 1）：L1/L2 写 cpus_per_core - 1，L3 写 cpu_count - 1，与 Intel 侧 leaf 0x4 的处理思路一致；
• 0x8000001e（update_extended_apic_id_entry，同文件 L307-L377）：EAX[31:0] 写扩展 APIC ID = cpu_index；EBX[7:0] 写 compute unit / core ID = cpu_index / cpus_per_core（SMT 下相邻两个逻辑 CPU 共享同一 core ID）；EBX[15:8] 写每计算单元线程数 − 1 = cpus_per_core - 1；ECX[10:8] 置 0（每个 socket 视为单节点），ECX[7:0] 置 0（所有 CPU 同属 node 0）。

4.4 AMD 品牌字符串

update_brand_string_entry（同文件 L379-L384）直接应用常量 DEFAULT_BRAND_STRING = AMD EPYC（零填充至 48 字节），不做频率透传——这与 Intel 侧“默认格式 + 真实频率”形成鲜明对比，也解释了 原文档 中两张表格该行的措辞差异。

五、归一化与 CPU 模板的覆盖次序

原文档 开篇就强调了一个对模板使用者至关重要的语义，源码在 mod.rs 中给出顺序证据：

模板应用（apply_template_to_cpuid）  →  逐 vCPU 归一化（normalize）  →  KVM_SET_CPUID2

因此：

1. 模板想把归一化涉及的位改成“非默认值”是无效的。例如模板若尝试修改 leaf 0x1 的 HYPERVISOR 位、TPR/APIC 相关字段、leaf 0xB 的拓扑字段、Intel leaf 0x4/0x6/0x7/0xA、AMD leaf 0x7 的 EDX[29] 等，都会在归一化阶段被覆盖回归一化结果；
2. 模板仍然能控制归一化范围之外的海量字段（如各种指令集扩展位、leaf 0x7 未被归一化触及的其余位等），这也是 CPU 模板的核心价值所在；
3. 归一化是逐 vCPU 的：同一微VM内不同 vCPU 在 APIC ID 类字段上必然不同，模板修饰则对所有 vCPU 一致。若要做跨快照恢复、跨内核版本对比，请留意最终生效的是“模板 ∪ 归一化”之后的复合结果，仓库中的指纹比对测试（见 tests/data/cpu_template_helper 下的 fingerprint_* JSON）本质上就是针对这一最终 CPUID 集合做基线比对的。

六、归一化结果的下游消费：MSR 快照记账

归一化不是孤立的“装修步骤”，它的产物还会决定引导期 MSR 采集与快照记账。从 vcpu.rs 的 configure_msrs_for_boot 与 mod.rs 的阶段注释可以看出：

• 顺序约束：必须先把归一化后的 CPUID 通过 KVM_SET_CPUID2 安装到 vCPU，再执行 KVM_GET_MSRS。因为 KVM 依据访客 CPUID 决定哪些 CPUID 依赖型 MSR 有值，顺序颠倒会导致取回全零；
• 依赖推断：configure_msrs_for_boot 收到 configure_cpuid 返回的最终 CPUID，再调用 msrs_to_save_by_cpuid（common.rs），按 CPUID 特性位（如 MPX → MSR_IA32_BNDCFGS、MTRR 族 MSR、MCE bank MSR 区间）追加快照需要保存的额外 MSR。也就是说，归一化最终改变了哪些 MSR 会进入快照。

这同时也解释了为何归一的字段多与“拓扑 / 虚拟化标识 / 性能监控”强相关——它们直接影响引导 MSR 状态与后续快照的迁移一致性。

七、Boot 协议相关参照

CPUID 归一化只是 x86_64 引导期 CPU 配置的一部分。Boot 协议层对段寄存器、CR0/CR4 标志与 MSR 的设定与本文内容互补，两者共同决定客户机内核启动后看到的完整 CPU 视图，可进一步参阅 boot protocol 设置说明。若需要把 CPUID 归一化与模板联动做更细粒度的定制或诊断，CPU 模板总览 与 cpu-template-helper 指纹工具 提供了对应的操作入口。

小结

x86_64 的 CPUID 归一化是 Firecracker 中少有的“无条件生效”的默认行为：它以宿主的 KVM_GET_SUPPORTED_CPUID 为基底，先用模板修饰、再做归一化，最后逐 vCPU 安装。通用部分负责 vendor 透传、leaf 0x1 特性位与拓扑、leaf 0xB 扩展拓扑和缓存叶子透传；Intel 部分额外修正确定性缓存参数、电源管理、WAITPKG 与品牌字符串；AMD 部分额外修正 ARCH_CAPABILITIES 枚举、缓存拓扑透传与扩展 APIC ID。理解这些表项，是把 CPU 模板、SMT/vCPU 拓扑配置与快照行为正确组合起来的前提。