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
  29   The purpose of this interface is to make it possible to implement
  30   virtual devices in the host OS.   It is intended to be used by
  31   passthrough device implementations, such as the generic device
  32   and the PCI passthrough device.
  33
  34   One use of this interface, and the generic and PCI passthrough devices
  35   might be to build an interface with simulated devices in SST
  36   under a Linux host.  That scenario would look like this:
  37
  38 Guest config:
  39
  40   generic device:
  41     <device class="generic" id="mydev" impl="host_sst">
  42        ports, memory regions, interrupts set with PASSTHROUGH option
  43     </device>
  44
  45   PCI passthrough devive:
  46     <device class="pci_passthrough" id="mydev", impl="host_sst">
  47        vendor and device ids, etc
  48     </device>
  49
  50 impl="physical" or lack of an impl key would indicate that direct hardware
  51 access is expected, which is how these devices currently operate.
  52
  53
  54 Host (Linux) side:
  55
  56     There would be an implementation and registration of the hooks
  57     defined and explained in this file
  58
  59     The implementation might, for example, create an interface to
  60     a user space process, for example like the console
  61     (palacios-console.[ch] + v3_cons.c) or graphics console
  62     (palacios-graphics-console.[ch] + v3_vncserver.c) do
  63     and route the hook functions defined here through it.
  64     Through this interface, the calls could be routed to an SST
  65     device module.
  66
  67 */
  68
  69
  70 /* A host device is opaque to the palacios */
  71 typedef void * v3_host_dev_t;
  72 /* A guest device is opaque to the host */
  73 typedef void * v3_guest_dev_t;
  74
  75
  76 /* There is a notion of a bus class to which the device is attached */
  77 typedef enum { DIRECT, PCI } v3_bus_class_t;
  78
  79 #ifdef __V3VEE__
  80
  81 v3_host_dev_t v3_host_dev_open(char *impl,
  82                                v3_bus_class_t bus,
  83                                v3_guest_dev_t gdev);
  84
  85 uin64_t v3_host_dev_read_io(v3_host_dev_t hostdev,
  86                             uint16_t      port,
  87                             void          *dest
  88                             uint64_t      len);
  89
  90 uint64_t v3_host_dev_write_io(v3_host_dev_t hostdev,
  91                               uint16_t      port,
  92                               void          *src,
  93                               uint64_t      len);
  94
  95 uint64_t v3_host_dev_read_mem(v3_host_dev_t hostdev,
  96                               addr_t        gpa,
  97                               void          *dest,
  98                               uint64_t      len);
  99
 100 uint64_t v3_host_dev_write_mem(v3_host_dev_t hostdev,
 101                                addr_t        gpa,
 102                                void          *src,
 103                                uint64_t      len);
 104
 105 int v3_host_dev_ack_irq(v3_host_dev_t hostdev, uint32_t irq);
 106
 107 uint64_t v3_host_dev_config_read(v3_host_dev_t hostdev,
 108                                  void          *dest,
 109                                  uint64_t      len);
 110
 111 uint64_t v3_host_dev_config_write(v3_host_dev_t hostdev,
 112                                   void          *src,
 113                                   uint64_t      len);
 114
 115 #endif
 116
 117 struct v3_host_dev_hooks {
 118
 119     // The host is given the implementation name, the type of bus
 120     // this device is attached to and an opaque pointer back to the
 121     // guest device.  It returns an opaque representation of
 122     // the host device it has attached to, with zero indicating
 123     // failure
 124     v3_host_dev_t (*open)(char *impl,
 125                           v3_bus_class_t bus,
 126                           v3_guest_dev_t gdev);
 127
 128     // Read/Write from/to an IO port. The read must either
 129     // completely succeed, returning len or completely
 130     // fail, returning != len
 131     // Callee gets the host dev id and the port in the guest
 132     uint64_t (*read_io)(v3_host_dev_t hostdev,
 133                         uint16_t      port,
 134                         void          *dest
 135                         uint64_t      len);
 136
 137     uint64_t (*write_io)(v3_host_dev_t hostdev,
 138                          uint16_t      port,
 139                          void          *src,
 140                          uint64_t      len);
 141
 142     // Read/Write from/to memory. The reads/writes must
 143     // completely succeed, returning len or completely
 144     // fail, returning != len
 145     // Callee gets the host dev id, and the guest physical address
 146     uint64_t (*read_mem)(v3_host_dev_t hostdev,
 147                          addr_t        gpa,
 148                          void          *dest,
 149                          uint64_t      len);
 150
 151     uint64_t (*write_mem)(v3_host_dev_t hostdev,
 152                           addr_t        gpa,
 153                           void          *src,
 154                           uint64_t      len);
 155
 156     // Palacis will call this when it has taken posession of the
 157     // IRQ ad wants the host device to lower it
 158     // This interface is unclear
 159     //
 160     // One potential use would be to allow for a palacios
 161     // side device to raise the irq asynchronously from
 162     // the host device.  If this is permitted, then we
 163     // need a way of informing the host device that the
 164     // irq has actually been signalled.
 165     int (*ack_irq)(v3_host_dev_t hostdev, uint8_t irq);
 166
 167     // Configuration space reads/writes for devices that
 168     // have them, such as PCI devices
 169     // As with other reads/writes, these must be fully successful
 170     // or fail
 171     //
 172     // Palacios maintains its own configuration for some
 173     // devices (e.g., pci_passthrough) and will take care of
 174     // relevant hooking/unhooking, and maintain its own
 175     // config space info.   However, a read will return
 176     // the host device's config, while a write will affect
 177     // both the palacios-internal config and the hsot device's config
 178     uint64_t (*config_read)(v3_host_dev_t hostdev,
 179                             void          *dest,
 180                             uint64_t      len);
 181
 182     uint64_t (*config_write)(v3_host_dev_t hostdev,
 183                              void          *src,
 184                              uint64_t      len);
 185
 186 };
 187
 188 /* This function is how the host will raise an irq to palacios
 189    for the device.   The IRQ argument will be ignored for devices
 190    whose irqs are managed by palacios */
 191 int v3_host_dev_raise_irq(v3_host_dev_t hostdev,
 192                           v3_guest_dev_t guest_dev,
 193                           uint8_t irq);
 194
 195 /* These functions allow the host to read and write the guest
 196    memory by physical address, for example to implement DMA
 197
 198    These functions are incremental - that is, they can return
 199    a smaller amount than requested
 200 */
 201 uint64_t v3_host_dev_read_guest_mem(v3_host_dev_t  hostdev,
 202                                     v3_guest_dev_t guest_dev,
 203                                     addr_t         gpa,
 204                                     void           *dest,
 205                                     uint64_t       len);
 206
 207 uint64_t v3_host_dev_write_guest_mem(v3_host_dev_t  hostdev,
 208                                      v3_guest_dev_t guest_dev,
 209                                      addr_t         gpa,
 210                                      void           *src,
 211                                      uint64_t       len);
 212
 213
 214 extern void V3_Init_Host_Device_Support(struct v3_host_dev_hooks *hooks);
 215
 216 #endif