direct-io.hg

annotate tools/libxc/xenguest.h @ 12765:2dd4569e0640

[LIBXC] Add an error reporting API to the libxc library.

- An 'xc_error' struct is used to pass around error
details. Currently contains two members 'code' an enumeration of
error types, and 'message' a free text description of the specific
problem.

- The xc_get_last_error() method returns a const pointer to the
internal instance of this struct manged by libxc. By returning a
const pointer we can add extra members to the end of the struct at
any time without worrying about ABI of callers. This will let us
provide more fine-grained info if needed in the future.

- The xc_error instance is statically defined inside libxc and marked
__thread. This ensures that errors are recorded per-thread, and
that when dealing with errors we never need to call malloc - all
storage needed is statically allocated.

- The xc_clear_last_error() method resets any currently recorded
error details

- The xc_error_code_to_desc() method converts the integer error code
into a generic user facing messsage. eg "Invalid kernel". Together
with the 'message' field from xc_error, this provides the user
visible feedback. eg "Invalid kernel: Non PAE-kernel on PAE host."

- A callback can be registered with xc_set_error_handler to receive
notification whenever an error is recorded, rather than querying
for error details after the fact with xc_get_last_error

- If built with -DDEBUG set, a default error handler will be
registered which calls fprintf(stderr), thus maintaining current
behaviour of logging errors to stderr during developer builds.

- The python binding for libxc is updated to use xc_get_last_error
to pull out error details whenever appropriate, instead of
returning info based on 'errno'

- The xc_set_error method is private to libxc internals, and is used
for setting error details

- The ERROR and PERROR macros have been updated to call xc_set_error
automatically specifying XC_INTERNAL_ERROR as the error code. This
gives a generic error report for all current failure points

- Some uses of the ERROR macro have been replaced with explicit
calls to xc_set_error to enable finer grained error reporting. In
particular the code dealing with invalid kernel types uses this
to report about PAE/architecture/wordsize mismatches

The patch has been tested by calling xm create against a varietry of
config files defining invalid kernels of various kinds. It has also
been tested with libvirt talking to xend. In both cases the error
messages were propagated all the way back up the stack.

