docs: document DMA message dirty handling (#755)

Document that on vfu_sgl_write(), it's the client's responsibility to track any dirty pages. Signed-off-by: John Levon <[email protected]>
nutanix · Jul 31, 2023 · 8038da1 · 8038da1
1 parent 56eeb68
commit 8038da1
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 2 deletions.
diff --git a/docs/memory-mapping.md b/docs/memory-mapping.md
@@ -133,7 +133,11 @@ case, then the server may only read or write the region the slower way:
 
 ```
 ...
-vfu_addr_to_sgl(ctx, iova, len, sg, 1, PROT_READ);
+vfu_addr_to_sgl(ctx, iova, len, sg, 1, PROT_WRITE);
 
-vfu_sgl_read(ctx, sg, 1, &buf);
+vfu_sgl_write(ctx, sg, 1, &buf);
 ```
+
+Note that in this case, the server is not expected to report any dirty writes
+via `vfu_sgl_mark_dirty()`: as the client is actually writing to memory, it's
+the client's responsibility to track any dirtying.
diff --git a/include/libvfio-user.h b/include/libvfio-user.h
@@ -869,6 +869,9 @@ vfu_sgl_read(vfu_ctx_t *vfu_ctx, dma_sg_t *sg, size_t cnt, void *data);
  * alternative to reading from a vfu_sgl_get() mapping, if the region is not
  * directly mappable, or DMA notification callbacks have not been provided.
  *
+ * During live migration, this call does not mark any of the written pages as
+ * dirty; the client is expected to track this.
+ *
  * @vfu_ctx: the libvfio-user context
  * @sg: a DMA segment obtained from dma_addr_to_sg
  * @data: data buffer to write