From 2a07ec4a5d8e40153872b8e299f1052af7108e99 Mon Sep 17 00:00:00 2001
From: pjh456 <147148383@qq.com>
Date: Thu, 17 Sep 2026 17:02:16 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=94=B9=E5=86=99=E6=B4=BB=E8=B7=83?=
 =?UTF-8?q?=E5=8F=98=E9=87=8F=E5=88=86=E6=9E=90=E6=B3=A8=E9=87=8A=E7=9A=84?=
 =?UTF-8?q?=E7=BC=96=E5=8F=B7=E4=B8=8E=E8=A1=8C=E5=8F=B7=E5=BC=95=E7=94=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 crates/oxide_liveness/src/dataflow.rs | 14 +++++++-------
 crates/oxide_liveness/src/ranges.rs   |  5 +++--
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/crates/oxide_liveness/src/dataflow.rs b/crates/oxide_liveness/src/dataflow.rs
index 87ba9739..b9b559a9 100644
--- a/crates/oxide_liveness/src/dataflow.rs
+++ b/crates/oxide_liveness/src/dataflow.rs
@@ -3,7 +3,7 @@
 //! gen/kill 直接消费 `oxide_ir::contract` 的 `def_reg`/`use_regs`，
 //! None→0 / This→254 / NewTarget→255 / CALL 隐式 reg0 全内置，不重复建。
 //! Exception 边当普通边参与迭代；Exception 目标块入口 reg 0 隐式 def
-//! （异常展开写 regs[0]，vm_runtime.rs:204-205）在此建模：gen.remove(0)+kill.insert(0)。
+//! （异常展开由 VM 派发循环写入 regs[0]）在此建模：gen.remove(0)+kill.insert(0)。
 //!
 //! 位集为 `u64` 压缩（1 字 64 位，密度为 `Vec<bool>` 的 8 倍）；不动点迭代
 //! 复用 out/input 两块缓冲（clear + 覆盖），不逐块逐迭代分配。
@@ -16,7 +16,7 @@ use crate::live_info::{bitset_clear, bitset_set};
 /// 块级 liveness：返回 (block_live_in, block_live_out, reg_count)。
 /// reg_count = 全部 def/use 最大 reg 号（bitset 容量 = reg_count+1）。
 pub(super) fn block_liveness(f: &IRFunction, cfg: &Cfg) -> (Vec<Vec<u64>>, Vec<Vec<u64>>, usize) {
-    // 1. reg_count 上界扫描（不信任 f.n_registers，动态求上界，照 iter_sweep 先例）
+    // 上界扫描：f.n_registers 在 emit 阶段未必填准，故不信任它，逐 inst 取 def/use 最大 reg 号作 bitset 容量上界。
     let mut reg_count = 255usize; // 兜底 This/NewTarget 254/255
     for inst in &f.insts {
         if let Some(d) = inst.def_reg() {
@@ -30,12 +30,12 @@ pub(super) fn block_liveness(f: &IRFunction, cfg: &Cfg) -> (Vec<Vec<u64>>, Vec<V
     let words = (reg_count + 1).div_ceil(64);
     let n = cfg.blocks.len();
 
-    // 2. 每块 gen/kill
+    // 每块 gen/kill：先算块内反向扫描的 gen，再算正向扫描的 kill。
     let mut gen: Vec<Vec<u64>> = vec![vec![0u64; words]; n];
     let mut kill: Vec<Vec<u64>> = vec![vec![0u64; words]; n];
     for (b, block) in cfg.blocks.iter().enumerate() {
         // gen：块内反向扫描，kill 先于 gen（`live = (live − def) ∪ use`）。
-        // 顺序理由：COMPOUND_ADD 等读-写同寄存器指令 use 含 rd（contract.rs:137），
+        // 顺序理由：COMPOUND_ADD 等读-写同寄存器指令的 uses 含 Rd（见 oxide_ir::contract 的 def/use 约定），
         // gen 先于 kill 会把 rd 旧值从 live_before 错误剔除。
         let mut live = vec![0u64; words];
         for i in block.inst_range.clone().rev() {
@@ -68,10 +68,10 @@ pub(super) fn block_liveness(f: &IRFunction, cfg: &Cfg) -> (Vec<Vec<u64>>, Vec<V
         }
     }
 
-    // 3. reverse_postorder（确定性，禁 HashMap 迭代序）
+    // reverse_postorder：从 entry 沿 succs 存储序 DFS，保证确定性（禁 HashMap 迭代序）。
     let rpo = reverse_postorder(cfg);
 
-    // 4. 不动点迭代：out/input 缓冲循环外分配复用，clear + 覆盖免逐迭代分配
+    // 不动点迭代：out/input 缓冲在循环外分配复用，clear + 覆盖，免逐迭代分配。
     let mut live_in = vec![vec![0u64; words]; n];
     let mut live_out = vec![vec![0u64; words]; n];
     let mut out = vec![0u64; words];
@@ -265,7 +265,7 @@ mod tests {
     #[test]
     fn none_operand_maps_to_reg0() {
         // 0: LOAD_VAR(Reg(5), None, None)   def 5 use {0}
-        // 1: HALT(None, None, None)          contract.rs HALT 读 regs[0]
+        // 1: HALT(None, None, None)          HALT 读 regs[0]（contract 约定）
         let mut f = empty_function();
         f.insts
             .push(Inst::new(OpCode::LOAD_VAR, Operand::Reg(5), Operand::None, Operand::None));
diff --git a/crates/oxide_liveness/src/ranges.rs b/crates/oxide_liveness/src/ranges.rs
index 01a3ef11..33b4ce84 100644
--- a/crates/oxide_liveness/src/ranges.rs
+++ b/crates/oxide_liveness/src/ranges.rs
@@ -2,7 +2,7 @@
 //!
 //! 起点是 **block_live_out**（非 liveIn——从 liveIn 出发会得到错误放大的逐指令集）。
 //! 反向扫描 **kill 先于 gen**（`live = (live − def) ∪ use`）：COMPOUND_ADD 等读-写
-//! 同寄存器指令 use 含 rd（contract.rs:137），gen 先于 kill 会把 rd 旧值从
+//! 同寄存器指令的 uses 含 Rd（见 oxide_ir::contract 的 def/use 约定），gen 先于 kill 会把 rd 旧值从
 //! live_before 错误剔除。Exception 目标块入口 reg 0 隐式 def 在此截断，并以
 //! `debug_assert_eq!(live, block_live_in[b])` 校验与 dataflow 一致性。
 //!
@@ -24,7 +24,8 @@ pub(super) fn inst_liveness(
         let mut live = block_live_out[b].clone(); // 从块级 liveOut 出发（非 liveIn）
         for i in block.inst_range.clone().rev() {
             after[i].copy_from_slice(&live);
-            // kill 先于 gen：本指令先写后读（COMPOUND_ADD 等读-写同寄存器，contract.rs:137）
+            // kill 先于 gen：本指令先写后读。COMPOUND_ADD 等读-写同寄存器指令的
+            // uses 含 Rd，见 oxide_ir::contract 的 def/use 约定。
             if let Some(d) = f.insts[i].def_reg() {
                 bitset_clear(&mut live, d as usize);
             }