2 kernel-migration-flow: 内核迁移主流程

本篇讲清楚一次 UVM_MIGRATE 从 ioctl 进入内核后的完整路径，重点标注 NUMA 目标节点（dst_node_id / dest_nid）在各层如何传递。

---

1. 入口：uvm_api_migrate()

文件：uvm_migrate.c（uvm_api_migrate，约 L860+）。

主要职责：

1. 解析 UVM_MIGRATE_PARAMS，把 destinationUuid 解析成目标处理器（dest_gpu 或 CPU）。
2. 校验 cpuNumaNode（见文档 01 的合法性规则），uvm_migrate.c。
3. 区分内存类型，分派到不同实现：
   • UVM_API_RANGE_TYPE_NUMA（pageable，透明访问）→ uvm_migrate_pageable()；
   • 其它（managed / HMM）→ uvm_migrate()。
4. 处理集成 GPU / CDMM / 关闭 pageable 迁移 等特殊情形：把目标改写为 CPU，并把 cpu_numa_node 设为 GPU 的 closest_cpu_numa_node（见 uvm_migrate.c，详见文档 04）。

// 集成 GPU：迁到该 GPU 等价于迁到它最近的 CPU NUMA 节点
if (dest_gpu && dest_gpu->parent->is_integrated_gpu) {
    dest_id = UVM_ID_CPU;
    cpu_numa_node = dest_gpu->parent->closest_cpu_numa_node;
}

---

2. Managed 内存：uvm_migrate()

文件：uvm_migrate.c。

2.1 把目标 NUMA 节点注入 service context

关键一行------这是把用户请求的节点交给下游 make_resident 的地方：

service_context->block_context->make_resident.dest_nid = dest_nid;   // uvm_migrate.c:626

dest_nid 即用户 cpuNumaNode（或被特殊硬件逻辑改写后的值）。

2.2 两遍（two-pass）策略

见 uvm_migrate.c 大段注释。除非只覆盖单个 VA block 或带 UVM_MIGRATE_FLAG_SKIP_CPU_MAP，否则做两遍：

1. Pass 1 ：搬运所有 VA block 的数据，不建立映射；
2. Pass 2：逐 block 复查（可能被别人移动过）并补建映射。

目的：避免「建立 CPU 映射（同步）」阻塞后续 block 的搬运，并减少并发迁移间的假依赖。HMM 始终单遍。

调用链：

uvm_migrate()
  └─ uvm_migrate_ranges()                      // 遍历 [base,len) 覆盖的 managed range
       └─ uvm_va_range_migrate()               // 单个 range 内按 block 切分
            └─ uvm_va_range_migrate_multi_block()
                 └─ uvm_va_block_migrate_locked()
                      └─ uvm_va_block_make_resident*()   // 真正 make resident

2.3 HMM 分支

若无 managed range，uvm_migrate_ranges() 转 uvm_hmm_migrate_ranges()（uvm_migrate.c），同样最终走 make_resident + CPU chunk 分配，NUMA 处理与 managed 一致。

---

3. make_resident：CPU 目标的核心

文件：uvm_va_block.c。

当目标是 CPU 时，uvm_va_block_make_resident* 需要为目标页分配 CPU 物理内存并拷贝 。分配这一步就是 NUMA 感知的落点，由 block_populate_pages_cpu() 完成（uvm_va_block.c），详见 03-numa-node-selection。

目标节点通过 uvm_va_block_context_get_node() 归一化（uvm_va_block.c）：

static int uvm_va_block_context_get_node(...)
{
    if (va_block_context->make_resident.dest_nid != NUMA_NO_NODE)
        return va_block_context->make_resident.dest_nid;   // 1) 迁移请求指定
    if (policy->preferred_nid != NUMA_NO_NODE)
        return policy->preferred_nid;                      // 2) 首选位置策略
    return numa_mem_id();                                  // 3) 就近兜底
}

make_resident 上下文中与 NUMA 相关的字段（uvm_va_block_types.h）：

字段	作用
dest_id	最终驻留处理器（CPU / GPU）
dest_nid	目标为 CPU 时的最终 NUMA 节点
node_pages_mask	计算「每个 CPU 节点对应哪些页」的临时掩码
pages_migrated / pages_changed_residency	结果掩码

---

4. Pageable 内存：uvm_migrate_pageable()

文件：uvm_migrate_pageable.c。

与 managed 不同，pageable 借助内核 migrate_vma_setup/pages/finalize 框架，目标页由 UVM 自己 alloc_pages_node() 分配 ，因此 NUMA 落点直接由 dst_node_id 决定。

4.1 目标节点保存在 uvm_migrate_args->dst_node_id

结构见 uvm_migrate_pageable.h：

// dst_node_id may be clobbered by uvm_migrate_pageable().
int dst_node_id;

4.2 决定每页是否需要搬（NUMA 判断）

migrate_vma_compute_masks()（uvm_migrate_pageable.c）里对每个源页判断：

src_nid = page_to_nid(src_page);

// 已在目标节点 → 不搬
if (src_nid == uvm_migrate_args->dst_node_id) { ...dst_resident...; continue; }

// 目标是 CPU，且该页已在某个「有 CPU 的」节点 → 不搬
if (UVM_ID_IS_CPU(dst_id) && node_state(src_nid, N_CPU)) { ...; continue; }

// 目标是 CPU，且源节点不是任何 GPU 的内存节点 → 不搬
if (UVM_ID_IS_CPU(dst_id) && !src_gpu) { ...; continue; }

含义：回迁到 CPU 时，如果页面已经在某个 CPU NUMA 节点上，默认不会为了「换个 CPU 节点」而搬（除非它当前在 GPU 内存节点上）。这是一个重要的性能取舍。

