chore: add docs

.gitignore

@@ -2,4 +2,5 @@
 *.wasm
 /.idea
 /cmake-build-*
+/docs
 /wasm-micro-runtime

main.c

@@ -39,57 +39,9 @@ void test_wrt() {
     free(buf);
 }
 
-unsigned char foo(unsigned int x, float y, char z, double w) {
-    printf("foo: x=%u, y=%f, z=%c, w=%lf\n", x, y, z, w);
-    return 'P';
-}
-
-void test_ffi() {
-    ffi_cif    cif;
-    ffi_type  *arg_types[4];
-    void      *arg_values[4];
-    ffi_status status;
-
-    // Because the return value from foo() is smaller than sizeof(long), it
-    // must be passed as ffi_arg or ffi_sarg.
-    ffi_arg result;
-
-    // Specify the data type of each argument. Available types are defined
-    // in <ffi/ffi.h>.
-    arg_types[0] = &ffi_type_uint;
-    arg_types[1] = &ffi_type_float;
-    arg_types[2] = &ffi_type_schar;
-    arg_types[3] = &ffi_type_double;
-
-    // Prepare the ffi_cif structure.
-    if ((status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 4, &ffi_type_uint8, arg_types)) != FFI_OK) {
-        // Handle the ffi_status error.
-        LOG_ERR("ffi_prep_cif failed: %d", status);
-    }
-
-    // Specify the values of each argument.
-    unsigned int arg1 = 42;
-    float        arg2 = 5.1f;
-    char         arg3 = 'A';
-    double       arg4 = 114.1514;
-
-    arg_values[0] = &arg1;
-    arg_values[1] = &arg2;
-    arg_values[2] = &arg3;
-    arg_values[3] = &arg4;
-
-    // Invoke the function.
-    ffi_call(&cif, FFI_FN(foo), &result, arg_values);
-
-    // The ffi_arg 'result' now contains the unsigned char returned from foo(),
-    // which can be accessed by a typecast.
-    printf("result is %c\n", (unsigned char)result);
-}
-
 int main() {
     LOG_INFO("WRT Test");
 
-    test_ffi();
     test_wrt();
 
     return 0;

wrt/lib/dl.h

@@ -7,18 +7,32 @@
 
 #include "utils/defs.h"
 
+/// Dynamic Library Context
 typedef struct {
+    /// memory allocator, must be set before `dl_init`
     struct {
+        /// platform memory allocator, same as `malloc`
         Allocator malloc;
+        /// platform memory de-allocator, same as `free`
         DeAllocator free;
     } mem;
+
+    /// native symbol table, which could be registered by `wasm_runtime_register_natives`
     NativeSymbol *symTable;
+
+    /// dynamic library handle table
     struct {
+        /// handle of the opened dynamic library, returned by `dlopen`
         void *handle;
     } hnd[DL_MAX_HANDLES];
+
+    /// dynamic library symbol table
     struct {
+        /// back reference to the handle, 1-based
         unsigned backref;
+        /// symbol address, returned by `dlsym`
         void    *symbol;
+        /// `ffi_cif`, created in `dl_sym`
         ffi_cif *cif;
     } sym[DL_MAX_SYMBOLS];
 } DLContext;

wrt/wrt.h

@@ -6,23 +6,31 @@
 #include "utils/defs.h"
 #include "wrt/lib/dl.h"
 
+/// WASM Runtime Context
 typedef struct {
+    /// Platform specific allocator and de-allocator
     struct {
         Allocator   malloc;
         DeAllocator free;
     } platform;
+
+    /// WAMR specific context
     struct {
         wasm_module_t        module;
         wasm_module_inst_t   module_inst;
         wasm_exec_env_t      exec_env;
         wasm_function_inst_t entry_func;
     } wamr;
+
+    /// Memory context
     struct {
         uint8_t *heap_buf;
         uint32_t heap_buf_size;
         char    *error_buf;
         uint32_t error_buf_size;
     } mem;
+
+    /// Program context
     struct {
         uint8_t      *wasm_buffer;
         uint32_t      wasm_buffer_size;
@@ -32,18 +40,47 @@ typedef struct {
     } program;
 } WRTContext;
 
+/// Initialize WRTContext
+/// \param context WRTContext
+/// \param allocator malloc
+/// \param deAllocator free
+/// \return always WRT_OK
 Status wrt_platform_init(WRTContext *context, Allocator allocator, DeAllocator deAllocator);
 
+/// Initialize memory context, malloc heap_buf and error_buf
+/// \param context WRTContext
+/// \param heap_buf_size heap_buf size
+/// \param error_buf_size error_buf size
+/// \return WRT_OK, unless malloc failed
 Status wrt_mem_init(WRTContext *context, uint32_t heap_buf_size, uint32_t error_buf_size);
 
+/// Initialize program context, as well as dl context
+/// \param context WRTContext
+/// \param wasm_buffer WASM file buffer
+/// \param wasm_buffer_size WASM file buffer size
+/// \param native_symbols native symbols to be registered
+/// \param native_symbols_size native symbols size
+/// \return always WRT_OK
 Status wrt_program_init(WRTContext *context, uint8_t *wasm_buffer, uint32_t wasm_buffer_size,
                         NativeSymbol *native_symbols, uint32_t native_symbols_size);
 
+/// Initialize WAMR context
+/// \param context WRTContext
+/// \param entry_func entry function name
+/// \param stack_size program stack size
+/// \param heap_size program heap size
+/// \return `Status` of WAMR initialization
 Status wrt_wamr_init(WRTContext *context, char *entry_func, uint32_t stack_size,
                      uint32_t heap_size);
 
+/// Free WRTContext
+/// \param context WRTContext
+/// \return always WRT_OK
 Status wrt_free(WRTContext *context);
 
+/// Run WASM program
+/// \param context WRTContext
+/// \return WRT_OK, unless exception occurred
 Status wrt_run(WRTContext *context);
 
 #endif // WRT_WRT_H