libvfio-user.h

/*
 * Copyright (c) 2019 Nutanix Inc. All rights reserved.
 *
 * Authors: Thanos Makatos <thanos@nutanix.com>
 *          Swapnil Ingle <swapnil.ingle@nutanix.com>
 *          Felipe Franciosi <felipe@nutanix.com>
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *      * Redistributions of source code must retain the above copyright
 *        notice, this list of conditions and the following disclaimer.
 *      * Redistributions in binary form must reproduce the above copyright
 *        notice, this list of conditions and the following disclaimer in the
 *        documentation and/or other materials provided with the distribution.
 *      * Neither the name of Nutanix nor the names of its contributors may be
 *        used to endorse or promote products derived from this software without
 *        specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
 *  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 *  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 *  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 *  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 *  DAMAGE.
 *
 */

/*
 * Defines the libvfio-user server-side API.  The protocol definitions can be
 * found in vfio-user.h.
 *
 * This is not currently a stable API or ABI, and may change at any time.
 * Library calls are not guaranteed thread-safe: multi-threaded consumers need
 * to protect calls with their own exclusion methods.
 */

#ifndef LIB_VFIO_USER_H
#define LIB_VFIO_USER_H

#include <stdint.h>
#include <sys/uio.h>
#include <unistd.h>
#include <syslog.h>
#include <sys/queue.h>

#include "pci_caps/dsn.h"
#include "pci_caps/msi.h"
#include "pci_caps/msix.h"
#include "pci_caps/pm.h"
#include "pci_caps/px.h"
#include "pci_defs.h"
#include "vfio-user.h"

