refactor sock send/recv functions (#114)

Use shorter, more readable, function names, add re-jig the wrappers such that
the most common operations are shortest.

5 files changed, 132 insertions, 72 deletions

diff --git a/lib/irq.c b/lib/irq.c
index 4c67915..4fa7513 100644
--- a/lib/irq.c
+++ b/lib/irq.c
@@ -413,10 +413,10 @@ lm_irq_message(lm_ctx_t *lm_ctx, uint32_t subindex)
     }
 
     irq_info.subindex = subindex;
-    ret = send_recv_vfio_user_msg(lm_ctx->conn_fd, msg_id,
-                                  VFIO_USER_VM_INTERRUPT,
-                                  &irq_info, sizeof irq_info,
-                                  NULL, 0, NULL, NULL, 0);
+    ret = vfio_user_msg(lm_ctx->conn_fd, msg_id,
+                        VFIO_USER_VM_INTERRUPT,
+                        &irq_info, sizeof irq_info,
+                        NULL, NULL, 0);
     if (ret < 0) {
         /* FIXME should return -errno */
 	    errno = -ret;
diff --git a/lib/migration.h b/lib/migration.h
index ccbbe1e..535f97b 100644
--- a/lib/migration.h
+++ b/lib/migration.h
@@ -28,10 +28,18 @@
  *
  */
 
+
+// FIXME: license header (and SPDX ?) everywhere
+
 /* FIXME: regularize across private headers */
 #ifndef MUSER_MIGRATION_H
 #define MUSER_MIGRATION_H
 
+/*
+ * These are not public routines, but for convenience, they are used by the
+ * sample/test code as well as privately within libmuser.
+ */
+
 #include <stddef.h>
 
 #include "muser.h"
diff --git a/lib/muser_ctx.c b/lib/muser_ctx.c
index 1b606d5..617a218 100644
--- a/lib/muser_ctx.c
+++ b/lib/muser_ctx.c
@@ -978,8 +978,10 @@ reply:
     } else {
         ret = 0;
     }
-    ret = _send_vfio_user_msg(lm_ctx->conn_fd, hdr.msg_id, true,
-                             0, iovecs, nr_iovecs, NULL, 0, -ret);
+
+    // FIXME: SPEC: should the reply include the command? I'd say yes?
+    ret = vfio_user_send_iovec(lm_ctx->conn_fd, hdr.msg_id, true,
+                               0, iovecs, nr_iovecs, NULL, 0, -ret);
     if (unlikely(ret < 0)) {
         lm_log(lm_ctx, LM_ERR, "failed to complete command: %s",
                 strerror(-ret));
@@ -1478,9 +1480,9 @@ lm_dma_read(lm_ctx_t *lm_ctx, dma_sg_t *sg, void *data)
 
     dma_send.addr = sg->dma_addr;
     dma_send.count = sg->length;
-    ret = send_recv_vfio_user_msg(lm_ctx->conn_fd, msg_id, VFIO_USER_DMA_READ,
-                                  &dma_send, sizeof dma_send, NULL, 0, NULL,
-                                  dma_recv, recv_size);
+    ret = vfio_user_msg(lm_ctx->conn_fd, msg_id, VFIO_USER_DMA_READ,
+                        &dma_send, sizeof dma_send, NULL,
+                        dma_recv, recv_size);
     memcpy(data, dma_recv->data, sg->length); /* FIXME no need for memcpy */
     free(dma_recv);
 
@@ -1504,9 +1506,9 @@ lm_dma_write(lm_ctx_t *lm_ctx, dma_sg_t *sg, void *data)
     dma_send->addr = sg->dma_addr;
     dma_send->count = sg->length;
     memcpy(dma_send->data, data, sg->length); /* FIXME no need to copy! */
-    ret = send_recv_vfio_user_msg(lm_ctx->conn_fd, msg_id, VFIO_USER_DMA_WRITE,
-                                  dma_send, send_size,
-                                  NULL, 0, NULL, &dma_recv, sizeof(dma_recv));
+    ret = vfio_user_msg(lm_ctx->conn_fd, msg_id, VFIO_USER_DMA_WRITE,
+                        dma_send, send_size, NULL,
+                        &dma_recv, sizeof(dma_recv));
     free(dma_send);
 
     return ret;
diff --git a/lib/tran_sock.c b/lib/tran_sock.c
index 2e8e2bc..7834a77 100644
--- a/lib/tran_sock.c
+++ b/lib/tran_sock.c
@@ -131,7 +131,7 @@ out:
 }
 
 int
