docs(cndrv): ResourcesWapper 改为 RawContainer，更新文档准备发布

Signed-off-by: YdrMaster <ydrml@hotmail.com>
InfiniTensor · Jun 20, 2024 · 9063603 · 9063603
1 parent dfcea11
commit 9063603
Show file tree

Hide file tree

Showing 9 changed files with 54 additions and 48 deletions.
diff --git a/cndrv/Cargo.toml b/cndrv/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "cndrv"
 description = "Safe Cambricon driver API."
-version = "0.1.0"
+version = "0.0.0"
 edition = "2021"
 authors = ["YdrMaster <ydrml@hotmail.com>"]
 repository = "https://github.com/YdrMaster/cndrv.git"

diff --git a/cndrv/README.md b/cndrv/README.md
@@ -1 +1,8 @@
 # cndrv
+
+[![CI](https://github.com/YdrMaster/cndrv/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/YdrMaster/cndrv/actions)
+[![Latest version](https://img.shields.io/crates/v/cndrv.svg)](https://crates.io/crates/cndrv)
+[![Documentation](https://docs.rs/cndrv/badge.svg)](https://docs.rs/cndrv)
+[![license](https://img.shields.io/github/license/YdrMaster/cndrv)](https://mit-license.org/)
+
+Safe Cambricon driver API bindings based on CNDrv 2.7.1, see the [official documentation](https://www.cambricon.com/docs/sdk_1.15.0/cntoolkit_3.7.2/cndrv_2.7.1/index.html) for details.
diff --git a/cndrv/src/cnrtc/module.rs b/cndrv/src/cnrtc/module.rs
@@ -8,21 +8,21 @@ impl ContextGuard<'_> {
     pub fn load(&self, bin: CnrtcBinary) -> Module {
         let mut module = null_mut();
         cndrv!(cnModuleLoadFatBinary(bin.as_ptr(), &mut module));
-        Module(unsafe { self.wrap_resource(module) }, PhantomData)
+        Module(unsafe { self.wrap_raw(module) }, PhantomData)
     }
 }
 
 impl Drop for Module<'_> {
     #[inline]
     fn drop(&mut self) {
-        cndrv!(cnModuleUnload(self.0.res));
+        cndrv!(cnModuleUnload(self.0.raw));
     }
 }
 
 impl AsRaw for Module<'_> {
     type Raw = CNmodule;
     #[inline]
     unsafe fn as_raw(&self) -> Self::Raw {
-        self.0.res
+        self.0.raw
     }
 }
diff --git a/cndrv/src/context.rs b/cndrv/src/context.rs
@@ -1,4 +1,4 @@
-use crate::{bindings as cn, AsRaw, Device, ResourceWrapper};
+use crate::{bindings as cn, AsRaw, Device, RawContainer};
 use std::{ffi::c_uint, marker::PhantomData, ptr::null_mut};
 
 #[derive(PartialEq, Eq, Hash, Debug)]
@@ -123,9 +123,14 @@ impl ContextGuard<'_> {
         cndrv!(cnCtxSync());
     }
 
+    /// Wrap a raw object in a `RawContainer`.
+    ///
+    /// # Safety
+    ///
+    /// The raw object must be created in this [`Context`].
     #[inline]
-    pub unsafe fn wrap_resource<T>(&self, res: T) -> ResourceWrapper<T> {
-        ResourceWrapper { ctx: self.0, res }
+    pub unsafe fn wrap_raw<T>(&self, raw: T) -> RawContainer<T> {
+        RawContainer { ctx: self.0, raw }
     }
 }
 

diff --git a/cndrv/src/lib.rs b/cndrv/src/lib.rs
@@ -1,4 +1,6 @@
-#![cfg(detected_neuware)]
+#![doc = include_str!("../README.md")]
+#![cfg(detected_neuware)]
+#![deny(warnings)]
 
 #[macro_use]
 #[allow(unused, non_upper_case_globals, non_camel_case_types, non_snake_case)]
@@ -85,7 +87,7 @@ pub use device::Device;
 pub use memory::{memcpy_d2d, memcpy_d2h, memcpy_h2d, DevByte, DevMem, DevMemSpore};
 pub use notifier::{Notifier, NotifierSpore};
 pub use queue::{Queue, QueueSpore};
-pub use spore::{ContextResource, ContextSpore, ResourceWrapper};
+pub use spore::{ContextResource, ContextSpore, RawContainer};
 pub use version::{driver_version, library_version, Version};
 
 struct Blob<P> {

diff --git a/cndrv/src/memory.rs b/cndrv/src/memory.rs
@@ -69,10 +69,7 @@ impl ContextGuard<'_> {
         let len = Layout::array::<T>(len).unwrap().size();
         let mut ptr = 0;
         cndrv!(cnMalloc(&mut ptr, len as _));
-        DevMem(
-            unsafe { self.wrap_resource(Blob { ptr, len }) },
-            PhantomData,
-        )
+        DevMem(unsafe { self.wrap_raw(Blob { ptr, len }) }, PhantomData)
     }
 
     pub fn from_host<T: Copy>(&self, slice: &[T]) -> DevMem<'_> {
@@ -81,39 +78,36 @@ impl ContextGuard<'_> {
         let mut ptr = 0;
         cndrv!(cnMalloc(&mut ptr, len as _));
         cndrv!(cnMemcpyHtoD(ptr, src, len as _));
-        DevMem(
-            unsafe { self.wrap_resource(Blob { ptr, len }) },
-            PhantomData,
-        )
+        DevMem(unsafe { self.wrap_raw(Blob { ptr, len }) }, PhantomData)
     }
 }
 
 impl Drop for DevMem<'_> {
     #[inline]
     fn drop(&mut self) {
-        cndrv!(cnFree(self.0.res.ptr));
+        cndrv!(cnFree(self.0.raw.ptr));
     }
 }
 
 impl Deref for DevMem<'_> {
     type Target = [DevByte];
     #[inline]
     fn deref(&self) -> &Self::Target {
-        if self.0.res.len == 0 {
+        if self.0.raw.len == 0 {
             &[]
         } else {
-            unsafe { from_raw_parts(self.0.res.ptr as _, self.0.res.len) }
+            unsafe { from_raw_parts(self.0.raw.ptr as _, self.0.raw.len) }
         }
     }
 }
 
 impl DerefMut for DevMem<'_> {
     #[inline]
     fn deref_mut(&mut self) -> &mut Self::Target {
-        if self.0.res.len == 0 {
+        if self.0.raw.len == 0 {
             &mut []
         } else {
-            unsafe { from_raw_parts_mut(self.0.res.ptr as _, self.0.res.len) }
+            unsafe { from_raw_parts_mut(self.0.raw.ptr as _, self.0.raw.len) }
         }
     }
 }
@@ -122,19 +116,19 @@ impl AsRaw for DevMemSpore {
     type Raw = CNaddr;
     #[inline]
     unsafe fn as_raw(&self) -> Self::Raw {
-        self.0.res.ptr
+        self.0.raw.ptr
     }
 }
 
 impl DevMemSpore {
     #[inline]
     pub const fn len(&self) -> usize {
-        self.0.res.len
+        self.0.raw.len
     }
 
     #[inline]
     pub const fn is_empty(&self) -> bool {
-        self.0.res.len == 0
+        self.0.raw.len == 0
     }
 }
 
@@ -145,25 +139,22 @@ impl<'ctx> ContextGuard<'ctx> {
         let len = Layout::array::<T>(len).unwrap().size();
         let mut ptr = null_mut();
         cndrv!(cnMallocHost(&mut ptr, len as _));
-        HostMem(
-            unsafe { self.wrap_resource(Blob { ptr, len }) },
-            PhantomData,
-        )
+        HostMem(unsafe { self.wrap_raw(Blob { ptr, len }) }, PhantomData)
     }
 }
 
 impl Drop for HostMem<'_> {
     #[inline]
     fn drop(&mut self) {
-        cndrv!(cnFreeHost(self.0.res.ptr));
+        cndrv!(cnFreeHost(self.0.raw.ptr));
     }
 }
 
 impl AsRaw for HostMem<'_> {
     type Raw = *mut c_void;
     #[inline]
     unsafe fn as_raw(&self) -> Self::Raw {
-        self.0.res.ptr
+        self.0.raw.ptr
     }
 }
 