4.3 分配目标页并校验落点

uvm_migrate_vma_alloc_page()（uvm_migrate_pageable.c）：

dst_page = alloc_pages_node(uvm_migrate_args->dst_node_id, g_migrate_vma_gfp_flags, 0);

// 校验内核是否真的把页分到了目标节点（规避历史内核 __GFP_THISNODE 未生效的 bug）
if (dst_page && page_to_nid(dst_page) != uvm_migrate_args->dst_node_id) {
    __free_page(dst_page);
    dst_page = NULL;         // 视为 OOM，触发用户态换节点重试协议
}

分配失败会最终以 NV_ERR_MORE_PROCESSING_REQUIRED 返回用户态（对应文档 01 的重试协议）。

4.4 dst_node_id == NUMA_NO_NODE 的处理

pageable 路径要求确定节点；在 uvm_migrate_pageable() 内部若 dst_node_id == NUMA_NO_NODE（uvm_migrate_pageable.c）会做相应处理/校验，这也是为什么用户态对 pageable 传 -1 被判非法。

---

5. 流程小结（回迁到 CPU 的 NUMA 视角）

#mermaid-svg-fNL1LaXXePOHFreT{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-fNL1LaXXePOHFreT .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-fNL1LaXXePOHFreT .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-fNL1LaXXePOHFreT .error-icon{fill:#552222;}#mermaid-svg-fNL1LaXXePOHFreT .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-fNL1LaXXePOHFreT .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-fNL1LaXXePOHFreT .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-fNL1LaXXePOHFreT .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-fNL1LaXXePOHFreT .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-fNL1LaXXePOHFreT .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-fNL1LaXXePOHFreT .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-fNL1LaXXePOHFreT .marker{fill:#333333;stroke:#333333;}#mermaid-svg-fNL1LaXXePOHFreT .marker.cross{stroke:#333333;}#mermaid-svg-fNL1LaXXePOHFreT svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-fNL1LaXXePOHFreT p{margin:0;}#mermaid-svg-fNL1LaXXePOHFreT .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-fNL1LaXXePOHFreT .cluster-label text{fill:#333;}#mermaid-svg-fNL1LaXXePOHFreT .cluster-label span{color:#333;}#mermaid-svg-fNL1LaXXePOHFreT .cluster-label span p{background-color:transparent;}#mermaid-svg-fNL1LaXXePOHFreT .label text,#mermaid-svg-fNL1LaXXePOHFreT span{fill:#333;color:#333;}#mermaid-svg-fNL1LaXXePOHFreT .node rect,#mermaid-svg-fNL1LaXXePOHFreT .node circle,#mermaid-svg-fNL1LaXXePOHFreT .node ellipse,#mermaid-svg-fNL1LaXXePOHFreT .node polygon,#mermaid-svg-fNL1LaXXePOHFreT .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-fNL1LaXXePOHFreT .rough-node .label text,#mermaid-svg-fNL1LaXXePOHFreT .node .label text,#mermaid-svg-fNL1LaXXePOHFreT .image-shape .label,#mermaid-svg-fNL1LaXXePOHFreT .icon-shape .label{text-anchor:middle;}#mermaid-svg-fNL1LaXXePOHFreT .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-fNL1LaXXePOHFreT .rough-node .label,#mermaid-svg-fNL1LaXXePOHFreT .node .label,#mermaid-svg-fNL1LaXXePOHFreT .image-shape .label,#mermaid-svg-fNL1LaXXePOHFreT .icon-shape .label{text-align:center;}#mermaid-svg-fNL1LaXXePOHFreT .node.clickable{cursor:pointer;}#mermaid-svg-fNL1LaXXePOHFreT .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-fNL1LaXXePOHFreT .arrowheadPath{fill:#333333;}#mermaid-svg-fNL1LaXXePOHFreT .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-fNL1LaXXePOHFreT .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-fNL1LaXXePOHFreT .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fNL1LaXXePOHFreT .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-fNL1LaXXePOHFreT .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fNL1LaXXePOHFreT .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-fNL1LaXXePOHFreT .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-fNL1LaXXePOHFreT .cluster text{fill:#333;}#mermaid-svg-fNL1LaXXePOHFreT .cluster span{color:#333;}#mermaid-svg-fNL1LaXXePOHFreT div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-fNL1LaXXePOHFreT .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-fNL1LaXXePOHFreT rect.text{fill:none;stroke-width:0;}#mermaid-svg-fNL1LaXXePOHFreT .icon-shape,#mermaid-svg-fNL1LaXXePOHFreT .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fNL1LaXXePOHFreT .icon-shape p,#mermaid-svg-fNL1LaXXePOHFreT .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-fNL1LaXXePOHFreT .icon-shape .label rect,#mermaid-svg-fNL1LaXXePOHFreT .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fNL1LaXXePOHFreT .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-fNL1LaXXePOHFreT .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-fNL1LaXXePOHFreT :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 集成GPU/CDMM/禁用pageable
managed/HMM
pageable
失败
UVM_MIGRATE ioctl
uvm_api_migrate 校验 cpuNumaNode
dst=CPU, node=closest_cpu_numa_node
内存类型
uvm_migrate: make_resident.dest_nid = cpuNumaNode
block_populate_pages_cpu
uvm_cpu_chunk_alloc __GFP_THISNODE + 回退
uvm_migrate_pageable: dst_node_id
alloc_pages_node + 校验落点
NV_ERR_MORE_PROCESSING_REQUIRED → 用户态换节点

下一篇 03-numa-node-selection 深入 managed/HMM 路径的 CPU chunk 分配与 per-node 驻留跟踪。