re-work SGL API (#675)

Harmonize and rename the vfu_*sg() APIs to better reflect their functionality:
in our case, there is no mapping happening as part of these calls, they are
merely housekeeping for range splitting, dirty tracking, and so on.

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

7 files changed, 68 insertions, 68 deletions

diff --git a/test/py/libvfio_user.py b/test/py/libvfio_user.py
index aeaefa5..4bdb761 100644
--- a/test/py/libvfio_user.py
+++ b/test/py/libvfio_user.py
@@ -611,12 +611,12 @@ lib.vfu_setup_device_dma.argtypes = (c.c_void_p, vfu_dma_register_cb_t,
 lib.vfu_setup_device_migration_callbacks.argtypes = (c.c_void_p,
     c.POINTER(vfu_migration_callbacks_t), c.c_uint64)
 lib.dma_sg_size.restype = (c.c_size_t)
-lib.vfu_addr_to_sg.argtypes = (c.c_void_p, c.c_void_p, c.c_size_t,
-                               c.POINTER(dma_sg_t), c.c_int, c.c_int)
-lib.vfu_map_sg.argtypes = (c.c_void_p, c.POINTER(dma_sg_t), c.POINTER(iovec_t),
-                           c.c_int, c.c_int)
-lib.vfu_unmap_sg.argtypes = (c.c_void_p, c.POINTER(dma_sg_t),
-                             c.POINTER(iovec_t), c.c_int)
+lib.vfu_addr_to_sgl.argtypes = (c.c_void_p, c.c_void_p, c.c_size_t,
+                                c.POINTER(dma_sg_t), c.c_size_t, c.c_int)
+lib.vfu_sgl_get.argtypes = (c.c_void_p, c.POINTER(dma_sg_t),
+                            c.POINTER(iovec_t), c.c_size_t, c.c_int)
+lib.vfu_sgl_put.argtypes = (c.c_void_p, c.POINTER(dma_sg_t),
+                            c.POINTER(iovec_t), c.c_size_t)
 
 lib.vfu_create_ioeventfd.argtypes = (c.c_void_p, c.c_uint32, c.c_int,
                                      c.c_size_t, c.c_uint32, c.c_uint32,
@@ -1147,21 +1147,22 @@ def dma_sg_size():
     return lib.dma_sg_size()
 
 
-def vfu_addr_to_sg(ctx, dma_addr, length, max_sg=1,
-                   prot=(mmap.PROT_READ | mmap.PROT_WRITE)):
+def vfu_addr_to_sgl(ctx, dma_addr, length, max_nr_sgs=1,
+                    prot=(mmap.PROT_READ | mmap.PROT_WRITE)):
     assert ctx is not None
 
-    sg = (dma_sg_t * max_sg)()
+    sg = (dma_sg_t * max_nr_sgs)()
 
-    return (lib.vfu_addr_to_sg(ctx, dma_addr, length, sg, max_sg, prot), sg)
+    return (lib.vfu_addr_to_sgl(ctx, dma_addr, length,
+                                sg, max_nr_sgs, prot), sg)
 
 
-def vfu_map_sg(ctx, sg, iovec, cnt=1, flags=0):
-    return lib.vfu_map_sg(ctx, sg, iovec, cnt, flags)
+def vfu_sgl_get(ctx, sg, iovec, cnt=1, flags=0):
+    return lib.vfu_sgl_get(ctx, sg, iovec, cnt, flags)
 
 
-def vfu_unmap_sg(ctx, sg, iovec, cnt=1):
-    return lib.vfu_unmap_sg(ctx, sg, iovec, cnt)
+def vfu_sgl_put(ctx, sg, iovec, cnt=1):
+    return lib.vfu_sgl_put(ctx, sg, iovec, cnt)
 
 
 def vfu_create_ioeventfd(ctx, region_idx, fd, offset, size, flags, datamatch):
diff --git a/test/py/meson.build b/test/py/meson.build
index e8266e7..d9c97b3 100644
--- a/test/py/meson.build
+++ b/test/py/meson.build
@@ -37,7 +37,6 @@ python_tests = [
     'test_dma_map.py',
     'test_dma_unmap.py',
     'test_irq_trigger.py',
-    'test_map_unmap_sg.py',
     'test_migration.py',
     'test_negotiate.py',
     'test_pci_caps.py',
@@ -45,6 +44,7 @@ python_tests = [
     'test_quiesce.py',
     'test_request_errors.py',
     'test_setup_region.py',
+    'test_sgl_get_put.py',
     'test_vfu_create_ctx.py',
     'test_vfu_realize_ctx.py',
 ]
diff --git a/test/py/test_dirty_pages.py b/test/py/test_dirty_pages.py
index 9f892bd..6cf87fb 100644
--- a/test/py/test_dirty_pages.py
+++ b/test/py/test_dirty_pages.py
@@ -312,46 +312,45 @@ iovec3 = None
 
 
 def test_dirty_pages_get_modified():
-    ret, sg1 = vfu_addr_to_sg(ctx, dma_addr=0x10000, length=0x1000)
+    ret, sg1 = vfu_addr_to_sgl(ctx, dma_addr=0x10000, length=0x1000)
     assert ret == 1
     iovec1 = iovec_t()
-    ret = vfu_map_sg(ctx, sg1, iovec1)
+    ret = vfu_sgl_get(ctx, sg1, iovec1)
     assert ret == 0
 
     # read only
-    ret, sg2 = vfu_addr_to_sg(ctx, dma_addr=0x11000, length=0x1000,
-                              prot=mmap.PROT_READ)
+    ret, sg2 = vfu_addr_to_sgl(ctx, dma_addr=0x11000, length=0x1000,
+                               prot=mmap.PROT_READ)
     assert ret == 1
     iovec2 = iovec_t()
-    ret = vfu_map_sg(ctx, sg2, iovec2)
+    ret = vfu_sgl_get(ctx, sg2, iovec2)
     assert ret == 0
 
-    ret, sg3 = vfu_addr_to_sg(ctx, dma_addr=0x12000, length=0x1000)
+    ret, sg3 = vfu_addr_to_sgl(ctx, dma_addr=0x12000, length=0x1000)
     assert ret == 1
     iovec3 = iovec_t()
-    ret = vfu_map_sg(ctx, sg3, iovec3)
+    ret = vfu_sgl_get(ctx, sg3, iovec3)
     assert ret == 0
 
-    ret, sg4 = vfu_addr_to_sg(ctx, dma_addr=0x14000, length=0x4000)
+    ret, sg4 = vfu_addr_to_sgl(ctx, dma_addr=0x14000, length=0x4000)
     assert ret == 1
     iovec4 = iovec_t()
-    ret = vfu_map_sg(ctx, sg4, iovec4)
+    ret = vfu_sgl_get(ctx, sg4, iovec4)
     assert ret == 0
 
-    # not unmapped yet, dirty bitmap should be zero, but dirty maps will have
-    # been marked dirty still
+    # not put yet, dirty bitmap should be zero
     bitmap = get_dirty_page_bitmap()
     assert bitmap == 0b00000000
 
-    # unmap segments, dirty bitmap should be updated
-    vfu_unmap_sg(ctx, sg1, iovec1)
-    vfu_unmap_sg(ctx, sg4, iovec4)
+    # put SGLs, dirty bitmap should be updated
+    vfu_sgl_put(ctx, sg1, iovec1)
+    vfu_sgl_put(ctx, sg4, iovec4)
     bitmap = get_dirty_page_bitmap()
     assert bitmap == 0b11110001
 
-    # after another two unmaps, should just be one dirty page
-    vfu_unmap_sg(ctx, sg2, iovec2)
-    vfu_unmap_sg(ctx, sg3, iovec3)
+    # after another two puts, should just be one dirty page
+    vfu_sgl_put(ctx, sg2, iovec2)
+    vfu_sgl_put(ctx, sg3, iovec3)
     bitmap = get_dirty_page_bitmap()
     assert bitmap == 0b00000100
 
@@ -393,12 +392,12 @@ def test_dirty_pages_bitmap_with_quiesce():
 
     quiesce_errno = errno.EBUSY
 
-    ret, sg1 = vfu_addr_to_sg(ctx, dma_addr=0x10000, length=0x1000)
+    ret, sg1 = vfu_addr_to_sgl(ctx, dma_addr=0x10000, length=0x1000)
     assert ret == 1
     iovec1 = iovec_t()
-    ret = vfu_map_sg(ctx, sg1, iovec1)
+    ret = vfu_sgl_get(ctx, sg1, iovec1)
     assert ret == 0
-    vfu_unmap_sg(ctx, sg1, iovec1)
+    vfu_sgl_put(ctx, sg1, iovec1)
 
     send_dirty_page_bitmap(busy=True)
 
diff --git a/test/py/test_dma_map.py b/test/py/test_dma_map.py
index f33d110..e8ce8f2 100644
--- a/test/py/test_dma_map.py
+++ b/test/py/test_dma_map.py
@@ -119,7 +119,7 @@ def test_dma_map_busy(mock_dma_register, mock_quiesce):
     mock_dma_register.assert_called_once()
 
     # check that the DMA region has been added
-    count, sgs = vfu_addr_to_sg(ctx, 0x10000, 0x1000)
+    count, sgs = vfu_addr_to_sgl(ctx, 0x10000, 0x1000)
     assert len(sgs) == 1
     sg = sgs[0]
     assert sg.dma_addr == 0x10000 and sg.region == 0 and sg.length == 0x1000 \
@@ -224,7 +224,7 @@ def test_dma_map_busy_reply_fail(mock_dma_register, mock_quiesce, mock_reset):
     mock_reset.assert_called_once()
 
     # check that the DMA region was NOT added
-    count, sgs = vfu_addr_to_sg(ctx, 0x10000, 0x1000)
+    count, sgs = vfu_addr_to_sgl(ctx, 0x10000, 0x1000)
     assert count == -1
     assert c.get_errno() == errno.ENOENT
 
diff --git a/test/py/test_quiesce.py b/test/py/test_quiesce.py
index f283ccc..0e2a980 100644
--- a/test/py/test_quiesce.py
+++ b/test/py/test_quiesce.py
@@ -102,7 +102,7 @@ def test_device_quiesce_error_after_busy(mock_quiesce, mock_dma_register):
     mock_dma_register.assert_not_called()
 
     # check that the DMA region was NOT added
-    count, sgs = vfu_addr_to_sg(ctx, 0x10000, 0x1000)
+    count, sgs = vfu_addr_to_sgl(ctx, 0x10000, 0x1000)
     assert count == -1
     assert c.get_errno() == errno.ENOENT
 
@@ -110,18 +110,18 @@ def test_device_quiesce_error_after_busy(mock_quiesce, mock_dma_register):
 # DMA map/unmap, migration device state transition, and reset callbacks
 # have the same function signature in Python
 def _side_effect(ctx, _):
-    count, sgs = vfu_addr_to_sg(ctx, 0x10000, 0x1000)
+    count, sgs = vfu_addr_to_sgl(ctx, 0x10000, 0x1000)
     assert count == 1
     sg = sgs[0]
     assert sg.dma_addr == 0x10000 and sg.region == 0 \
         and sg.length == 0x1000 and sg.offset == 0 and sg.writeable
     iovec = iovec_t()
-    ret = vfu_map_sg(ctx, sg, iovec)
+    ret = vfu_sgl_get(ctx, sg, iovec)
     assert ret == 0, "%s" % c.get_errno()
     assert iovec.iov_base != 0
     assert iovec.iov_len == 0x1000
     assert ret == 0
-    vfu_unmap_sg(ctx, sg, iovec)
+    vfu_sgl_put(ctx, sg, iovec)
     return 0
 
 
diff --git a/test/py/test_map_unmap_sg.py b/test/py/test_sgl_get_put.py
index fd606f4..d44dc6e 100644
--- a/test/py/test_map_unmap_sg.py
+++ b/test/py/test_sgl_get_put.py
@@ -40,7 +40,7 @@ def test_dma_sg_size():
     assert size == len(dma_sg_t())
 
 
-def test_map_sg_with_invalid_region():
+def test_sgl_get_with_invalid_region():
     global ctx
 
     ctx = prepare_ctx_for_dma()
@@ -48,12 +48,12 @@ def test_map_sg_with_invalid_region():
 
     sg = dma_sg_t()
     iovec = iovec_t()
-    ret = vfu_map_sg(ctx, sg, iovec)
+    ret = vfu_sgl_get(ctx, sg, iovec)
     assert ret == -1
     assert ctypes.get_errno() == errno.EINVAL
 
 
-def test_map_sg_without_fd():
+def test_sgl_get_without_fd():
     sock = connect_client(ctx)
 
     payload = vfio_user_dma_map(argsz=len(vfio_user_dma_map()),
@@ -64,14 +64,14 @@ def test_map_sg_without_fd():
     sg = dma_sg_t()
     iovec = iovec_t()
     sg.region = 0
-    ret = vfu_map_sg(ctx, sg, iovec)
+    ret = vfu_sgl_get(ctx, sg, iovec)
     assert ret == -1
     assert ctypes.get_errno() == errno.EFAULT
 
     disconnect_client(ctx, sock)
 
 
-def test_map_multiple_sge():
+def test_get_multiple_sge():
     sock = connect_client(ctx)
     regions = 4
     f = tempfile.TemporaryFile()
@@ -83,12 +83,12 @@ def test_map_multiple_sge():
             offset=0, addr=0x1000 * i, size=4096)
         msg(ctx, sock, VFIO_USER_DMA_MAP, payload, fds=[f.fileno()])
 
-    ret, sg = vfu_addr_to_sg(ctx, dma_addr=0x1000, length=4096 * 3, max_sg=3,
-                             prot=mmap.PROT_READ)
+    ret, sg = vfu_addr_to_sgl(ctx, dma_addr=0x1000, length=4096 * 3,
+                              max_nr_sgs=3, prot=mmap.PROT_READ)
     assert ret == 3
 
     iovec = (iovec_t * 3)()
-    ret = vfu_map_sg(ctx, sg, iovec, cnt=3)
+    ret = vfu_sgl_get(ctx, sg, iovec, cnt=3)
     assert ret == 0
     assert iovec[0].iov_len == 4096
     assert iovec[1].iov_len == 4096
@@ -97,7 +97,7 @@ def test_map_multiple_sge():
     disconnect_client(ctx, sock)
 
 
-def test_unmap_sg():
+def test_sgl_put():
     sock = connect_client(ctx)
     regions = 4
     f = tempfile.TemporaryFile()
@@ -109,19 +109,19 @@ def test_unmap_sg():
             offset=0, addr=0x1000 * i, size=4096)
         msg(ctx, sock, VFIO_USER_DMA_MAP, payload, fds=[f.fileno()])
 
-    ret, sg = vfu_addr_to_sg(ctx, dma_addr=0x1000, length=4096 * 3, max_sg=3,
-                             prot=mmap.PROT_READ)
+    ret, sg = vfu_addr_to_sgl(ctx, dma_addr=0x1000, length=4096 * 3,
+                              max_nr_sgs=3, prot=mmap.PROT_READ)
     assert ret == 3
 
     iovec = (iovec_t * 3)()
-    ret = vfu_map_sg(ctx, sg, iovec, cnt=3)
+    ret = vfu_sgl_get(ctx, sg, iovec, cnt=3)
     assert ret == 0
-    vfu_unmap_sg(ctx, sg, iovec, cnt=3)
+    vfu_sgl_put(ctx, sg, iovec, cnt=3)
 
     disconnect_client(ctx, sock)
 
 
-def test_map_unmap_sg_cleanup():
+def test_sgl_get_put_cleanup():
     vfu_destroy_ctx(ctx)
 
 # ex: set tabstop=4 shiftwidth=4 softtabstop=4 expandtab:
diff --git a/test/unit-tests.c b/test/unit-tests.c
index 97b06f1..cdb88a2 100644
--- a/test/unit-tests.c
+++ b/test/unit-tests.c
@@ -310,7 +310,7 @@ test_dma_controller_remove_region_unmapped(void **state UNUSED)
 }
 
 static void
-test_dma_addr_to_sg(void **state UNUSED)
+test_dma_addr_to_sgl(void **state UNUSED)
 {
     dma_memory_region_t *r, *r1;
     struct iovec iov[2] = { };
@@ -325,8 +325,8 @@ test_dma_addr_to_sg(void **state UNUSED)
 
     /* fast path, region hint hit */
     r->info.prot = PROT_WRITE;
-    ret = dma_addr_to_sg(vfu_ctx.dma, (vfu_dma_addr_t)0x2000,
-                         0x400, sg, 1, PROT_READ);
+    ret = dma_addr_to_sgl(vfu_ctx.dma, (vfu_dma_addr_t)0x2000,
+                          0x400, sg, 1, PROT_READ);
     assert_int_equal(1, ret);
     assert_int_equal(r->info.iova.iov_base, sg[0].dma_addr);
     assert_int_equal(0, sg[0].region);
@@ -337,20 +337,20 @@ test_dma_addr_to_sg(void **state UNUSED)
 
     errno = 0;
     r->info.prot = PROT_WRITE;
-    ret = dma_addr_to_sg(vfu_ctx.dma, (vfu_dma_addr_t)0x6000,
-                         0x400, sg, 1, PROT_READ);
+    ret = dma_addr_to_sgl(vfu_ctx.dma, (vfu_dma_addr_t)0x6000,
+                          0x400, sg, 1, PROT_READ);
     assert_int_equal(-1, ret);
     assert_int_equal(ENOENT, errno);
 
     r->info.prot = PROT_READ;
-    ret = dma_addr_to_sg(vfu_ctx.dma, (vfu_dma_addr_t)0x2000,
-                         0x400, sg, 1, PROT_WRITE);
+    ret = dma_addr_to_sgl(vfu_ctx.dma, (vfu_dma_addr_t)0x2000,
+                          0x400, sg, 1, PROT_WRITE);
     assert_int_equal(-1, ret);
     assert_int_equal(EACCES, errno);
 
     r->info.prot = PROT_READ|PROT_WRITE;
-    ret = dma_addr_to_sg(vfu_ctx.dma, (vfu_dma_addr_t)0x2000,
-                         0x400, sg, 1, PROT_READ);
+    ret = dma_addr_to_sgl(vfu_ctx.dma, (vfu_dma_addr_t)0x2000,
+                          0x400, sg, 1, PROT_READ);
     assert_int_equal(1, ret);
 
     vfu_ctx.dma->nregions = 2;
@@ -359,8 +359,8 @@ test_dma_addr_to_sg(void **state UNUSED)
     r1->info.iova.iov_len = 0x2000;
     r1->info.vaddr = (void *)0xcafebabe;
     r1->info.prot = PROT_WRITE;
-    ret = dma_addr_to_sg(vfu_ctx.dma, (vfu_dma_addr_t)0x1000,
-                         0x5000, sg, 2, PROT_READ);
+    ret = dma_addr_to_sgl(vfu_ctx.dma, (vfu_dma_addr_t)0x1000,
+                          0x5000, sg, 2, PROT_READ);
     assert_int_equal(2, ret);
     assert_int_equal(0x4000, sg[0].length);
     assert_int_equal(r->info.iova.iov_base, sg[0].dma_addr);
@@ -374,7 +374,7 @@ test_dma_addr_to_sg(void **state UNUSED)
     assert_int_equal(0, sg[1].offset);
     assert_true(vfu_sg_is_mappable(&vfu_ctx, &sg[1]));
 
-    assert_int_equal(0, dma_map_sg(vfu_ctx.dma, sg, iov, 2));
+    assert_int_equal(0, dma_sgl_get(vfu_ctx.dma, sg, iov, 2));
     assert_int_equal(r->info.vaddr + sg[0].offset, iov[0].iov_base);
     assert_int_equal(sg[0].length, iov[0].iov_len);
     assert_int_equal(r1->info.vaddr + sg[1].offset, iov[1].iov_base);
@@ -672,7 +672,7 @@ main(void)
         cmocka_unit_test_setup(test_dma_controller_add_region_no_fd, setup),
         cmocka_unit_test_setup(test_dma_controller_remove_region_mapped, setup),
         cmocka_unit_test_setup(test_dma_controller_remove_region_unmapped, setup),
-        cmocka_unit_test_setup(test_dma_addr_to_sg, setup),
+        cmocka_unit_test_setup(test_dma_addr_to_sgl, setup),
         cmocka_unit_test_setup(test_vfu_setup_device_dma, setup),
         cmocka_unit_test_setup(test_migration_state_transitions, setup),
         cmocka_unit_test_setup_teardown(test_setup_migration_region_size_ok,