#ifdef __cplusplus
extern "C" {
#endif

#define LIB_VFIO_USER_MAJOR 0
#define LIB_VFIO_USER_MINOR 2

/* DMA addresses cannot be directly de-referenced. */
typedef void *vfu_dma_addr_t;

struct dma_sg;
typedef struct dma_sg dma_sg_t;

typedef struct vfu_ctx vfu_ctx_t;

/*
 * Returns the size, in bytes, of dma_sg_t.
 */
size_t
dma_sg_size(void);

/*
 * Attaching to the transport is non-blocking.
 * The caller must then manually call vfu_attach_ctx(),
 * which is non-blocking, as many times as necessary.
 *
 * This also applies to vfu_run_ctx(). However, it's presumed that any actual
 * reads or writes of the socket connection will not need to block, since both
 * APIS are synchronous.
 */
#define LIBVFIO_USER_FLAG_ATTACH_NB  (1 << 0)

typedef enum {
    VFU_TRANS_SOCK,
    // For internal testing only
    VFU_TRANS_PIPE,
    VFU_TRANS_MAX
} vfu_trans_t;

typedef enum {
    VFU_DEV_TYPE_PCI
} vfu_dev_type_t;

/**
 * Creates libvfio-user context. By default one ERR and one REQ IRQs are
 * initialized, this can be overridden with vfu_setup_device_nr_irqs.
 *
 * @trans: transport type
 * @path: path to socket file.
 * @flags: context flags (LIBVFIO_USER_FLAG_*)
 * @pvt: private data
 * @dev_type: device type
 *
 * @returns the vfu_ctx to be used or NULL on error. Sets errno.
 */
vfu_ctx_t *
vfu_create_ctx(vfu_trans_t trans, const char *path,
               int flags, void *pvt, vfu_dev_type_t dev_type);

/*
 * Finalizes the device making it ready for vfu_attach_ctx(). This function is
 * mandatory to be called before vfu_attach_ctx().
 * @vfu_ctx: the libvfio-user context
 *
 * @returns: 0 on success, -1 on error. Sets errno.
 */
int
vfu_realize_ctx(vfu_ctx_t *vfu_ctx);

/*
 * Attempts to attach to the transport. Attach is mandatory before vfu_run_ctx()
 * and is non blocking if context is created with LIBVFIO_USER_FLAG_ATTACH_NB
 * flag.
 *
 * @returns: 0 on success, -1 on error. Sets errno.  If errno is set to EAGAIN
 * or EWOULDBLOCK then the transport is not ready to attach to and the operation
 * must be retried.
 *
 * @vfu_ctx: the libvfio-user context
 */
int
vfu_attach_ctx(vfu_ctx_t *vfu_ctx);

/**
 * Return a file descriptor suitable for waiting on via epoll() or similar. The
 * file descriptor may change after a successful vfu_attach_ctx(), or on
 * receiving ENOTCONN error message from vfu_run_ctx(); in those cases,
 * vfu_get_poll_fd() should be called again to get the current correct file
 * descriptor.
 */
int
vfu_get_poll_fd(vfu_ctx_t *vfu_ctx);

/**
 * Polls the vfu_ctx and processes the command received from client.
 * - Blocking vfu_ctx:
 *   Blocks until new request is received from client and continues processing
 *   the requests. Exits only in case of error or if the client disconnects.
 * - Non-blocking vfu_ctx(LIBVFIO_USER_FLAG_ATTACH_NB):
 *   Processes one request from client if it's available, otherwise it
 *   immediately returns and the caller is responsible for periodically
 *   calling again.
 *
 * @vfu_ctx: The libvfio-user context to poll
 *
 * @returns the number of requests processed (0 or more); or -1 on error,
 *          with errno set as follows:
 *
 * ENOTCONN: client closed connection, vfu_attach_ctx() should be called again
 * EBUSY: the device was asked to quiesce and is still quiescing
 * Other errno values are also possible.
 */
int
vfu_run_ctx(vfu_ctx_t *vfu_ctx);

/**
 * Destroys libvfio-user context. During this call the device must already be
 * in quiesced state; the quiesce callback is not called. Any other device
 * callback can be called.
 *
 * @vfu_ctx: the libvfio-user context to destroy
 */
void
vfu_destroy_ctx(vfu_ctx_t *vfu_ctx);

/**
 * Return the private pointer given to vfu_create_ctx().
 */
void *
vfu_get_private(vfu_ctx_t *vfu_ctx);

/**
 * Callback function signature for log function
 * @vfu_ctx: the libvfio-user context
 * @level: log level as defined in syslog(3)
 * @vfu_log_fn_t: typedef for log function.
 * @msg: message
 */
typedef void (vfu_log_fn_t)(vfu_ctx_t *vfu_ctx, int level, const char *msg);

/**
 * Log to the logging function configured for this context. The format should
 * not include a new line.
 */
void
vfu_log(vfu_ctx_t *vfu_ctx, int level, const char *fmt, ...) \
    __attribute__((format(printf, 3, 4)));

/**
 * Set up logging information.
 * @vfu_ctx: the libvfio-user context
 * @log: logging function
 * @level: logging level as defined in syslog(3)
 *
 * The log handler is expected to add a newline (that is, log messages do not
 * include a newline).
 */
int
vfu_setup_log(vfu_ctx_t *vfu_ctx, vfu_log_fn_t *log, int level);

/**
 * Prototype for region access callback. When a region is accessed, libvfio-user
 * calls the previously registered callback with the following arguments:
 *
 * @vfu_ctx: the libvfio-user context
 * @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 -1 on error, setting errno.
 */
typedef ssize_t (vfu_region_access_cb_t)(vfu_ctx_t *vfu_ctx, 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_RW        (VFU_REGION_FLAG_READ | VFU_REGION_FLAG_WRITE)
/* If unset, this is an IO region. */
#define VFU_REGION_FLAG_MEM       (1 << 2)
#define VFU_REGION_FLAG_ALWAYS_CB (1 << 3)
#define VFU_REGION_FLAG_MASK      (VFU_REGION_FLAG_RW | VFU_REGION_FLAG_MEM | \
                                   VFU_REGION_FLAG_ALWAYS_CB)

/**
 * Set up a device region.
 *
 * 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.
 *
 * 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.
 *
 * 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.
 *
 * 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.
 *
 * The following regions are special and are explained below:
 *  - VFU_PCI_DEV_CFG_REGION_IDX,
 *  - VFU_PCI_DEV_MIGR_REGION_IDX, and
 *  - VFU_GENERIC_DEV_MIGR_REG_IDX.
 *
 * Region VFU_PCI_DEV_CFG_REGION_IDX, 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 (see vfu_pci_add_capability())
 *    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
 *  - if VFU_REGION_FLAG_ALWAYS_CB flag is set, all accesses to the config
 *    space are forwarded to the callback
 *
 * Regions VFU_PCI_DEV_MIGR_REGION_IDX and VFU_GENERIC_DEV_MIGR_REG_IDX,
 * corresponding to the migration region, enable live migration support for
 * the device. The migration region must contain at the beginning the migration
 * registers (struct vfio_user_migration_info) and the remaining part of the
 * region can be arbitrarily used by the device implementation. The region
 * provided must have at least vfu_get_migr_register_area_size() bytes available
 * at the start of the region (this size is guaranteed to be page-aligned). If
 * mmap_areas is given, it must _not_ include this part of the region.
 *
 * libvfio-user offers two ways for the migration region to be used:
 *  1. natively: the device implementation must handle accesses to the
 *      migration registers and migration data via the region callbacks. The
 *      semantics of these registers are explained in <linux/vfio.h>.
 *  2. via the vfu_migration_callbacks_t callbacks: the device implementation
 *      registers a set of callbacks by calling vfu_setup_device_migration.
 *      The region's read/write callbacks are never called.
 *
 * @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; if an fd is provided, but this
 * is NULL, then the entire region is mappable.
 * @nr_mmap_areas: number of sparse areas in @mmap_areas; must be provided if
 *  the @mmap_areas is non-NULL, or 0 otherwise.
 * @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.
 * @offset: offset of the region within the fd, or zero.
 *
 * @returns 0 on success, -1 on error, Sets errno.
 */
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,
                 int fd, uint64_t offset);

