qemu

libvduse.h (6478B)

---

 /*
  * VDUSE (vDPA Device in Userspace) library
  *
  * Copyright (C) 2022 Bytedance Inc. and/or its affiliates. All rights reserved.
  *
  * Author:
  *   Xie Yongji <xieyongji@bytedance.com>
  *
  * This work is licensed under the terms of the GNU GPL, version 2 or
  * later.  See the COPYING file in the top-level directory.
  */
 
 #ifndef LIBVDUSE_H
 #define LIBVDUSE_H
 
 #include <stdint.h>
 #include <sys/uio.h>
 
 #define VIRTQUEUE_MAX_SIZE 1024
 
 /* VDUSE device structure */
 typedef struct VduseDev VduseDev;
 
 /* Virtqueue structure */
 typedef struct VduseVirtq VduseVirtq;
 
 /* Some operation of VDUSE backend */
 typedef struct VduseOps {
     /* Called when virtqueue can be processed */
     void (*enable_queue)(VduseDev *dev, VduseVirtq *vq);
     /* Called when virtqueue processing should be stopped */
     void (*disable_queue)(VduseDev *dev, VduseVirtq *vq);
 } VduseOps;
 
 /* Describing elements of the I/O buffer */
 typedef struct VduseVirtqElement {
     /* Descriptor table index */
     unsigned int index;
     /* Number of physically-contiguous device-readable descriptors */
     unsigned int out_num;
     /* Number of physically-contiguous device-writable descriptors */
     unsigned int in_num;
     /* Array to store physically-contiguous device-writable descriptors */
     struct iovec *in_sg;
     /* Array to store physically-contiguous device-readable descriptors */
     struct iovec *out_sg;
 } VduseVirtqElement;
 
 
 /**
  * vduse_get_virtio_features:
  *
  * Get supported virtio features
  *
  * Returns: supported feature bits
  */
 uint64_t vduse_get_virtio_features(void);
 
 /**
  * vduse_queue_get_dev:
  * @vq: specified virtqueue
  *
  * Get corresponding VDUSE device from the virtqueue.
  *
  * Returns: a pointer to VDUSE device on success, NULL on failure.
  */
 VduseDev *vduse_queue_get_dev(VduseVirtq *vq);
 
 /**
  * vduse_queue_get_fd:
  * @vq: specified virtqueue
  *
  * Get the kick fd for the virtqueue.
  *
  * Returns: file descriptor on success, -1 on failure.
  */
 int vduse_queue_get_fd(VduseVirtq *vq);
 
 /**
  * vduse_queue_pop:
  * @vq: specified virtqueue
  * @sz: the size of struct to return (must be >= VduseVirtqElement)
  *
  * Pop an element from virtqueue available ring.
  *
  * Returns: a pointer to a structure containing VduseVirtqElement on success,
  * NULL on failure.
  */
 void *vduse_queue_pop(VduseVirtq *vq, size_t sz);
 
 /**
  * vduse_queue_push:
  * @vq: specified virtqueue
  * @elem: pointer to VduseVirtqElement returned by vduse_queue_pop()
  * @len: length in bytes to write
  *
  * Push an element to virtqueue used ring.
  */
 void vduse_queue_push(VduseVirtq *vq, const VduseVirtqElement *elem,
                       unsigned int len);
 /**
  * vduse_queue_notify:
  * @vq: specified virtqueue
  *
  * Request to notify the queue.
  */
 void vduse_queue_notify(VduseVirtq *vq);
 
 /**
  * vduse_dev_get_priv:
  * @dev: VDUSE device
  *
  * Get the private pointer passed to vduse_dev_create().
  *
  * Returns: private pointer on success, NULL on failure.
  */
 void *vduse_dev_get_priv(VduseDev *dev);
 
 /**
  * vduse_dev_get_queue:
  * @dev: VDUSE device
  * @index: virtqueue index
  *
  * Get the specified virtqueue.
  *
  * Returns: a pointer to the virtqueue on success, NULL on failure.
  */
 VduseVirtq *vduse_dev_get_queue(VduseDev *dev, int index);
 
 /**
  * vduse_dev_get_fd:
  * @dev: VDUSE device
  *
  * Get the control message fd for the VDUSE device.
  *
  * Returns: file descriptor on success, -1 on failure.
  */
 int vduse_dev_get_fd(VduseDev *dev);
 
 /**
  * vduse_dev_handler:
  * @dev: VDUSE device
  *
  * Used to process the control message.
  *
  * Returns: file descriptor on success, -errno on failure.
  */
 int vduse_dev_handler(VduseDev *dev);
 
 /**
  * vduse_dev_update_config:
  * @dev: VDUSE device
  * @size: the size to write to configuration space
  * @offset: the offset from the beginning of configuration space
  * @buffer: the buffer used to write from
  *
  * Update device configuration space and inject a config interrupt.
  *
  * Returns: 0 on success, -errno on failure.
  */
 int vduse_dev_update_config(VduseDev *dev, uint32_t size,
                             uint32_t offset, char *buffer);
 
 /**
  * vduse_dev_setup_queue:
  * @dev: VDUSE device
  * @index: virtqueue index
  * @max_size: the max size of virtqueue
  *
  * Setup the specified virtqueue.
  *
  * Returns: 0 on success, -errno on failure.
  */
 int vduse_dev_setup_queue(VduseDev *dev, int index, int max_size);
 
 /**
  * vduse_set_reconnect_log_file:
  * @dev: VDUSE device
  * @file: filename of reconnect log
  *
  * Specify the file to store log for reconnecting. It should
  * be called before vduse_dev_setup_queue().
  *
  * Returns: 0 on success, -errno on failure.
  */
 int vduse_set_reconnect_log_file(VduseDev *dev, const char *filename);
 
 /**
  * vduse_dev_create_by_fd:
  * @fd: passed file descriptor
  * @num_queues: the number of virtqueues
  * @ops: the operation of VDUSE backend
  * @priv: private pointer
  *
  * Create VDUSE device from a passed file descriptor.
  *
  * Returns: pointer to VDUSE device on success, NULL on failure.
  */
 VduseDev *vduse_dev_create_by_fd(int fd, uint16_t num_queues,
                                  const VduseOps *ops, void *priv);
 
 /**
  * vduse_dev_create_by_name:
  * @name: VDUSE device name
  * @num_queues: the number of virtqueues
  * @ops: the operation of VDUSE backend
  * @priv: private pointer
  *
  * Create VDUSE device on /dev/vduse/$NAME.
  *
  * Returns: pointer to VDUSE device on success, NULL on failure.
  */
 VduseDev *vduse_dev_create_by_name(const char *name, uint16_t num_queues,
                                    const VduseOps *ops, void *priv);
 
 /**
  * vduse_dev_create:
  * @name: VDUSE device name
  * @device_id: virtio device id
  * @vendor_id: virtio vendor id
  * @features: virtio features
  * @num_queues: the number of virtqueues
  * @config_size: the size of the configuration space
  * @config: the buffer of the configuration space
  * @ops: the operation of VDUSE backend
  * @priv: private pointer
  *
  * Create VDUSE device.
  *
  * Returns: pointer to VDUSE device on success, NULL on failure.
  */
 VduseDev *vduse_dev_create(const char *name, uint32_t device_id,
                            uint32_t vendor_id, uint64_t features,
                            uint16_t num_queues, uint32_t config_size,
                            char *config, const VduseOps *ops, void *priv);
 
 /**
  * vduse_dev_destroy:
  * @dev: VDUSE device
  *
  * Destroy the VDUSE device.
  *
  * Returns: 0 on success, -errno on failure.
  */
 int vduse_dev_destroy(VduseDev *dev);
 
 #endif