要让 GPU 干任何活，第一步都是准备内存：命令流（IB/PM4）要放在 GPU 能读到的内存里，被拷贝的 src/dst 数据也要有 GPU 虚拟地址。裸用 libdrm 做这件事，每次都要走「分配 BO → 分配 VA 范围 → 建立映射 →（可选）CPU 映射」四步，还要处理各步失败时的逆序回滚。amd_memory.{c,h}的价值就是把这套样板收敛成一两个函数。这一篇讲清楚它封装了什么、每层 libdrm 调用各自负责什么、以及不同变体该怎么选。
一、一个 BO 从分配到可用，要过几关
在 amdgpu 的模型里，「一块能被 GPU 命令直接引用的内存」不是一次调用就绪的，它有三个正交的概念：
- BO（buffer object）：真实的物理后备，分配时用
preferred_heap决定放在 VRAM 还是 GTT（系统内存），用flags指定 CPU 可访问等属性。 - VA 范围：GPU 侧的虚拟地址空间，独立于物理 BO 分配。命令流里写的地址（如 WRITE_DATA 的目标）就是这个 VA。
- MAP：把物理 BO 绑到某段 VA 上，页表由此建立，GPU 才能通过该地址访问到数据。
- CPU map：可选，给测试代码一个
void*去填数据 / 读回校验。
这四步任何一步失败，前面已成功的都要按逆序撤销——这正是最容易写错、也最值得封装的部分。
二、主力函数：amdgpu_bo_alloc_and_map
绝大多数测试用的就是它。一次调用把四步和回滚全包了：
intamdgpu_bo_alloc_and_map(amdgpu_device_handle dev,unsignedsize,unsignedalignment,unsignedheap,uint64_tflags,amdgpu_bo_handle*bo,void**cpu,uint64_t*mc_address,amdgpu_va_handle*va_handle){structamdgpu_bo_alloc_requestrequest={.alloc_size=size,.phys_alignment=alignment,.preferred_heap=heap,.flags=flags,};amdgpu_bo_handle buf_handle;amdgpu_va_handle handle;uint64_tvmc_addr;intr;r=amdgpu_bo_alloc(dev,&request,&buf_handle);if(r)returnr;r=amdgpu_va_range_alloc(dev,amdgpu_gpu_va_range_general,size,alignment,0,&vmc_addr,&handle,0);if(r)gotoerror_va_alloc;r=amdgpu_bo_va_op(buf_handle,0,size,vmc_addr,0,AMDGPU_VA_OP_MAP);if(r)gotoerror_va_map;r=amdgpu_bo_cpu_map(buf_handle,cpu);if(r)gotoerror_cpu_map;*bo=buf_handle;*mc_address=vmc_addr;*va_handle=handle;return0;error_cpu_map:amdgpu_bo_cpu_unmap(buf_handle);error_va_map:amdgpu_bo_va_op(buf_handle,0,size,vmc_addr,0,AMDGPU_VA_OP_UNMAP);error_va_alloc:amdgpu_bo_free(buf_handle);returnr;}调用方拿回四样东西，各有用途：
| 输出 | 类型 | 用途 |
|---|---|---|
*bo | amdgpu_bo_handle | 提交时进 BO list，让内核知道这次提交引用了它 |
*cpu | void* | CPU 侧填数据 / 读回校验 |
*mc_address | uint64_t | GPU 虚拟地址，写进 PM4 packet 的地址字段 |
*va_handle | amdgpu_va_handle | 释放时归还 VA 范围 |
关键设计点是那串goto的逆序回滚：CPU map 失败就只回滚到 unmap+free；VA map 失败就回滚 VA 分配……保证任何中途失败都不泄漏 BO 或 VA。这段逻辑写一次、所有测试复用，是这个库最实在的价值之一。
三、释放：一句对称的收尾
分配的逆操作同样打包好，顺序与分配严格镜像：
voidamdgpu_bo_unmap_and_free(amdgpu_bo_handle bo,amdgpu_va_handle va_handle,uint64_tmc_addr,uint64_tsize){amdgpu_bo_cpu_unmap(bo);amdgpu_bo_va_op(bo,0,size,mc_addr,0,AMDGPU_VA_OP_UNMAP);amdgpu_va_range_free(va_handle);amdgpu_bo_free(bo);}CPU unmap → VA unmap → 归还 VA 范围 → 释放 BO。测试里alloc_and_map/unmap_and_free成对出现，就不会漏资源。
四、几个变体：什么时候用哪个
同一主题有几个变体，差别只在「映射那一步怎么做」：
| 函数 | 差别 | 适用场景 |
|---|---|---|
amdgpu_bo_alloc_and_map | 标准 MAP，默认读写权限 | 绝大多数测试 |
amdgpu_bo_alloc_and_map_raw | 用amdgpu_bo_va_op_raw，显式带READABLE|WRITEABLE|EXECUTABLE+ 自定义mapping_flags，并按getpagesize()对齐 | 需要可执行页（放 shader ISA）或自定义映射标志 |
amdgpu_bo_alloc_and_map_sync | 按sync参数分流：走 user-queue 路径（_uq）或普通路径 | 用户队列（UQ）提交模型 |
_raw版本的映射长这样，注意它显式给出页权限并把大小对齐到系统页：
r=amdgpu_bo_va_op_raw(dev,buf_handle,0,ALIGN(size,getpagesize()),vmc_addr,AMDGPU_VM_PAGE_READABLE|AMDGPU_VM_PAGE_WRITEABLE|AMDGPU_VM_PAGE_EXECUTABLE|mapping_flags,AMDGPU_VA_OP_MAP);放 compute shader 二进制的 BO 必须可执行，就得走_raw显式带EXECUTABLE位；普通数据 BO 用标准版即可。
五、BO list：把提交要引用的 BO 打包
提交一次命令，内核需要知道这次会碰到哪些 BO（用于驻留/换页）。amd_memory提供了一个最常用的两 BO 打包：
intamdgpu_get_bo_list(amdgpu_device_handle dev,amdgpu_bo_handle bo1,amdgpu_bo_handle bo2,amdgpu_bo_list_handle*list){amdgpu_bo_handle resources[]={bo1,bo2};returnamdgpu_bo_list_create(dev,bo2?2:1,resources,NULL,list);}bo2传 NULL 就只登记一个。典型场景：bo1是命令 IB，bo2是数据 BO。这个 list 会交给下一步的命令提交（下一篇 6.4 之后的提交框架会用到）。
六、其它职责
amd_memory还兼管几类与内存相关的杂活，用到时知道去哪找即可：
- 内存信息查询：
get_available_vram/get_available_system_memory/get_gpu_memory_info，用于按可用容量裁剪测试规模。 - dmabuf / 导入导出：
create_dmabuf、virtual_mem_to_gpu_bo（把一段用户虚拟内存包成 GPU BO），服务跨设备共享与 SVM 类场景。 - 裸 CPU 虚拟内存：
virtual_alloc_memory/virtual_free_memory/wait_on_value，用于纯 CPU 侧的辅助缓冲与轮询等待。 - 多 fence 等待：
amdgpu_command_submission_multi_fence_wait_all。
七、关键结论
- amdgpu 内存有三个正交概念：物理 BO、GPU VA 范围、二者的 MAP；
amd_memory的核心就是把「分配四步 + 逆序回滚」封成一句amdgpu_bo_alloc_and_map。 - 一次分配返回四样东西各司其职：
bo（进 BO list）、cpu（填/读）、mc_address（写进 PM4）、va_handle（释放用）。 - 需要可执行页（放 shader）或自定义映射标志时用
_raw变体；用户队列模型用_sync变体。 amdgpu_get_bo_list把「这次提交引用了哪些 BO」打包，衔接到命令提交环节。
