1 /****************************************************************************** 2 * xenguest.h 3 * 4 * A library for guest domain management in Xen. 5 * 6 * Copyright (c) 2003-2004, K A Fraser. 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; 11 * version 2.1 of the License. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library; If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 #ifndef XENGUEST_H 23 #define XENGUEST_H 24 25 #define XC_NUMA_NO_NODE (~0U) 26 27 #define XCFLAGS_LIVE (1 << 0) 28 #define XCFLAGS_DEBUG (1 << 1) 29 #define XCFLAGS_HVM (1 << 2) 30 #define XCFLAGS_STDVGA (1 << 3) 31 #define XCFLAGS_CHECKPOINT_COMPRESS (1 << 4) 32 33 #define X86_64_B_SIZE 64 34 #define X86_32_B_SIZE 32 35 36 /* 37 * User not using xc_suspend_* / xc_await_suspent may not want to 38 * include the full libxenevtchn API here. 39 */ 40 struct xenevtchn_handle; 41 42 /* For save's precopy_policy(). */ 43 struct precopy_stats 44 { 45 unsigned int iteration; 46 unsigned int total_written; 47 long dirty_count; /* -1 if unknown */ 48 }; 49 50 /* 51 * A precopy_policy callback may not be running in the same address 52 * space as libxc an so precopy_stats is passed by value. 53 */ 54 typedef int (*precopy_policy_t)(struct precopy_stats, void *); 55 56 /* callbacks provided by xc_domain_save */ 57 struct save_callbacks { 58 /* Called after expiration of checkpoint interval, 59 * to suspend the guest. 60 */ 61 int (*suspend)(void* data); 62 63 /* 64 * Called before and after every batch of page data sent during 65 * the precopy phase of a live migration to ask the caller what 66 * to do next based on the current state of the precopy migration. 67 * 68 * Should return one of the values listed below: 69 */ 70 #define XGS_POLICY_ABORT (-1) /* Abandon the migration entirely 71 * and tidy up. */ 72 #define XGS_POLICY_CONTINUE_PRECOPY 0 /* Remain in the precopy phase. */ 73 #define XGS_POLICY_STOP_AND_COPY 1 /* Immediately suspend and transmit the 74 * remaining dirty pages. */ 75 precopy_policy_t precopy_policy; 76 77 /* 78 * Called after the guest's dirty pages have been 79 * copied into an output buffer. 80 * Callback function resumes the guest & the device model, 81 * returns to xc_domain_save. 82 * xc_domain_save then flushes the output buffer, while the 83 * guest continues to run. 84 */ 85 int (*postcopy)(void* data); 86 87 /* 88 * Called after the memory checkpoint has been flushed 89 * out into the network. Typical actions performed in this 90 * callback include: 91 * (a) send the saved device model state (for HVM guests), 92 * (b) wait for checkpoint ack 93 * (c) release the network output buffer pertaining to the acked checkpoint. 94 * (c) sleep for the checkpoint interval. 95 * 96 * returns: 97 * 0: terminate checkpointing gracefully 98 * 1: take another checkpoint 99 */ 100 int (*checkpoint)(void* data); 101 102 /* 103 * Called after the checkpoint callback. 104 * 105 * returns: 106 * 0: terminate checkpointing gracefully 107 * 1: take another checkpoint 108 */ 109 int (*wait_checkpoint)(void* data); 110 111 /* Enable qemu-dm logging dirty pages to xen */ 112 int (*switch_qemu_logdirty)(uint32_t domid, unsigned enable, void *data); /* HVM only */ 113 114 /* to be provided as the last argument to each callback function */ 115 void* data; 116 }; 117 118 typedef enum { 119 XC_MIG_STREAM_NONE, /* plain stream */ 120 XC_MIG_STREAM_REMUS, 121 XC_MIG_STREAM_COLO, 122 } xc_migration_stream_t; 123 124 /** 125 * This function will save a running domain. 126 * 127 * @parm xch a handle to an open hypervisor interface 128 * @parm fd the file descriptor to save a domain to 129 * @parm dom the id of the domain 130 * @param stream_type XC_MIG_STREAM_NONE if the far end of the stream 131 * doesn't use checkpointing 132 * @return 0 on success, -1 on failure 133 */ 134 int xc_domain_save(xc_interface *xch, int io_fd, uint32_t dom, 135 uint32_t flags /* XCFLAGS_xxx */, 136 struct save_callbacks* callbacks, int hvm, 137 xc_migration_stream_t stream_type, int recv_fd); 138 139 /* callbacks provided by xc_domain_restore */ 140 struct restore_callbacks { 141 /* Called after a new checkpoint to suspend the guest. 142 */ 143 int (*suspend)(void* data); 144 145 /* Called after the secondary vm is ready to resume. 146 * Callback function resumes the guest & the device model, 147 * returns to xc_domain_restore. 148 */ 149 int (*postcopy)(void* data); 150 151 /* A checkpoint record has been found in the stream. 152 * returns: */ 153 #define XGR_CHECKPOINT_ERROR 0 /* Terminate processing */ 154 #define XGR_CHECKPOINT_SUCCESS 1 /* Continue reading more data from the stream */ 155 #define XGR_CHECKPOINT_FAILOVER 2 /* Failover and resume VM */ 156 int (*checkpoint)(void* data); 157 158 /* 159 * Called after the checkpoint callback. 160 * 161 * returns: 162 * 0: terminate checkpointing gracefully 163 * 1: take another checkpoint 164 */ 165 int (*wait_checkpoint)(void* data); 166 167 /* 168 * callback to send store gfn and console gfn to xl 169 * if we want to resume vm before xc_domain_save() 170 * exits. 171 */ 172 void (*restore_results)(xen_pfn_t store_gfn, xen_pfn_t console_gfn, 173 void *data); 174 175 /* to be provided as the last argument to each callback function */ 176 void* data; 177 }; 178 179 /** 180 * This function will restore a saved domain. 181 * 182 * Domain is restored in a suspended state ready to be unpaused. 183 * 184 * @parm xch a handle to an open hypervisor interface 185 * @parm fd the file descriptor to restore a domain from 186 * @parm dom the id of the domain 187 * @parm store_evtchn the store event channel for this domain to use 188 * @parm store_mfn returned with the mfn of the store page 189 * @parm hvm non-zero if this is a HVM restore 190 * @parm pae non-zero if this HVM domain has PAE support enabled 191 * @parm stream_type non-zero if the far end of the stream is using checkpointing 192 * @parm callbacks non-NULL to receive a callback to restore toolstack 193 * specific data 194 * @return 0 on success, -1 on failure 195 */ 196 int xc_domain_restore(xc_interface *xch, int io_fd, uint32_t dom, 197 unsigned int store_evtchn, unsigned long *store_mfn, 198 uint32_t store_domid, unsigned int console_evtchn, 199 unsigned long *console_mfn, uint32_t console_domid, 200 unsigned int hvm, unsigned int pae, 201 xc_migration_stream_t stream_type, 202 struct restore_callbacks *callbacks, int send_back_fd); 203 204 /** 205 * This function will create a domain for a paravirtualized Linux 206 * using file names pointing to kernel and ramdisk 207 * 208 * @parm xch a handle to an open hypervisor interface 209 * @parm domid the id of the domain 210 * @parm mem_mb memory size in megabytes 211 * @parm image_name name of the kernel image file 212 * @parm ramdisk_name name of the ramdisk image file 213 * @parm cmdline command line string 214 * @parm flags domain creation flags 215 * @parm store_evtchn the store event channel for this domain to use 216 * @parm store_mfn returned with the mfn of the store page 217 * @parm console_evtchn the console event channel for this domain to use 218 * @parm conole_mfn returned with the mfn of the console page 219 * @return 0 on success, -1 on failure 220 */ 221 int xc_linux_build(xc_interface *xch, 222 uint32_t domid, 223 unsigned int mem_mb, 224 const char *image_name, 225 const char *ramdisk_name, 226 const char *cmdline, 227 const char *features, 228 unsigned long flags, 229 unsigned int store_evtchn, 230 unsigned long *store_mfn, 231 unsigned int console_evtchn, 232 unsigned long *console_mfn); 233 234 struct xc_hvm_firmware_module { 235 uint8_t *data; 236 uint32_t length; 237 uint64_t guest_addr_out; 238 }; 239 240 /* 241 * Sets *lockfd to -1. 242 * Has deallocated everything even on error. 243 */ 244 int xc_suspend_evtchn_release(xc_interface *xch, 245 struct xenevtchn_handle *xce, 246 uint32_t domid, int suspend_evtchn, int *lockfd); 247 248 /** 249 * This function eats the initial notification. 250 * xce must not be used for anything else 251 * See xc_suspend_evtchn_init_sane re lockfd. 252 */ 253 int xc_suspend_evtchn_init_exclusive(xc_interface *xch, 254 struct xenevtchn_handle *xce, 255 uint32_t domid, int port, int *lockfd); 256 257 /* xce must not be used for anything else */ 258 int xc_await_suspend(xc_interface *xch, struct xenevtchn_handle *xce, 259 int suspend_evtchn); 260 261 /** 262 * The port will be signaled immediately after this call 263 * The caller should check the domain status and look for the next event 264 * On success, *lockfd will be set to >=0 and *lockfd must be preserved 265 * and fed to xc_suspend_evtchn_release. (On error *lockfd is 266 * undefined and xc_suspend_evtchn_release is not allowed.) 267 */ 268 int xc_suspend_evtchn_init_sane(xc_interface *xch, 269 struct xenevtchn_handle *xce, 270 uint32_t domid, int port, int *lockfd); 271 272 int xc_mark_page_online(xc_interface *xch, unsigned long start, 273 unsigned long end, uint32_t *status); 274 275 int xc_mark_page_offline(xc_interface *xch, unsigned long start, 276 unsigned long end, uint32_t *status); 277 278 int xc_query_page_offline_status(xc_interface *xch, unsigned long start, 279 unsigned long end, uint32_t *status); 280 281 int xc_exchange_page(xc_interface *xch, uint32_t domid, xen_pfn_t mfn); 282 283 284 /** 285 * Memory related information, such as PFN types, the P2M table, 286 * the guest word width and the guest page table levels. 287 */ 288 struct xc_domain_meminfo { 289 unsigned int pt_levels; 290 unsigned int guest_width; 291 xen_pfn_t *pfn_type; 292 xen_pfn_t *p2m_table; 293 unsigned long p2m_size; 294 }; 295 296 int xc_map_domain_meminfo(xc_interface *xch, uint32_t domid, 297 struct xc_domain_meminfo *minfo); 298 299 int xc_unmap_domain_meminfo(xc_interface *xch, struct xc_domain_meminfo *mem); 300 301 /** 302 * This function map m2p table 303 * @parm xch a handle to an open hypervisor interface 304 * @parm max_mfn the max pfn 305 * @parm prot the flags to map, such as read/write etc 306 * @parm mfn0 return the first mfn, can be NULL 307 * @return mapped m2p table on success, NULL on failure 308 */ 309 xen_pfn_t *xc_map_m2p(xc_interface *xch, 310 unsigned long max_mfn, 311 int prot, 312 unsigned long *mfn0); 313 #endif /* XENGUEST_H */ 314