diff options
author | John Levon <john.levon@nutanix.com> | 2021-01-07 19:55:44 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-01-07 19:55:44 +0000 |
commit | 6ec31642f6253f5c19187c1ffb396d5921138b67 (patch) | |
tree | 9dd88104b0d56e63a83a48efbec6887cafc26730 /include/libvfio-user.h | |
parent | 70524c550322948765415d9b0eb29ac766e32e79 (diff) | |
download | libvfio-user-6ec31642f6253f5c19187c1ffb396d5921138b67.zip libvfio-user-6ec31642f6253f5c19187c1ffb396d5921138b67.tar.gz libvfio-user-6ec31642f6253f5c19187c1ffb396d5921138b67.tar.bz2 |
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>
Diffstat (limited to 'include/libvfio-user.h')
-rw-r--r-- | include/libvfio-user.h | 76 |
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. * |