【PR】: 增加UVM内存申请用例readme-runtime-AtomGit

已合并

【PR】: 增加UVM内存申请用例readme #3962

hnn___36创建于 7月30日从hnn___36/runtime_7962： master 合入到 cann/runtime： master

【PR】: 增加UVM内存申请用例readme #3962

已合并

hnn___36创建于 7月30日

从hnn___36/runtime_7962 master合入到cann/runtime master

共 5 个文件变更+100-34

Mdocs/zh/api_ref/11-05_unified_addressing.md+6-6

	@@ -25,7 +25,7 @@ aclError aclrtMemAllocManaged(void **ptr, uint64_t size, uint32_t flag)
25	- Ascend 950PR/Ascend 950DT：不支持	25	- Ascend 950PR/Ascend 950DT：不支持
26	<!-- end id3214 -->	26	<!-- end id3214 -->
27	<!-- npu="A3" id3215 -->	27	<!-- npu="A3" id3215 -->
28	-- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持	28	+- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
29	<!-- end id3215 -->	29	<!-- end id3215 -->
30	<!-- npu="910b" id3216 -->	30	<!-- npu="910b" id3216 -->
31	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持	31	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
	@@ -84,7 +84,7 @@ aclError aclrtMemManagedAdvise(const void *const ptr, uint64_t size, aclrtMemMan
84	- Ascend 950PR/Ascend 950DT：不支持	84	- Ascend 950PR/Ascend 950DT：不支持
85	<!-- end id2150 -->	85	<!-- end id2150 -->
86	<!-- npu="A3" id2151 -->	86	<!-- npu="A3" id2151 -->
87	-- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持	87	+- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
88	<!-- end id2151 -->	88	<!-- end id2151 -->
89	<!-- npu="910b" id2152 -->	89	<!-- npu="910b" id2152 -->
90	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持	90	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
	@@ -140,7 +140,7 @@ aclError aclrtMemManagedGetAttr(aclrtMemManagedRangeAttribute attribute, const v
140	- Ascend 950PR/Ascend 950DT：不支持	140	- Ascend 950PR/Ascend 950DT：不支持
141	<!-- end id1688 -->	141	<!-- end id1688 -->
142	<!-- npu="A3" id1689 -->	142	<!-- npu="A3" id1689 -->
143	-- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持	143	+- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
144	<!-- end id1689 -->	144	<!-- end id1689 -->
145	<!-- npu="910b" id1690 -->	145	<!-- npu="910b" id1690 -->
146	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持	146	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
	@@ -199,7 +199,7 @@ aclError aclrtMemManagedGetAttrs(aclrtMemManagedRangeAttribute *attributes, size
199	- Ascend 950PR/Ascend 950DT：不支持	199	- Ascend 950PR/Ascend 950DT：不支持
200	<!-- end id2073 -->	200	<!-- end id2073 -->
201	<!-- npu="A3" id2074 -->	201	<!-- npu="A3" id2074 -->
202	-- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持	202	+- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
203	<!-- end id2074 -->	203	<!-- end id2074 -->
204	<!-- npu="910b" id2075 -->	204	<!-- npu="910b" id2075 -->
205	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持	205	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
	@@ -259,7 +259,7 @@ aclError aclrtMemManagedPrefetchAsync(const void* ptr, size_t size, aclrtMemMana
259	- Ascend 950PR/Ascend 950DT：不支持	259	- Ascend 950PR/Ascend 950DT：不支持
260	<!-- end id2136 -->	260	<!-- end id2136 -->
261	<!-- npu="A3" id2137 -->	261	<!-- npu="A3" id2137 -->
262	-- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持	262	+- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
263	<!-- end id2137 -->	263	<!-- end id2137 -->
264	<!-- npu="910b" id2138 -->	264	<!-- npu="910b" id2138 -->
265	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持	265	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
	@@ -316,7 +316,7 @@ aclError aclrtMemManagedPrefetchBatchAsync(const void** ptrs, size_t* sizes, siz
316	- Ascend 950PR/Ascend 950DT：不支持	316	- Ascend 950PR/Ascend 950DT：不支持
317	<!-- end id2339 -->	317	<!-- end id2339 -->
318	<!-- npu="A3" id2340 -->	318	<!-- npu="A3" id2340 -->
319	-- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持	319	+- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
320	<!-- end id2340 -->	320	<!-- end id2340 -->
321	<!-- npu="910b" id2341 -->	321	<!-- npu="910b" id2341 -->
322	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持	322	- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

Mexample/3_memory_advanced/managed_memory/0_uvm_allocate/README.md+7-10

	@@ -2,7 +2,7 @@
2		2
3	## 描述	3	## 描述
4		4
5	-本样例基于UVM（Unified Virtual Memory）统一虚拟内存机制，通过UVM内存申请接口为算子输入、输出分配内存，消除了算子参数追加和结果写回过程中的显式数据搬运。覆盖UVM类型内存申请、二进制加载、核函数句柄获取、参数组装、任务下发、Stream 同步和结果校验。运行后会生成输入数据、执行 Kernel，并校验输出结果。	5	+本样例基于UVM（Unified Virtual Memory）统一虚拟内存机制，通过UVM内存申请接口为算子输入、输出分配内存，消除了算子参数追加和结果回写过程中的显式数据搬运。覆盖UVM类型内存申请、二进制加载、核函数句柄获取、参数组装、任务下发、Stream 同步和结果校验。运行该样例后会生成算子输入数据、执行算子，并校验算子输出结果。
6		6
7	## 产品支持情况	7	## 产品支持情况
8		8
	@@ -10,12 +10,15 @@
10		10
11	\| 产品 \| 是否支持 \|	11	\| 产品 \| 是否支持 \|
12	\| --- \| --- \|	12	\| --- \| --- \|
		13	+\| Ascend 950PR/Ascend 950DT \| × \|
13	\| Atlas A3 训练系列产品/Atlas A3 推理系列产品 \| √ \|	14	\| Atlas A3 训练系列产品/Atlas A3 推理系列产品 \| √ \|
		Y Y ycm00287月30日 950是否支持呢？我看其他样例，都写了3款产品。另外，UVM的接口，只有A2支持，为啥这个样例A3也支持？ hnn___36 26 天前评论： 26 天前评论：
14	\| Atlas A2 训练系列产品/Atlas A2 推理系列产品 \| √ \|	15	\| Atlas A2 训练系列产品/Atlas A2 推理系列产品 \| √ \|
15		16
		17	+
16	## 编译运行	18	## 编译运行
17		19
18	1. 下载样例代码至安装 CANN 软件的环境，切换到样例目录。	20	1. 下载样例代码至安装 CANN 软件的环境，切换到样例目录。
		21	+
19	```bash	22	```bash
20	cd ${git_clone_path}/example/3_memory_advanced/managed_memory/0_uvm_allocate	23	cd ${git_clone_path}/example/3_memory_advanced/managed_memory/0_uvm_allocate
21	```	24	```
	@@ -25,18 +28,12 @@ cd ${git_clone_path}/example/3_memory_advanced/managed_memory/0_uvm_allocate
25	```bash	28	```bash
26	# ${install_root} 替换为 CANN 安装根目录，默认安装在 /usr/local/Ascend 目录	29	# ${install_root} 替换为 CANN 安装根目录，默认安装在 /usr/local/Ascend 目录
27	source ${install_root}/cann/set_env.sh	30	source ${install_root}/cann/set_env.sh
28	-export ASCEND_INSTALL_PATH=${install_root}/cann
29		31
30	-# ${ascend_name} 替换为昇腾 AI 处理器型号，可通过 npu-smi info 查看 Name 字段并去掉空格获得	32	+# 自动识别 SOC_VERSION 和 ASCENDC_CMAKE_DIR
31	-export SOC_VERSION=${ascend_name}	33	+source ${git_clone_path}/example/set_sample_env.sh
32	-
33	-# ${cmake_path} 替换为 ascendc.cmake 所在目录，例如 ${install_root}/cann/aarch64-linux/tikcpp/ascendc_kernel_cmake
34	-export ASCENDC_CMAKE_DIR=${cmake_path}
35	```	34	```
36		35
37	-如果未提前设置环境变量，`run.sh` 会自动尝试探测 `ASCEND_INSTALL_PATH`、`ASCEND_HOME_PATH`、`$HOME/Ascend/cann`、`/usr/local/Ascend/cann`、`/opt/Ascend/cann`、`SOC_VERSION` 和 `ASCENDC_CMAKE_DIR`；如果自动探测失败，请按上述命令手动设置。	36	+本样例的数据生成与结果校验依赖 `numpy`，执行 `run.sh` 前请确保 Python 环境已安装 `numpy`。依赖numpy版本 >= 1.19.0。
38	-
39	-本样例的数据生成与结果校验依赖 `numpy`，执行 `run.sh` 前请确保 Python 环境已安装 `numpy`。
40		37
41	3. 执行以下命令运行样例。	38	3. 执行以下命令运行样例。
42		39

Aexample/3_memory_advanced/managed_memory/0_uvm_allocate/README_en.md+83-0

@@ -0,0 +1,83 @@
	1	+# 0_uvm_allocate
	2	+
	3	+## Description
	4	+
	5	+This sample uses the UVM (Unified Virtual Memory) mechanism and allocates memory for Kernel inputs and outputs through the UVM memory allocation interface, eliminating explicit data transfer during Kernel parameter appending and result writing back. The sample covers UVM-type memory allocation, binary loading, kernel function handle retrieval, parameter assembly, task dispatch, Stream synchronization, and result verification. After running this sample, Kernel input data is generated, Kernel is executed, and Kernel output result is verified.
	6	+
	7	+## Product Support
	8	+
	9	+This sample supports the following products:
	10	+
	11	+\| Product \| Supported \|
	12	+\| --- \| --- \|
	13	+\| Ascend 950PR/Ascend 950DT \| No \|
	14	+\| Atlas A3 training series products/Atlas A3 inference series products \| Yes \|
	15	+\| Atlas A2 training series products/Atlas A2 inference series products \| Yes \|
	16	+
	17	+## Build and Run
	18	+
	19	+1. Download sample code to environment with CANN software installed, switch to sample directory.
	20	+
	21	+```bash
	22	+cd ${git_clone_path}/example/3_memory_advanced/managed_memory/0_uvm_allocate
	23	+```
	24	+
	25	+2. Set environment variables.
	26	+
	27	+```bash
	28	+# Replace ${install_root} with CANN installation root directory, default installation at /usr/local/Ascend
	29	+source ${install_root}/cann/set_env.sh
	30	+
	31	+# Automatically identify SOC_VERSION and ASCENDC_CMAKE_DIR.
	32	+source ${git_clone_path}/example/set_sample_env.sh
	33	+
	34	+
	35	+```
	36	+
	37	+This sample data generation and result verification depends on `numpy`. Ensure Python environment has `numpy` installed before executing `run.sh`. The `numpy` version of 1.19.0 or higher is required.
	38	+
	39	+3. Run the following command to execute the sample.
	40	+
	41	+```bash
	42	+# mode can be simple or placeholder; defaults to simple if not specified
	atomgit-bot7月30日 🟡 Medium Priority changed line → affected behavior/contract → failure mode → suggested fix 新增的 `README_en.md` 第 41 行有一条注释 `# mode can be simple or placeholder; defaults to simple if not specified`，该注释是从 `example/2_advanced_features/kernel/0_launch_kernel/README_en.md` 复制粘贴而来，并不适用于本样例。证据链：本样例的 `run.sh` 第 60 行硬编码 `RUN_MODE="simple"`，没有 `-r` 参数解析逻辑； `main.cpp` 第 110 行只加载 `ascendc_kernels_simple.o`，不存在 placeholder 变体； `scripts/gen_data.py` 只有 `gen_golden_data_simple()` 函数；对比参考样例 `0_launch_kernel`：其 `run.sh` 解析 `-r` 参数并校验 `simple`/`placeholder`，`main.cpp` 也接受 mode 参数。失败模式：用户看到该注释后可能尝试 `bash run.sh -r placeholder`，由于 `run.sh` 不解析命令行参数，该参数被静默忽略，用户会误以为运行在 placeholder 模式下，实际运行的仍是 simple 模式，导致认知偏差和调试困难。中文版 `README.md` 正确地去掉了这条注释，英文版应与之保持一致。建议：删除该行注释，使英文版与中文版 README.md 保持一致（中文版没有这条注释，因为本样例确实不支持 mode 选择）。
	43	+bash run.sh
	44	+```
	45	+
	46	+## CANN RUNTIME API
	47	+
	48	+Key features and interfaces in this sample:
	49	+
	50	+- Initialization
	51	+ - Call `aclInit` interface to initialize configuration.
	52	+ - Call `aclFinalize` interface to deinitialize.
	53	+- Device Management
	54	+ - Call `aclrtSetDevice` interface to specify Device for computation.
	55	+ - Call `aclrtResetDeviceForce` interface to forcibly reset current computation Device and reclaim Device resources.
	56	+- Stream Management
	57	+ - Call `aclrtCreateStream` interface to create Stream.
	58	+ - Call `aclrtSynchronizeStream` interface to block waiting for Stream task execution completion.
	59	+ - Call `aclrtDestroyStreamForce` interface to forcibly destroy Stream.
	60	+- Memory Management
	61	+ - Call `aclrtMemAllocManaged` interface to allocate UVM-type memory.
	62	+ - Call `aclrtFree` interface to release UVM-type memory.
	63	+- Kernel Loading and Execution
	64	+ - Call `aclrtBinaryLoadFromFile` interface to load and parse operator binary file from file.
	65	+ - Call `aclrtBinaryGetFunction` interface to get kernel function handle.
	66	+ - Call `aclrtKernelArgsInit` interface to initialize parameter list based on kernel function handle.
	67	+ - Call `aclrtKernelArgsAppend` interface to append parameters to parameter list.
	68	+ - Call `aclrtKernelArgsFinalize` interface to mark parameter assembly complete.
	69	+ - Call `aclrtLaunchKernelWithConfig` interface to dispatch Kernel computation task.
	70	+ - Call `aclrtBinaryUnLoad` interface to unload operator binary file.
	71	+
	72	+## Sample Output
	73	+
	74	+```text
	75	+Configuring CMake...
	76	+Building...
	77	+...
	78	+[INFO] Run the uvm_allocate sample successfully.
	79	+... output/output_z.bin
	80	+... output/golden.bin
	81	+error ratio: 0.0000, tolerance: 0.0010
	82	+[SUCCESS] result correct
	83	+```

Mexample/3_memory_advanced/managed_memory/README.md+2-9

	@@ -2,13 +2,6 @@
2		2
3	本目录聚焦托管内存、统一寻址或更高级内存抽象的学习主题。	3	本目录聚焦托管内存、统一寻址或更高级内存抽象的学习主题。
4		4
5	-## 建议关注	5	+## 样例列表
6		6
7	-- 托管内存使用方式与限制。	7	+- [0_uvm_allocate](./0_uvm_allocate/README.md)：演示统一虚拟内存的申请。
8	-- 与显式拷贝模型之间的差异。
9	-- 内存可见性、迁移和访问开销。
10	-
11	-## 可选参考
12	-
13	-- [../../1_basic_features/memory/](../../1_basic_features/memory/)：显式内存管理基础。
14	-- [../allocator/README.md](../allocator/README.md)：高级内存封装方式。

Mexample/3_memory_advanced/managed_memory/README_en.md+2-9

	@@ -2,13 +2,6 @@
2		2
3	This directory focuses on learning topics about managed memory, unified addressing, and higher-level memory abstractions.	3	This directory focuses on learning topics about managed memory, unified addressing, and higher-level memory abstractions.
4		4
5	-## Key Points	5	+## Sample List
6		6
7	-- Usage and limitations of managed memory.	7	+- [0_uvm_allocate](./0_uvm_allocate/README_en.md)：Allocation of unified virtual memory.
8	-- Differences from the explicit copy model.
9	-- Memory visibility, migration, and access overhead.
10	-
11	-## Prerequisites
12	-
13	-- [../../1_basic_features/memory/](../../1_basic_features/memory/README_en.md): Explicit memory management basics.
14	-- [../allocator/README_en.md](../allocator/README_en.md): Advanced memory encapsulation methods.