include/hw/hyperv/vmbus.h

   1 /*
   2  * QEMU Hyper-V VMBus
   3  *
   4  * Copyright (c) 2017-2018 Virtuozzo International GmbH.
   5  *
   6  * This work is licensed under the terms of the GNU GPL, version 2 or later.
   7  * See the COPYING file in the top-level directory.
   8  */
   9
  10 #ifndef HW_HYPERV_VMBUS_H
  11 #define HW_HYPERV_VMBUS_H
  12
  13 #include "sysemu/sysemu.h"
  14 #include "sysemu/dma.h"
  15 #include "hw/qdev-core.h"
  16 #include "migration/vmstate.h"
  17 #include "hw/hyperv/vmbus-proto.h"
  18 #include "qemu/uuid.h"
  19
  20 #define TYPE_VMBUS_DEVICE "vmbus-dev"
  21
  22 #define VMBUS_DEVICE(obj) \
  23     OBJECT_CHECK(VMBusDevice, (obj), TYPE_VMBUS_DEVICE)
  24 #define VMBUS_DEVICE_CLASS(klass) \
  25     OBJECT_CLASS_CHECK(VMBusDeviceClass, (klass), TYPE_VMBUS_DEVICE)
  26 #define VMBUS_DEVICE_GET_CLASS(obj) \
  27     OBJECT_GET_CLASS(VMBusDeviceClass, (obj), TYPE_VMBUS_DEVICE)
  28
  29 /*
  30  * Object wrapping a GPADL -- GPA Descriptor List -- an array of guest physical
  31  * pages, to be used for various buffers shared between the host and the guest.
  32  */
  33 typedef struct VMBusGpadl VMBusGpadl;
  34 /*
  35  * VMBus channel -- a pair of ring buffers for either direction, placed within
  36  * one GPADL, and the associated notification means.
  37  */
  38 typedef struct VMBusChannel VMBusChannel;
  39 /*
  40  * Base class for VMBus devices.  Includes one or more channels.  Identified by
  41  * class GUID and instance GUID.
  42  */
  43 typedef struct VMBusDevice VMBusDevice;
  44
  45 typedef void(*VMBusChannelNotifyCb)(struct VMBusChannel *chan);
  46
  47 typedef struct VMBusDeviceClass {
  48     DeviceClass parent;
  49
  50     QemuUUID classid;
  51     QemuUUID instanceid;     /* Fixed UUID for singleton devices */
  52     uint16_t channel_flags;
  53     uint16_t mmio_size_mb;
  54
  55     /* Extentions to standard device callbacks */
  56     void (*vmdev_realize)(VMBusDevice *vdev, Error **errp);
  57     void (*vmdev_unrealize)(VMBusDevice *vdev);
  58     void (*vmdev_reset)(VMBusDevice *vdev);
  59     /*
  60      * Calculate the number of channels based on the device properties.  Called
  61      * at realize time.
  62      **/
  63     uint16_t (*num_channels)(VMBusDevice *vdev);
  64     /*
  65      * Device-specific actions to complete the otherwise successful process of
  66      * opening a channel.
  67      * Return 0 on success, -errno on failure.
  68      */
  69     int (*open_channel)(VMBusChannel *chan);
  70     /*
  71      * Device-specific actions to perform before closing a channel.
  72      */
  73     void (*close_channel)(VMBusChannel *chan);
  74     /*
  75      * Main device worker; invoked in response to notifications from either
  76      * side, when there's work to do with the data in the channel ring buffers.
  77      */
  78     VMBusChannelNotifyCb chan_notify_cb;
  79 } VMBusDeviceClass;
  80
  81 struct VMBusDevice {
  82     DeviceState parent;
  83     QemuUUID instanceid;
  84     uint16_t num_channels;
  85     VMBusChannel *channels;
  86     AddressSpace *dma_as;
  87 };
  88
  89 extern const VMStateDescription vmstate_vmbus_dev;
  90
  91 /*
  92  * A unit of work parsed out of a message in the receive (i.e. guest->host)
  93  * ring buffer of a channel.  It's supposed to be subclassed (through
  94  * embedding) by the specific devices.
  95  */
  96 typedef struct VMBusChanReq {
  97     VMBusChannel *chan;
  98     uint16_t pkt_type;
  99     uint32_t msglen;
 100     void *msg;
 101     uint64_t transaction_id;
 102     bool need_comp;
 103     QEMUSGList sgl;
 104 } VMBusChanReq;
 105
 106 VMBusDevice *vmbus_channel_device(VMBusChannel *chan);
 107 VMBusChannel *vmbus_device_channel(VMBusDevice *dev, uint32_t chan_idx);
 108 uint32_t vmbus_channel_idx(VMBusChannel *chan);
 109 bool vmbus_channel_is_open(VMBusChannel *chan);
 110
 111 /*
 112  * Notify (on guest's behalf) the host side of the channel that there's data in
 113  * the ringbuffer to process.
 114  */
 115 void vmbus_channel_notify_host(VMBusChannel *chan);
 116
 117 /*
 118  * Reserve space for a packet in the send (i.e. host->guest) ringbuffer.  If
 119  * there isn't enough room, indicate that to the guest, to be notified when it
 120  * becomes available.
 121  * Return 0 on success, negative errno on failure.
 122  * The ringbuffer indices are NOT updated, the requested space indicator may.
 123  */
 124 int vmbus_channel_reserve(VMBusChannel *chan,
 125                           uint32_t desclen, uint32_t msglen);
 126
 127 /*
 128  * Send a packet to the guest.  The space for the packet MUST be reserved
 129  * first.
 130  * Return total number of bytes placed in the send ringbuffer on success,
 131  * negative errno on failure.
 132  * The ringbuffer indices are updated on success, and the guest is signaled if
 133  * needed.
 134  */
 135 ssize_t vmbus_channel_send(VMBusChannel *chan, uint16_t pkt_type,
 136                            void *desc, uint32_t desclen,
 137                            void *msg, uint32_t msglen,
 138                            bool need_comp, uint64_t transaction_id);
 139
 140 /*
 141  * Prepare to fetch a batch of packets from the receive ring buffer.
 142  * Return 0 on success, negative errno on failure.
 143  */
 144 int vmbus_channel_recv_start(VMBusChannel *chan);
 145
 146 /*
 147  * Shortcut for a common case of sending a simple completion packet with no
 148  * auxiliary descriptors.
 149  */
 150 ssize_t vmbus_channel_send_completion(VMBusChanReq *req,
 151                                       void *msg, uint32_t msglen);
 152
 153 /*
 154  * Peek at the receive (i.e. guest->host) ring buffer and extract a unit of
 155  * work (a device-specific subclass of VMBusChanReq) from a packet if there's
 156  * one.
 157  * Return an allocated buffer, containing the request of @size with filled
 158  * VMBusChanReq at the beginning, followed by the message payload, or NULL on
 159  * failure.
 160  * The ringbuffer indices are NOT updated, nor is the private copy of the read
 161  * index.
 162  */
 163 void *vmbus_channel_recv_peek(VMBusChannel *chan, uint32_t size);
 164
 165 /*
 166  * Update the private copy of the read index once the preceding peek is deemed
 167  * successful.
 168  * The ringbuffer indices are NOT updated.
 169  */
 170 void vmbus_channel_recv_pop(VMBusChannel *chan);
 171
 172 /*
 173  * Propagate the private copy of the read index into the receive ring buffer,
 174  * and thus complete the reception of a series of packets.  Notify guest if
 175  * needed.
 176  * Return the number of bytes popped off the receive ring buffer by the
 177  * preceding recv_peek/recv_pop calls on success, negative errno on failure.
 178  */
 179 ssize_t vmbus_channel_recv_done(VMBusChannel *chan);
 180
 181 /*
 182  * Free the request allocated by vmbus_channel_recv_peek, together with its
 183  * fields.
 184  */
 185 void vmbus_free_req(void *req);
 186
 187 /*
 188  * Find and reference a GPADL by @gpadl_id.
 189  * If not found return NULL.
 190  */
 191 VMBusGpadl *vmbus_get_gpadl(VMBusChannel *chan, uint32_t gpadl_id);
 192
 193 /*
 194  * Unreference @gpadl.  If the reference count drops to zero, free it.
 195  * @gpadl may be NULL, in which case nothing is done.
 196  */
 197 void vmbus_put_gpadl(VMBusGpadl *gpadl);
 198
 199 /*
 200  * Calculate total length in bytes of @gpadl.
 201  * @gpadl must be valid.
 202  */
 203 uint32_t vmbus_gpadl_len(VMBusGpadl *gpadl);
 204
 205 /*
 206  * Copy data from @iov to @gpadl at offset @off.
 207  * Return the number of bytes copied, or a negative status on failure.
 208  */
 209 ssize_t vmbus_iov_to_gpadl(VMBusChannel *chan, VMBusGpadl *gpadl, uint32_t off,
 210                            const struct iovec *iov, size_t iov_cnt);
 211
 212 /*
 213  * Map SGList contained in the request @req, at offset @off and no more than
 214  * @len bytes, for io in direction @dir, and populate @iov with the mapped
 215  * iovecs.
 216  * Return the number of iovecs mapped, or negative status on failure.
 217  */
 218 int vmbus_map_sgl(VMBusChanReq *req, DMADirection dir, struct iovec *iov,
 219                   unsigned iov_cnt, size_t len, size_t off);
 220
 221 /*
 222  * Unmap *iov mapped with vmbus_map_sgl, marking the number of bytes @accessed.
 223  */
 224 void vmbus_unmap_sgl(VMBusChanReq *req, DMADirection dir, struct iovec *iov,
 225                      unsigned iov_cnt, size_t accessed);
 226
 227 void vmbus_save_req(QEMUFile *f, VMBusChanReq *req);
 228 void *vmbus_load_req(QEMUFile *f, VMBusDevice *dev, uint32_t size);
 229
 230 #endif