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