typedef enum vfu_reset_type {
    /*
     * Client requested a device reset (for example, as part of a guest VM
     * reboot). The vfio-user context remains valid, but it's expected that all
     * ongoing operations are completed or cancelled, and any device state is
     * reset to a known-good initial state (including any PCI register state).
     */
    VFU_RESET_DEVICE,

    /*
     * The vfio-user socket client connection was closed or reset. The attached
     * context is cleaned up after returning from the reset callback, and
     * vfu_attach_ctx() must be called to establish a new client.
     */
    VFU_RESET_LOST_CONN,

    /*
     * Client requested to initiate PCI function level reset.
     */
    VFU_RESET_PCI_FLR
} vfu_reset_type_t;

/*
 * Device callback for quiescing the device.
 *
 * vfu_run_ctx uses this callback to request from the device to quiesce its
 * operation. A quiesced device must not call vfu_addr_to_sgl() or vfu_sgl_*(),
 * unless it does so from a device callback.
 *
 * The callback can return two values:
 * 1) 0: this indicates that the device was quiesced. vfu_run_ctx then continues
 *      to execute and when vfu_run_ctx returns to the caller the device is
 *      unquiesced.
 * 2) -1 with errno set to EBUSY: this indicates that the device cannot
 *      immediately quiesce. In this case, vfu_run_ctx returns -1 with errno
 *      set to EBUSY and future calls to vfu_run_ctx return the same. Until the
 *      device quiesces it can continue operate as normal. The device indicates
 *      that it quiesced by calling vfu_device_quiesced. When
 *      vfu_device_quiesced returns the device is no longer quiesced.
 *
 * A quiesced device should expect for any of the following callbacks to be
 * executed: vfu_dma_register_cb_t, vfu_unregister_cb_t, vfu_reset_cb_t, and
 * the migration transition callback. These callbacks are only called after the
 * device has been quiesced.
 *
 * The following example demonstrates how a device can use the SG routines and
 * friends while quiesced:
 *
 * A DMA region is mapped, libvfio-user calls the quiesce callback but the
 * device cannot immediately quiesce:
 *
 *     int quiesce_cb(vfu_ctx_t *vfu_ctx) {
 *         errno = EBUSY;
 *         return -1;
 *     }
 *
 * While quiescing, the device can continue to operate as normal, including
 * calling functions such as vfu_sgl_get(). Then, the device finishes quiescing:
 *
 *  vfu_quiesce_done(vfu_ctx, 0);
 *
 * At this point, the device must have stopped using functions like
 * vfu_sgl_get(), for example by pausing any I/O threads.  libvfio-user
 * eventually calls the dma_register device callback before vfu_quiesce_done
 * returns. In this callback the device is allowed to call functions such as
 * vfu_sgl_get()
 *
 *     void (dma_register_cb(vfu_ctx_t *vfu_ctx, vfu_dma_info_t *info) {
 *         vfu_sgl_get(ctx, ...);
 *     }
 *
 * Once vfu_quiesce_done returns, the device is unquiesced.
 *
 *
 * @vfu_ctx: the libvfio-user context
 *
 * @returns: 0 on success, -1 on failure with errno set.
 */
typedef int (vfu_device_quiesce_cb_t)(vfu_ctx_t *vfu_ctx);

/**
 * Sets up the device quiesce callback.
 *
 * @vfu_ctx: the libvfio-user context
 * @quiesce_cb: device quiesce callback
 */
void
vfu_setup_device_quiesce_cb(vfu_ctx_t *vfu_ctx,
                            vfu_device_quiesce_cb_t *quiesce_cb);

