palacios/include/interfaces/vmm_host_dev.h

   1 /*
   2  * This file is part of the Palacios Virtual Machine Monitor developed
   3  * by the V3VEE Project with funding from the United States National
   4  * Science Foundation and the Department of Energy.
   5  *
   6  * The V3VEE Project is a joint project between Northwestern University
   7  * and the University of New Mexico.  You can find out more at
   8  * http://www.v3vee.org
   9  *
  10  * Copyright (c) 2011, Peter Dinda <pdinda@northwestern.edu>
  11  * Copyright (c) 2011, The V3VEE Project <http://www.v3vee.org>
  12  * All rights reserved.
  13  *
  14  * Author: Peter Dinda <pdinda@northwestern.edu>
  15  *
  16  * This is free software.  You are permitted to use,
  17  * redistribute, and modify it as specified in the file "V3VEE_LICENSE".
  18  */
  19
  20
  21 #ifndef __VMM_HOST_DEV_H__
  22 #define __VMM_HOST_DEV_H__
  23
  24 #include <palacios/vmm.h>
  25
  26 /*
  27
  28   The purpose of this interface is to make it possible to implement
  29   virtual devices in the host OS.   It is intended to be used by
  30   passthrough device implementations, such as the generic device
  31   and the PCI front-end device.
  32
  33   One use of this interface, and the generic and PCI passthrough devices
  34   might be to build an interface with simulated devices in QEMU, SST, etc
  35   under a Linux host.  That scenario would look like this:
  36
  37 Guest config:
  38
  39   generic device:
  40     <device class="generic" id="mydev" forward="host_device" hostdev="url" >
  41        ports, memory regions, interrupts set with PASSTHROUGH option
  42     </device>
  43
  44   PCI front devive:
  45     <device class="pci_front" id="mydev", hostdev="url">
  46        vendor and device ids, etc
  47     </device>
  48
  49
  50 Host (Linux) side:
  51
  52     There would be an implementation and registration of the hooks
  53     defined and explained in this file
  54
  55     The implementation might, for example, create an interface to
  56     a user space process, for example like the console
  57     (palacios-console.[ch] + v3_cons.c) or graphics console
  58     (palacios-graphics-console.[ch] + v3_vncserver.c) do
  59     and route the hook functions defined here through it.
  60     Through this interface, the calls could be routed to an SST
  61     device module.
  62
  63 */
  64
  65
  66 /* A host device is opaque to the palacios */
  67 typedef void * v3_host_dev_t;
  68 /* A guest device is opaque to the host */
  69 typedef void * v3_guest_dev_t;
  70 /* Optional support for special interrupt handling ; raise=1 => raise otherwise lower */
  71 typedef void (*v3_guest_dev_intr_t)(v3_host_dev_t hdev, v3_guest_dev_t gdev, uint8_t irq, int raise);
  72
  73 /* There is a notion of a bus class to which the device is attached */
  74 typedef enum { V3_BUS_CLASS_DIRECT, V3_BUS_CLASS_PCI } v3_bus_class_t;
  75
  76 #ifdef __V3VEE__
  77
  78 struct v3_vm_info;
  79
  80 v3_host_dev_t v3_host_dev_open(char *impl,
  81                                v3_bus_class_t bus,
  82                                v3_guest_dev_t gdev,
  83                                v3_guest_dev_intr_t intr,
  84                                struct v3_vm_info *vm);
  85
  86 int v3_host_dev_close(v3_host_dev_t hdev);
  87
  88 uint64_t v3_host_dev_read_io(v3_host_dev_t hostdev,
  89                              uint16_t      port,
  90                              void          *dest,
  91                              uint64_t      len);
  92
  93 uint64_t v3_host_dev_write_io(v3_host_dev_t hostdev,
  94                               uint16_t      port,
  95                               void          *src,
  96                               uint64_t      len);
  97
  98 uint64_t v3_host_dev_read_mem(v3_host_dev_t hostdev,
  99                               addr_t        gpa,
 100                               void          *dest,
 101                               uint64_t      len);
 102
 103 uint64_t v3_host_dev_write_mem(v3_host_dev_t hostdev,
 104                                addr_t        gpa,
 105                                void          *src,
 106                                uint64_t      len);
 107
 108 int v3_host_dev_ack_irq(v3_host_dev_t hostdev, uint8_t irq);
 109
 110 uint64_t v3_host_dev_read_config(v3_host_dev_t hostdev,
 111                                  uint64_t      offset,
 112                                  void          *dest,
 113                                  uint64_t      len);
 114
 115 uint64_t v3_host_dev_write_config(v3_host_dev_t hostdev,
 116                                   uint64_t      offset,
 117                                   void          *src,
 118                                   uint64_t      len);
 119
 120 #endif
 121
 122 struct v3_host_dev_hooks {
 123
 124     // The host is given the implementation name, the type of bus
 125     // this device is attached to and an opaque pointer back to the
 126     // guest device.  It returns an opaque representation of
 127     // the host device it has attached to, with zero indicating
 128     // failure.  The host_priv_data arguement supplies to the
 129     // host the pointer that the VM was originally registered with
 130     v3_host_dev_t (*open)(char *impl,
 131                           v3_bus_class_t bus,
 132                           v3_guest_dev_t gdev,
 133                           v3_guest_dev_intr_t intr,
 134                           void *host_priv_data);
 135
 136     int (*close)(v3_host_dev_t hdev);
 137
 138     // Read/Write from/to an IO port. The read must either
 139     // completely succeed, returning len or completely
 140     // fail, returning != len
 141     // Callee gets the host dev id and the port in the guest
 142     uint64_t (*read_io)(v3_host_dev_t hostdev,
 143                         uint16_t      port,
 144                         void          *dest,
 145                         uint64_t      len);
 146
 147     uint64_t (*write_io)(v3_host_dev_t hostdev,
 148                          uint16_t      port,
 149                          void          *src,
 150                          uint64_t      len);
 151
 152     // Read/Write from/to memory. The reads/writes must
 153     // completely succeed, returning len or completely
 154     // fail, returning != len
 155     // Callee gets the host dev id, and the guest physical address
 156     uint64_t (*read_mem)(v3_host_dev_t hostdev,
 157                          void *        gpa,
 158                          void          *dest,
 159                          uint64_t      len);
 160
 161     uint64_t (*write_mem)(v3_host_dev_t hostdev,
 162                           void *        gpa,
 163                           void          *src,
 164                           uint64_t      len);
 165
 166     //
 167     // Palacios or the guest device will call this
 168     // function when it has injected the irq
 169     // requested by the guest
 170     //
 171     int (*ack_irq)(v3_host_dev_t hostdev, uint8_t irq);
 172
 173     // Configuration space reads/writes for devices that
 174     // have them, such as PCI devices
 175     // As with other reads/writes, these must be fully successful
 176     // or fail
 177     //
 178     // Palacios maintains its own configuration for some
 179     // devices (e.g., pci_passthrough) and will take care of
 180     // relevant hooking/unhooking, and maintain its own
 181     // config space info.   However, a read will return
 182     // the host device's config, while a write will affect
 183     // both the palacios-internal config and the hsot device's config
 184     //
 185     // for V3_BUS_CLASS_PCI they correspond to PCI config space (e.g., BARS, etc)
 186     // reads and writes
 187     //
 188     uint64_t (*read_config)(v3_host_dev_t hostdev,
 189                             uint64_t      offset,
 190                             void          *dest,
 191                             uint64_t      len);
 192
 193     uint64_t (*write_config)(v3_host_dev_t hostdev,
 194                              uint64_t      offset,
 195                              void          *src,
 196                              uint64_t      len);
 197
 198 };
 199
 200 /* This function is how the host will raise an irq to palacios
 201    for the device.   */
 202 int v3_host_dev_raise_irq(v3_host_dev_t hostdev,
 203                           v3_guest_dev_t guest_dev,
 204                           v3_guest_dev_intr_t intr,
 205                           uint8_t irq);
 206 int v3_host_dev_lower_irq(v3_host_dev_t hostdev,
 207                           v3_guest_dev_t guest_dev,
 208                           v3_guest_dev_intr_t intr,
 209                           uint8_t irq);
 210
 211 /* These functions allow the host to read and write the guest
 212    memory by physical address, for example to implement DMA
 213 */
 214 uint64_t v3_host_dev_read_guest_mem(v3_host_dev_t  hostdev,
 215                                     v3_guest_dev_t guest_dev,
 216                                     void *         gpa,
 217                                     void           *dest,
 218                                     uint64_t       len);
 219
 220 uint64_t v3_host_dev_write_guest_mem(v3_host_dev_t  hostdev,
 221                                      v3_guest_dev_t guest_dev,
 222                                      void *         gpa,
 223                                      void           *src,
 224                                      uint64_t       len);
 225
 226
 227 extern void V3_Init_Host_Device_Support(struct v3_host_dev_hooks *hooks);
 228
 229 #endif