enhance docs

Author: ehsanmok

README.md

@@ -1,22 +1,22 @@
 # TVM Runtime Frontend Support
 
-This crate provides idiomatic Rust API for [TVM](https://github.com/dmlc/tvm) runtime frontend as part of [ongoing RFC 1601](https://github.com/dmlc/tvm/issues/1601). Currently this requires **Nightly Rust**.
+This crate provides an idiomatic Rust API for [TVM](https://github.com/dmlc/tvm) runtime frontend as part of the [ongoing RFC](https://github.com/dmlc/tvm/issues/1601). Currently this requires **Nightly Rust**.
 
 Checkout the [docs](https://ehsanmok.github.io/tvm_frontend/tvm_frontend/index.html).
 
 ## What Does This Crate Offer?
 
 Here is a major workflow
 
-1. Train your **Deep Learning** model using any major framework [PyTorch](https://pytorch.org/), [Apache MXNet](https://mxnet.incubator.apache.org/) and [TensorFlow](https://www.tensorflow.org/)
-2. Use **TVM** to build optimized model artifacts for a given supported TVM context such as CPU, GPU, OpenCL, Vulkan, VPI, ROCM, etc.
+1. Train your **Deep Learning** model using any major framework such as [PyTorch](https://pytorch.org/), [Apache MXNet](https://mxnet.incubator.apache.org/) or [TensorFlow](https://www.tensorflow.org/)
+2. Use **TVM** to build optimized model artifacts on a supported context such as CPU, GPU, OpenCL, Vulkan, VPI, ROCM, etc.
 3. Deploy your models using **Rust** :heart:
 
 ### Example: Deploy Image Classification from Pretrained Resnet18 on ImageNet1k
 
 Please checkout [examples/resnet](https://github.com/ehsanmok/tvm-rust/tree/master/examples/resnet) for the complete end-to-end example.
 
-Here's python snippet for download and building a pretrained Resnet18 via MXNet and TVM
+Here's a Python snippet for downloading and building a pretrained Resnet18 via MXNet and TVM
 
 ```python
 block = get_model('resnet18_v1', pretrained=True)
@@ -39,7 +39,7 @@ with open(os.path.join(target_dir,"deploy_param.params"), "wb") as fo:
     fo.write(nnvm.compiler.save_param_dict(params))
 ```
 
-Now, we can read input the artifacts to create and run the Graph Runtime to detect our cat image
+Now, we need to input the artifacts to create and run the *Graph Runtime* to detect our input cat image
 
 ![cat](https://github.com/dmlc/mxnet.js/blob/master/data/cat.png?raw=true)
 
@@ -94,11 +94,11 @@ call_packed!(get_output_fn, &0, &output)?;
 let output = output.to_vec::<f32>()?;
 ```
 
-## Installation
+## Installations
 
-Please follow the TVM [installation](https://docs.tvm.ai/install/index.html), `export TVM_HOME=/path/to/tvm` and add `libtvm_runtime` to your `LD_LIBRARY_PATH`.
+Please follow TVM [installations](https://docs.tvm.ai/install/index.html), `export TVM_HOME=/path/to/tvm` and add `libtvm_runtime` to your `LD_LIBRARY_PATH`.
 
-*Note:* To run the end-to-end examples and tests, `tvm`, `nnvm` and `topi` need to be added to your `PYTHONPATH`.
+*Note:* To run the end-to-end examples and tests, `tvm`, `nnvm` and `topi` need to be added to your `PYTHONPATH` or it's automatic via an Anaconda environment when install individually.
 
 ## Supported TVM Functionalities
 
@@ -108,11 +108,9 @@ One can use the following Python snippet to generate `add_gpu.so` which add two
 
 ```python
 import os
-
 import tvm
 from tvm.contrib import cc
 
-
 def test_add(target_dir):
     if not tvm.module.enabled("cuda"):
         print(f"skip {__file__} because cuda is not enabled...")
@@ -121,9 +119,7 @@ def test_add(target_dir):
     A = tvm.placeholder((n,), name='A')
     B = tvm.placeholder((n,), name='B')
     C = tvm.compute(A.shape, lambda i: A[i] + B[i], name="C")
-
     s = tvm.create_schedule(C.op)
-
     bx, tx = s[C].split(C.op.axis[0], factor=64)
     s[C].bind(bx, tvm.thread_axis("blockIdx.x"))
     s[C].bind(tx, tvm.thread_axis("threadIdx.x"))
@@ -144,7 +140,7 @@ if __name__ == "__main__":
 
 ### Run the Generated Shared Library
 
-The following code snippet demonstrate how to load generated shared library (`add_gpu.so`).
+The following code snippet demonstrates how to load and test the generated shared library (`add_gpu.so`) in Rust.
 
 ```rust
 extern crate tvm_frontend as tvm;
@@ -174,14 +170,15 @@ fn main() {
     assert_eq!(ret.to_vec::<f32>().unwrap(), vec![6f32, 8.0]);
 }
 ```
+
 **Note:** it is required to instruct the `rustc` to link to the generated `add_gpu.so` in runtime, for example by
 `cargo:rustc-link-search=native=add_gpu`. 
 
 See the tests and examples custom `build.rs` for more details.
 
 ### Convert and Register a Rust Function as a TVM Packed Function
 
-One can you the `register_global_func!` macro to convert and register a Rust's 
+One can use `register_global_func!` macro to convert and register a Rust 
 function of type `fn(&[TVMArgValue]) -> Result<TVMRetValue>` to a global TVM **packed function** as follows
 
 ```rust
@@ -210,12 +207,12 @@ fn main() {
     let mut data = vec![3f32, 4.0];
     let mut arr = empty(shape, TVMContext::cpu(0), TVMType::from("float"));
     arr.copy_from_buffer(data.as_mut_slice());
-
     let mut registered = function::Builder::default();
     registered
         .get_function("sum", true)
         .arg(&arr)
         .arg(&arr);
+
     assert_eq!(registered.invoke().unwrap().to_float(), 14f64);
     }
 ```

run_tests.sh

@@ -0,0 +1,28 @@
+source activate py36
+
+cargo build
+cargo test
+
+cd tests/basics
+cargo build --features cpu
+cargo run --features cpu
+if [ $(which nvcc) ]; then
+  cargo build --features gpu
+  cargo run --features gpu
+fi
+cd -
+
+cd tests/callback
+cargo build
+cargo run --bin int
+cargo run --bin float
+cargo run --bin array
+cargo run --bin string
+cargo run --bin error
+cd -
+
+cd examples/resnet
+cargo build
+cargo run
+cd -
+

src/bytearray.rs

@@ -1,14 +1,13 @@
-//! Provides [`TVMByteArray`] which is used for passing the model parameters
+//! Provides [`TVMByteArray`] used for passing the model parameters
 //! (stored as byte-array) to a runtime module.
 //!
-//! This function can be obtained from a graph runtime module loading the model.
 //! For more detail, please see the example `resnet` in `examples` repository.
 
 use std::os::raw::c_char;
 
 use ts;
 
-/// A struct holding the TVM byte-array.
+/// A struct holding TVM byte-array.
 ///
 /// ## Example
 ///

src/context.rs

@@ -1,4 +1,4 @@
-//! Provides [`TVMContext`] and related device specific informations.
+//! Provides [`TVMContext`] and related device specific queries.
 //!
 //! Create a new context by device type (cpu is 1) and device id.
 //!
@@ -9,7 +9,8 @@
 //! let cpu0 = TVMContext::cpu(0);
 //! assert_eq!(ctx, cpu0);
 //! ```
-//! Or from supported device name.
+//!
+//! Or from a supported device name.
 //!
 //! ```
 //! let cpu0 = TVMContext::from("cpu");
@@ -27,8 +28,8 @@ use internal_api;
 use ts;
 use Result;
 
-/// Device type which can be from a supported device name. See the supported devices
-/// in [TVM](https://github.com/dmlc/tvm) project.
+/// Device type can be from a supported device name. See the supported devices
+/// in [TVM](https://github.com/dmlc/tvm).
 ///
 /// ## Example
 ///
@@ -128,7 +129,8 @@ impl<'a> From<&'a str> for TVMDeviceType {
 /// assert!(ctx.exist());
 ///
 /// ```
-/// It is possible to query the context and get information such as
+///
+/// It is possible to query the underlying context as follows
 ///
 /// ```
 /// println!("maximun threads per block: {}", ctx.max_threads_per_block());

src/errors.rs

@@ -7,7 +7,7 @@ use rust_ndarray;
 error_chain!{
     errors {
         EmptyArray {
-            description("cannot convert from empty array")
+            description("cannot convert from an empty array")
         }
 
         NullHandle(name: String) {
@@ -31,6 +31,7 @@ error_chain!{
         }
 
     }
+
     foreign_links {
         ShapeError(rust_ndarray::ShapeError);
         NulError(ffi::NulError);

src/function.rs

@@ -1,10 +1,10 @@
-//! This module provides idiomatic Rust API for creating and working with TVM functions.
+//! This module provides an idiomatic Rust API for creating and working with TVM functions.
 //!
-//! For calling an already registered TVM function use [`function::Builder`] and to register
-//! a TVM packed function from Rust either use [`function::register`] or the
-//! macro [`register_global_func`].
+//! For calling an already registered TVM function use [`function::Builder`]
+//! To register a TVM packed function from Rust side either
+//! use [`function::register`] or the macro [`register_global_func`].
 //!
-//! See the `tests` and `examples` repository for usage examples.
+//! See the tests and examples repository for more examples.
 
 use std::{
     ffi::{CStr, CString},
@@ -60,8 +60,9 @@ pub fn get_global_func(name: &str, is_global: bool) -> Option<Function> {
 }
 
 /// Wrapper around TVM function handle which includes `is_global`
-/// indicating whether the function is global or not and `is_released`
-/// to help for dropping the function handle.
+/// indicating whether the function is global or not, `is_released`
+/// to hint dropping the function handle and `is_cloned` showing
+/// not to drop a cloned function from Rust side.
 /// The value of these fields can be accessed through their respective methods.
 #[derive(Debug, Hash)]
 pub struct Function {
@@ -106,6 +107,12 @@ impl Function {
     pub fn is_released(&self) -> bool {
         self.is_released
     }
+
+    /// Returns `true` if the underlying TVM function has been cloned
+    /// from the frontend and `false` otherwise.
+    pub fn is_cloned(&self) -> bool {
+        self.is_cloned
+    }
 }
 
 impl Clone for Function {
@@ -133,7 +140,8 @@ impl Drop for Function {
 }
 
 /// Function builder in order to create and call functions.
-/// *Note:* Currently TVM functions accept at most one return value.
+///
+/// *Note:* Currently TVM functions accept *at most* one return value.
 #[derive(Debug, Clone, Default)]
 pub struct Builder<'a> {
     pub func: Option<Function>,
@@ -159,7 +167,7 @@ impl<'a> Builder<'a> {
         self
     }
 
-    /// Pushes a [`TVMArgValue`] into the function.
+    /// Pushes a [`TVMArgValue`] into the function argument buffer.
     pub fn arg<'b, T: ?Sized>(&mut self, arg: &'b T) -> &mut Self
     where
         TVMValue: From<&'b T>,
@@ -181,7 +189,7 @@ impl<'a> Builder<'a> {
         self
     }
 
-    /// Pushes multiple [`TVMArgValue`]s into the function.
+    /// Pushes multiple [`TVMArgValue`]s into the function argument buffer.
     pub fn args<'b, T: 'b + ?Sized, I>(&mut self, args: I) -> &mut Self
     where
         I: IntoIterator<Item = &'b T>,
@@ -195,7 +203,7 @@ impl<'a> Builder<'a> {
     }
 
     /// Sets an output for a function that requirs a mutable output to be provided.
-    /// See the `basics` in `tests` for an example.
+    /// See the `basics` in tests for an example.
     pub fn set_output<'b, T: 'b + ?Sized>(&mut self, arg: &'b mut T) -> &mut Self
     where
         TVMValue: From<&'b T>,
@@ -215,7 +223,7 @@ impl<'a> Builder<'a> {
         self
     }
 
-    /// Calls the function that created from builder.
+    /// Calls the function that created from `Builder`.
     pub fn invoke(&mut self) -> Result<TVMRetValue> {
         self.clone()(())
     }
@@ -356,7 +364,7 @@ fn convert_to_tvm_func(f: fn(&[TVMArgValue]) -> Result<TVMRetValue>) -> Function
 }
 
 /// Registers a Rust function with signature
-/// `fn(&[TVMArgValue]) -> Result<TVMRetValue<'static>>`
+/// `fn(&[TVMArgValue]) -> Result<TVMRetValue>`
 /// as a **global TVM packed function** from frontend to TVM backend.
 ///
 /// Use [`register_global_func`] if overriding an existing global TVM function
@@ -365,7 +373,7 @@ fn convert_to_tvm_func(f: fn(&[TVMArgValue]) -> Result<TVMRetValue>) -> Function
 /// ## Example
 ///
 /// ```
-/// fn sum(args: &[TVMArgValue]) -> Result<TVMRetValue<'static>> {
+/// fn sum(args: &[TVMArgValue]) -> Result<TVMRetValue> {
 ///     let mut ret = 0;
 ///     for arg in args.iter() {
 ///         ret += arg.to_int();
@@ -438,8 +446,8 @@ macro_rules! register_global_func {
     }}
 }
 
-/// Convenient macro for calling TVM packed functions by providing
-/// function identifier and the arguments. This macro outputs a `Result`
+/// Convenient macro for calling TVM packed functions by providing a
+/// function identifier and some arguments. This macro outputs a `Result` type
 /// and let user to perform proper error handling.
 ///
 /// **Note**: this macro does *not* expect an outside mutable output. To

src/internal_api.rs

@@ -2,6 +2,7 @@ use std::{cell::RefCell, collections::HashMap};
 
 use Function;
 
+// access TVM internal API
 thread_local! {
     pub(crate) static API: RefCell<HashMap<String, Function>> = RefCell::new(HashMap::new());
 }

src/lib.rs

@@ -1,11 +1,11 @@
 //! [TVM](https://github.com/dmlc/tvm) is a compiler stack for deep learning systems.
 //!
-//! This crate provides idiomatic Rust API for TVM runtime frontend.
+//! This crate provides an idiomatic Rust API for TVM runtime frontend.
 //!
-//! One particular usage is that given an optimized deep learning model,
-//! compiled with TVM, one can load the model artifacts which includes a shared library
-//! `lib.so`, `graph.json` and byte-array `param.params`
-//! in Rust to create a runtime, run the model for some inputs and get the
+//! One particular use case is that given optimized deep learning model artifacts,
+//! already compiled with TVM, which include a shared library
+//! `lib.so`, `graph.json` and a byte-array `param.params`, one can load them
+//! in Rust to create a graph runtime. Then, run the model for some inputs and get the
 //! desired predictions all in Rust.
 //!
 //! Checkout the `examples` repository for more details.

src/module.rs

@@ -1,4 +1,4 @@
-//! Provides [`Module`] type and methods for working with runtime TVM modules.
+//! Provides the [`Module`] type and methods for working with runtime TVM modules.
 
 use std::{
     ffi::CString,
@@ -17,9 +17,9 @@ use Result;
 
 const ENTRY_FUNC: &'static str = "__tvm_main__";
 
-/// Wrapper around TVM module handle which contains an entry function
-/// which can be applied to an imported module through [`entry_func`]
-/// and to check whether the module has be dropped use [`is_released`].
+/// Wrapper around TVM module handle which contains an entry function.
+/// The entry function can be applied to an imported module through [`entry_func`].
+/// Also [`is_released`] shows whether the module is dropped or not.
 ///
 /// [`entry_func`]:struct.Module.html#method.entry_func
 /// [`is_released`]:struct.Module.html#method.is_released