/*
 * Called by the device to complete a pending quiesce operation. After the
 * function returns the device is unquiesced.
 *
 * @vfu_ctx: the libvfio-user context
 * @quiesce_errno: 0 for success or errno in case the device fails to quiesce,
 *                 in which case the operation requiring the quiesce is failed
 *                 and the device is reset.
 *
 * @returns 0 on success, or -1 on failure. Sets errno.
 */
int
vfu_device_quiesced(vfu_ctx_t *vfu_ctx, int quiesce_errno);

/*
 * Callback function that is called when the device must be reset.
 */
typedef int (vfu_reset_cb_t)(vfu_ctx_t *vfu_ctx, vfu_reset_type_t type);

/**
 * Set up device reset callback.
 *
 * A reset should ensure that all on-going use of device IRQs or guest memory is
 * completed or cancelled before returning from the callback.
 *
 * @vfu_ctx: the libvfio-user context
 * @reset: device reset callback
 */
int
vfu_setup_device_reset_cb(vfu_ctx_t *vfu_ctx, vfu_reset_cb_t *reset);

/*
 * Info for a guest DMA region.  @iova is always valid; the other parameters
 * will only be set if the guest DMA region is mappable.
 *
 * @iova: guest DMA range. This is the guest physical range (as we don't
 *   support vIOMMU) that the guest registers for DMA, via a VFIO_USER_DMA_MAP
 *   message, and is the address space used as input to vfu_addr_to_sgl().
 * @vaddr: if the range is mapped into this process, this is the virtual address
 *   of the start of the region.
 * @mapping: if @vaddr is non-NULL, this range represents the actual range
 *   mmap()ed into the process. This might be (large) page aligned, and
 *   therefore be different from @vaddr + @iova.iov_len.
 * @page_size: if @vaddr is non-NULL, page size of the mapping (e.g. 2MB)
 * @prot: if @vaddr is non-NULL, protection settings of the mapping as per
 *   mmap(2)
 *
 * For a real example, using the gpio sample server, and a qemu configured to
 * use huge pages and share its memory:
 *
 * gpio: mapped DMA region iova=[0xf0000-0x10000000) vaddr=0x2aaaab0f0000
 * page_size=0x200000 mapping=[0x2aaaab000000-0x2aaabb000000)
 *
 *     0xf0000                    0x10000000
 *     |                                   |
 *     v                                   v
 *     +-----------------------------------+
 *     | Guest IOVA (DMA) space            |
 *  +--+-----------------------------------+--+
 *  |  |                                   |  |
 *  |  +-----------------------------------+  |
 *  |  ^ libvfio-user server address space    |
 *  +--|--------------------------------------+
 *  ^ vaddr=0x2aaaab0f0000                    ^
 *  |                                         |
 *  0x2aaaab000000               0x2aaabb000000
 *
 * This region can be directly accessed at 0x2aaaab0f0000, but the underlying
 * large page mapping is in the range [0x2aaaab000000-0x2aaabb000000).
 */
typedef struct vfu_dma_info {
    struct iovec iova;
    void *vaddr;
    struct iovec mapping;
    size_t page_size;
    uint32_t prot;
} vfu_dma_info_t;

/*
 * Called when a guest registers one of its DMA regions via a VFIO_USER_DMA_MAP
 * message.
 *
 * @vfu_ctx: the libvfio-user context
 * @info: the DMA info
 */
typedef void (vfu_dma_register_cb_t)(vfu_ctx_t *vfu_ctx, vfu_dma_info_t *info);

/*
 * Function that is called when the guest unregisters a DMA region.  This
 * callback is required if you want to be able to access guest memory directly
 * via a mapping. The device must release all references to that region before
 * the callback returns.
 *
 * @vfu_ctx: the libvfio-user context
 * @info: the DMA info
 */
typedef void (vfu_dma_unregister_cb_t)(vfu_ctx_t *vfu_ctx, vfu_dma_info_t *info);

/**
 * Set up device DMA registration callbacks. When libvfio-user is notified of a
 * DMA range addition or removal, these callbacks will be invoked.
 *
 * If this function is not called, guest DMA regions are not accessible via
 * vfu_addr_to_sgl().
 *
 * To directly access this DMA memory via a local mapping with vfu_sgl_get(), at
 * least @dma_unregister must be provided.
 *
 * @vfu_ctx: the libvfio-user context
 * @dma_register: DMA region registration callback (optional)
 * @dma_unregister: DMA region unregistration callback (optional)
 */

