ia64/xen-unstable

view tools/libxen/include/xen_vm.h @ 12317:4e3ddf1288fb

Add support for VM.destroy RPC in libxen.

Signed-off-by: Jim Fehlig <jfehlig@novell.com>
author jfehlig@jfehlig2.provo.novell.com
date Tue Nov 07 18:14:16 2006 -0700 (2006-11-07)
parents 5bef3f695b55
children 08b38d041269
line source
1 /*
2 * Copyright (c) 2006, XenSource Inc.
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 */
19 #ifndef XEN_VM_H
20 #define XEN_VM_H
22 #include "xen_boot_type.h"
23 #include "xen_common.h"
24 #include "xen_cpu_feature.h"
25 #include "xen_host_decl.h"
26 #include "xen_int_float_map.h"
27 #include "xen_on_crash_behaviour.h"
28 #include "xen_on_normal_exit.h"
29 #include "xen_string_string_map.h"
30 #include "xen_vbd_decl.h"
31 #include "xen_vif_decl.h"
32 #include "xen_vm_decl.h"
33 #include "xen_vm_power_state.h"
34 #include "xen_vtpm_decl.h"
37 /*
38 * The VM class.
39 *
40 * A virtual machine (or 'guest').
41 */
44 /**
45 * Free the given xen_vm. The given handle must have been allocated by
46 * this library.
47 */
48 extern void
49 xen_vm_free(xen_vm vm);
52 typedef struct xen_vm_set
53 {
54 size_t size;
55 xen_vm *contents[];
56 } xen_vm_set;
58 /**
59 * Allocate a xen_vm_set of the given size.
60 */
61 extern xen_vm_set *
62 xen_vm_set_alloc(size_t size);
64 /**
65 * Free the given xen_vm_set. The given set must have been allocated
66 * by this library.
67 */
68 extern void
69 xen_vm_set_free(xen_vm_set *set);
72 typedef struct xen_vm_record
73 {
74 xen_vm handle;
75 char *uuid;
76 enum xen_vm_power_state power_state;
77 char *name_label;
78 char *name_description;
79 int64_t user_version;
80 bool is_a_template;
81 struct xen_host_record_opt *resident_on;
82 int64_t memory_static_max;
83 int64_t memory_dynamic_max;
84 int64_t memory_actual;
85 int64_t memory_dynamic_min;
86 int64_t memory_static_min;
87 char *vcpus_policy;
88 char *vcpus_params;
89 int64_t vcpus_number;
90 xen_int_float_map *vcpus_utilisation;
91 struct xen_cpu_feature_set *vcpus_features_required;
92 struct xen_cpu_feature_set *vcpus_features_can_use;
93 struct xen_cpu_feature_set *vcpus_features_force_on;
94 struct xen_cpu_feature_set *vcpus_features_force_off;
95 enum xen_on_normal_exit actions_after_shutdown;
96 enum xen_on_normal_exit actions_after_reboot;
97 enum xen_on_normal_exit actions_after_suspend;
98 enum xen_on_crash_behaviour actions_after_crash;
99 struct xen_vif_record_opt_set *vifs;
100 struct xen_vbd_record_opt_set *vbds;
101 struct xen_vtpm_record_opt_set *vtpms;
102 char *bios_boot;
103 bool platform_std_vga;
104 char *platform_serial;
105 bool platform_localtime;
106 bool platform_clock_offset;
107 bool platform_enable_audio;
108 char *builder;
109 enum xen_boot_type boot_method;
110 char *kernel_kernel;
111 char *kernel_initrd;
112 char *kernel_args;
113 char *grub_cmdline;
114 char *pci_bus;
115 xen_string_string_map *tools_version;
116 xen_string_string_map *otherconfig;
117 } xen_vm_record;
119 /**
120 * Allocate a xen_vm_record.
121 */
122 extern xen_vm_record *
123 xen_vm_record_alloc(void);
125 /**
126 * Free the given xen_vm_record, and all referenced values. The given
127 * record must have been allocated by this library.
128 */
129 extern void
130 xen_vm_record_free(xen_vm_record *record);
133 typedef struct xen_vm_record_opt
134 {
135 bool is_record;
136 union
137 {
138 xen_vm handle;
139 xen_vm_record *record;
140 } u;
141 } xen_vm_record_opt;
143 /**
144 * Allocate a xen_vm_record_opt.
145 */
146 extern xen_vm_record_opt *
147 xen_vm_record_opt_alloc(void);
149 /**
150 * Free the given xen_vm_record_opt, and all referenced values. The
151 * given record_opt must have been allocated by this library.
152 */
153 extern void
154 xen_vm_record_opt_free(xen_vm_record_opt *record_opt);
157 typedef struct xen_vm_record_set
158 {
159 size_t size;
160 xen_vm_record *contents[];
161 } xen_vm_record_set;
163 /**
164 * Allocate a xen_vm_record_set of the given size.
165 */
166 extern xen_vm_record_set *
167 xen_vm_record_set_alloc(size_t size);
169 /**
170 * Free the given xen_vm_record_set, and all referenced values. The
171 * given set must have been allocated by this library.
172 */
173 extern void
174 xen_vm_record_set_free(xen_vm_record_set *set);
178 typedef struct xen_vm_record_opt_set
179 {
180 size_t size;
181 xen_vm_record_opt *contents[];
182 } xen_vm_record_opt_set;
184 /**
185 * Allocate a xen_vm_record_opt_set of the given size.
186 */
187 extern xen_vm_record_opt_set *
188 xen_vm_record_opt_set_alloc(size_t size);
190 /**
191 * Free the given xen_vm_record_opt_set, and all referenced values.
192 * The given set must have been allocated by this library.
193 */
194 extern void
195 xen_vm_record_opt_set_free(xen_vm_record_opt_set *set);
198 /**
199 * Get the current state of the given VM. !!!
200 */
201 extern bool
202 xen_vm_get_record(xen_session *session, xen_vm_record **result, xen_vm vm);
205 /**
206 * Get a reference to the object with the specified UUID. !!!
207 */
208 extern bool
209 xen_vm_get_by_uuid(xen_session *session, xen_vm *result, char *uuid);
212 /**
213 * Create a new VM instance, and return its handle.
214 */
215 extern bool
216 xen_vm_create(xen_session *session, xen_vm *result, xen_vm_record *record);
219 /**
220 * Get all the VM instances with the given label.
221 */
222 extern bool
223 xen_vm_get_by_name_label(xen_session *session, struct xen_vm_set **result, char *label);
226 /**
227 * Get the uuid field of the given VM.
228 */
229 extern bool
230 xen_vm_get_uuid(xen_session *session, char **result, xen_vm vm);
233 /**
234 * Get the power_state field of the given VM.
235 */
236 extern bool
237 xen_vm_get_power_state(xen_session *session, enum xen_vm_power_state *result, xen_vm vm);
240 /**
241 * Get the name/label field of the given VM.
242 */
243 extern bool
244 xen_vm_get_name_label(xen_session *session, char **result, xen_vm vm);
247 /**
248 * Get the name/description field of the given VM.
249 */
250 extern bool
251 xen_vm_get_name_description(xen_session *session, char **result, xen_vm vm);
254 /**
255 * Get the user_version field of the given VM.
256 */
257 extern bool
258 xen_vm_get_user_version(xen_session *session, int64_t *result, xen_vm vm);
261 /**
262 * Get the is_a_template field of the given VM.
263 */
264 extern bool
265 xen_vm_get_is_a_template(xen_session *session, bool *result, xen_vm vm);
268 /**
269 * Get the resident_on field of the given VM.
270 */
271 extern bool
272 xen_vm_get_resident_on(xen_session *session, xen_host *result, xen_vm vm);
275 /**
276 * Get the memory/static_max field of the given VM.
277 */
278 extern bool
279 xen_vm_get_memory_static_max(xen_session *session, int64_t *result, xen_vm vm);
282 /**
283 * Get the memory/dynamic_max field of the given VM.
284 */
285 extern bool
286 xen_vm_get_memory_dynamic_max(xen_session *session, int64_t *result, xen_vm vm);
289 /**
290 * Get the memory/actual field of the given VM.
291 */
292 extern bool
293 xen_vm_get_memory_actual(xen_session *session, int64_t *result, xen_vm vm);
296 /**
297 * Get the memory/dynamic_min field of the given VM.
298 */
299 extern bool
300 xen_vm_get_memory_dynamic_min(xen_session *session, int64_t *result, xen_vm vm);
303 /**
304 * Get the memory/static_min field of the given VM.
305 */
306 extern bool
307 xen_vm_get_memory_static_min(xen_session *session, int64_t *result, xen_vm vm);
310 /**
311 * Get the VCPUs/policy field of the given VM.
312 */
313 extern bool
314 xen_vm_get_vcpus_policy(xen_session *session, char **result, xen_vm vm);
317 /**
318 * Get the VCPUs/params field of the given VM.
319 */
320 extern bool
321 xen_vm_get_vcpus_params(xen_session *session, char **result, xen_vm vm);
324 /**
325 * Get the VCPUs/number field of the given VM.
326 */
327 extern bool
328 xen_vm_get_vcpus_number(xen_session *session, int64_t *result, xen_vm vm);
331 /**
332 * Get the VCPUs/utilisation field of the given VM.
333 */
334 extern bool
335 xen_vm_get_vcpus_utilisation(xen_session *session, xen_int_float_map **result, xen_vm vm);
338 /**
339 * Get the VCPUs/features/required field of the given VM.
340 */
341 extern bool
342 xen_vm_get_vcpus_features_required(xen_session *session, struct xen_cpu_feature_set **result, xen_vm vm);
345 /**
346 * Get the VCPUs/features/can_use field of the given VM.
347 */
348 extern bool
349 xen_vm_get_vcpus_features_can_use(xen_session *session, struct xen_cpu_feature_set **result, xen_vm vm);
352 /**
353 * Get the VCPUs/features/force_on field of the given VM.
354 */
355 extern bool
356 xen_vm_get_vcpus_features_force_on(xen_session *session, struct xen_cpu_feature_set **result, xen_vm vm);
359 /**
360 * Get the VCPUs/features/force_off field of the given VM.
361 */
362 extern bool
363 xen_vm_get_vcpus_features_force_off(xen_session *session, struct xen_cpu_feature_set **result, xen_vm vm);
366 /**
367 * Get the actions/after_shutdown field of the given VM.
368 */
369 extern bool
370 xen_vm_get_actions_after_shutdown(xen_session *session, enum xen_on_normal_exit *result, xen_vm vm);
373 /**
374 * Get the actions/after_reboot field of the given VM.
375 */
376 extern bool
377 xen_vm_get_actions_after_reboot(xen_session *session, enum xen_on_normal_exit *result, xen_vm vm);
380 /**
381 * Get the actions/after_suspend field of the given VM.
382 */
383 extern bool
384 xen_vm_get_actions_after_suspend(xen_session *session, enum xen_on_normal_exit *result, xen_vm vm);
387 /**
388 * Get the actions/after_crash field of the given VM.
389 */
390 extern bool
391 xen_vm_get_actions_after_crash(xen_session *session, enum xen_on_crash_behaviour *result, xen_vm vm);
394 /**
395 * Get the VIFs field of the given VM.
396 */
397 extern bool
398 xen_vm_get_vifs(xen_session *session, struct xen_vif_set **result, xen_vm vm);
401 /**
402 * Get the VBDs field of the given VM.
403 */
404 extern bool
405 xen_vm_get_vbds(xen_session *session, struct xen_vbd_set **result, xen_vm vm);
408 /**
409 * Get the VTPMs field of the given VM.
410 */
411 extern bool
412 xen_vm_get_vtpms(xen_session *session, struct xen_vtpm_set **result, xen_vm vm);
415 /**
416 * Get the bios/boot field of the given VM.
417 */
418 extern bool
419 xen_vm_get_bios_boot(xen_session *session, char **result, xen_vm vm);
422 /**
423 * Get the platform/std_VGA field of the given VM.
424 */
425 extern bool
426 xen_vm_get_platform_std_vga(xen_session *session, bool *result, xen_vm vm);
429 /**
430 * Get the platform/serial field of the given VM.
431 */
432 extern bool
433 xen_vm_get_platform_serial(xen_session *session, char **result, xen_vm vm);
436 /**
437 * Get the platform/localtime field of the given VM.
438 */
439 extern bool
440 xen_vm_get_platform_localtime(xen_session *session, bool *result, xen_vm vm);
443 /**
444 * Get the platform/clock_offset field of the given VM.
445 */
446 extern bool
447 xen_vm_get_platform_clock_offset(xen_session *session, bool *result, xen_vm vm);
450 /**
451 * Get the platform/enable_audio field of the given VM.
452 */
453 extern bool
454 xen_vm_get_platform_enable_audio(xen_session *session, bool *result, xen_vm vm);
457 /**
458 * Get the builder field of the given VM.
459 */
460 extern bool
461 xen_vm_get_builder(xen_session *session, char **result, xen_vm vm);
464 /**
465 * Get the boot_method field of the given VM.
466 */
467 extern bool
468 xen_vm_get_boot_method(xen_session *session, enum xen_boot_type *result, xen_vm vm);
471 /**
472 * Get the kernel/kernel field of the given VM.
473 */
474 extern bool
475 xen_vm_get_kernel_kernel(xen_session *session, char **result, xen_vm vm);
478 /**
479 * Get the kernel/initrd field of the given VM.
480 */
481 extern bool
482 xen_vm_get_kernel_initrd(xen_session *session, char **result, xen_vm vm);
485 /**
486 * Get the kernel/args field of the given VM.
487 */
488 extern bool
489 xen_vm_get_kernel_args(xen_session *session, char **result, xen_vm vm);
492 /**
493 * Get the grub/cmdline field of the given VM.
494 */
495 extern bool
496 xen_vm_get_grub_cmdline(xen_session *session, char **result, xen_vm vm);
499 /**
500 * Get the PCI_bus field of the given VM.
501 */
502 extern bool
503 xen_vm_get_pci_bus(xen_session *session, char **result, xen_vm vm);
506 /**
507 * Get the tools_version field of the given VM.
508 */
509 extern bool
510 xen_vm_get_tools_version(xen_session *session, xen_string_string_map **result, xen_vm vm);
513 /**
514 * Get the otherConfig field of the given VM.
515 */
516 extern bool
517 xen_vm_get_otherconfig(xen_session *session, xen_string_string_map **result, xen_vm vm);
520 /**
521 * Set the name/label field of the given VM.
522 */
523 extern bool
524 xen_vm_set_name_label(xen_session *session, xen_vm xen_vm, char *label);
527 /**
528 * Set the name/description field of the given VM.
529 */
530 extern bool
531 xen_vm_set_name_description(xen_session *session, xen_vm xen_vm, char *description);
534 /**
535 * Set the user_version field of the given VM.
536 */
537 extern bool
538 xen_vm_set_user_version(xen_session *session, xen_vm xen_vm, int64_t user_version);
541 /**
542 * Set the is_a_template field of the given VM.
543 */
544 extern bool
545 xen_vm_set_is_a_template(xen_session *session, xen_vm xen_vm, bool is_a_template);
548 /**
549 * Set the memory/dynamic_max field of the given VM.
550 */
551 extern bool
552 xen_vm_set_memory_dynamic_max(xen_session *session, xen_vm xen_vm, int64_t dynamic_max);
555 /**
556 * Set the memory/dynamic_min field of the given VM.
557 */
558 extern bool
559 xen_vm_set_memory_dynamic_min(xen_session *session, xen_vm xen_vm, int64_t dynamic_min);
562 /**
563 * Set the VCPUs/policy field of the given VM.
564 */
565 extern bool
566 xen_vm_set_vcpus_policy(xen_session *session, xen_vm xen_vm, char *policy);
569 /**
570 * Set the VCPUs/params field of the given VM.
571 */
572 extern bool
573 xen_vm_set_vcpus_params(xen_session *session, xen_vm xen_vm, char *params);
576 /**
577 * Set the VCPUs/features/force_on field of the given VM.
578 */
579 extern bool
580 xen_vm_set_vcpus_features_force_on(xen_session *session, xen_vm xen_vm, struct xen_cpu_feature_set *force_on);
583 /**
584 * Set the VCPUs/features/force_off field of the given VM.
585 */
586 extern bool
587 xen_vm_set_vcpus_features_force_off(xen_session *session, xen_vm xen_vm, struct xen_cpu_feature_set *force_off);
590 /**
591 * Set the actions/after_shutdown field of the given VM.
592 */
593 extern bool
594 xen_vm_set_actions_after_shutdown(xen_session *session, xen_vm xen_vm, enum xen_on_normal_exit after_shutdown);
597 /**
598 * Set the actions/after_reboot field of the given VM.
599 */
600 extern bool
601 xen_vm_set_actions_after_reboot(xen_session *session, xen_vm xen_vm, enum xen_on_normal_exit after_reboot);
604 /**
605 * Set the actions/after_suspend field of the given VM.
606 */
607 extern bool
608 xen_vm_set_actions_after_suspend(xen_session *session, xen_vm xen_vm, enum xen_on_normal_exit after_suspend);
611 /**
612 * Set the actions/after_crash field of the given VM.
613 */
614 extern bool
615 xen_vm_set_actions_after_crash(xen_session *session, xen_vm xen_vm, enum xen_on_crash_behaviour after_crash);
618 /**
619 * Set the bios/boot field of the given VM.
620 */
621 extern bool
622 xen_vm_set_bios_boot(xen_session *session, xen_vm xen_vm, char *boot);
625 /**
626 * Set the platform/std_VGA field of the given VM.
627 */
628 extern bool
629 xen_vm_set_platform_std_vga(xen_session *session, xen_vm xen_vm, bool std_vga);
632 /**
633 * Set the platform/serial field of the given VM.
634 */
635 extern bool
636 xen_vm_set_platform_serial(xen_session *session, xen_vm xen_vm, char *serial);
639 /**
640 * Set the platform/localtime field of the given VM.
641 */
642 extern bool
643 xen_vm_set_platform_localtime(xen_session *session, xen_vm xen_vm, bool localtime);
646 /**
647 * Set the platform/clock_offset field of the given VM.
648 */
649 extern bool
650 xen_vm_set_platform_clock_offset(xen_session *session, xen_vm xen_vm, bool clock_offset);
653 /**
654 * Set the platform/enable_audio field of the given VM.
655 */
656 extern bool
657 xen_vm_set_platform_enable_audio(xen_session *session, xen_vm xen_vm, bool enable_audio);
660 /**
661 * Set the builder field of the given VM.
662 */
663 extern bool
664 xen_vm_set_builder(xen_session *session, xen_vm xen_vm, char *builder);
667 /**
668 * Set the boot_method field of the given VM.
669 */
670 extern bool
671 xen_vm_set_boot_method(xen_session *session, xen_vm xen_vm, enum xen_boot_type boot_method);
674 /**
675 * Set the kernel/kernel field of the given VM.
676 */
677 extern bool
678 xen_vm_set_kernel_kernel(xen_session *session, xen_vm xen_vm, char *kernel);
681 /**
682 * Set the kernel/initrd field of the given VM.
683 */
684 extern bool
685 xen_vm_set_kernel_initrd(xen_session *session, xen_vm xen_vm, char *initrd);
688 /**
689 * Set the kernel/args field of the given VM.
690 */
691 extern bool
692 xen_vm_set_kernel_args(xen_session *session, xen_vm xen_vm, char *args);
695 /**
696 * Set the grub/cmdline field of the given VM.
697 */
698 extern bool
699 xen_vm_set_grub_cmdline(xen_session *session, xen_vm xen_vm, char *cmdline);
702 /**
703 * Set the otherConfig field of the given VM.
704 */
705 extern bool
706 xen_vm_set_otherconfig(xen_session *session, xen_vm xen_vm, xen_string_string_map *otherconfig);
709 /**
710 * Clones the specified VM, making a new VM. Clone automatically
711 * exploits the capabilities of the underlying storage repository in which the
712 * VM's disk images are stored (e.g. Copy on Write). This function can only
713 * be called when the VM is in the Halted State.
714 */
715 extern bool
716 xen_vm_clone(xen_session *session, xen_vm *result, xen_vm vm, char *new_name);
719 /**
720 * Start the specified VM. This function can only be called with the
721 * VM is in the Halted State.
722 */
723 extern bool
724 xen_vm_start(xen_session *session, xen_vm vm, bool start_paused);
727 /**
728 * Pause the specified VM. This can only be called when the specified
729 * VM is in the Running state.
730 */
731 extern bool
732 xen_vm_pause(xen_session *session, xen_vm vm);
735 /**
736 * Resume the specified VM. This can only be called when the specified
737 * VM is in the Paused state.
738 */
739 extern bool
740 xen_vm_unpause(xen_session *session, xen_vm vm);
743 /**
744 * Attempt to cleanly shutdown the specified VM. (Note: this may not be
745 * supported---e.g. if a guest agent is not installed).
746 *
747 * Once shutdown has been completed perform poweroff action specified in guest
748 * configuration.
749 */
750 extern bool
751 xen_vm_clean_shutdown(xen_session *session, xen_vm vm);
754 /**
755 * Attempt to cleanly shutdown the specified VM (Note: this may not be
756 * supported---e.g. if a guest agent is not installed).
757 *
758 * Once shutdown has been completed perform reboot action specified in guest
759 * configuration.
760 */
761 extern bool
762 xen_vm_clean_reboot(xen_session *session, xen_vm vm);
765 /**
766 * Stop executing the specified VM without attempting a clean shutdown.
767 * Then perform poweroff action specified in VM configuration.
768 */
769 extern bool
770 xen_vm_hard_shutdown(xen_session *session, xen_vm vm);
773 /**
774 * Stop executing the specified VM without attempting a clean shutdown.
775 * Then perform reboot action specified in VM configuration
776 */
777 extern bool
778 xen_vm_hard_reboot(xen_session *session, xen_vm vm);
781 /**
782 * Suspend the specified VM to disk.
783 */
784 extern bool
785 xen_vm_suspend(xen_session *session, xen_vm vm);
788 /**
789 * Awaken the specified VM and resume it.
790 */
791 extern bool
792 xen_vm_resume(xen_session *session, xen_vm vm, bool start_paused);
795 /**
796 * Return a list of all the VMs known to the system.
797 */
798 extern bool
799 xen_vm_get_all(xen_session *session, struct xen_vm_set **result);
802 /**
803 * Destroy the specified VM. The VM is completely removed from the system.
804 * This function can only be called when the VM is in the Halted State.
805 */
806 extern bool
807 xen_vm_destroy(xen_session *session, xen_vm vm);
810 #endif