Merge pull request wolfSSL#2 from wolfSSL/async

Async match for wolfSSL master PR 482

README.md

@@ -2,8 +2,8 @@
 
 This respository contains the async.c and async.h files required for using Asynchronous Cryptography with the wolfSSL library.
 
-* The async.c file goes into ./src/.
-* The async.h file goes into ./wolfssl/.
+* The async.c file goes into `./wolfcrypt/src/`.
+* The async.h file goes into `./wolfssl/wolfcrypt/`.
 
 This feature is enabled using:
 `./configure --enable-asynccrypt` or `#define WOLFSSL_ASYNC_CRYPT`.
@@ -13,51 +13,133 @@ The async crypt simulator is enabled by default if the hardware does not support
 ## Design
 A generic event system has been created using a `WOLF_EVENT` structure. If `HAVE_WOLF_EVENT` is defined then the `WOLFSSL` structure inclues a generic `WOLF_EVENT` for uses specific to that SSL connection.
 
-The asyncronous crypto system is modeled after epoll. The implementation uses `wolfSSL_CTX_poll` to check if any async operations are complete.
+The asyncronous crypto system is modeled after epoll. The implementation uses `wolfSSL_AsyncPoll` to check if any async operations are complete.
 
 ## API's
 
-### ```wolfSSL_async_pop```
+### ```wolfSSL_AsyncPoll```
+```
+int wolfSSL_AsyncPoll(WOLFSSL* ssl, WOLF_EVENT_FLAG flags);
+```
+
+Polls the provided WOLFSSL object's event to see if its done. Return 1 on success.
+
+### ```wolfSSL_CTX_AsyncPoll```
+```
+int wolfSSL_CTX_AsyncPoll(WOLFSSL_CTX* ctx, WOLF_EVENT** events, int maxEvents, WOLF_EVENT_FLAG flags, int* eventCount);
+```
+
+Polls the provided WOLFSSL_CTX context queue to see if any pending events are done.
+
+### ```wolfAsync_DevOpen```
+```
+int wolfAsync_DevOpen(int *devId);
+```
+
+Open the async device and returns an `int` device id for it.
+
+### ```wolfAsync_DevClose```
+```
+void wolfAsync_DevClose(int *devId)
+```
+
+Closes the async device.
+
+### ```wolfAsync_DevCtxInit```
+```
+int wolfAsync_DevCtxInit(AsyncCryptDev* asyncDev, int marker, int devId);
+```
+
+Initialize the device context and open the device hardware using the provided `AsyncCryptDev` pointer, marker and device id (from wolfAsync_DevOpen).
 
+### ```wolfAsync_DevCtxFree```
 ```
-int wolfSSL_async_pop(WOLFSSL* ssl, enum WOLF_EVENT_TYPE event_type);
+void wolfAsync_DevCtxFree(AsyncCryptDev* asyncDev);
 ```
 
-This will check the ssl->event to see if the event type matches and the event is complete. If it is then the async return code is returned.
+Closes and free's the device context.
+
+
+
+### ```wolfAsync_EventPop ```
 
-### ```wolfSSL_async_push```
 ```
-int wolfSSL_async_push(WOLFSSL* ssl, enum WOLF_EVENT_TYPE event_type);
+int wolfAsync_EventPop(WOLF_EVENT* event, enum WOLF_EVENT_TYPE event_type);
 ```
 
-This populates the ssl->event with type and places it onto the ssl->ctx event queue.
+This will check the event to see if the event type matches and the event is complete. If it is then the async return code is returned.
 
-### ```wolfSSL_async_poll ```
+
+### ```wolfAsync_EventQueuePush```
 ```
-int wolfSSL_async_poll(WOLF_EVENT* event, unsigned char flags);
+int wolfAsync_EventQueuePush(WOLF_EVENT_QUEUE* queue, WOLF_EVENT* event, 
+    enum WOLF_EVENT_TYPE event_type, void* context);
 ```
 
-This function will physically try and check the status of the event in hardware. If the `WOLFSSL_ASYNC_CRYPT_TEST` define is set then it will use the async simulator.
+Pushes an event to the provided event queue and assigns the provided event type and context.
+
+### ```wolfAsync_EventPoll```
+```
+int wolfAsync_EventPoll(WOLF_EVENT* event, WOLF_EVENT_FLAG flags);
+```
 
-### Poll flags:
+Polls the provided event to determine if its done.
 
-* `WOLF_POLL_FLAG_CHECK_HW`: Flag permitting hardware check.
-* `WOLF_POLL_FLAG_PEEK`: Flag to peek at the events only. If `events` arg is provided actual event data will be returned, otherwise the returned `eventCount` will be the total number of pending events.
+### ```wolfAsync_EventQueue_Poll```
 
-### `wolfSSL_CTX_poll`
 ```
-int wolfSSL_CTX_poll(WOLFSSL_CTX* ctx, WOLF_EVENT* events, int maxEvents,
-                                 unsigned char flags, int* eventCount);
+int wolfAsync_EventQueue_Poll(WOLF_EVENT_QUEUE* queue, void* context_filter,
+    WOLF_EVENT** events, int maxEvents, WOLF_EVENT_FLAG flags, int* eventCount);
 ```
 
-Poll function to perform async check for contact and return completed events. Events are returned in the `events` pointer (array) with `maxEvents` indicating how many `WOLF_EVENT` buffers are available. The number of actual events populated into `events` is returned in `eventCount`. If the `WOLF_POLL_FLAG_PEEK` flag is used the `events` arg is optional. If ommited the `eventCount` will be total count of items in queue.
+Polls all events in the provided event queue. Optionally filters by context. Will return pointers to the done events.
 
+### ```wolfAsync_EventInit```
+```
+int wolfAsync_EventInit(WOLF_EVENT* event, WOLF_EVENT_TYPE type, void* context);
+```
+
+Initialize an event structure with provided type and context. Sets the pending flag and the status code to WC_PENDING_E.
+
+### ```wolfAsync_EventWait```
+```
+int wolfAsync_EventWait(WOLF_EVENT* event);
+```
 
+Waits for the provided event to complete.
+
+## TLS Server Example
 
-### `wolfSSL_poll `
 ```
-int wolfSSL_poll(WOLFSSL* ssl, WOLF_EVENT* events,
-    int maxEvents, unsigned char flags, int* eventCount);
+#ifdef WOLFSSL_ASYNC_CRYPT
+    static int devId = INVALID_DEVID;
+
+    ret = wolfAsync_DevOpen(&devId);
+    if (ret != 0) {
+        err_sys("Async device open failed");
+    }
+    wolfSSL_CTX_UseAsync(ctx, devId);
+#endif /* WOLFSSL_ASYNC_CRYPT */
+
+	err = 0;
+	do {
+	#ifdef WOLFSSL_ASYNC_CRYPT
+	    if (err == WC_PENDING_E) {
+	       ret = wolfSSL_AsyncPoll(ssl);
+	       if (ret < 0) { break; } else if (ret == 0) { continue; }
+	    }
+	#endif
+	
+	    ret = wolfSSL_accept(ssl);
+	    if (ret != SSL_SUCCESS) {
+	        err = wolfSSL_get_error(ssl, 0);
+	    }
+	} while (ret != SSL_SUCCESS && err == WC_PENDING_E);
+    
+#ifdef WOLFSSL_ASYNC_CRYPT
+    wolfAsync_DevClose(&devId);
+#endif
 ```
 
-Same as `wolfSSL_CTX_poll`, but filters by `ssl` object.
+## wolfCrypt Example
+