int
vfu_setup_device_dma(vfu_ctx_t *vfu_ctx, vfu_dma_register_cb_t *dma_register,
                     vfu_dma_unregister_cb_t *dma_unregister);

enum vfu_dev_irq_type {
    VFU_DEV_INTX_IRQ,
    VFU_DEV_MSI_IRQ,
    VFU_DEV_MSIX_IRQ,
    VFU_DEV_ERR_IRQ,
    VFU_DEV_REQ_IRQ,
    VFU_DEV_NUM_IRQS
};

/**
 * Set up device IRQ counts.
 * @vfu_ctx: the libvfio-user context
 * @type: IRQ type (VFU_DEV_INTX_IRQ ... VFU_DEV_REQ_IRQ)
 * @count: number of irqs
 */
int
vfu_setup_device_nr_irqs(vfu_ctx_t *vfu_ctx, enum vfu_dev_irq_type type,
                         uint32_t count);

/*
 * Function that is called when the guest masks or unmasks an IRQ vector.
 *
 * @vfu_ctx: the libvfio-user context
 * @start: starting IRQ vector
 * @count: number of vectors
 * @mask: indicates if the IRQ is masked or unmasked
 */
typedef void (vfu_dev_irq_state_cb_t)(vfu_ctx_t *vfu_ctx, uint32_t start,
                                      uint32_t count, bool mask);

/**
 * Set up IRQ state change callback. When libvfio-user is notified of a
 * change to IRQ state, whether masked or unmasked, it invokes
 * this callback.
 *
 * @vfu_ctx: the libvfio-user context
 * @type: IRQ type such as VFU_DEV_MSIX_IRQ - defined by vfu_dev_irq_type
 * @cb: IRQ state change callback
 *
 * @returns 0 on success, -1 on error, sets errno.
 */
int
vfu_setup_irq_state_callback(vfu_ctx_t *vfu_ctx, enum vfu_dev_irq_type type,
                             vfu_dev_irq_state_cb_t *cb);

typedef enum {
    VFU_MIGR_STATE_STOP,
    VFU_MIGR_STATE_RUNNING,
    VFU_MIGR_STATE_STOP_AND_COPY,
    VFU_MIGR_STATE_PRE_COPY,
    VFU_MIGR_STATE_RESUME
} vfu_migr_state_t;

#define VFU_MIGR_CALLBACKS_VERS 2

typedef struct {

    /*
     * Set it to VFU_MIGR_CALLBACKS_VERS.
     */
    int version;

    /*
     * Migration state transition callback.
     *
     * The callback should return -1 on error, setting errno.
     *
     *
     * TODO rename to vfu_migration_state_transition_callback
     * FIXME maybe we should create a single callback and pass the state?
     */
    int (*transition)(vfu_ctx_t *vfu_ctx, vfu_migr_state_t state);
    
    /*
     * Function that is called to read `count` bytes of migration data into
     * `buf`. The function must return the amount of data read or -1 on error,
     * setting errno. The function may return less data than requested.
     *
     * If the function returns zero, this is interpreted to mean that there is
     * no more migration data to read.
     */
    ssize_t (*read_data)(vfu_ctx_t *vfu_ctx, void *buf, uint64_t count);

    /*
     * Function that is called for writing previously stored device state. The
     * function must return the amount of data written or -1 on error, setting
     * errno. Partial writes are not supported, so any return value other than
     * `count` is invalid.
     */
    ssize_t (*write_data)(vfu_ctx_t *vfu_ctx, void *buf, uint64_t count);

} vfu_migration_callbacks_t;

int
vfu_setup_device_migration_callbacks(vfu_ctx_t *vfu_ctx,
    const vfu_migration_callbacks_t *callbacks);

/**
 * Triggers an interrupt.
 *
 * libvfio-user takes care of using the correct IRQ type (IRQ index: INTx or
 * MSI/X), the caller only needs to specify the sub-index.
 *
 * @vfu_ctx: the libvfio-user context to trigger interrupt
 * @subindex: vector subindex to trigger interrupt on
 *
 * @returns 0 on success, or -1 on failure. Sets errno.
 */
int
vfu_irq_trigger(vfu_ctx_t *vfu_ctx, uint32_t subindex);

