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 30 #define X86_64_B_SIZE 64 31 #define X86_32_B_SIZE 32 32 33 /* 34 * User not using xc_suspend_* / xc_await_suspent may not want to 35 * include the full libxenevtchn API here. 36 */ 37 struct xenevtchn_handle; 38 39 /* For save's precopy_policy(). */ 40 struct precopy_stats 41 { 42 unsigned int iteration; 43 unsigned int total_written; 44 long dirty_count; /* -1 if unknown */ 45 }; 46 47 /* 48 * A precopy_policy callback may not be running in the same address 49 * space as libxc an so precopy_stats is passed by value. 50 */ 51 typedef int (*precopy_policy_t)(struct precopy_stats, void *); 52 53 /* callbacks provided by xc_domain_save */ 54 struct save_callbacks { 55 /* 56 * Called after expiration of checkpoint interval, 57 * to suspend the guest. 58 */ 59 int (*suspend)(void *data); 60 61 /* 62 * Called before and after every batch of page data sent during 63 * the precopy phase of a live migration to ask the caller what 64 * to do next based on the current state of the precopy migration. 65 * 66 * Should return one of the values listed below: 67 */ 68 #define XGS_POLICY_ABORT (-1) /* Abandon the migration entirely 69 * and tidy up. */ 70 #define XGS_POLICY_CONTINUE_PRECOPY 0 /* Remain in the precopy phase. */ 71 #define XGS_POLICY_STOP_AND_COPY 1 /* Immediately suspend and transmit the 72 * remaining dirty pages. */ 73 precopy_policy_t precopy_policy; 74 75 /* 76 * Called after the guest's dirty pages have been 77 * copied into an output buffer. 78 * Callback function resumes the guest & the device model, 79 * returns to xc_domain_save. 80 * xc_domain_save then flushes the output buffer, while the 81 * guest continues to run. 82 */ 83 int (*postcopy)(void *data); 84 85 /* 86 * Called after the memory checkpoint has been flushed 87 * out into the network. Typical actions performed in this 88 * callback include: 89 * (a) send the saved device model state (for HVM guests), 90 * (b) wait for checkpoint ack 91 * (c) release the network output buffer pertaining to the acked checkpoint. 92 * (c) sleep for the checkpoint interval. 93 * 94 * returns: 95 * 0: terminate checkpointing gracefully 96 * 1: take another checkpoint 97 */ 98 int (*checkpoint)(void *data); 99 100 /* 101 * Called after the checkpoint callback. 102 * 103 * returns: 104 * 0: terminate checkpointing gracefully 105 * 1: take another checkpoint 106 */ 107 int (*wait_checkpoint)(void *data); 108 109 /* Enable qemu-dm logging dirty pages to xen */ 110 int (*switch_qemu_logdirty)(uint32_t domid, unsigned enable, void *data); /* HVM only */ 111 112 /* to be provided as the last argument to each callback function */ 113 void *data; 114 }; 115 116 /* Type of stream. Plain, or using a continuous replication protocol? */ 117 typedef enum { 118 XC_STREAM_PLAIN, 119 XC_STREAM_REMUS, 120 XC_STREAM_COLO, 121 } xc_stream_type_t; 122 123 /** 124 * This function will save a running domain. 125 * 126 * @param xch a handle to an open hypervisor interface 127 * @param io_fd the file descriptor to save a domain to 128 * @param dom the id of the domain 129 * @param flags XCFLAGS_xxx 130 * @param stream_type XC_STREAM_PLAIN if the far end of the stream 131 * doesn't use checkpointing 132 * @param recv_fd Only used for XC_STREAM_COLO. Contains backchannel from 133 * the destination side. 134 * @return 0 on success, -1 on failure 135 */ 136 int xc_domain_save(xc_interface *xch, int io_fd, uint32_t dom, 137 uint32_t flags, struct save_callbacks *callbacks, 138 xc_stream_type_t stream_type, int recv_fd); 139 140 /* callbacks provided by xc_domain_restore */ 141 struct restore_callbacks { 142 /* 143 * Called once the STATIC_DATA_END record has been received/inferred. 144 * 145 * For compatibility with older streams, provides a list of static data 146 * expected to be found in the stream, which was missing. A higher level 147 * toolstack is responsible for providing any necessary compatibiltiy. 148 */ 149 #define XGR_SDD_MISSING_CPUID (1 << 0) 150 #define XGR_SDD_MISSING_MSR (1 << 1) 151 int (*static_data_done)(unsigned int missing, void *data); 152 153 /* Called after a new checkpoint to suspend the guest. */ 154 int (*suspend)(void *data); 155 156 /* 157 * Called after the secondary vm is ready to resume. 158 * Callback function resumes the guest & the device model, 159 * returns to xc_domain_restore. 160 */ 161 int (*postcopy)(void *data); 162 163 /* 164 * A checkpoint record has been found in the stream. 165 * returns: 166 */ 167 #define XGR_CHECKPOINT_ERROR 0 /* Terminate processing */ 168 #define XGR_CHECKPOINT_SUCCESS 1 /* Continue reading more data from the stream */ 169 #define XGR_CHECKPOINT_FAILOVER 2 /* Failover and resume VM */ 170 int (*checkpoint)(void *data); 171 172 /* 173 * Called after the checkpoint callback. 174 * 175 * returns: 176 * 0: terminate checkpointing gracefully 177 * 1: take another checkpoint 178 */ 179 int (*wait_checkpoint)(void *data); 180 181 /* 182 * callback to send store gfn and console gfn to xl 183 * if we want to resume vm before xc_domain_save() 184 * exits. 185 */ 186 void (*restore_results)(xen_pfn_t store_gfn, xen_pfn_t console_gfn, 187 void *data); 188 189 /* to be provided as the last argument to each callback function */ 190 void *data; 191 }; 192 193 /** 194 * This function will restore a saved domain. 195 * 196 * Domain is restored in a suspended state ready to be unpaused. 197 * 198 * @param xch a handle to an open hypervisor interface 199 * @param io_fd the file descriptor to restore a domain from 200 * @param dom the id of the domain 201 * @param store_evtchn the xenstore event channel for this domain to use 202 * @param store_mfn filled with the gfn of the store page 203 * @param store_domid the backend domain for xenstore 204 * @param console_evtchn the console event channel for this domain to use 205 * @param console_mfn filled with the gfn of the console page 206 * @param console_domid the backend domain for xenconsole 207 * @param stream_type XC_STREAM_PLAIN if the far end of the stream is using 208 * checkpointing 209 * @param callbacks non-NULL to receive a callback to restore toolstack 210 * specific data 211 * @param send_back_fd Only used for XC_STREAM_COLO. Contains backchannel to 212 * the source side. 213 * @return 0 on success, -1 on failure 214 */ 215 int xc_domain_restore(xc_interface *xch, int io_fd, uint32_t dom, 216 unsigned int store_evtchn, unsigned long *store_mfn, 217 uint32_t store_domid, unsigned int console_evtchn, 218 unsigned long *console_mfn, uint32_t console_domid, 219 xc_stream_type_t stream_type, 220 struct restore_callbacks *callbacks, int send_back_fd); 221 222 /** 223 * This function will create a domain for a paravirtualized Linux 224 * using file names pointing to kernel and ramdisk 225 * 226 * @parm xch a handle to an open hypervisor interface 227 * @parm domid the id of the domain 228 * @parm mem_mb memory size in megabytes 229 * @parm image_name name of the kernel image file 230 * @parm ramdisk_name name of the ramdisk image file 231 * @parm cmdline command line string 232 * @parm flags domain creation flags 233 * @parm store_evtchn the store event channel for this domain to use 234 * @parm store_mfn returned with the mfn of the store page 235 * @parm console_evtchn the console event channel for this domain to use 236 * @parm conole_mfn returned with the mfn of the console page 237 * @return 0 on success, -1 on failure 238 */ 239 int xc_linux_build(xc_interface *xch, 240 uint32_t domid, 241 unsigned int mem_mb, 242 const char *image_name, 243 const char *ramdisk_name, 244 const char *cmdline, 245 const char *features, 246 unsigned long flags, 247 unsigned int store_evtchn, 248 unsigned long *store_mfn, 249 unsigned int console_evtchn, 250 unsigned long *console_mfn); 251 252 struct xc_hvm_firmware_module { 253 uint8_t *data; 254 uint32_t length; 255 uint64_t guest_addr_out; 256 }; 257 258 /* 259 * Sets *lockfd to -1. 260 * Has deallocated everything even on error. 261 */ 262 int xc_suspend_evtchn_release(xc_interface *xch, 263 struct xenevtchn_handle *xce, 264 uint32_t domid, int suspend_evtchn, int *lockfd); 265 266 /** 267 * This function eats the initial notification. 268 * xce must not be used for anything else 269 * See xc_suspend_evtchn_init_sane re lockfd. 270 */ 271 int xc_suspend_evtchn_init_exclusive(xc_interface *xch, 272 struct xenevtchn_handle *xce, 273 uint32_t domid, int port, int *lockfd); 274 275 /* xce must not be used for anything else */ 276 int xc_await_suspend(xc_interface *xch, struct xenevtchn_handle *xce, 277 int suspend_evtchn); 278 279 /** 280 * The port will be signaled immediately after this call 281 * The caller should check the domain status and look for the next event 282 * On success, *lockfd will be set to >=0 and *lockfd must be preserved 283 * and fed to xc_suspend_evtchn_release. (On error *lockfd is 284 * undefined and xc_suspend_evtchn_release is not allowed.) 285 */ 286 int xc_suspend_evtchn_init_sane(xc_interface *xch, 287 struct xenevtchn_handle *xce, 288 uint32_t domid, int port, int *lockfd); 289 290 int xc_mark_page_online(xc_interface *xch, unsigned long start, 291 unsigned long end, uint32_t *status); 292 293 int xc_mark_page_offline(xc_interface *xch, unsigned long start, 294 unsigned long end, uint32_t *status); 295 296 int xc_query_page_offline_status(xc_interface *xch, unsigned long start, 297 unsigned long end, uint32_t *status); 298 299 int xc_exchange_page(xc_interface *xch, uint32_t domid, xen_pfn_t mfn); 300 301 302 /** 303 * Memory related information, such as PFN types, the P2M table, 304 * the guest word width and the guest page table levels. 305 */ 306 struct xc_domain_meminfo { 307 unsigned int pt_levels; 308 unsigned int guest_width; 309 xen_pfn_t *pfn_type; 310 xen_pfn_t *p2m_table; 311 unsigned long p2m_size; 312 }; 313 314 int xc_map_domain_meminfo(xc_interface *xch, uint32_t domid, 315 struct xc_domain_meminfo *minfo); 316 317 int xc_unmap_domain_meminfo(xc_interface *xch, struct xc_domain_meminfo *mem); 318 319 /** 320 * This function map m2p table 321 * @parm xch a handle to an open hypervisor interface 322 * @parm max_mfn the max pfn 323 * @parm prot the flags to map, such as read/write etc 324 * @parm mfn0 return the first mfn, can be NULL 325 * @return mapped m2p table on success, NULL on failure 326 */ 327 xen_pfn_t *xc_map_m2p(xc_interface *xch, 328 unsigned long max_mfn, 329 int prot, 330 unsigned long *mfn0); 331 #endif /* XENGUEST_H */ 332