-_send_vfio_user_msg(int sock, uint16_t msg_id, bool is_reply,
+vfio_user_send_iovec(int sock, uint16_t msg_id, bool is_reply,
                     enum vfio_user_command cmd,
                     struct iovec *iovecs, size_t nr_iovecs,
                     int *fds, int count, int err)
@@ -194,10 +194,9 @@ _send_vfio_user_msg(int sock, uint16_t msg_id, bool is_reply,
 }
 
 int
-send_vfio_user_msg(int sock, uint16_t msg_id, bool is_reply,
-                   enum vfio_user_command cmd,
-                   void *data, size_t data_len,
-                   int *fds, size_t count)
+vfio_user_send(int sock, uint16_t msg_id, bool is_reply,
+               enum vfio_user_command cmd,
+               void *data, size_t data_len)
 {
     /* [0] is for the header. */
     struct iovec iovecs[2] = {
@@ -206,8 +205,17 @@ send_vfio_user_msg(int sock, uint16_t msg_id, bool is_reply,
             .iov_len = data_len
         }
     };
-    return _send_vfio_user_msg(sock, msg_id, is_reply, cmd, iovecs,
-                               ARRAY_SIZE(iovecs), fds, count, 0);
+    return vfio_user_send_iovec(sock, msg_id, is_reply, cmd, iovecs,
+                                ARRAY_SIZE(iovecs), NULL, 0, 0);
+}
+
+int
+send_vfio_user_error(int sock, uint16_t msg_id,
+                     enum vfio_user_command cmd,
+                     int error)
+{
+    return vfio_user_send_iovec(sock, msg_id, true, cmd,
+                                NULL, 0, NULL, 0, error);
 }
 
 /*
@@ -220,7 +228,7 @@ send_vfio_user_msg(int sock, uint16_t msg_id, bool is_reply,
  * better.
  */
 int
-recv_vfio_user_msg(int sock, struct vfio_user_header *hdr, bool is_reply,
+vfio_user_recv(int sock, struct vfio_user_header *hdr, bool is_reply,
                    uint16_t *msg_id, void *data, size_t *len)
 {
     int ret;
@@ -272,19 +280,19 @@ recv_vfio_user_msg(int sock, struct vfio_user_header *hdr, bool is_reply,
 }
 
 /*
- * Like recv_vfio_user_msg(), but will automatically allocate reply data.
+ * Like vfio_user_recv(), but will automatically allocate reply data.
  *
  * FIXME: this does an unconstrained alloc of client-supplied data.
  */
 int
-recv_vfio_user_msg_alloc(int sock, struct vfio_user_header *hdr, bool is_reply,
+vfio_user_recv_alloc(int sock, struct vfio_user_header *hdr, bool is_reply,
                          uint16_t *msg_id, void **datap, size_t *lenp)
 {
     void *data;
     size_t len;
     int ret;
 
-    ret = recv_vfio_user_msg(sock, hdr, is_reply, msg_id, NULL, NULL);
+    ret = vfio_user_recv(sock, hdr, is_reply, msg_id, NULL, NULL);
 
     if (ret != 0) {
         return ret;
@@ -322,30 +330,33 @@ recv_vfio_user_msg_alloc(int sock, struct vfio_user_header *hdr, bool is_reply,
     return 0;
 }
 
+/*
+ * FIXME: all these send/recv handlers need to be made robust against async
+ * messages.
+ */
 int
-_send_recv_vfio_user_msg(int sock, uint16_t msg_id, enum vfio_user_command cmd,
-                         struct iovec *iovecs, size_t nr_iovecs,
-                         int *send_fds, size_t fd_count,
-                         struct vfio_user_header *hdr,
-                         void *recv_data, size_t recv_len)
+vfio_user_msg_iovec(int sock, uint16_t msg_id, enum vfio_user_command cmd,
+                    struct iovec *iovecs, size_t nr_iovecs,
+                    int *send_fds, size_t fd_count,
+                    struct vfio_user_header *hdr,
+                    void *recv_data, size_t recv_len)
 {
-    int ret = _send_vfio_user_msg(sock, msg_id, false, cmd, iovecs, nr_iovecs,
-                                  send_fds, fd_count, 0);
+    int ret = vfio_user_send_iovec(sock, msg_id, false, cmd, iovecs, nr_iovecs,
+                                   send_fds, fd_count, 0);
     if (ret < 0) {
         return ret;
     }
     if (hdr == NULL) {
         hdr = alloca(sizeof *hdr);
     }
-    return recv_vfio_user_msg(sock, hdr, true, &msg_id, recv_data, &recv_len);
+    return vfio_user_recv(sock, hdr, true, &msg_id, recv_data, &recv_len);
 }
 
 int
-send_recv_vfio_user_msg(int sock, uint16_t msg_id, enum vfio_user_command cmd,
-                        void *send_data, size_t send_len,
-                        int *send_fds, size_t fd_count,
-                        struct vfio_user_header *hdr,
-                        void *recv_data, size_t recv_len)
+vfio_user_msg(int sock, uint16_t msg_id, enum vfio_user_command cmd,
+              void *send_data, size_t send_len,
+              struct vfio_user_header *hdr,
+              void *recv_data, size_t recv_len)
 {
     /* [0] is for the header. */
     struct iovec iovecs[2] = {
@@ -354,9 +365,8 @@ send_recv_vfio_user_msg(int sock, uint16_t msg_id, enum vfio_user_command cmd,
             .iov_len = send_len
         }
     };
-    return _send_recv_vfio_user_msg(sock, msg_id, cmd, iovecs,
-                                    ARRAY_SIZE(iovecs), send_fds, fd_count,
-                                    hdr, recv_data, recv_len);
+    return vfio_user_msg_iovec(sock, msg_id, cmd, iovecs, ARRAY_SIZE(iovecs),
+                               NULL, 0, hdr, recv_data, recv_len);
 }
 
 /*
@@ -375,7 +385,8 @@ send_recv_vfio_user_msg(int sock, uint16_t msg_id, enum vfio_user_command cmd,
  * available in newer library versions, so we don't use it.
  */
 int
-parse_version_json(const char *json_str, int *client_max_fdsp, size_t *pgsizep)
+vfio_user_parse_version_json(const char *json_str,
+                             int *client_max_fdsp, size_t *pgsizep)
 {
     struct json_object *jo_caps = NULL;
     struct json_object *jo_top = NULL;
@@ -448,12 +459,12 @@ recv_version(lm_ctx_t *lm_ctx, int sock, uint16_t *msg_idp,
 
     *versionp = NULL;
 
-    ret = recv_vfio_user_msg_alloc(sock, &hdr, false, msg_idp,
+    ret = vfio_user_recv_alloc(sock, &hdr, false, msg_idp,
                                    (void **)&cversion, &vlen);
 
     if (ret < 0) {
         lm_log(lm_ctx, LM_ERR, "failed to receive version: %s", strerror(-ret));
-        goto out;
+        return ret;
     }
 
     if (hdr.cmd != VFIO_USER_VERSION) {
@@ -490,7 +501,8 @@ recv_version(lm_ctx_t *lm_ctx, int sock, uint16_t *msg_idp,
             goto out;
         }
 
-        ret = parse_version_json(json_str, &lm_ctx->client_max_fds, &pgsize);
+        ret = vfio_user_parse_version_json(json_str, &lm_ctx->client_max_fds,
+                                           &pgsize);
 
         if (ret < 0) {
             /* No client-supplied strings in the log for release build. */
@@ -525,6 +537,8 @@ recv_version(lm_ctx_t *lm_ctx, int sock, uint16_t *msg_idp,
 
 out:
     if (ret != 0) {
+        // FIXME: spec, is it OK to just have the header?
+        (void) send_vfio_user_error(sock, *msg_idp, hdr.cmd, ret);
         free(cversion);
         cversion = NULL;
     }
@@ -573,8 +587,8 @@ send_version(lm_ctx_t *lm_ctx, int sock, uint16_t msg_id,
     /* Include the NUL. */
     iovecs[2].iov_len = slen + 1;
 
-    return _send_vfio_user_msg(sock, msg_id, true, VFIO_USER_VERSION,
-                               iovecs, ARRAY_SIZE(iovecs), NULL, 0, 0);
+    return vfio_user_send_iovec(sock, msg_id, true, VFIO_USER_VERSION,
+                                iovecs, ARRAY_SIZE(iovecs), NULL, 0, 0);
 }
 
 static int
diff --git a/lib/tran_sock.h b/lib/tran_sock.h
index cbd6603..9add12c 100644
--- a/lib/tran_sock.h
+++ b/lib/tran_sock.h
@@ -48,44 +48,80 @@
 
 extern struct transport_ops sock_transport_ops;
 
-int
-parse_version_json(const char *json_str, int *client_max_fdsp, size_t *pgsizep);
+/*
+ * Parse JSON supplied from the other side into the known parameters. Note: they
+ * will not be set if not found in the JSON.
+ */
+int vfio_user_parse_version_json(const char *json_str, int *client_max_fdsp,
+                                 size_t *pgsizep);
 
-int
-_send_vfio_user_msg(int sock, uint16_t msg_id, bool is_reply,
-                   enum vfio_user_command cmd,
-                   struct iovec *iovecs, size_t nr_iovecs,
-                   int *fds, int count, int err);
+/*
+ * Send a message to the other end.  The iovecs array should leave the first
+ * entry empty, as it will be used for the header.
+ */
+int vfio_user_send_iovec(int sock, uint16_t msg_id, bool is_reply,
+                         enum vfio_user_command cmd,
+                         struct iovec *iovecs, size_t nr_iovecs,
+                         int *fds, int count,
+                         int err);
 
-int
-send_vfio_user_msg(int sock, uint16_t msg_id, bool is_reply,
+/*
+ * Send a message to the other end with the given data.
+ */
+int vfio_user_send(int sock, uint16_t msg_id, bool is_reply,
                    enum vfio_user_command cmd,
-                   void *data, size_t data_len,
-                   int *fds, size_t count);
-
+                   void *data, size_t data_len);
 
-int
-recv_vfio_user_msg(int sock, struct vfio_user_header *hdr, bool is_reply,
-                   uint16_t *msg_id, void *data, size_t *len);
+/*
+ * Send an empty reply back to the other end with the given errno.
+ */
+int vfio_user_send_error(int sock, uint16_t msg_id,
+                         enum vfio_user_command cmd,
+                         int error);
 
-int
-recv_vfio_user_msg_alloc(int sock, struct vfio_user_header *hdr, bool is_reply,
-                   uint16_t *msg_id, void **datap, size_t *lenp);
+/*
+ * Receive a message from the other end, and place the data into the given
+ * buffer. If data is supplied by the other end, it must be exactly *len in
+ * size.
+ */
+int vfio_user_recv(int sock, struct vfio_user_header *hdr,
+                   bool is_reply, uint16_t *msg_id,
+                   void *data, size_t *len);
 
-int
-_send_recv_vfio_user_msg(int sock, uint16_t msg_id, enum vfio_user_command cmd,
-                         struct iovec *iovecs, size_t nr_iovecs,
-                         int *send_fds, size_t fd_count,
-                         struct vfio_user_header *hdr,
-                         void *recv_data, size_t recv_len);
+/*
+ * Receive a message from the other end, but automatically allocate a buffer for
+ * it, which must be freed by the caller.  If there is no data, *datap is set to
+ * NULL.
+ */
+int vfio_user_recv_alloc(int sock, struct vfio_user_header *hdr,
+                         bool is_reply, uint16_t *msg_id,
+                         void **datap, size_t *lenp);
 
-int
-send_recv_vfio_user_msg(int sock, uint16_t msg_id, enum vfio_user_command cmd,
-                        void *send_data, size_t send_len,
+/*
+ * Send and receive a message to the other end, using iovecs for the send. The
+ * iovecs array should leave the first entry empty, as it will be used for the
+ * header.
+ *
+ * If specified, the given fds are sent to the other side. @hdr is filled with
+ * the reply header if non-NULL.
+ */
+int vfio_user_msg_iovec(int sock, uint16_t msg_id,
+                        enum vfio_user_command cmd,
+                        struct iovec *iovecs, size_t nr_iovecs,
                         int *send_fds, size_t fd_count,
                         struct vfio_user_header *hdr,
                         void *recv_data, size_t recv_len);
 
+/*
+ * Send and receive a message to the other end.  @hdr is filled with the reply
+ * header if non-NULL.
+ */
+int vfio_user_msg(int sock, uint16_t msg_id,
+                  enum vfio_user_command cmd,
+                  void *send_data, size_t send_len,
+                  struct vfio_user_header *hdr,
+                  void *recv_data, size_t recv_len);
+
 #endif /* TRAN_SOCK_H */
 
 /* ex: set tabstop=4 shiftwidth=4 softtabstop=4 expandtab: */