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