Enable AoT and wamr-sdk, and change arguments of call wasm API (#157)

* Implement memory profiler, optimize memory usage, modify code indent * Implement memory.grow and limit heap space base offset to 1G; modify iwasm build type to Release and 64 bit by default * Add a new extension library: connection * Fix bug of reading magic number and version in big endian platform * Re-org platform APIs: move most platform APIs from iwasm to shared-lib * Enhance wasm loader to fix some security issues * Fix issue about illegal load of EXC_RETURN into PC on stm32 board * Updates that let a restricted version of the interpreter run in SGX * Enable native/app address validation and conversion for wasm app * Remove wasm_application_exectue_* APIs from wasm_export.h which makes confused * Refine binary size and fix several minor issues Optimize interpreter LOAD/STORE opcodes to decrease the binary size Fix issues when using iwasm library: _bh_log undefined, bh_memory.h not found Remove unused _stdin/_stdout/_stderr global variables resolve in libc wrapper Add macros of global heap size, stack size, heap size for Zephyr main.c Clear compile warning of wasm_application.c * Add more strict security checks for libc wrapper API's * Use one libc wrapper copy for sgx and other platforms; remove bh_printf macro for other platform header files * Enhance security of libc strcpy/sprintf wrapper function * Fix issue of call native for x86_64/arm/mips, add module inst parameter for native wrapper functions * Remove get_module_inst() and fix issue of call native * Refine wgl lib: remove module_inst parameter from widget functions; move function index check to runtime instantiate * Refine interpreter call native process, refine memory boudary check * Fix issues of invokeNative function of arm/mips/general version * Add a switch to build simple sample without gui support * Add BUILD_TARGET setting in makefile to replace cpu compiler flags in source code * Re-org shared lib header files, remove unused info; fix compile issues of vxworks * Add build target general * Remove unused files * Update license header * test push * Restore file * Sync up with internal/feature * Sync up with internal/feature * Rename build_wamr_app to build_wasm_app * Fix small issues of README * Enhance malformed wasm file checking Fix issue of print hex int and implement utf8 string check Fix wasi file read/write right issue Fix minor issue of build wasm app doc * Sync up with internal/feature * Sync up with internal/feature: fix interpreter arm issue, fix read leb issue * Sync up with internal/feature * Fix bug of config.h and rename wasi config.h to ssp_config.h * Sync up with internal/feature * Import wamr aot * update document * update document * Update document, disable WASI in 32bit * update document * remove files * update document * Update document * update document * update document * update samples * Sync up with internal repo
2020-01-21 13:26:14 +08:00
parent 2a4528c749
commit 46b93b9d22
464 changed files with 25137 additions and 7911 deletions
--- a/doc/wamr_api.md
+++ b/doc/wamr_api.md
@ -1,104 +1,66 @@

-WAMR application library
+WAMR application framework
 ========================

-WAMR APP API includes built-in Libc API's, Base library and Extension library reference.
-
-
-**Libc API's**<br/>
-This is a minimal set of Libc API's for memory allocation, string manipulation and printing. The header file is located at ```lib/app-libs/libc/lib_base.h```. The current supported API set is listed here:
+## Application system callbacks
+The `on_init` and `on_destroy` functions are wamr application system callbacks which must be implemented in the wasm application if you want to use the APP framework.
 ``` C
-void *malloc(size_t size);
-void *calloc(size_t n, size_t size);
-void free(void *ptr);
-int memcmp(const void *s1, const void *s2, size_t n);
-void *memcpy(void *dest, const void *src, size_t n);
-void *memmove(void *dest, const void *src, size_t n);
-void *memset(void *s, int c, size_t n);
-int putchar(int c);
-int snprintf(char *str, size_t size, const char *format, ...);
-int sprintf(char *str, const char *format, ...);
-char *strchr(const char *s, int c);
-int strcmp(const char *s1, const char *s2);
-char *strcpy(char *dest, const char *src);
-size_t strlen(const char *s);
-int strncmp(const char * str1, const char * str2, size_t n);
-char *strncpy(char *dest, const char *src, unsigned long n);
+void on_init()
+{
+    /*
+        Your init functions here, for example:
+        * platform initialization
+        * timer registration
+        * service / event registration
+        * ......
+    */
+}
+
+void on_destroy()
+{
+    /*
+        your destroy functions here
+    */
+}
 ```

-**Base library**<br/>
-Basic support for communication, timers, etc is available. You can refer to the header file ```lib/app-libs/base/wasm_app.h``` which contains the definitions for request and response API's, event pub/sub API's and timer API's. Please note that these API's require the native implementations.
-The API set is listed below:
+## Base App library
+
+The base library of application framework supports the essential API for WASM applications, such as inter-app communication, timers, etc. Other application framework components rely on the base library.
+
+When building the WAMR SDK, once application framework is enabled, the base library will automatically enabled.
+
+### Timer
+The *timer* API's can be used to create some `soft timers` with single-shot mode or periodic mode. Here is a reference of how to use timer API's to execute a function every one second.
 ``` C
-typedef void(*request_handler_f)(request_t *) ;
-typedef void(*response_handler_f)(response_t *, void *) ;
+/* User global variable */
+static int num = 0;

-// Request API's
-bool api_register_resource_handler(const char *url, request_handler_f);
-void api_send_request(request_t * request, response_handler_f response_handler, void * user_data);
-void api_response_send(response_t *response);
+/* Timer callback */
+void timer1_update(user_timer_t timer)
+{
+    printf("Timer update %d\n", num++);
+}

-// Event API's
-bool api_publish_event(const char *url,  int fmt, void *payload,  int payload_len);
-bool api_subscribe_event(const char * url, request_handler_f handler);
+void on_init()
+{
+    user_timer_t timer;

-struct user_timer;
-typedef struct user_timer * user_timer_t;
+    /* set up a timer */
+    timer = api_timer_create(1000, true, false, timer1_update);
+    api_timer_restart(timer, 1000);
+}

-// Timer API's
-user_timer_t api_timer_create(int interval, bool is_period, bool auto_start, void(*on_user_timer_update)(user_timer_t
-));
-void api_timer_cancel(user_timer_t timer);
-void api_timer_restart(user_timer_t timer, int interval);
+void on_destroy()
+{
+
+}
 ```

-**Library extension reference**<br/>
-Currently we provide several kinds of extension library for reference including sensor, connection and GUI.
-
-Sensor API: In the header file ```lib/app-libs/extension/sensor/sensor.h```, the API set is defined as below:
-``` C
-sensor_t sensor_open(const char* name, int index,
-                     void(*on_sensor_event)(sensor_t, attr_container_t *, void *),
-                     void *user_data);
-bool sensor_config(sensor_t sensor, int interval, int bit_cfg, int delay);
-bool sensor_config_with_attr_container(sensor_t sensor, attr_container_t *cfg);
-bool sensor_close(sensor_t sensor);
-```
-Connection API: In the header file `lib/app-libs/extension/connection/connection.h.`, the API set is defined as below:
-``` C
-/* Connection event type */
-typedef enum {
-    /* Data is received */
-    CONN_EVENT_TYPE_DATA = 1,
-    /* Connection is disconnected */
-    CONN_EVENT_TYPE_DISCONNECT
-} conn_event_type_t;
-
-typedef void (*on_connection_event_f)(connection_t *conn,
-                                      conn_event_type_t type,
-                                      const char *data,
-                                      uint32 len,
-                                      void *user_data);
-connection_t *api_open_connection(const char *name,
-                                  attr_container_t *args,
-                                  on_connection_event_f on_event,
-                                  void *user_data);
-void api_close_connection(connection_t *conn);
-int api_send_on_connection(connection_t *conn, const char *data, uint32 len);
-bool api_config_connection(connection_t *conn, attr_container_t *cfg);
-```
-GUI API: The API's is list in header file ```lib/app-libs/extension/gui/wgl.h``` which is implemented based open soure 2D graphic library [LittlevGL](https://docs.littlevgl.com/en/html/index.html). Currently supported widgets include button, label, list and check box and more wigdet would be provided in future.
-
-
-Communication programming models
-=========================
-WAMR supports two typical communication programming models, the microservice model and the pub/sub model. 
-
-
-Microservice model
-------------------------
+### Micro-service model (request/response)
 The microservice model is also known as request and response model. One WASM application acts as the server which provides a specific service. Other WASM applications or host/cloud applications request that service and get the response.
-<img src="./pics/request.PNG" width="60%" height="60%">
+
+<center><img src="./pics/request.PNG" width="60%" height="60%"></center>

 Below is the reference implementation of the server application. It provides room temperature measurement service.

@ -136,11 +98,10 @@ void room_temp_handler(request_t *request)
 ```


-Pub/sub model
-------------------------
+### Pub/sub model
 One WASM application acts as the event publisher. It publishes events to notify WASM applications or host/cloud applications which subscribe to the events.

-<img src="./pics/sub.PNG" width="60%" height="60%">
+<center><img src="./pics/sub.PNG" width="60%" height="60%"></center>

 Below is the reference implementation of the pub application. It utilizes a timer to repeatedly publish an overheat alert event to the subscriber applications. Then the subscriber applications receive the events immediately.

@ -193,4 +154,198 @@ void on_destroy()
 {
 }
 ```
-**Note:** You can also subscribe this event from host side by using host tool. Please refer `samples/simple` project for deail usage.
+**Note:** You can also subscribe this event from host side by using host tool. Please refer `samples/simple` project for detail usage.
+
+
+## Sensor API
+
+The API set is defined in the header file ```core/app-framework/sensor/app/wa-inc/sensor.h```.
+
+Here is a reference of how to use sensor API's:
+
+``` C
+static sensor_t sensor = NULL;
+
+/* Sensor event callback*/
+void sensor_event_handler(sensor_t sensor, attr_container_t *event,
+                          void *user_data)
+{
+    printf("### app get sensor event\n");
+    attr_container_dump(event);
+}
+
+void on_init()
+{
+    char *user_data;
+    attr_container_t *config;
+
+    printf("### app on_init 1\n");
+    /* open a sensor */
+    user_data = malloc(100);
+    printf("### app on_init 2\n");
+    sensor = sensor_open("sensor_test", 0, sensor_event_handler, user_data);
+    printf("### app on_init 3\n");
+
+    /* config the sensor */
+    sensor_config(sensor, 1000, 0, 0);
+    printf("### app on_init 4\n");
+}
+
+void on_destroy()
+{
+    if (NULL != sensor) {
+        sensor_config(sensor, 0, 0, 0);
+    }
+}
+```
+
+## Connection API: 
+
+The API set is defined in the header file `core/app-framework/connection/app/wa-inc/connection.h`
+
+Here is a reference of how to use connection API's:
+``` C
+/* User global variable */
+static int num = 0;
+static user_timer_t g_timer;
+static connection_t *g_conn = NULL;
+
+void on_data1(connection_t *conn,
+              conn_event_type_t type,
+              const char *data,
+              uint32 len,
+              void *user_data)
+{
+    if (type == CONN_EVENT_TYPE_DATA) {
+        char message[64] = {0};
+        memcpy(message, data, len);
+        printf("Client got a message from server -> %s\n", message);
+    } else if (type == CONN_EVENT_TYPE_DISCONNECT) {
+        printf("connection is close by server!\n");
+    } else {
+        printf("error: got unknown event type!!!\n");
+    }
+}
+
+/* Timer callback */
+void timer1_update(user_timer_t timer)
+{
+    char message[64] = {0};
+    /* Reply to server */
+    snprintf(message, sizeof(message), "Hello %d", num++);
+    api_send_on_connection(g_conn, message, strlen(message));
+}
+
+void my_close_handler(request_t * request)
+{
+    response_t response[1];
+
+    if (g_conn != NULL) {
+        api_timer_cancel(g_timer);
+        api_close_connection(g_conn);
+    }
+
+    make_response_for_request(request, response);
+    set_response(response, DELETED_2_02, 0, NULL, 0);
+    api_response_send(response);
+}
+
+void on_init()
+{
+    user_timer_t timer;
+    attr_container_t *args;
+    char *str = "this is client!";
+
+    api_register_resource_handler("/close", my_close_handler);
+
+    args = attr_container_create("");
+    attr_container_set_string(&args, "address", "127.0.0.1");
+    attr_container_set_uint16(&args, "port", 7777);
+
+    g_conn = api_open_connection("TCP", args, on_data1, NULL);
+    if (g_conn == NULL) {
+        printf("connect to server fail!\n");
+        return;
+    }
+
+    printf("connect to server success! handle: %p\n", g_conn);
+
+    /* set up a timer */
+    timer = api_timer_create(1000, true, false, timer1_update);
+    api_timer_restart(timer, 1000);
+}
+
+void on_destroy()
+{
+
+}
+```
+
+## GUI API
+
+The API's is listed in header file ```core/app-framework/wgl/app/wa-inc/wgl.h``` which is implemented based on open soure 2D graphic library [LittlevGL](https://docs.littlevgl.com/en/html/index.html).
+
+``` C
+static void btn_event_cb(wgl_obj_t btn, wgl_event_t event);
+
+uint32_t count = 0;
+char count_str[11] = { 0 };
+wgl_obj_t hello_world_label;
+wgl_obj_t count_label;
+wgl_obj_t btn1;
+wgl_obj_t label_count1;
+int label_count1_value = 0;
+char label_count1_str[11] = { 0 };
+
+void timer1_update(user_timer_t timer1)
+{
+    if ((count % 100) == 0) {
+        snprintf(count_str, sizeof(count_str), "%d", count / 100);
+        wgl_label_set_text(count_label, count_str);
+    }
+    ++count;
+}
+
+void on_init()
+{
+    hello_world_label = wgl_label_create((wgl_obj_t)NULL, (wgl_obj_t)NULL);
+    wgl_label_set_text(hello_world_label, "Hello world!");
+    wgl_obj_align(hello_world_label, (wgl_obj_t)NULL, WGL_ALIGN_IN_TOP_LEFT, 0, 0);
+
+    count_label = wgl_label_create((wgl_obj_t)NULL, (wgl_obj_t)NULL);
+    wgl_obj_align(count_label, (wgl_obj_t)NULL, WGL_ALIGN_IN_TOP_MID, 0, 0);
+
+    btn1 = wgl_btn_create((wgl_obj_t)NULL, (wgl_obj_t)NULL); /*Create a button on the currently loaded screen*/
+    wgl_obj_set_event_cb(btn1, btn_event_cb); /*Set function to be called when the button is released*/
+    wgl_obj_align(btn1, (wgl_obj_t)NULL, WGL_ALIGN_CENTER, 0, 0); /*Align below the label*/
+
+    /*Create a label on the button*/
+    wgl_obj_t btn_label = wgl_label_create(btn1, (wgl_obj_t)NULL);
+    wgl_label_set_text(btn_label, "Click ++");
+
+    label_count1 = wgl_label_create((wgl_obj_t)NULL, (wgl_obj_t)NULL);
+    wgl_label_set_text(label_count1, "0");
+    wgl_obj_align(label_count1, (wgl_obj_t)NULL, WGL_ALIGN_IN_BOTTOM_MID, 0, 0);
+
+    /* set up a timer */
+    user_timer_t timer;
+    timer = api_timer_create(10, true, false, timer1_update);
+    if (timer)
+        api_timer_restart(timer, 10);
+    else
+        printf("Fail to create timer.\n");
+}
+
+static void btn_event_cb(wgl_obj_t btn, wgl_event_t event)
+{
+    if(event == WGL_EVENT_RELEASED) {
+        label_count1_value++;
+        snprintf(label_count1_str, sizeof(label_count1_str),
+                 "%d", label_count1_value);
+        wgl_label_set_text(label_count1, label_count1_str);
+    }
+}
+
+```
+
+Currently supported widgets include button, label, list and check box and more wigdet would be provided in future.