make migration state callback optionally asynchronous (#608)

Some devices need the migration state callback to be asynchronous. The simplest way to implement this is to require from the callback to return -1 and set errno to EBUSY, not process any other new messages (vfu_ctx_run returns -1 and sets errno to EBUSY), and provide a way to the user to complete migration (vfu_migr_done).

Signed-off-by: Thanos Makatos <thanos.makatos@nutanix.com>
Reviewed-by: John Levon <john.levon@nutanix.com>
Reviewed-by: Swapnil Ingle <swapnil.ingle@nutanix.com>

1 files changed, 22 insertions, 0 deletions

diff --git a/include/libvfio-user.h b/include/libvfio-user.h
index 8a4bfe7..de215ff 100644
--- a/include/libvfio-user.h
+++ b/include/libvfio-user.h
@@ -503,6 +503,17 @@ typedef struct {
      *
      * The callback should return -1 on error, setting errno.
      *
+     * When operating in non-blocking mode (LIBVFIO_USER_FLAG_ATTACH_NB was
+     * passed to vfu_create_ctx) and -1 is returned with errno set to EBUSY,
+     * transitioning to the new state becomes asynchronous: libvfio-user does
+     * not send a response to the client and does not process any new messages.
+     * Transitioning to the new device state is completed by calling
+     * vfu_migr_done. This behavior can be beneficial for devices whose
+     * threading model does not allow blocking.
+     *
+     * The user must not call functions vfu_dma_read or vfu_dma_write, doing so
+     * results in undefined behavior.
+     *
      * TODO rename to vfu_migration_state_transition_callback
      * FIXME maybe we should create a single callback and pass the state?
      */
@@ -569,6 +580,17 @@ typedef struct {
 
 } vfu_migration_callbacks_t;
 
+/*
+ * Completes a pending migration state transition. Calling this function when
+ * there is no pending migration state transition results in undefined
+ * behavior.
+ *
+ * @vfu_ctx: the libvfio-user context
+ * @reply_errno: 0 for success or errno on error.
+ */
+void
+vfu_migr_done(vfu_ctx_t *vfu_ctx, int reply_errno);
+
 
 #ifndef VFIO_DEVICE_STATE_STOP