direct-io.hg

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