Skip to content

Commit a0313c9

Browse files
committed
Change the notion of async "test" to "software."
The async simulator is a software backend for the async code that just calls into wolfcrypt to handle crypto ops instead of some truly async hardware device. This is useful for testing, but it also provides a nice way for non-blocking crypto algorithms in wolfCrypt to be used by wolfSSL's TLS/DTLS layer, as the non-blocking coding patterns map neatly onto the async patterns. With non-blocking TLS/DTLS being a "real-world" use case of the async simulator, this commit changes all the language in the async code from "test" to "software."
1 parent e98066f commit a0313c9

3 files changed

Lines changed: 175 additions & 174 deletions

File tree

README-async.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This repository contains the async.c and async.h files required for using Asynch
88
This feature is enabled using:
99
`./configure --enable-asynccrypt` or `#define WOLFSSL_ASYNC_CRYPT`.
1010

11-
The async crypt simulator is enabled by default if the hardware does not support async crypto or it can be manually enabled using `#define WOLFSSL_ASYNC_CRYPT_TEST`.
11+
If async crypto is enabled but no hardware backend is enabled or if `WOLFSSL_ASYNC_CRYPT_SW` is defined, a software backend using wolfCrypt is used instead. This software backend can simulate periodic hardware delays using the macro `WOLF_ASYNC_SW_SKIP_MOD`, which is on by default if `DEBUG_WOLFSSL` is defined.
1212

1313
## Design
1414

@@ -20,14 +20,17 @@ A generic event system has been created using a `WOLF_EVENT` structure when `HAV
2020

2121
The asynchronous crypto system is modeled after epoll. The implementation uses `wolfSSL_AsyncPoll` or `wolfSSL_CTX_AsyncPoll` to check if any async operations are complete.
2222

23+
## Hardware Backends
2324

24-
## Hardware
25-
26-
Supported hardware:
25+
Supported hardware backends:
2726

2827
* Intel QuickAssist with QAT 1.6 or QAT 1.7 driver. See README.md in `wolfcrypt/src/port/intel/README.md`.
2928
* Cavium Nitrox III and V. See README.md in `wolfcrypt/src/port/cavium/README.md`.
3029

30+
## wolfCrypt Backend
31+
32+
The wolfCrypt backend uses the same API as the hardware backends do. Once an asynchronous operation is initiated with the software backend, subsequent calls to `wolfSSL_AsyncPoll` will call into wolfCrypt to complete the operation. If non-blocking is enabled, for example, for ECC (via `WC_ECC_NONBLOCK`), each `wolfSSL_AsyncPoll` will do a chunk of work for the operation and return, to minimize blocking time.
33+
3134
## API's
3235

3336
### ```wolfSSL_AsyncPoll```
@@ -42,7 +45,7 @@ Polls the provided WOLFSSL object's reference to the WOLFSSL_CTX's event queue t
4245
int wolfSSL_CTX_AsyncPoll(WOLFSSL_CTX* ctx, WOLF_EVENT** events, int maxEvents, WOLF_EVENT_FLAG flags, int* eventCount)
4346
```
4447

45-
Polls the provided WOLFSSL_CTX context event queue to see if any pending events are done. If the `events` argument is provided then a pointer to the `WOLF_EVENT` will be returned up to `maxEvents`. If `eventCount` is provided then the number of events populated will be returned. The `flags` allows for `WOLF_POLL_FLAG_CHECK_HW` to indicate if hardware should be polled again or just return more events.
48+
Polls the provided WOLFSSL_CTX context event queue to see if any pending events are done. If the `events` argument is provided then a pointer to the `WOLF_EVENT` will be returned up to `maxEvents`. If `eventCount` is provided then the number of events populated will be returned. The `flags` allows for `WOLF_POLL_FLAG_CHECK_HW` to indicate if the crypto backend (i.e. hardware or wolfCrypt, if the software implementation is being used) should be polled again or just return more events.
4649

4750
### ```wolfAsync_DevOpen```
4851
```
@@ -65,7 +68,6 @@ void wolfAsync_DevClose(int *devId)
6568
Closes the async device.
6669

6770
### ```wolfAsync_DevCopy```
68-
6971
```
7072
int wolfAsync_DevCopy(WC_ASYNC_DEV* src, WC_ASYNC_DEV* dst);
7173
```

0 commit comments

Comments
 (0)