diff options
author | swapnili <swapnil.ingle@nutanix.com> | 2020-11-24 21:55:47 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-11-24 21:55:47 +0100 |
commit | 5429a84fe3b7def278ad1df6819d2ad7467ee5b0 (patch) | |
tree | e2f7be049a096eae9a16bf84d13f9dc1a62b8cd6 /include | |
parent | d33f124c5b0335c0525187e820c6b42be0bae743 (diff) | |
download | libvfio-user-5429a84fe3b7def278ad1df6819d2ad7467ee5b0.zip libvfio-user-5429a84fe3b7def278ad1df6819d2ad7467ee5b0.tar.gz libvfio-user-5429a84fe3b7def278ad1df6819d2ad7467ee5b0.tar.bz2 |
Api refactoring (#115)
API refactoring
Diffstat (limited to 'include')
-rw-r--r-- | include/muser.h | 330 |
1 files changed, 158 insertions, 172 deletions
diff --git a/include/muser.h b/include/muser.h index 7c18490..be8b0d0 100644 --- a/include/muser.h +++ b/include/muser.h @@ -62,13 +62,6 @@ typedef struct { typedef struct lm_ctx lm_ctx_t; -// Region flags. -#define LM_REG_FLAG_READ (1 << 0) -#define LM_REG_FLAG_WRITE (1 << 1) -#define LM_REG_FLAG_MMAP (1 << 2) // TODO: how this relates to IO bar? -#define LM_REG_FLAG_RW (LM_REG_FLAG_READ | LM_REG_FLAG_WRITE) -#define LM_REG_FLAG_MEM (1 << 3) // if unset, bar is IO - struct lm_mmap_area { uint64_t start; uint64_t size; @@ -80,39 +73,24 @@ struct lm_sparse_mmap_areas { }; /** - * Prototype for region access callback. When a region is accessed, libmuser - * calls the previously registered callback with the following arguments: - * - * @pvt: private data originally set in dev_info - * @buf: buffer containing the data to be written or data to be read into - * @count: number of bytes being read or written - * @offset: byte offset within the region - * @is_write: whether or not this is a write - * - * @returns the number of bytes read or written, or a negative integer on error - */ -typedef ssize_t (lm_region_access_t) (void *pvt, char *buf, size_t count, - loff_t offset, bool is_write); - -/** * Prototype for memory access callback. The program MUST first map device * memory in its own virtual address space using lm_mmap, do any additional * work required, and finally return that memory. When a region is memory * mapped, libmuser calls previously register callback with the following * arguments: * - * @pvt: private data originally set in dev_info + * @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 lm_mmap, or MAP_FAILED on failure */ -typedef unsigned long (lm_map_region_t) (void *pvt, unsigned long off, +typedef unsigned long (lm_map_region_cb_t) (void *pvt, unsigned long off, unsigned long len); /** * Creates a mapping of a device region into the caller's virtual memory. It - * must be called by lm_map_region_t. + * must be called by lm_map_region_cb_t. * * @lm_ctx: the libmuser context to create mapping from * @offset: offset of the region being mapped @@ -122,81 +100,6 @@ typedef unsigned long (lm_map_region_t) (void *pvt, unsigned long off, */ void *lm_mmap(lm_ctx_t * lm_ctx, off_t offset, size_t length); -typedef struct { - - /* - * Region flags, see LM_REG_FLAG_XXX above. - */ - uint32_t flags; - - /* - * Size of the region. - */ - uint32_t size; - - /* - * Callback function that is called when the region is read or written. - * Note that the memory of the region is owned by the user, except for the - * standard header (first 64 bytes) of the PCI configuration space. - */ - lm_region_access_t *fn; - - /* - * Callback function that is called when the region is memory mapped. - * Required if LM_REG_FLAG_MEM is set, otherwise ignored. - */ - lm_map_region_t *map; - struct lm_sparse_mmap_areas *mmap_areas; /* sparse mmap areas */ -} lm_reg_info_t; - -enum { - LM_DEV_INTX_IRQ_IDX, - LM_DEV_MSI_IRQ_IDX, - LM_DEV_MSIX_IRQ_IDX, - LM_DEV_ERR_IRQ_INDEX, - LM_DEV_REQ_IRQ_INDEX, - LM_DEV_NUM_IRQS -}; - -/* FIXME these are PCI regions */ -enum { - LM_DEV_BAR0_REG_IDX, - LM_DEV_BAR1_REG_IDX, - LM_DEV_BAR2_REG_IDX, - LM_DEV_BAR3_REG_IDX, - LM_DEV_BAR4_REG_IDX, - LM_DEV_BAR5_REG_IDX, - LM_DEV_ROM_REG_IDX, - LM_DEV_CFG_REG_IDX, - LM_DEV_VGA_REG_IDX, - LM_DEV_NUM_REGS, /* TODO rename to LM_DEV_NUM_PCI_REGS */ -}; - -typedef struct { - uint32_t irq_count[LM_DEV_NUM_IRQS]; - - /* - * Per-region information. Only supported regions need to be defined, - * unsupported regions should be left to 0. - */ - lm_reg_info_t reg_info[LM_DEV_NUM_REGS]; - - /* - * Device and vendor ID. - */ - lm_pci_hdr_id_t id; - - /* - * Subsystem vendor and device ID. - */ - lm_pci_hdr_ss_t ss; - - /* - * Class code. - */ - lm_pci_hdr_cc_t cc; -} lm_pci_info_t; - /* * Returns a pointer to the standard part of the PCI configuration space. */ @@ -212,8 +115,9 @@ typedef enum { /** * Callback function signature for log function - * + * @pvt: private pointer * @lm_log_fn_t: typedef for log function. + * @msg: message */ typedef void (lm_log_fn_t) (void *pvt, lm_log_lvl_t lvl, const char *msg); @@ -254,6 +158,10 @@ typedef enum { * FIXME the names of migration callback functions are probably far too long, * but for now it helps with the implementation. */ +/** + * Migration callback function. + * @pvt: private pointer + */ typedef int (lm_migration_callback_t)(void *pvt); typedef enum { @@ -318,85 +226,168 @@ typedef struct { struct lm_sparse_mmap_areas *mmap_areas; } lm_migration_t; +/* + * Attaching to the transport is non-blocking. The library will not attempt + * to attach during context creation time. The caller must then manually + * call lm_ctx_try_attach(), which is non-blocking, as many times as + * necessary. + */ +#define LM_FLAG_ATTACH_NB (1 << 0) + /** - * Device information structure, used to create the lm_ctx. - * To be filled and passed to lm_ctx_create() + * Creates libmuser context. + * @trans: transport type + * @path: path to socket file. + * @flags: context flag + * @log: log function + * @log_lvl: logging level + * @pvt: private data + * @returns the lm_ctx to be used or NULL on error. Sets errno. */ -typedef struct { - char *uuid; +lm_ctx_t *lm_create_ctx(lm_trans_t trans, const char *path, + int flags, lm_log_fn_t *log, lm_log_lvl_t log_lvl, + void *pvt); - /* - * Private data passed to various lm_XXX functions. - */ - void *pvt; +//TODO: Check other PCI header registers suitable to be filled by device. +// Or should we pass whole lm_pci_hdr_t to be filled by user. +/** + * Setup PCI header data. + * @lm_ctx: the libmuser context + * @id: Device and vendor ID + * @ss: Subsystem vendor and device ID + * @cc: Class code + * @extended: support extended PCI config space + */ +int lm_pci_setup_config_hdr(lm_ctx_t *lm_ctx, lm_pci_hdr_id_t id, + lm_pci_hdr_ss_t ss, lm_pci_hdr_cc_t cc, + bool extended); - /* - * Whether an extended PCI configuration space should be created. - */ - bool extended; +//TODO: Support variable size capabilities. +/** + * Setup PCI capabilities. + * @lm_ctx: the libmuser context + * @caps: array of (lm_cap_t *) + * *nr_caps: number of elements in @caps + */ +int lm_pci_setup_caps(lm_ctx_t *lm_ctx, lm_cap_t **caps, int nr_caps); - /* - * Function to call for logging. Optional. - */ - lm_log_fn_t *log; +// Region flags. +#define LM_REG_FLAG_READ (1 << 0) +#define LM_REG_FLAG_WRITE (1 << 1) +#define LM_REG_FLAG_MMAP (1 << 2) // TODO: how this relates to IO bar? +#define LM_REG_FLAG_RW (LM_REG_FLAG_READ | LM_REG_FLAG_WRITE) +#define LM_REG_FLAG_MEM (1 << 3) // if unset, bar is IO - /* - * Log level. Messages above this level are not logged. Optional - */ - lm_log_lvl_t log_lvl; +/** + * Prototype for region access callback. When a region is accessed, libmuser + * calls the previously registered callback with the following arguments: + * + * @pvt: private data originally passed by lm_create_ctx() + * @buf: buffer containing the data to be written or data to be read into + * @count: number of bytes being read or written + * @offset: byte offset within the region + * @is_write: whether or not this is a write + * + * @returns the number of bytes read or written, or a negative integer on error + */ +typedef ssize_t (lm_region_access_cb_t) (void *pvt, char *buf, size_t count, + loff_t offset, bool is_write); - /* - * PCI configuration. - */ - lm_pci_info_t pci_info; +/* FIXME these are PCI regions */ +enum { + LM_DEV_BAR0_REG_IDX, + LM_DEV_BAR1_REG_IDX, + LM_DEV_BAR2_REG_IDX, + LM_DEV_BAR3_REG_IDX, + LM_DEV_BAR4_REG_IDX, + LM_DEV_BAR5_REG_IDX, + LM_DEV_ROM_REG_IDX, + LM_DEV_CFG_REG_IDX, + LM_DEV_VGA_REG_IDX, + LM_DEV_NUM_REGS, /* TODO rename to LM_DEV_NUM_PCI_REGS */ +}; - /* - * Function that is called when the guest resets the device. Optional. - */ - int (*reset) (void *pvt); +/** + * Set up a region. + * @lm_ctx: the libmuser context + * @region_idx: region index + * @size: size of the region + * @region_access: callback function to access region + * @flags: region flags + * @mmap_areas: mmap areas info + * @region_map: callback function to map region + */ +int lm_setup_region(lm_ctx_t *lm_ctx, int region_idx, size_t size, + lm_region_access_cb_t *region_access, int flags, + struct lm_sparse_mmap_areas *mmap_areas, + lm_map_region_cb_t *map); - /* - * Function that is called when the guest maps a DMA region. Optional. - */ - void (*map_dma) (void *pvt, uint64_t iova, uint64_t len); +/* + * Callback function that is called when the guest resets the device. + * @pvt: private pointer + */ +typedef int (lm_reset_cb_t) (void *pvt); - /* - * Function that is called when the guest unmaps a DMA region. The device - * must release all references to that region before the callback returns. - * This is required if you want to be able to access guest memory. - */ - int (*unmap_dma) (void *pvt, uint64_t iova); +/* + * Function that is called when the guest maps a DMA region. Optional. + * @pvt: private pointer + * @iova: iova address + * @len: length + */ +typedef void (lm_map_dma_cb_t) (void *pvt, uint64_t iova, uint64_t len); - lm_trans_t trans; +/* + * Function that is called when the guest unmaps a DMA region. The device + * must release all references to that region before the callback returns. + * This is required if you want to be able to access guest memory. + * @pvt: private pointer + * @iova: iova address + * @len: length + */ +typedef int (lm_unmap_dma_cb_t) (void *pvt, uint64_t iova, uint64_t len); - /* - * Attaching to the transport is non-blocking. The library will not attempt - * to attach during context creation time. The caller must then manually - * call lm_ctx_try_attach(), which is non-blocking, as many times as - * necessary. - */ -#define LM_FLAG_ATTACH_NB (1 << 0) - uint64_t flags; +/** + * Setup device reset callback. + * @lm_ctx: the libmuser context + * @reset: device reset callback (optional) + */ +int lm_setup_device_reset_cb(lm_ctx_t *lm_ctx, lm_reset_cb_t *reset); - /* - * PCI capabilities. - */ - int nr_caps; - lm_cap_t **caps; +/** + * Setup device DMA map/unmap callbacks. + * @lm_ctx: the libmuser context + * @map_dma: DMA region map callback (optional) + * @unmap_dma: DMA region unmap callback (optional) + */ - lm_migration_t migration; +int lm_setup_device_dma_cb(lm_ctx_t *lm_ctx, lm_map_dma_cb_t *map_dma, + lm_unmap_dma_cb_t *unmap_dma); -} lm_dev_info_t; +enum lm_dev_irq_type { + LM_DEV_INTX_IRQ, + LM_DEV_MSI_IRQ, + LM_DEV_MSIX_IRQ, + LM_DEV_ERR_IRQ, + LM_DEV_REQ_IRQ, + LM_DEV_NUM_IRQS +}; /** - * Creates libmuser context. - * - * @dev_info: device information used to create the context. - * - * @returns the lm_ctx to be used or NULL on error. Sets errno. + * Setup device IRQ counts. + * @lm_ctx: the libmuser context + * @type: IRQ type (LM_DEV_INTX_IRQ ... LM_DEV_REQ_IRQ) + * @count: number of irqs */ -lm_ctx_t * -lm_ctx_create(const lm_dev_info_t *dev_info); +int lm_setup_device_nr_irqs(lm_ctx_t *lm_ctx, enum lm_dev_irq_type type, + uint32_t count); + +//TODO: Re-visit once migration support is done. +/** + * Enable support for device migration. + * @lm_ctx: the libmuser context + * @migration: information required to migrate device + */ +int lm_setup_device_migration(lm_ctx_t *lm_ctx, lm_migration_t *migration); /** * Destroys libmuser context. @@ -418,16 +409,6 @@ int lm_ctx_drive(lm_ctx_t *lm_ctx); /** - * Creates and runs an lm_ctx. - * - * @dev_info: device information used to create the context - * - * @returns 0 on success, -1 on failure. Sets errno. - */ -int -lm_ctx_run(lm_dev_info_t *dev_info); - -/** * Polls, without blocking, an lm_ctx. This is an alternative to using * a thread and making a blocking call to lm_ctx_drive(). Instead, the * application can periodically poll the context directly from one of @@ -540,6 +521,7 @@ void lm_unmap_sg(lm_ctx_t *lm_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. @@ -579,6 +561,7 @@ lm_dma_write(lm_ctx_t *lm_ctx, dma_sg_t *sg, void *data); /** * Returns the non-standard part of the PCI configuration space. + * @lm_ctx: the libmuser context */ uint8_t * lm_get_pci_non_std_config_space(lm_ctx_t *lm_ctx); @@ -588,6 +571,7 @@ lm_get_pci_non_std_config_space(lm_ctx_t *lm_ctx); * creating the context. Returns 0 on success and -1 on error. If errno is set * to EAGAIN or EWOULDBLOCK then the transport is not ready to attach to and the * operation must be retried. + * @lm_ctx: the libmuser context */ int lm_ctx_try_attach(lm_ctx_t *lm_ctx); @@ -595,6 +579,8 @@ lm_ctx_try_attach(lm_ctx_t *lm_ctx); /* * FIXME need to make sure that there can be at most one capability with a given * ID, otherwise this function will return the first one with this ID. + * @lm_ctx: the libmuser context + * @id: capability id */ uint8_t * lm_ctx_get_cap(lm_ctx_t *lm_ctx, uint8_t id); |