/**
 * Takes a guest physical address range and populates an array of scatter/gather
 * entries than can be individually mapped in the program's virtual memory.  A
 * single linear guest physical address span may need to be split into multiple
 * scatter/gather regions due to limitations of how memory can be mapped.
 *
 * vfu_setup_device_dma() must have been called prior to using this function.
 *
 * @vfu_ctx: the libvfio-user context
 * @dma_addr: the guest physical address
 * @len: size of memory to be mapped
 * @sgl: array that receives the scatter/gather entries to be mapped
 * @max_nr_sgs: maximum number of elements in above array
 * @prot: protection as defined in <sys/mman.h>
 *
 * @returns the number of scatter/gather entries created on success, and on
 * failure:
 *  -1:         if the GPA address span is invalid (errno=ENOENT) or
 *              protection violation (errno=EACCES)
 *  (-x - 1):   if @max_nr_sgs is too small, where x is the number of SG
 *              entries necessary to complete this request (errno=0).
 */
int
vfu_addr_to_sgl(vfu_ctx_t *vfu_ctx, vfu_dma_addr_t dma_addr, size_t len,
                dma_sg_t *sgl, size_t max_nr_sgs, int prot);

/**
 * Populate the given iovec array (accessible in the process's virtual memory),
 * based upon the SGL previously built via vfu_addr_to_sgl().
 * It is the caller's responsibility to return the release the iovecs via
 * vfu_sgl_put().
 *
 * This is only supported when a @dma_unregister callback is provided to
 * vfu_setup_device_dma().
 *
 * @vfu_ctx: the libvfio-user context
 * @sgl: array of scatter/gather entries returned by vfu_addr_to_sg. These
 *       entries must not be modified and the array must not be deallocated
 *       until vfu_sgl_put() has been called.
 * @iov: array of iovec structures (defined in <sys/uio.h>) to receive each
 *       mapping
 * @cnt: number of scatter/gather entries to map
 * @flags: must be 0
 *
 * @returns 0 on success, -1 on failure. Sets errno.
 */
int
vfu_sgl_get(vfu_ctx_t *vfu_ctx, dma_sg_t *sgl, struct iovec *iov, size_t cnt,
            int flags);

/**
 * Mark scatter/gather entries (previously acquired via vfu_sgl_get())
 * as dirty (written to). This is only necessary if vfu_sgl_put() is not called.
 *
 * @vfu_ctx: the libvfio-user context
 * @sg: array of scatter/gather entries to mark as dirty
 * @cnt: number of scatter/gather entries to mark as dirty
 */
void
vfu_sgl_mark_dirty(vfu_ctx_t *vfu_ctx, dma_sg_t *sgl, size_t cnt);

/**
 * Release the iovec array previously acquired by vfu_sgl_get().
 *
 * This will automatically mark the sgl as dirty if needed.
 *
 * @vfu_ctx: the libvfio-user context
 * @sgl: array of scatter/gather entries to unmap
 * @iov: array of iovec structures for each scatter/gather entry
 * @cnt: number of scatter/gather entries to unmap
 */
void
vfu_sgl_put(vfu_ctx_t *vfu_ctx, dma_sg_t *sgl, struct iovec *iov, size_t cnt);

/**
 * Read from the dma region exposed by the client. This can be used as an
 * alternative to reading from a vfu_sgl_get() mapping, if the region is not
 * directly mappable, or DMA notification callbacks have not been provided.
 *
 * @vfu_ctx: the libvfio-user context
 * @sg: a DMA segment obtained from dma_addr_to_sg
 * @data: data buffer to read into
 *
 * @returns 0 on success, -1 on failure. Sets errno.
 */
int
vfu_sgl_read(vfu_ctx_t *vfu_ctx, dma_sg_t *sg, size_t cnt, void *data);

/**
 * Write to the dma region exposed by the client. This can be used as an
 * alternative to reading from a vfu_sgl_get() mapping, if the region is not
 * directly mappable, or DMA notification callbacks have not been provided.
 *
 * During live migration, this call does not mark any of the written pages as
 * dirty; the client is expected to track this.
 *
 * @vfu_ctx: the libvfio-user context
 * @sg: a DMA segment obtained from dma_addr_to_sg
 * @data: data buffer to write
 *
 * @returns 0 on success, -1 on failure. Sets errno.
 */
int
vfu_sgl_write(vfu_ctx_t *vfu_ctx, dma_sg_t *sg, size_t cnt, void *data);

