diff options
author | Thanos Makatos <thanos.makatos@nutanix.com> | 2020-12-15 14:56:32 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-12-15 14:56:32 +0000 |
commit | 8694149b351e3e125aa8f1740f8d5925e7ec112c (patch) | |
tree | 55fae56b5280eddd8c5c23d8c846fe36425e7ba2 /include/libvfio-user.h | |
parent | 3148a598f4ac0711d2f46ef9186e51a4779f1bf1 (diff) | |
download | libvfio-user-8694149b351e3e125aa8f1740f8d5925e7ec112c.zip libvfio-user-8694149b351e3e125aa8f1740f8d5925e7ec112c.tar.gz libvfio-user-8694149b351e3e125aa8f1740f8d5925e7ec112c.tar.bz2 |
send file descriptors for sparse areas in get region info (#201)
Signed-off-by: Thanos Makatos <thanos.makatos@nutanix.com>
Diffstat (limited to 'include/libvfio-user.h')
-rw-r--r-- | include/libvfio-user.h | 59 |
1 files changed, 31 insertions, 28 deletions
diff --git a/include/libvfio-user.h b/include/libvfio-user.h index 342f3e5..d5a8c6a 100644 --- a/include/libvfio-user.h +++ b/include/libvfio-user.h @@ -188,28 +188,6 @@ void * vfu_mmap(vfu_ctx_t * vfu_ctx, off_t offset, size_t length); /** - * Prototype for memory access callback. The program MUST first map device - * memory in its own virtual address space using vfu_mmap, do any additional work - * required, and finally return that memory. When a region is memory mapped, - * libvfio-user calls the previously registered callback with the following - * arguments: - * - * @pvt: private pointer - * @off: offset of memory area being memory mapped - * @len: length of memory area being memory mapped - * - * @returns the memory address returned by vfu_mmap, or MAP_FAILED on failure - */ -typedef unsigned long (vfu_map_region_cb_t) (void *pvt, unsigned long off, - unsigned long len); - -#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 - -/** * Prototype for region access callback. When a region is accessed, libvfio-user * calls the previously registered callback with the following arguments: * @@ -224,6 +202,12 @@ typedef unsigned long (vfu_map_region_cb_t) (void *pvt, unsigned long off, typedef ssize_t (vfu_region_access_cb_t) (void *pvt, char *buf, size_t count, loff_t offset, bool is_write); +#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 + /** * Set up a region. * @@ -236,11 +220,30 @@ typedef ssize_t (vfu_region_access_cb_t) (void *pvt, char *buf, size_t count, * @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 - * @mmap_areas: array of memory mappable areas - * @nr_mmap_areas: size of mmap_areas - * @map: callback function to map 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 + * file descriptor, even if not supposed to do so acocrding to @mmap_areas. + * There is no way in Linux to avoid this. + * + * TODO maybe we should introduce per-sparse region file descriptors so that + * the client cannot possibly memory map areas it's not supposed to. Even if + * the client needs to have region under the same backing file, it is possible + * to create linear device-mapper targets, one for each area, and provide file + * descriptors of these DM targets. This is something we can document and + * demonstrate in a sample. * * @returns 0 on success, -1 on error, Sets errno. */ @@ -248,7 +251,7 @@ int vfu_setup_region(vfu_ctx_t *vfu_ctx, int region_idx, size_t size, vfu_region_access_cb_t *region_access, int flags, struct iovec *mmap_areas, uint32_t nr_mmap_areas, - vfu_map_region_cb_t *map); + int fd); /* * Callback function that is called when the guest resets the device. |