re-work access handling (#220)

Various cleanups and fixes to handling of region accesses, including:

- there should be no reason for us to split accesses into 1/2/4/8 byte accesses:
in general, the client will have already be doing that, and if not, there's no
particular reason we should be the ones to split up such larger accesses.

- use a callback for PCI config space reads and writes if one is provided (needs
more work for capabilities)

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

1 files changed, 36 insertions, 40 deletions

diff --git a/include/libvfio-user.h b/include/libvfio-user.h
index 61f94ca..d74087e 100644
--- a/include/libvfio-user.h
+++ b/include/libvfio-user.h
@@ -200,37 +200,18 @@ typedef ssize_t (vfu_region_access_cb_t)(vfu_ctx_t *vfu_ctx, char *buf,
 
 #define VFU_REGION_FLAG_READ    (1 << 0)
 #define VFU_REGION_FLAG_WRITE   (1 << 1)
-#define VFU_REGION_FLAG_MMAP    (1 << 2)    // TODO: how this relates to IO bar?
 #define VFU_REGION_FLAG_RW      (VFU_REGION_FLAG_READ | VFU_REGION_FLAG_WRITE)
-#define VFU_REGION_FLAG_MEM     (1 << 3)    // if unset, bar is IO
+#define VFU_REGION_FLAG_MEM     (1 << 2)    // if unset, bar is IO
 
 /**
- * Set up a region.
+ * Set up a device region.
  *
- * If this is the PCI configuration space, the @size argument is ignored. The
- * size of the region is determined by the PCI type (set when the libvfio-user
- * context is created). Accesses to the PCI configuration space header and the
- * PCI capabilities are handled internally; the user supplied callback is not
- * called.
+ * A region is an area of device memory that can be accessed by the client,
+ * either via VFIO_USER_REGION_READ/WRITE, or directly by mapping the region
+ * into the client's address space if an fd is given.
  *
- * @vfu_ctx: the libvfio-user context
- * @region_idx: region index
- * @size: size of the region
- * @region_access: callback function to access region. If the region is memory
- *  mappable and the client accesses the region or part of sparse area, then
- *  the callback is not called.
- * @flags: region flags (VFU_REGION_FLAG_)
- * @mmap_areas: array of memory mappable areas. This array provides to the
- *  server greater control of which specific areas should be memory mapped by
- *  the client. Each element in the @mmap_areas array describes one such area.
- *  Ignored if @nr_mmap_areas is 0 or if the region is not memory mappable.
- * @nr_mmap_areas: number of sparse areas in @mmap_areas. Must be 0 if the
- *  region is not memory mappable.
- * @fd: file descriptor of the file backing the region if it's a mappable
- *  region. It is the server's responsibility to create a file suitable for
- *  memory mapping by the client. Ignored if the region is not memory mappable.
- *
- * A note on memory-mappable regions: the client can memory map any part of the
+ * A mappable region can be split into mappable sub-areas according to the
+ * @mmap_areas array. Note that the client can memory map any part of the
  * file descriptor, even if not supposed to do so according to @mmap_areas.
  * There is no way in Linux to avoid this.
  *
@@ -241,6 +222,35 @@ typedef ssize_t (vfu_region_access_cb_t)(vfu_ctx_t *vfu_ctx, char *buf,
  * descriptors of these DM targets. This is something we can document and
  * demonstrate in a sample.
  *
+ * Areas that are accessed via such a mapping by definition do not invoke any
+ * given callback.  However, the callback can still be invoked, even on a
+ * mappable area, if the client chooses to call VFIO_USER_REGION_READ/WRITE.
+ *
+ * A VFU_PCI_DEV_CFG_REGION_IDX region, corresponding to PCI config space, has
+ * special handling:
+ *
+ *  - the @size argument is ignored: the region size is always the size defined
+ *    by the relevant PCI specification
+ *  - all accesses to the standard PCI header (i.e. the first 64 bytes of the
+ *    region) are handled by the library
+ *  - all accesses to known PCI capabilities are handled by the library
+ *  - if no callback is provided, reads to other areas are a simple memcpy(),
+ *    and writes are an error
+ *  - otherwise, the callback is expected to handle the access
+ *
+ * @vfu_ctx: the libvfio-user context
+ * @region_idx: region index
+ * @size: size of the region
+ * @region_access: callback function to access region
+ * @flags: region flags (VFU_REGION_FLAG_)
+ * @mmap_areas: array of memory mappable areas; must be provided if the region
+ *  is mappable.
+ * @nr_mmap_areas: number of sparse areas in @mmap_areas; must be provided if
+ *  the region is mappable.
+ * @fd: file descriptor of the file backing the region if the region is
+ *  mappable; it is the server's responsibility to create a file suitable for
+ *  memory mapping by the client.
+ *
  * @returns 0 on success, -1 on error, Sets errno.
  */
 int
@@ -490,20 +500,6 @@ void
 vfu_unmap_sg(vfu_ctx_t *vfu_ctx, const dma_sg_t *sg,
              struct iovec *iov, int cnt);
 
-//FIXME: Remove if we dont need this.
-/**
- * Returns the PCI region given the position and size of an address span in the
- * PCI configuration space.
- *
- * @pos: offset of the address span
- * @count: size of the address span
- * @off: output parameter that receives the relative offset within the region.
- *
- * Returns the PCI region (VFU_PCI_DEV_XXX_REGION_IDX), or -errno on error.
- */
-int
-vfu_get_region(loff_t pos, size_t count, loff_t *off);
-
 /**
  * Read from the dma region exposed by the client.
  *