/*
 * Supported PCI regions.
 *
 * Note: in VFIO, each region starts at a terabyte offset
 * (VFIO_PCI_INDEX_TO_OFFSET) and because Linux supports up to 128 TB of user
 * space virtual memory, there can be up to 128 device regions. PCI regions are
 * fixed and in retrospect this choice has proven to be problematic because
 * devices might contain potentially unused regions. New regions can now be
 * positioned anywhere by using the VFIO_REGION_INFO_CAP_TYPE capability.  In
 * vfio-user we don't have this problem because the region index is just an
 * identifier: the VMM memory maps a file descriptor that is passed to it and
 * the mapping offset is derived from the mmap_areas offset value, rather than a
 * static mapping from region index to offset. Thus, additional regions can
 * have static indexes in vfio-user.
 */
enum {
    VFU_PCI_DEV_BAR0_REGION_IDX,
    VFU_PCI_DEV_BAR1_REGION_IDX,
    VFU_PCI_DEV_BAR2_REGION_IDX,
    VFU_PCI_DEV_BAR3_REGION_IDX,
    VFU_PCI_DEV_BAR4_REGION_IDX,
    VFU_PCI_DEV_BAR5_REGION_IDX,
    VFU_PCI_DEV_ROM_REGION_IDX,
    VFU_PCI_DEV_CFG_REGION_IDX,
    VFU_PCI_DEV_VGA_REGION_IDX,
    VFU_PCI_DEV_NUM_REGIONS,
};

typedef enum {
    VFU_PCI_TYPE_CONVENTIONAL,
    VFU_PCI_TYPE_PCI_X_1,
    VFU_PCI_TYPE_PCI_X_2,
    VFU_PCI_TYPE_EXPRESS
} vfu_pci_type_t;

enum {
    VFU_GENERIC_DEV_MIGR_REGION_IDX,
    VFU_GENERIC_DEV_NUM_REGIONS
};

/**
 * Initialize the context for a PCI device. This function must be called only
 * once per libvfio-user context.
 *
 * This function initializes a buffer for the PCI config space, accessible via
 * vfu_pci_get_config_space().
 *
 * Returns 0 on success, or -1 on error, setting errno.
 *
 * @vfu_ctx: the libvfio-user context
 * @pci_type: PCI type (convention PCI, PCI-X mode 1, PCI-X mode2, PCI-Express)
 * @hdr_type: PCI header type. Only PCI_HEADER_TYPE_NORMAL is supported.
 * @revision: PCI/PCI-X/PCIe revision
 */
int
vfu_pci_init(vfu_ctx_t *vfu_ctx, vfu_pci_type_t pci_type,
             int hdr_type, int revision);

/*
 * Set the Vendor ID, Device ID, Subsystem Vendor ID, and Subsystem ID fields of
 * the PCI config header (PCI3 6.2.1, 6.2.4).
 *
 * This must always be called for PCI devices, after vfu_pci_init().
 */
void
vfu_pci_set_id(vfu_ctx_t *vfu_ctx, uint16_t vid, uint16_t did,
               uint16_t ssvid, uint16_t ssid);

/*
 * Set the class code fields (base, sub-class, and programming interface) of the
 * PCI config header (PCI3 6.2.1).
 *
 * If this function is not called, the fields are initialized to zero.
 */
void
vfu_pci_set_class(vfu_ctx_t *vfu_ctx, uint8_t base, uint8_t sub, uint8_t pi);


/*
 * Returns a pointer to the PCI configuration space.
 *
 * PCI config space consists of an initial 64-byte vfu_pci_hdr_t, plus
 * additional space, containing capabilities and/or device-specific
 * configuration.  Standard config space is 256 bytes (PCI_CFG_SPACE_SIZE);
 * extended config space is 4096 bytes (PCI_CFG_SPACE_EXP_SIZE).
 */
vfu_pci_config_space_t *
vfu_pci_get_config_space(vfu_ctx_t *vfu_ctx);

#define VFU_CAP_FLAG_EXTENDED (1 << 0)
#define VFU_CAP_FLAG_CALLBACK (1 << 1)
#define VFU_CAP_FLAG_READONLY (1 << 2)

