lib/vfu_target: add missed comments to vfu_target.h
Change-Id: Ie43b53e8b84b14ec92622a32052272d310e7145f Signed-off-by: Changpeng Liu <changpeng.liu@intel.com> Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/15029 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Konrad Sztyber <konrad.sztyber@intel.com>
This commit is contained in:
Changpeng Liu
Konrad Sztyber
parent
a6f6454073
commit
296bca08c1
@ -13,36 +13,118 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Callback for spdk_vfu_init().
|
||||
*
|
||||
* \param rc 0 on success, negative errno on failure.
|
||||
*/
|
||||
typedef void (*spdk_vfu_init_cb)(int rc);
|
||||
|
||||
|
||||
/**
|
||||
* Callback for spdk_vfu_fini().
|
||||
*/
|
||||
typedef void (*spdk_vfu_fini_cb)(void);
|
||||
|
||||
/**
|
||||
* Initialize vfio-user target environment.
|
||||
*/
|
||||
void spdk_vfu_init(spdk_vfu_init_cb init_cb);
|
||||
|
||||
/**
|
||||
* Clean up vfio-user target environment.
|
||||
*/
|
||||
void spdk_vfu_fini(spdk_vfu_fini_cb fini_cb);
|
||||
|
||||
/**
|
||||
* Opaque handle to a PCI endpoint, it's representative of a Unix Domain socket file.
|
||||
*/
|
||||
struct spdk_vfu_endpoint;
|
||||
|
||||
#define SPDK_VFU_MAX_NAME_LEN (64)
|
||||
|
||||
/**
|
||||
* Vfio-user PCI device sparse MMAP region.
|
||||
*
|
||||
* The sparse mmap allows finer granularity of specifying areas
|
||||
* within a PCI region with mmap support.
|
||||
*/
|
||||
struct spdk_vfu_sparse_mmap {
|
||||
/**
|
||||
* Sparse mmap region offset, starts from 0 of current PCI region.
|
||||
*/
|
||||
uint64_t offset;
|
||||
|
||||
/**
|
||||
* Sparse mmap region length.
|
||||
*/
|
||||
uint64_t len;
|
||||
};
|
||||
|
||||
#define SPDK_VFU_MAXIMUM_SPARSE_MMAP_REGIONS 8
|
||||
|
||||
/**
|
||||
* Callback for vfio-user PCI region access.
|
||||
*
|
||||
* \param vfu_ctx Opaque value of the PCI endpoint, it's created by libvfio-user.
|
||||
* \param buf data buffer to R/W.
|
||||
* \param count R/W size, the value could be 1,2,4,8.
|
||||
* \param pos offset from PCI region.
|
||||
* \param is_write true if access is WRITE.
|
||||
*
|
||||
* \return count on success, negative errno on failure.
|
||||
*/
|
||||
typedef ssize_t (*spdk_vfu_access_cb)(vfu_ctx_t *vfu_ctx, char *buf, size_t count, loff_t pos,
|
||||
bool is_write);
|
||||
|
||||
/**
|
||||
* Vfio-user device PCI region.
|
||||
*
|
||||
* PCI region is definition of PCI device BAR.
|
||||
*/
|
||||
struct spdk_vfu_pci_region {
|
||||
/**
|
||||
* Offset of the PCI region.
|
||||
*/
|
||||
uint64_t offset;
|
||||
|
||||
/**
|
||||
* Length of the PCI region.
|
||||
*/
|
||||
uint64_t len;
|
||||
|
||||
/**
|
||||
* Capability flags.
|
||||
*/
|
||||
uint64_t flags;
|
||||
|
||||
/**
|
||||
* Number of sparse mmap region.
|
||||
*/
|
||||
uint32_t nr_sparse_mmaps;
|
||||
|
||||
/**
|
||||
* Representative of the PCI region access file descriptor.
|
||||
*/
|
||||
int fd;
|
||||
|
||||
/**
|
||||
* Sparse mmap regions.
|
||||
*/
|
||||
struct spdk_vfu_sparse_mmap mmaps[SPDK_VFU_MAXIMUM_SPARSE_MMAP_REGIONS];
|
||||
|
||||
/**
|
||||
* PCI region access callback.
|
||||
*/
|
||||
spdk_vfu_access_cb access_cb;
|
||||
};
|
||||
|
||||
/**
|
||||
* Vfio-user PCI device information.
|
||||
*
|
||||
* vfio-user target uses this data structure to get all the informations
|
||||
* from backend emulated device module.
|
||||
*/
|
||||
struct spdk_vfu_pci_device {
|
||||
struct {
|
||||
/* Vendor ID */
|
||||
@ -64,54 +146,228 @@ struct spdk_vfu_pci_device {
|
||||
uint8_t pi;
|
||||
} class;
|
||||
|
||||
/* Standard PCI Capabilities */
|
||||
/* Standard Power Management capabilities */
|
||||
struct pmcap pmcap;
|
||||
/* Standard PCI Express Capability ID */
|
||||
struct pxcap pxcap;
|
||||
/* Standard MSI-X Capability */
|
||||
struct msixcap msixcap;
|
||||
/* Number of vendor specific capabilities */
|
||||
uint16_t nr_vendor_caps;
|
||||
|
||||
/* Legacy interrupt pin number */
|
||||
uint16_t intr_ipin;
|
||||
/* Number of legacy interrupts */
|
||||
uint32_t nr_int_irqs;
|
||||
/* Number of MSIX interrupts */
|
||||
uint32_t nr_msix_irqs;
|
||||
|
||||
/* PCI regions */
|
||||
struct spdk_vfu_pci_region regions[VFU_PCI_DEV_NUM_REGIONS];
|
||||
};
|
||||
|
||||
struct spdk_vfu_endpoint_ops {
|
||||
/* PCI device type name */
|
||||
/**
|
||||
* Backend emulated PCI device type name.
|
||||
*/
|
||||
char name[SPDK_VFU_MAX_NAME_LEN];
|
||||
|
||||
/**
|
||||
* Initialize endpoint to PCI device with base path.
|
||||
*/
|
||||
void *(*init)(struct spdk_vfu_endpoint *endpoint,
|
||||
char *basename, const char *endpoint_name);
|
||||
|
||||
/**
|
||||
* Get PCI device information from backend device module.
|
||||
*/
|
||||
int (*get_device_info)(struct spdk_vfu_endpoint *endpoint,
|
||||
struct spdk_vfu_pci_device *device_info);
|
||||
|
||||
/**
|
||||
* Get vendor capabilitiy based on ID in PCI configuration space.
|
||||
*/
|
||||
uint16_t (*get_vendor_capability)(struct spdk_vfu_endpoint *endpoint, char *buf,
|
||||
uint16_t buf_len, uint16_t idx);
|
||||
|
||||
/**
|
||||
* Attach active connection to the PCI endpoint.
|
||||
*/
|
||||
int (*attach_device)(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* Detach the active connection of the PCI endpoint.
|
||||
*/
|
||||
int (*detach_device)(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* Destruct the PCI endpoint.
|
||||
*/
|
||||
int (*destruct)(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* Post-notification to backend module after a new memory region is added.
|
||||
*/
|
||||
int (*post_memory_add)(struct spdk_vfu_endpoint *endpoint, void *map_start, void *map_end);
|
||||
|
||||
/**
|
||||
* Pre-notification to backend module before removing the memory region.
|
||||
*/
|
||||
int (*pre_memory_remove)(struct spdk_vfu_endpoint *endpoint, void *map_start, void *map_end);
|
||||
|
||||
/**
|
||||
* PCI device reset callback.
|
||||
*/
|
||||
int (*reset_device)(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* PCI device quiesce callback, after this callback, the backend device module
|
||||
* should stopping processing any IOs.
|
||||
*/
|
||||
int (*quiesce_device)(struct spdk_vfu_endpoint *endpoint);
|
||||
};
|
||||
|
||||
/**
|
||||
* Register the operations of emulated backend PCI device.
|
||||
*
|
||||
* \param ops The operations of emulated backend PCI device.
|
||||
*
|
||||
* \return 0 on success, negative errno on failure.
|
||||
*/
|
||||
int spdk_vfu_register_endpoint_ops(struct spdk_vfu_endpoint_ops *ops);
|
||||
|
||||
/**
|
||||
* Create a PCI endpoint.
|
||||
*
|
||||
* \param endpoint_name Name of the PCI endpoint.
|
||||
* \param cpumask_str CPU masks that the endpoint is running on.
|
||||
* \param dev_type_name Name of the registered operation.
|
||||
*
|
||||
* \return 0 on success, negative errno on failure.
|
||||
*/
|
||||
int spdk_vfu_create_endpoint(const char *endpoint_name, const char *cpumask_str,
|
||||
const char *dev_type_name);
|
||||
|
||||
/**
|
||||
* Delete a PCI endpoint.
|
||||
*
|
||||
* \param endpoint_name Name of the PCI endpoint.
|
||||
*
|
||||
* \return 0 on success, negative errno on failure.
|
||||
*/
|
||||
int spdk_vfu_delete_endpoint(const char *endpoint_name);
|
||||
|
||||
/**
|
||||
* Set the base path to create socket files.
|
||||
*
|
||||
* \param basename Path to create socket files.
|
||||
*
|
||||
* \return 0 on success, negative errno on failure.
|
||||
*/
|
||||
int spdk_vfu_set_socket_path(const char *basename);
|
||||
|
||||
/**
|
||||
* Get UUID of the PCI endpoint.
|
||||
*
|
||||
* This function will return the absolute path of the PCI endpoint which
|
||||
* represented by a socket file.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
*
|
||||
* \return absolute path of the PCI endpoint.
|
||||
*/
|
||||
const char *spdk_vfu_get_endpoint_id(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* Get name of the PCI endpoint.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
*
|
||||
* \return name of the PCI endpoint.
|
||||
*/
|
||||
const char *spdk_vfu_get_endpoint_name(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* Get opaque handle of the PCI endpoint that created by libvfio-user library.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
*
|
||||
* \return opaque handle on success, NULL on failure.
|
||||
*/
|
||||
vfu_ctx_t *spdk_vfu_get_vfu_ctx(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* Get private opaque handle of backend PCI device moduel.
|
||||
*
|
||||
* This function is used in backend PCI device module to get the internal
|
||||
* private data structure saved in vfu_target library.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
*
|
||||
* \return opaque handle of backend device on success, NULL on failure.
|
||||
*/
|
||||
void *spdk_vfu_get_endpoint_private(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* MSI-X is enabled or not.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
*
|
||||
* \return ture if MSI-X is enabled, false otherwise.
|
||||
*/
|
||||
bool spdk_vfu_endpoint_msix_enabled(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* INT-X is enabled or not.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
*
|
||||
* \return true if INT-X is enabled, false otherwise.
|
||||
*/
|
||||
bool spdk_vfu_endpoint_intx_enabled(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* Get PCI configuration space.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
*
|
||||
* \return pointer to PCI configuration space on success, NULL on failure.
|
||||
*/
|
||||
void *spdk_vfu_endpoint_get_pci_config(struct spdk_vfu_endpoint *endpoint);
|
||||
|
||||
/**
|
||||
* Get PCI endpoint via name.
|
||||
*
|
||||
* \param name The PCI endpoint name.
|
||||
*
|
||||
* \return PCI endpoint pointer on success, NULL on failure.
|
||||
*/
|
||||
struct spdk_vfu_endpoint *spdk_vfu_get_endpoint_by_name(const char *name);
|
||||
|
||||
/**
|
||||
* Map Guest Physical Address to Host Virtual Address.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
* \param addr Physical address that to be mapped.
|
||||
* \param len Length of mapped address.
|
||||
* \param sg Scatter/gather entry to be mapped.
|
||||
* \param iov IOV to save mapped virtual address and length.
|
||||
* \param prot Protection flags.
|
||||
*
|
||||
* \return mapped virtual address on success, NULL on failure.
|
||||
*/
|
||||
void *spdk_vfu_map_one(struct spdk_vfu_endpoint *endpoint, uint64_t addr, uint64_t len,
|
||||
dma_sg_t *sg, struct iovec *iov, int prot);
|
||||
|
||||
/**
|
||||
* Unmap array of scatter/gather entries.
|
||||
*
|
||||
* \param endpoint The PCI endpoint.
|
||||
* \param array of scatter/gather entries to be unmapped.
|
||||
* \param iov array of IOVs contain virtual addresses and length.
|
||||
* \param iovcnt Number of IOVs.
|
||||
*
|
||||
*/
|
||||
void spdk_vfu_unmap_sg(struct spdk_vfu_endpoint *endpoint, dma_sg_t *sg, struct iovec *iov,
|
||||
int iovcnt);
|
||||
#ifdef __cplusplus
|
||||
|
||||
Loading…
Reference in New Issue
Block a user