cann_sys/acl_meta.rs
1//! ACL 张量/标量等 aclnn 基础类型绑定。
2//!
3//! 对应 CANN 头文件 `include/aclnn/acl_meta.h`(CANN 8.5.0)。
4//! 提供不透明句柄类型(`aclTensor`/`aclScalar`/`aclTensorList`/`aclIntArray`/
5//! `aclFloatArray`/`aclBoolArray`)、`aclnnStatus` 返回码类型,以及这些类型的
6//! 生命周期/创建/访问器 FFI 声明(全部为 `extern "C"` 链接,签名按本地 SDK 8.5.0
7//! 头文件逐项核对,未核对的函数不在此列)。
8
9use std::ffi::c_int;
10use std::ffi::c_void;
11
12/// aclnn 算子返回码。
13///
14/// 对应 C 类型 `int32_t`(acl_meta.h `typedef int32_t aclnnStatus;`)。
15/// 0(C 常量 `OK`)表示成功,非 0 为具体错误码。
16#[allow(non_camel_case_types)]
17pub type aclnnStatus = c_int;
18
19/// aclnn 张量句柄(不透明类型)。
20///
21/// 对应 acl_meta.h `typedef struct aclTensor aclTensor;`。
22#[allow(non_camel_case_types)]
23pub type aclTensor = c_void;
24
25/// aclnn 标量句柄(不透明类型)。
26///
27/// 对应 acl_meta.h `typedef struct aclScalar aclScalar;`。
28#[allow(non_camel_case_types)]
29pub type aclScalar = c_void;
30
31/// aclnn 张量列表句柄(不透明类型)。
32///
33/// 对应 acl_meta.h `typedef struct aclTensorList aclTensorList;`。
34#[allow(non_camel_case_types)]
35pub type aclTensorList = c_void;
36
37/// aclnn 整数数组句柄(不透明类型)。
38///
39/// 对应 acl_meta.h `typedef struct aclIntArray aclIntArray;`。
40#[allow(non_camel_case_types)]
41pub type aclIntArray = c_void;
42
43/// aclnn 浮点数组句柄(不透明类型)。
44///
45/// 对应 acl_meta.h `typedef struct aclFloatArray aclFloatArray;`。
46#[allow(non_camel_case_types)]
47pub type aclFloatArray = c_void;
48
49/// aclnn 布尔数组句柄(不透明类型)。
50///
51/// 对应 acl_meta.h `typedef struct aclBoolArray aclBoolArray;`。
52#[allow(non_camel_case_types)]
53pub type aclBoolArray = c_void;
54
55#[cfg(cann_sys_ffi)]
56use crate::acl_datatype::{aclDataType, aclFormat};
57
58// `libascendcl` aclnn 基础类型 FFI 声明(acl_meta.h,均为 `extern "C"`),仅在启用 `ffi` 特性时编译。
59// 签名已按本地 CANN 8.5.0 头文件逐项核对;不透明句柄一律以 `c_void` 指针表示。
60#[cfg(cann_sys_ffi)]
61unsafe extern "C" {
62 /// C 函数原名:`aclCreateTensor`(acl_meta.h)。
63 ///
64 /// 基于视图维度、步长、视图偏移、存储维度与数据地址创建一个 aclnn 张量句柄。
65 ///
66 /// # 参数
67 /// - `viewDims`:视图维度数组,长度 `viewDimsNum`。
68 /// - `viewDimsNum`:视图维度个数。
69 /// - `dataType`:张量数据类型,取 `aclDataType` 常量。
70 /// - `stride`:视图各维步长数组,长度 `viewDimsNum`。
71 /// - `offset`:视图相对存储首地址的偏移(元素个数)。
72 /// - `format`:张量内存布局格式,取 `aclFormat` 常量。
73 /// - `storageDims`:存储维度数组,长度 `storageDimsNum`;可传 NULL(与视图同形)。
74 /// - `storageDimsNum`:存储维度个数。
75 /// - `tensorData`:张量数据所在内存地址(通常为设备内存)。
76 ///
77 /// # Safety
78 /// - `viewDims`/`stride` 必须指向长度至少 `viewDimsNum` 的合法 `i64` 数组。
79 /// - `storageDims` 非 NULL 时必须指向长度至少 `storageDimsNum` 的合法 `i64` 数组。
80 /// - `tensorData` 指向的内存必须足以容纳 `storageDims` 所描述的数据(或传 NULL)。
81 /// - 返回的句柄必须由 `aclDestroyTensor` 释放,且只能释放一次。
82 pub fn aclCreateTensor(
83 viewDims: *const i64,
84 viewDimsNum: u64,
85 dataType: aclDataType,
86 stride: *const i64,
87 offset: i64,
88 format: aclFormat,
89 storageDims: *const i64,
90 storageDimsNum: u64,
91 tensorData: *mut c_void,
92 ) -> *mut c_void;
93
94 /// C 函数原名:`aclCreateScalar`(acl_meta.h)。
95 ///
96 /// 以指定数据类型的值创建 aclnn 标量句柄。
97 ///
98 /// # 参数
99 /// - `value`:指向标量值的指针(按 `dataType` 解释)。
100 /// - `dataType`:标量数据类型,取 `aclDataType` 常量。
101 ///
102 /// # Safety
103 /// - `value` 必须指向与 `dataType` 尺寸一致的合法内存(如 `ACL_INT32` 对应 `i32`)。
104 /// - 返回的句柄必须由 `aclDestroyScalar` 释放,且只能释放一次。
105 pub fn aclCreateScalar(value: *mut c_void, dataType: aclDataType) -> *mut c_void;
106
107 /// C 函数原名:`aclCreateTensorList`(acl_meta.h)。
108 ///
109 /// 以 `size` 个张量句柄创建 aclnn 张量列表句柄。
110 ///
111 /// # 参数
112 /// - `value`:指向 `size` 个 `aclTensor` 指针的数组(元素可含 NULL)。
113 /// - `size`:张量个数。
114 ///
115 /// # Safety
116 /// - `value` 必须指向长度至少 `size` 的合法指针数组。
117 /// - 返回的句柄必须由 `aclDestroyTensorList` 释放,且只能释放一次。
118 pub fn aclCreateTensorList(value: *const *const c_void, size: u64) -> *mut c_void;
119
120 /// C 函数原名:`aclCreateIntArray`(acl_meta.h)。
121 ///
122 /// 以 `size` 个 `int64_t` 值创建 aclnn 整数数组句柄。
123 ///
124 /// # 参数
125 /// - `value`:指向 `size` 个 `int64_t` 值的数组。
126 /// - `size`:元素个数。
127 ///
128 /// # Safety
129 /// - `value` 必须指向长度至少 `size` 的合法 `i64` 数组。
130 /// - 返回的句柄必须由 `aclDestroyIntArray` 释放(属同一家族,见 acl_meta.h 生命周期函数)。
131 pub fn aclCreateIntArray(value: *const i64, size: u64) -> *mut c_void;
132
133 /// C 函数原名:`aclCreateFloatArray`(acl_meta.h)。
134 ///
135 /// 以 `size` 个 `float` 值创建 aclnn 浮点数组句柄。
136 ///
137 /// # 参数
138 /// - `value`:指向 `size` 个 `float` 值的数组。
139 /// - `size`:元素个数。
140 ///
141 /// # Safety
142 /// - `value` 必须指向长度至少 `size` 的合法 `f32` 数组。
143 pub fn aclCreateFloatArray(value: *const f32, size: u64) -> *mut c_void;
144
145 /// C 函数原名:`aclCreateBoolArray`(acl_meta.h)。
146 ///
147 /// 以 `size` 个 `bool` 值创建 aclnn 布尔数组句柄。
148 ///
149 /// # 参数
150 /// - `value`:指向 `size` 个 `bool` 值的数组。
151 /// - `size`:元素个数。
152 ///
153 /// # Safety
154 /// - `value` 必须指向长度至少 `size` 的合法 `bool` 数组,且每个元素为合法布尔值(0 或 1)。
155 pub fn aclCreateBoolArray(value: *const bool, size: u64) -> *mut c_void;
156
157 /// C 函数原名:`aclDestroyTensor`(acl_meta.h)。
158 ///
159 /// 释放 `aclCreateTensor` 创建的张量句柄。
160 ///
161 /// # 参数
162 /// - `tensor`:待释放的张量句柄。
163 ///
164 /// # Safety
165 /// - `tensor` 必须由 `aclCreateTensor` 返回且尚未释放(或为 NULL)。
166 /// - 重复释放同一句柄、或释放非 `aclCreateTensor` 返回的指针,行为未定义。
167 pub fn aclDestroyTensor(tensor: *const c_void) -> aclnnStatus;
168
169 /// C 函数原名:`aclDestroyTensorList`(acl_meta.h)。
170 ///
171 /// 释放 `aclCreateTensorList` 创建的张量列表句柄。
172 ///
173 /// # 参数
174 /// - `array`:待释放的张量列表句柄。
175 ///
176 /// # Safety
177 /// - `array` 必须由 `aclCreateTensorList` 返回且尚未释放(或为 NULL)。
178 pub fn aclDestroyTensorList(array: *const c_void) -> aclnnStatus;
179
180 /// C 函数原名:`aclDestroyScalar`(acl_meta.h)。
181 ///
182 /// 释放 `aclCreateScalar` 创建的标量句柄。
183 ///
184 /// # 参数
185 /// - `scalar`:待释放的标量句柄。
186 ///
187 /// # Safety
188 /// - `scalar` 必须由 `aclCreateScalar` 返回且尚未释放(或为 NULL)。
189 pub fn aclDestroyScalar(scalar: *const c_void) -> aclnnStatus;
190
191 /// C 函数原名:`aclGetViewShape`(acl_meta.h)。
192 ///
193 /// 查询张量视图维度。
194 ///
195 /// # 参数
196 /// - `tensor`:目标张量句柄。
197 /// - `viewDims`:输出参数,接收指向视图维度数组的指针(归张量所有)。
198 /// - `viewDimsNum`:输出参数,接收维度个数。
199 ///
200 /// # Safety
201 /// - `tensor` 必须为 `aclCreateTensor` 返回且尚未释放的句柄。
202 /// - `viewDims`/`viewDimsNum` 必须指向有效的输出变量。
203 /// - 返回的 `*viewDims` 内存归张量所有:不得释放,且在 `aclDestroyTensor` 后失效。
204 pub fn aclGetViewShape(
205 tensor: *const c_void,
206 viewDims: *mut *mut i64,
207 viewDimsNum: *mut u64,
208 ) -> aclnnStatus;
209
210 /// C 函数原名:`aclGetStorageShape`(acl_meta.h)。
211 ///
212 /// 查询张量存储维度。
213 ///
214 /// # 参数
215 /// - `tensor`:目标张量句柄。
216 /// - `storageDims`:输出参数,接收指向存储维度数组的指针(归张量所有)。
217 /// - `storageDimsNum`:输出参数,接收存储维度个数。
218 ///
219 /// # Safety
220 /// - `tensor` 必须为 `aclCreateTensor` 返回且尚未释放的句柄。
221 /// - `storageDims`/`storageDimsNum` 必须指向有效的输出变量。
222 /// - 返回的 `*storageDims` 内存归张量所有:不得释放,且在 `aclDestroyTensor` 后失效。
223 pub fn aclGetStorageShape(
224 tensor: *const c_void,
225 storageDims: *mut *mut i64,
226 storageDimsNum: *mut u64,
227 ) -> aclnnStatus;
228
229 /// C 函数原名:`aclGetViewStrides`(acl_meta.h)。
230 ///
231 /// 查询张量视图各维步长。
232 ///
233 /// # 参数
234 /// - `tensor`:目标张量句柄。
235 /// - `stridesValue`:输出参数,接收指向步长数组的指针(归张量所有)。
236 /// - `stridesNum`:输出参数,接收步长个数。
237 ///
238 /// # Safety
239 /// - `tensor` 必须为 `aclCreateTensor` 返回且尚未释放的句柄。
240 /// - `stridesValue`/`stridesNum` 必须指向有效的输出变量。
241 /// - 返回的 `*stridesValue` 内存归张量所有:不得释放,且在 `aclDestroyTensor` 后失效。
242 pub fn aclGetViewStrides(
243 tensor: *const c_void,
244 stridesValue: *mut *mut i64,
245 stridesNum: *mut u64,
246 ) -> aclnnStatus;
247
248 /// C 函数原名:`aclGetViewOffset`(acl_meta.h)。
249 ///
250 /// 查询张量视图相对存储首地址的偏移(元素个数)。
251 ///
252 /// # 参数
253 /// - `tensor`:目标张量句柄。
254 /// - `offset`:输出参数,接收偏移值。
255 ///
256 /// # Safety
257 /// - `tensor` 必须为 `aclCreateTensor` 返回且尚未释放的句柄。
258 /// - `offset` 必须指向有效的输出变量。
259 pub fn aclGetViewOffset(tensor: *const c_void, offset: *mut i64) -> aclnnStatus;
260
261 /// C 函数原名:`aclGetFormat`(acl_meta.h)。
262 ///
263 /// 查询张量内存布局格式。
264 ///
265 /// # 参数
266 /// - `tensor`:目标张量句柄。
267 /// - `format`:输出参数,接收格式值(`aclFormat`)。
268 ///
269 /// # Safety
270 /// - `tensor` 必须为 `aclCreateTensor` 返回且尚未释放的句柄。
271 /// - `format` 必须指向有效的输出变量。
272 pub fn aclGetFormat(tensor: *const c_void, format: *mut aclFormat) -> aclnnStatus;
273
274 /// C 函数原名:`aclGetDataType`(acl_meta.h)。
275 ///
276 /// 查询张量数据类型。
277 ///
278 /// # 参数
279 /// - `tensor`:目标张量句柄。
280 /// - `dataType`:输出参数,接收数据类型值(`aclDataType`)。
281 ///
282 /// # Safety
283 /// - `tensor` 必须为 `aclCreateTensor` 返回且尚未释放的句柄。
284 /// - `dataType` 必须指向有效的输出变量。
285 pub fn aclGetDataType(tensor: *const c_void, dataType: *mut aclDataType) -> aclnnStatus;
286
287 /// C 函数原名:`aclGetTensorListSize`(acl_meta.h)。
288 ///
289 /// 查询张量列表中的张量个数。
290 ///
291 /// # 参数
292 /// - `tensorList`:目标张量列表句柄。
293 /// - `size`:输出参数,接收张量个数。
294 ///
295 /// # Safety
296 /// - `tensorList` 必须为 `aclCreateTensorList` 返回且尚未释放的句柄。
297 /// - `size` 必须指向有效的输出变量。
298 pub fn aclGetTensorListSize(tensorList: *const c_void, size: *mut u64) -> aclnnStatus;
299}
300
301#[cfg(test)]
302mod tests {
303 use super::*;
304
305 /// 不透明句柄类型与 `c_void` 指针同尺寸(别名保持成立)。
306 #[test]
307 fn test_opaque_types_are_pointer_sized() {
308 assert_eq!(size_of::<*const aclTensor>(), size_of::<*const c_void>());
309 assert_eq!(size_of::<*const aclScalar>(), size_of::<*const c_void>());
310 assert_eq!(
311 size_of::<*const aclTensorList>(),
312 size_of::<*const c_void>()
313 );
314 assert_eq!(size_of::<*const aclIntArray>(), size_of::<*const c_void>());
315 assert_eq!(
316 size_of::<*const aclFloatArray>(),
317 size_of::<*const c_void>()
318 );
319 assert_eq!(size_of::<*const aclBoolArray>(), size_of::<*const c_void>());
320 }
321
322 /// `aclnnStatus` 与 C `int32_t` 同尺寸。
323 #[test]
324 fn test_aclnn_status_is_i32() {
325 assert_eq!(size_of::<aclnnStatus>(), size_of::<i32>());
326 }
327}
328
329// FFI 链接冒烟测试:仅在启用 `ffi` 特性且运行 `cargo test` 时编译。
330// 真实调用需要 NPU 驱动与已初始化的 ACL 环境,本机(无驱动)一律 `--ignored` 跳过,
331// 仅作编译期/链接期验证。
332#[cfg(all(cann_sys_ffi, test))]
333mod ffi_tests {
334 use super::*;
335 use crate::acl_datatype::{ACL_FLOAT, ACL_FORMAT_ND, ACL_INT32};
336
337 /// 链接冒烟:`aclCreateTensor` → `aclGetDataType` → `aclDestroyTensor` 往返。
338 #[test]
339 #[ignore = "requires NPU driver"]
340 fn create_get_destroy_tensor() {
341 let dims: [i64; 2] = [2, 2];
342 let strides: [i64; 2] = [2, 1];
343 let storage: [i64; 2] = [2, 2];
344 unsafe {
345 // SAFETY: dims/strides/storage 均为长度 2 的合法数组;tensorData 传 NULL(仅创建元数据)。
346 let tensor = aclCreateTensor(
347 dims.as_ptr(),
348 2,
349 ACL_FLOAT,
350 strides.as_ptr(),
351 0,
352 ACL_FORMAT_ND,
353 storage.as_ptr(),
354 2,
355 std::ptr::null_mut(),
356 );
357 let mut dt: aclDataType = -1;
358 // SAFETY: tensor 由上面的 aclCreateTensor 返回且尚未释放;dt 为有效输出变量。
359 let status = aclGetDataType(tensor, &mut dt);
360 assert_eq!(status, 0);
361 assert_eq!(dt, ACL_FLOAT);
362 // SAFETY: tensor 由上面的 aclCreateTensor 返回,且本测试内仅释放一次。
363 let status = aclDestroyTensor(tensor);
364 assert_eq!(status, 0);
365 }
366 }
367
368 /// 链接冒烟:`aclCreateScalar` → `aclDestroyScalar` 往返。
369 #[test]
370 #[ignore = "requires NPU driver"]
371 fn create_destroy_scalar() {
372 let mut value: i32 = 1;
373 unsafe {
374 // SAFETY: value 为合法的可写 i32 变量,内存布局与 ACL_INT32 一致。
375 let scalar = aclCreateScalar(std::ptr::addr_of_mut!(value).cast(), ACL_INT32);
376 // SAFETY: scalar 由上面的 aclCreateScalar 返回,且本测试内仅释放一次。
377 let status = aclDestroyScalar(scalar);
378 assert_eq!(status, 0);
379 }
380 }
381
382 /// 链接冒烟:`aclCreateTensorList` → `aclGetTensorListSize` → `aclDestroyTensorList` 往返。
383 #[test]
384 #[ignore = "requires NPU driver"]
385 fn create_get_destroy_tensor_list() {
386 let dims: [i64; 1] = [4];
387 let strides: [i64; 1] = [1];
388 let storage: [i64; 1] = [4];
389 unsafe {
390 // SAFETY: dims/strides/storage 均为长度 1 的合法数组;tensorData 传 NULL(仅创建元数据)。
391 let t1 = aclCreateTensor(
392 dims.as_ptr(),
393 1,
394 ACL_FLOAT,
395 strides.as_ptr(),
396 0,
397 ACL_FORMAT_ND,
398 storage.as_ptr(),
399 1,
400 std::ptr::null_mut(),
401 );
402 // SAFETY: t1 由上面的 aclCreateTensor 返回;指针数组长度为 1 且元素有效。
403 let tensor_ptr: *const c_void = t1;
404 let list = aclCreateTensorList(&tensor_ptr as *const *const c_void, 1);
405 let mut size: u64 = 0;
406 // SAFETY: list 由上面的 aclCreateTensorList 返回且尚未释放;size 为有效输出变量。
407 let status = aclGetTensorListSize(list, &mut size);
408 assert_eq!(status, 0);
409 assert_eq!(size, 1);
410 // SAFETY: list 由上面的 aclCreateTensorList 返回,且本测试内仅释放一次。
411 let status = aclDestroyTensorList(list);
412 assert_eq!(status, 0);
413 // SAFETY: t1 由上面的 aclCreateTensor 返回,且本测试内仅释放一次。
414 let status = aclDestroyTensor(t1);
415 assert_eq!(status, 0);
416 }
417 }
418}