improve variable naming and documentation

Signed-off-by: William Henderson <william.henderson@nutanix.com>

3 files changed, 33 insertions, 23 deletions

diff --git a/include/vfio-user.h b/include/vfio-user.h
index 8434852..620945e 100644
--- a/include/vfio-user.h
+++ b/include/vfio-user.h
@@ -253,7 +253,10 @@ struct vfio_user_device_feature_migration {
 #define VFIO_MIGRATION_STOP_COPY    (1 << 0)
 #define VFIO_MIGRATION_P2P          (1 << 1)
 #endif
-/* PRE_COPY was added in a later kernel version */
+/*
+ * PRE_COPY was added in a later kernel version, after
+ * VFIO_REGION_TYPE_MIGRATION_DEPRECATED had been introduced.
+ */
 #ifndef VFIO_MIGRATION_PRE_COPY
 #define VFIO_MIGRATION_PRE_COPY     (1 << 2)
 #endif
diff --git a/lib/common.h b/lib/common.h
index c53a69e..1b1ee65 100644
--- a/lib/common.h
+++ b/lib/common.h
@@ -93,6 +93,13 @@ _get_bitmap_size(size_t size, size_t pgsize)
     return ROUND_UP(nr_pages, sizeof(uint64_t) * CHAR_BIT) / CHAR_BIT;
 }
 
+/*
+ * The size, in bytes, of the bitmap that represents the given range with the
+ * given page size.
+ * 
+ * Returns -1 and sets errno if the given page size is invalid for the given 
+ * range.
+ */
 static inline ssize_t
 get_bitmap_size(size_t region_size, size_t pgsize)
 {
diff --git a/lib/dma.c b/lib/dma.c
index 45a720a..67ee6c1 100644
--- a/lib/dma.c
+++ b/lib/dma.c
@@ -542,9 +542,9 @@ dma_controller_dirty_page_get(dma_controller_t *dma, vfu_dma_addr_t addr,
                               uint64_t len, size_t pgsize, size_t size,
                               char *bitmap)
 {
-    ssize_t converted_bitmap_size;
     dma_memory_region_t *region;
-    ssize_t bitmap_size;
+    ssize_t server_bitmap_size;
+    ssize_t client_bitmap_size;
     dma_sg_t sg;
     int ret;
 
@@ -581,25 +581,25 @@ dma_controller_dirty_page_get(dma_controller_t *dma, vfu_dma_addr_t addr,
         return ERROR_INT(EINVAL);
     }
 
-    bitmap_size = get_bitmap_size(len, dma->dirty_pgsize);
-    if (bitmap_size < 0) {
-        vfu_log(dma->vfu_ctx, LOG_ERR, "failed to get bitmap size");
-        return bitmap_size;
+    server_bitmap_size = get_bitmap_size(len, dma->dirty_pgsize);
+    if (server_bitmap_size < 0) {
+        vfu_log(dma->vfu_ctx, LOG_ERR, "failed to get server bitmap size");
+        return server_bitmap_size;
     }
 
-    converted_bitmap_size = get_bitmap_size(len, pgsize);
-    if (converted_bitmap_size < 0) {
-        vfu_log(dma->vfu_ctx, LOG_ERR, "failed to get bitmap size");
-        return converted_bitmap_size;
+    client_bitmap_size = get_bitmap_size(len, pgsize);
+    if (client_bitmap_size < 0) {
+        vfu_log(dma->vfu_ctx, LOG_ERR, "failed to get client bitmap size");
+        return client_bitmap_size;
     }
 
     /*
      * They must be equal because this is how much data the client expects to
      * receive.
      */
-    if (size != (size_t)converted_bitmap_size) {
+    if (size != (size_t)client_bitmap_size) {
         vfu_log(dma->vfu_ctx, LOG_ERR, "bad bitmap size %zu != %zu", size,
-                converted_bitmap_size);
+                client_bitmap_size);
         return ERROR_INT(EINVAL);
     }
 
@@ -611,10 +611,10 @@ dma_controller_dirty_page_get(dma_controller_t *dma, vfu_dma_addr_t addr,
     }
 
     if (pgsize == dma->dirty_pgsize) {
-        dirty_page_get_same_pgsize(region, bitmap, bitmap_size);
+        dirty_page_get_same_pgsize(region, bitmap, server_bitmap_size);
     } else {
-        dirty_page_get_different_pgsize(region, bitmap, bitmap_size,
-                                        converted_bitmap_size, pgsize,
+        dirty_page_get_different_pgsize(region, bitmap, server_bitmap_size,
+                                        client_bitmap_size, pgsize,
                                         dma->dirty_pgsize);
     }
 
@@ -657,20 +657,20 @@ dirty_page_get_same_pgsize(dma_memory_region_t *region, char *bitmap,
 
 void
 dirty_page_get_different_pgsize(dma_memory_region_t *region, char *bitmap,
-                                size_t bitmap_size,
-                                size_t converted_bitmap_size, size_t pgsize,
-                                size_t converted_pgsize)
+                                size_t server_bitmap_size,
+                                size_t client_bitmap_size, size_t server_pgsize,
+                                size_t client_pgsize)
 {
     uint8_t bit = 0;
     size_t i;
     int j;
 
-    bool extend = pgsize <= converted_pgsize;
+    bool extend = server_pgsize <= client_pgsize;
     size_t factor = extend ?
-        converted_pgsize / pgsize : pgsize / converted_pgsize;
+        client_pgsize / server_pgsize : server_pgsize / client_pgsize;
 
-    for (i = 0; i < bitmap_size &&
-         bit / CHAR_BIT < (size_t)converted_bitmap_size; i++) {
+    for (i = 0; i < server_bitmap_size &&
+         bit / CHAR_BIT < (size_t)client_bitmap_size; i++) {
         uint8_t out = 0;
 
         dirty_page_exchange(&out, &region->dirty_bitmap[i]);