Skip to main content

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}