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 <john.levon@nutanix.com>

2 files changed, 9 insertions, 2 deletions

diff --git a/docs/memory-mapping.md b/docs/memory-mapping.md
index f5c5bce..edd4468 100644
--- 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
index 0a8af2b..7cd28b5 100644
--- 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