/**
 * Add a PCI capability to PCI config space.
 *
 * Certain standard capabilities are handled entirely within the library:
 *
 * PCI_CAP_ID_EXP (pxcap)
 * PCI_CAP_ID_MSI (msicap)
 * PCI_CAP_ID_MSIX (msixcap)
 * PCI_CAP_ID_PM (pmcap)
 *
 * However, they must still be explicitly initialized and added here.
 *
 * The contents of @data are copied in. It must start with either a struct
 * cap_hdr or a struct ext_cap_hdr, with the ID field set; the 'next' field is
 * ignored.  For PCI_CAP_ID_VNDR or PCI_EXT_CAP_ID_VNDR, the embedded size field
 * must also be set; in general, any non-fixed-size capability must be
 * initialized such that the size can be derived at this point.
 *
 * If @pos is non-zero, the capability will be placed at the given offset within
 * configuration space. It must not overlap the PCI standard header, or any
 * existing capability. Note that if a capability is added "out of order" in
 * terms of the offset, there is no re-ordering of the capability list written
 * in configuration space.
 *
 * If @pos is zero, the capability will be placed at a suitable offset
 * automatically.
 *
 * The @flags field can be set as follows:
 *
 * VFU_CAP_FLAG_EXTENDED: this is an extended capability; supported if device is
 * of PCI type VFU_PCI_TYPE_{PCI_X_2,EXPRESS}.
 *
 * VFU_CAP_FLAG_CALLBACK: all accesses to the capability are delegated to the
 * callback for the region VFU_PCI_DEV_CFG_REGION_IDX. The callback should copy
 * data into and out of the capability as needed (this could be directly on the
 * config space area from vfu_pci_get_config_space()). It is not supported to
 * allow writes to the initial capability header (ID/next fields).
 *
 * VFU_CAP_FLAG_READONLY: this prevents clients from writing to the capability.
 * By default, clients are allowed to write to any part of the capability,
 * excluding the initial header.
 *
 * Returns the offset of the capability in config space, or -1 on error, with
 * errno set.
 *
 * @vfu_ctx: the libvfio-user context
 * @pos: specific offset for the capability, or 0.
 * @flags: VFU_CAP_FLAG_*
 * @data: capability data, including the header
 */
ssize_t
vfu_pci_add_capability(vfu_ctx_t *vfu_ctx, size_t pos, int flags, void *data);

/**
 * Find the offset within config space of a given capability (if there are
 * multiple possible matches, use vfu_pci_find_next_capability()).
 *
 * Returns 0 if no such capability was found, with errno set.
 *
 * @vfu_ctx: the libvfio-user context
 * @extended whether capability is an extended one or not
 * @id: capability id (PCI_CAP_ID_* or PCI_EXT_CAP_ID *)
 */
size_t
vfu_pci_find_capability(vfu_ctx_t *vfu_ctx, bool extended, int cap_id);

/**
 * Find the offset within config space of the given capability, starting from
 * @pos, which must be the valid offset of an existing capability. This can be
 * used to iterate through multiple capabilities with the same ID.
 *
 * Returns 0 if no more matching capabilities were found, with errno set.
 *
 * @vfu_ctx: the libvfio-user context
 * @extended whether capability is an extended one or not
 * @pos: offset within config space to start looking
 * @id: capability id (PCI_CAP_ID_*)
 */
size_t
vfu_pci_find_next_capability(vfu_ctx_t *vfu_ctx, bool extended,
                             size_t pos, int cap_id);

bool
vfu_sg_is_mappable(vfu_ctx_t *vfu_ctx, dma_sg_t *sg);

/*
 * Creates a new ioeventfd at the given setup memory region with @offset, @size,
 * @fd, @flags and @datamatch.
 *
 * Returns 0 on success and -1 on failure with errno set.
 *
 * @vfu_ctx: the libvfio-user context
 * @region_idx: The index of the memory region to set up the ioeventfd
 * @fd: the value of the file descriptor
 * @gpa_offset: The offset into the memory region
 * @size: size of the ioeventfd
 * @flags: Any flags to set up the ioeventfd
 * @datamatch: sets the datamatch value
 * @shadow_fd: File descriptor that can be mmap'ed, KVM will write there the
 *  otherwise discarded value when the ioeventfd is written to. If set to -1
 *  then a normal ioeventfd is set up instead of a shadow one. The vfio-user
 *  client is free to ignore this, even if it supports shadow ioeventfds.
 *  Requires a kernel with shadow ioeventfd support.
 *  Experimental, must be compiled with SHADOW_IOEVENTFD defined, otherwise
 *  must be -1.
 * @shadow_offset: offset in shadow memory where value is written to.
 */
int
vfu_create_ioeventfd(vfu_ctx_t *vfu_ctx, uint32_t region_idx, int fd,
                     size_t gpa_offset, uint32_t size, uint32_t flags,
                     uint64_t datamatch, int shadow_fd, size_t shadow_offset);
#ifdef __cplusplus
}
#endif

#endif /* LIB_VFIO_USER_H */

/* ex: set tabstop=4 shiftwidth=4 softtabstop=4 expandtab: */