@@ -172,14 +163,14 @@ impl Deref for HostMem<'_> {
 
     #[inline]
     fn deref(&self) -> &Self::Target {
-        unsafe { from_raw_parts(self.0.res.ptr.cast(), self.0.res.len) }
+        unsafe { from_raw_parts(self.0.raw.ptr.cast(), self.0.raw.len) }
     }
 }
 
 impl DerefMut for HostMem<'_> {
     #[inline]
     fn deref_mut(&mut self) -> &mut Self::Target {
-        unsafe { from_raw_parts_mut(self.0.res.ptr.cast(), self.0.res.len) }
+        unsafe { from_raw_parts_mut(self.0.raw.ptr.cast(), self.0.raw.len) }
     }
 }
 
@@ -188,14 +179,14 @@ impl Deref for HostMemSpore {
 
     #[inline]
     fn deref(&self) -> &Self::Target {
-        unsafe { from_raw_parts(self.0.res.ptr.cast(), self.0.res.len) }
+        unsafe { from_raw_parts(self.0.raw.ptr.cast(), self.0.raw.len) }
     }
 }
 
 impl DerefMut for HostMemSpore {
     #[inline]
     fn deref_mut(&mut self) -> &mut Self::Target {
-        unsafe { from_raw_parts_mut(self.0.res.ptr.cast(), self.0.res.len) }
+        unsafe { from_raw_parts_mut(self.0.raw.ptr.cast(), self.0.raw.len) }
     }
 }
 

