add an additional async notification communication method based on callback

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Paul Yang <yang.yang@baishancloud.com>
Signed-off-by: Ping Yu <ping.yu@intel.com>
Signed-off-by: Steven Linsell <stevenx.linsell@intel.com>

(Merged from https://github.com/openssl/openssl/pull/7573)

1 files changed, 69 insertions, 4 deletions

diff --git a/doc/man3/ASYNC_WAIT_CTX_new.pod b/doc/man3/ASYNC_WAIT_CTX_new.pod
index eeb2777a8b..9076be8171 100644
--- a/doc/man3/ASYNC_WAIT_CTX_new.pod
+++ b/doc/man3/ASYNC_WAIT_CTX_new.pod
@@ -4,13 +4,22 @@
 
 ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
 ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
-ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage
-waiting for asynchronous jobs to complete
+ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd,
+ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback,
+ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn,
+ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK,
+ASYNC_STATUS_EAGAIN
+- functions to manage waiting for asynchronous jobs to complete
 
 =head1 SYNOPSIS
 
  #include <openssl/async.h>
 
+ #define ASYNC_STATUS_UNSUPPORTED    0
+ #define ASYNC_STATUS_ERR            1
+ #define ASYNC_STATUS_OK             2
+ #define ASYNC_STATUS_EAGAIN         3
+ typedef int (*ASYNC_callback_fn)(void *arg);
  ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
  void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
  int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
@@ -26,6 +35,14 @@ waiting for asynchronous jobs to complete
                                     size_t *numaddfds, OSSL_ASYNC_FD *delfd,
                                     size_t *numdelfds);
  int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
+ int ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx,
+                                 ASYNC_callback_fn callback,
+                                 void *callback_arg);
+ int ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx,
+                                 ASYNC_callback_fn *callback,
+                                 void **callback_arg);
+ int ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status);
+ int ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx);
 
 
 =head1 DESCRIPTION
@@ -103,14 +120,58 @@ code that the job should be resumed by making the wait file descriptor
 "readable". Once resumed the engine should clear the wake signal on the wait
 file descriptor.
 
+As well as a file descriptor, user code may also be notified via a callback. The
+callback and data pointers are stored within the ASYNC_WAIT_CTX along with an
+additional status field that can be used for the notification of retries from an
+engine. This additional method can be used when the user thinks that a file
+descriptor is too costly in terms of CPU cycles or in some context where a file
+descriptor is not appropriate.
+
+ASYNC_WAIT_CTX_set_callback() sets the callback and the callback argument. The
+callback will be called to notify user code when an engine completes a
+cryptography operation. It is a requirement that the callback function is small
+and non-blocking as it will be run in the context of a polling mechanism or an
+interrupt.
+
+ASYNC_WAIT_CTX_get_callback() returns the callback set in the ASYNC_WAIT_CTX
+structure.
+
+ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine status.
+The possible status values are the following:
+ASYNC_STATUS_UNSUPPORTED: The engine does not support the callback mechanism.
+This is the default value. The engine must call ASYNC_WAIT_CTX_set_status() to
+set the status to some value other than ASYNC_STATUS_UNSUPPORTED if it intends
+to enable the callback mechanism.
+ASYNC_STATUS_ERR: The engine has a fatal problem with this request. The user
+code should clean up this session.
+ASYNC_STATUS_OK: The request has been successfully submitted.
+ASYNC_STATUS_EAGAIN: The engine has some problem which will be recovered soon,
+such as a buffer is full, so user code should resume the job.
+
+ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value.
+If the status is any value other than ASYNC_STATUS_OK then the user code should
+not expect to receive a callback from the engine even if one has been set.
+
+An example of the usage of the callback method might be the following. User
+code would initiate cryptographic operations, and the engine code would dispatch
+this operation to hardware, and if the dispatch is successful, then the engine
+code would call ASYNC_pause_job() to return control to the user code. After
+that, user code can perform other tasks. When the hardware completes the
+operation, normally it is detected by a polling function or an interrupt, as the
+user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously,
+then the registered callback will be called.
+
 =head1 RETURN VALUES
 
 ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or
 NULL on error.
 
 ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
-ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
-success or 0 on error.
+ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd,
+ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and
+ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error.
+ASYNC_WAIT_CTX_get_status() returs the engine status.
+
 
 =head1 NOTES
 
@@ -132,6 +193,10 @@ ASYNC_WAIT_CTX_get_fd(), ASYNC_WAIT_CTX_get_all_fds(),
 ASYNC_WAIT_CTX_get_changed_fds() and ASYNC_WAIT_CTX_clear_fd()
 were added in OpenSSL 1.1.0.
 
+ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(),
+ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status()
+were added in OpenSSL 3.0.0.
+
 =head1 COPYRIGHT
 
 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.