There is only one place where I need to do further work. The suspend
& restore APIs in Xend invoke external helper programs rather than
calling libxc directly. This means that error details are essentially
lost. Since there is already code in XenD which scans STDERR from
these programs I will investigate adapting this to extract actual
error messages from these helpers.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
author kfraser@localhost.localdomain
date Thu Dec 07 11:36:26 2006 +0000 (2006-12-07)
parents 9d6bc06919e0
children f2aaf35c7759
rev   line source
cl349@6389 1 /******************************************************************************
cl349@6389 2 * xenguest.h
kaf24@9660 3 *
cl349@6389 4 * A library for guest domain management in Xen.
kaf24@9660 5 *
cl349@6389 6 * Copyright (c) 2003-2004, K A Fraser.
cl349@6389 7 */
cl349@6389 8
shand@6597 9 #ifndef XENGUEST_H
shand@6597 10 #define XENGUEST_H
cl349@6389 11
shand@6597 12 #define XCFLAGS_LIVE 1
shand@6597 13 #define XCFLAGS_DEBUG 2
shand@6597 14
cl349@6389 15
cl349@6389 16 /**
cl349@6389 17 * This function will save a domain running Linux.
cl349@6389 18 *
cl349@6389 19 * @parm xc_handle a handle to an open hypervisor interface
cl349@6389 20 * @parm fd the file descriptor to save a domain to
cl349@6389 21 * @parm dom the id of the domain
cl349@6389 22 * @return 0 on success, -1 on failure
cl349@6389 23 */
kaf24@9660 24 int xc_linux_save(int xc_handle, int io_fd, uint32_t dom, uint32_t max_iters,
emellor@8527 25 uint32_t max_factor, uint32_t flags /* XCFLAGS_xxx */,
emellor@8568 26 int (*suspend)(int domid));
emellor@8527 27
cl349@6389 28
cl349@6389 29 /**
cl349@6389 30 * This function will restore a saved domain running Linux.
cl349@6389 31 *
cl349@6389 32 * @parm xc_handle a handle to an open hypervisor interface
cl349@6389 33 * @parm fd the file descriptor to restore a domain from
cl349@6389 34 * @parm dom the id of the domain
cl349@6389 35 * @parm nr_pfns the number of pages
cl349@6389 36 * @parm store_evtchn the store event channel for this domain to use
cl349@6389 37 * @parm store_mfn returned with the mfn of the store page
cl349@6389 38 * @return 0 on success, -1 on failure
cl349@6389 39 */
kaf24@9660 40 int xc_linux_restore(int xc_handle, int io_fd, uint32_t dom,
kaf24@9660 41 unsigned long nr_pfns, unsigned int store_evtchn,
cl349@6608 42 unsigned long *store_mfn, unsigned int console_evtchn,
kaf24@8913 43 unsigned long *console_mfn);
cl349@6389 44
kaf24@9180 45 /**
kaf24@9180 46 * This function will create a domain for a paravirtualized Linux
kaf24@9180 47 * using file names pointing to kernel and ramdisk
kaf24@9180 48 *
kaf24@9180 49 * @parm xc_handle a handle to an open hypervisor interface
kaf24@9180 50 * @parm domid the id of the domain
kfraser@12204 51 * @parm mem_mb memory size in megabytes
kfraser@12204 52 * @parm image_name name of the kernel image file
kfraser@12204 53 * @parm ramdisk_name name of the ramdisk image file
kaf24@9180 54 * @parm cmdline command line string
kaf24@9180 55 * @parm flags domain creation flags
kaf24@9180 56 * @parm store_evtchn the store event channel for this domain to use
kaf24@9180 57 * @parm store_mfn returned with the mfn of the store page
kaf24@9180 58 * @parm console_evtchn the console event channel for this domain to use
kaf24@9180 59 * @parm conole_mfn returned with the mfn of the console page
kaf24@9180 60 * @return 0 on success, -1 on failure
kaf24@9180 61 */
cl349@6389 62 int xc_linux_build(int xc_handle,
cl349@6389 63 uint32_t domid,
kfraser@12204 64 unsigned int mem_mb,
cl349@6389 65 const char *image_name,
cl349@6389 66 const char *ramdisk_name,
cl349@6389 67 const char *cmdline,
Ian@9002 68 const char *features,
cl349@6389 69 unsigned long flags,
cl349@6389 70 unsigned int store_evtchn,
cl349@6474 71 unsigned long *store_mfn,
cl349@6474 72 unsigned int console_evtchn,
cl349@6474 73 unsigned long *console_mfn);
cl349@6389 74
kaf24@9180 75 /**
kaf24@9180 76 * This function will create a domain for a paravirtualized Linux
kaf24@9180 77 * using buffers for kernel and initrd
kaf24@9180 78 *
kfraser@12204 79 * @parm xc_handle a handle to an open hypervisor interface
kfraser@12204 80 * @parm domid the id of the domain
kfraser@12204 81 * @parm mem_mb memory size in megabytes
kfraser@12204 82 * @parm image_buffer buffer containing kernel image
kfraser@12204 83 * @parm image_size size of the kernel image buffer
kfraser@12204 84 * @parm initrd_buffer name of the ramdisk image file
kfraser@12204 85 * @parm initrd_size size of the ramdisk buffer
kfraser@12204 86 * @parm cmdline command line string
kfraser@12204 87 * @parm flags domain creation flags
kfraser@12204 88 * @parm store_evtchn the store event channel for this domain to use
kfraser@12204 89 * @parm store_mfn returned with the mfn of the store page
kfraser@12204 90 * @parm console_evtchn the console event channel for this domain to use
kfraser@12204 91 * @parm conole_mfn returned with the mfn of the console page
kaf24@9180 92 * @return 0 on success, -1 on failure
kaf24@9180 93 */
kaf24@9180 94 int xc_linux_build_mem(int xc_handle,
kaf24@9180 95 uint32_t domid,
kfraser@12204 96 unsigned int mem_mb,
kaf24@9181 97 const char *image_buffer,
kaf24@9180 98 unsigned long image_size,
kaf24@9181 99 const char *initrd_buffer,
kaf24@9180 100 unsigned long initrd_size,
kaf24@9180 101 const char *cmdline,
kaf24@9180 102 const char *features,
kaf24@9180 103 unsigned long flags,
kaf24@9180 104 unsigned int store_evtchn,
kaf24@9180 105 unsigned long *store_mfn,
kaf24@9180 106 unsigned int console_evtchn,
kaf24@9180 107 unsigned long *console_mfn);
kaf24@9180 108
kaf24@8708 109 int xc_hvm_build(int xc_handle,
cl349@6389 110 uint32_t domid,
cl349@6389 111 int memsize,
kfraser@12569 112 const char *image_name);
cl349@6389 113
kaf24@9180 114 int xc_hvm_build_mem(int xc_handle,
kaf24@9180 115 uint32_t domid,
kaf24@9180 116 int memsize,
kaf24@9181 117 const char *image_buffer,
kfraser@12569 118 unsigned long image_size);
kfraser@12569 119
kfraser@12569 120 int xc_set_hvm_param(
kfraser@12569 121 int handle, domid_t dom, int param, unsigned long value);
kfraser@12569 122 int xc_get_hvm_param(
kfraser@12569 123 int handle, domid_t dom, int param, unsigned long *value);
kaf24@9180 124
kaf24@9180 125 #endif /* XENGUEST_H */