diff --git a/cndrv/src/notifier.rs b/cndrv/src/notifier.rs
@@ -11,22 +11,22 @@ impl<'ctx> Queue<'ctx> {
             CNNotifierFlags::CN_NOTIFIER_DEFAULT as _
         ));
         cndrv!(cnPlaceNotifier(event, self.as_raw()));
-        Notifier(unsafe { self.ctx().wrap_resource(event) }, PhantomData)
+        Notifier(unsafe { self.ctx().wrap_raw(event) }, PhantomData)
     }
 }
 
 impl Drop for Notifier<'_> {
     #[inline]
     fn drop(&mut self) {
-        cndrv!(cnDestroyNotifier(self.0.res));
+        cndrv!(cnDestroyNotifier(self.0.raw));
     }
 }
 
 impl AsRaw for Notifier<'_> {
     type Raw = CNnotifier;
     #[inline]
     unsafe fn as_raw(&self) -> Self::Raw {
-        self.0.res
+        self.0.raw
     }
 }
 
@@ -48,13 +48,13 @@ impl Queue<'_> {
 impl Notifier<'_> {
     #[inline]
     pub fn synchronize(&self) {
-        cndrv!(cnWaitNotifier(self.0.res));
+        cndrv!(cnWaitNotifier(self.0.raw));
     }
 
     #[inline]
     pub fn elapse_from(&self, start: &Self) -> Duration {
         let mut ms = 0.0;
-        cndrv!(cnNotifierElapsedTime(&mut ms, start.0.res, self.0.res));
+        cndrv!(cnNotifierElapsedTime(&mut ms, start.0.raw, self.0.raw));
         Duration::from_secs_f32(ms * 1e-3)
     }
 }
diff --git a/cndrv/src/queue.rs b/cndrv/src/queue.rs
@@ -8,30 +8,30 @@ impl ContextGuard<'_> {
     pub fn queue(&self) -> Queue {
         let mut queue = null_mut();
         cndrv!(cnCreateQueue(&mut queue, 0));
-        Queue(unsafe { self.wrap_resource(queue) }, PhantomData)
+        Queue(unsafe { self.wrap_raw(queue) }, PhantomData)
     }
 }
 
 impl Drop for Queue<'_> {
     #[inline]
     fn drop(&mut self) {
         self.synchronize();
-        cndrv!(cnDestroyQueue(self.0.res));
+        cndrv!(cnDestroyQueue(self.0.raw));
     }
 }
 
 impl AsRaw for Queue<'_> {
     type Raw = CNqueue;
     #[inline]
     unsafe fn as_raw(&self) -> Self::Raw {
-        self.0.res
+        self.0.raw
     }
 }
 
 impl Queue<'_> {
     #[inline]
     pub fn synchronize(&self) {
-        cndrv!(cnQueueSync(self.0.res));
+        cndrv!(cnQueueSync(self.0.raw));
     }
 }
 

diff --git a/cndrv/src/spore.rs b/cndrv/src/spore.rs
@@ -28,21 +28,22 @@ macro_rules! spore_convention {
     };
 }
 
-pub struct ResourceWrapper<T> {
+pub struct RawContainer<T> {
     pub ctx: CNcontext,
-    pub res: T,
+    pub raw: T,
 }
 
 #[macro_export]
 macro_rules! impl_spore {
     ($resource:ident and $spore:ident by $kernel:ty) => {
+        #[repr(transparent)]
         pub struct $resource<'ctx>(
-            $crate::ResourceWrapper<$kernel>,
+            $crate::RawContainer<$kernel>,
             std::marker::PhantomData<&'ctx ()>,
         );
 
         #[repr(transparent)]
-        pub struct $spore($crate::ResourceWrapper<$kernel>);
+        pub struct $spore($crate::RawContainer<$kernel>);
 
         $crate::spore_convention!($spore);