direct-io.hg

annotate tools/libxc/xenctrl.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 f7b7daed94d6
children df5fa63490f4
rev   line source
mjw@1623 1 /******************************************************************************
cl349@6388 2 * xenctrl.h
kaf24@9660 3 *
mjw@1623 4 * A library for low-level access to the Xen control interfaces.
kaf24@9660 5 *
kaf24@2787 6 * Copyright (c) 2003-2004, K A Fraser.
mjw@1623 7 */
mjw@1623 8
cl349@6389 9 #ifndef XENCTRL_H
cl349@6389 10 #define XENCTRL_H
mjw@1623 11
kaf24@11393 12 /* Tell the Xen public headers we are a user-space tools build. */
kaf24@11393 13 #ifndef __XEN_TOOLS__
kaf24@11393 14 #define __XEN_TOOLS__ 1
kaf24@11393 15 #endif
kaf24@11393 16
kaf24@9999 17 #include <stddef.h>
kaf24@3266 18 #include <stdint.h>
kaf24@2821 19 #include <xen/xen.h>
kfraser@11257 20 #include <xen/domctl.h>
kfraser@11257 21 #include <xen/sysctl.h>
vh249@6549 22 #include <xen/version.h>
kaf24@2821 23 #include <xen/event_channel.h>
kaf24@7196 24 #include <xen/sched.h>
smh22@7702 25 #include <xen/memory.h>
kaf24@5541 26 #include <xen/acm.h>
kaf24@9907 27 #include <xen/acm_ops.h>
kaf24@2787 28
kaf24@5914 29 #ifdef __ia64__
kaf24@5914 30 #define XC_PAGE_SHIFT 14
kaf24@5914 31 #else
kaf24@5914 32 #define XC_PAGE_SHIFT 12
kaf24@5914 33 #endif
kaf24@5914 34 #define XC_PAGE_SIZE (1UL << XC_PAGE_SHIFT)
kaf24@5914 35 #define XC_PAGE_MASK (~(XC_PAGE_SIZE-1))
kaf24@5914 36
kaf24@3961 37 /*
kaf24@3961 38 * DEFINITIONS FOR CPU BARRIERS
kaf24@9660 39 */
kaf24@3961 40
kaf24@3961 41 #if defined(__i386__)
kaf24@3966 42 #define mb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
kaf24@3966 43 #define rmb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
kaf24@3966 44 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
kaf24@3961 45 #elif defined(__x86_64__)
kaf24@3966 46 #define mb() __asm__ __volatile__ ( "mfence" : : : "memory")
kaf24@3966 47 #define rmb() __asm__ __volatile__ ( "lfence" : : : "memory")
kaf24@3966 48 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
kaf24@5914 49 #elif defined(__ia64__)
kfraser@12271 50 #define mb() __asm__ __volatile__ ("mf" ::: "memory")
kfraser@12271 51 #define rmb() __asm__ __volatile__ ("mf" ::: "memory")
kfraser@12271 52 #define wmb() __asm__ __volatile__ ("mf" ::: "memory")
kaf24@10687 53 #elif defined(__powerpc__)
kaf24@10687 54 /* XXX loosen these up later */
kaf24@10687 55 #define mb() __asm__ __volatile__ ("sync" : : : "memory")
kaf24@10687 56 #define rmb() __asm__ __volatile__ ("sync" : : : "memory") /* lwsync? */
kaf24@10687 57 #define wmb() __asm__ __volatile__ ("sync" : : : "memory") /* eieio? */
kaf24@3961 58 #else
kaf24@3961 59 #error "Define barriers"
kaf24@3961 60 #endif
kaf24@3961 61
kaf24@3961 62 /*
iap10@3443 63 * INITIALIZATION FUNCTIONS
kaf24@9660 64 */
iap10@3443 65
iap10@3443 66 /**
iap10@3443 67 * This function opens a handle to the hypervisor interface. This function can
iap10@3443 68 * be called multiple times within a single process. Multiple processes can
iap10@3443 69 * have an open hypervisor interface at the same time.
iap10@3443 70 *
iap10@3443 71 * Each call to this function should have a corresponding call to
iap10@3443 72 * xc_interface_close().
iap10@3443 73 *
iap10@3443 74 * This function can fail if the caller does not have superuser permission or
iap10@3443 75 * if a Xen-enabled kernel is not currently running.
iap10@3443 76 *
iap10@3443 77 * @return a handle to the hypervisor interface or -1 on failure
iap10@3443 78 */
mjw@1623 79 int xc_interface_open(void);
iap10@3443 80
iap10@3443 81 /**
iap10@3443 82 * This function closes an open hypervisor interface.
iap10@3443 83 *
iap10@3443 84 * This function can fail if the handle does not represent an open interface or
iap10@3443 85 * if there were problems closing the interface.
iap10@3443 86 *
iap10@3443 87 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 88 * @return 0 on success, -1 otherwise.
iap10@3443 89 */
mjw@1623 90 int xc_interface_close(int xc_handle);
mjw@1623 91
kaf24@3961 92 /*
kfraser@11672 93 * KERNEL INTERFACES
kfraser@11672 94 */
kfraser@11672 95
kfraser@11672 96 /*
kfraser@11672 97 * Resolve a kernel device name (e.g., "evtchn", "blktap0") into a kernel
kfraser@11672 98 * device number. Returns -1 on error (and sets errno).
kfraser@11672 99 */
kfraser@11672 100 int xc_find_device_number(const char *name);
kfraser@11672 101
kfraser@11672 102 /*
kaf24@4719 103 * DOMAIN DEBUGGING FUNCTIONS
kaf24@4719 104 */
kaf24@4719 105
kaf24@4719 106 typedef struct xc_core_header {
kaf24@4719 107 unsigned int xch_magic;
kaf24@4719 108 unsigned int xch_nr_vcpus;
kaf24@4719 109 unsigned int xch_nr_pages;
kaf24@4719 110 unsigned int xch_ctxt_offset;
kaf24@4719 111 unsigned int xch_index_offset;
kaf24@4719 112 unsigned int xch_pages_offset;
kaf24@4719 113 } xc_core_header_t;
kaf24@4719 114
kfraser@12224 115 #define XC_CORE_MAGIC 0xF00FEBED
kfraser@12224 116 #define XC_CORE_MAGIC_HVM 0xF00FEBEE
kaf24@4719 117
kfraser@11791 118 #ifdef __linux__
kfraser@11791 119
kfraser@11791 120 #include <sys/ptrace.h>
kfraser@11791 121 #include <thread_db.h>
kfraser@11791 122
kfraser@11774 123 typedef void (*thr_ev_handler_t)(long);
kfraser@11774 124
kfraser@11774 125 void xc_register_event_handler(
kfraser@11774 126 thr_ev_handler_t h,
kfraser@11774 127 td_event_e e);
kfraser@11774 128
kfraser@11774 129 long xc_ptrace(
kfraser@11774 130 int xc_handle,
kfraser@11774 131 enum __ptrace_request request,
kfraser@11774 132 uint32_t domid,
kfraser@11774 133 long addr,
kfraser@11774 134 long data);
kfraser@11774 135
kfraser@11774 136 int xc_waitdomain(
kfraser@11774 137 int xc_handle,
kfraser@11774 138 int domain,
kfraser@11774 139 int *status,
kfraser@11774 140 int options);
kfraser@11774 141
kfraser@11774 142 #endif /* __linux__ */
kaf24@4719 143
kaf24@4719 144 /*
iap10@3443 145 * DOMAIN MANAGEMENT FUNCTIONS
kaf24@3961 146 */
iap10@3443 147
kfraser@12224 148 typedef struct xc_dominfo {
kaf24@7378 149 uint32_t domid;
kaf24@7378 150 uint32_t ssidref;
kaf24@9660 151 unsigned int dying:1, crashed:1, shutdown:1,
kfraser@12224 152 paused:1, blocked:1, running:1,
kfraser@12224 153 hvm:1;
mjw@1623 154 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
mjw@1623 155 unsigned long nr_pages;
mjw@1623 156 unsigned long shared_info_frame;
kaf24@7378 157 uint64_t cpu_time;
mjw@1623 158 unsigned long max_memkb;
kaf24@7397 159 unsigned int nr_online_vcpus;
kaf24@7397 160 unsigned int max_vcpu_id;
kaf24@7378 161 xen_domain_handle_t handle;
mjw@1623 162 } xc_dominfo_t;
mjw@1623 163
kfraser@11257 164 typedef xen_domctl_getdomaininfo_t xc_domaininfo_t;
kaf24@9660 165 int xc_domain_create(int xc_handle,
kaf24@7339 166 uint32_t ssidref,
kaf24@7378 167 xen_domain_handle_t handle,
kfraser@12196 168 uint32_t flags,
kaf24@7339 169 uint32_t *pdomid);
iap10@3443 170
kaf24@4719 171
kaf24@9221 172 /* Functions to produce a dump of a given domain
kaf24@9221 173 * xc_domain_dumpcore - produces a dump to a specified file
kaf24@9221 174 * xc_domain_dumpcore_via_callback - produces a dump, using a specified
kaf24@9221 175 * callback function
kaf24@9221 176 */
kaf24@9660 177 int xc_domain_dumpcore(int xc_handle,
kaf24@7339 178 uint32_t domid,
cl349@4853 179 const char *corename);
kaf24@4719 180
kaf24@9221 181 /* Define the callback function type for xc_domain_dumpcore_via_callback.
kaf24@9221 182 *
kaf24@9221 183 * This function is called by the coredump code for every "write",
kaf24@9221 184 * and passes an opaque object for the use of the function and
kaf24@9221 185 * created by the caller of xc_domain_dumpcore_via_callback.
kaf24@9221 186 */
kaf24@9221 187 typedef int (dumpcore_rtn_t)(void *arg, char *buffer, unsigned int length);
kaf24@9221 188
kaf24@9660 189 int xc_domain_dumpcore_via_callback(int xc_handle,
kaf24@9221 190 uint32_t domid,
kaf24@9221 191 void *arg,
kaf24@9221 192 dumpcore_rtn_t dump_rtn);
kaf24@9221 193
kaf24@7354 194 /*
kaf24@7566 195 * This function sets the maximum number of vcpus that a domain may create.
kaf24@7354 196 *
kaf24@7354 197 * @parm xc_handle a handle to an open hypervisor interface.
kaf24@7354 198 * @parm domid the domain id in which vcpus are to be created.
kaf24@7354 199 * @parm max the maximum number of vcpus that the domain may create.
kaf24@7354 200 * @return 0 on success, -1 on failure.
kaf24@7354 201 */
kaf24@7354 202 int xc_domain_max_vcpus(int xc_handle,
kaf24@9660 203 uint32_t domid,
kaf24@7354 204 unsigned int max);
kaf24@4719 205
iap10@3443 206 /**
iap10@3443 207 * This function pauses a domain. A paused domain still exists in memory
iap10@3443 208 * however it does not receive any timeslices from the hypervisor.
iap10@3443 209 *
iap10@3443 210 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 211 * @parm domid the domain id to pause
iap10@3443 212 * @return 0 on success, -1 on failure.
iap10@3443 213 */
kaf24@9660 214 int xc_domain_pause(int xc_handle,
kaf24@7339 215 uint32_t domid);
iap10@3443 216 /**
iap10@3443 217 * This function unpauses a domain. The domain should have been previously
iap10@3443 218 * paused.
iap10@3443 219 *
iap10@3443 220 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 221 * @parm domid the domain id to unpause
iap10@3443 222 * return 0 on success, -1 on failure
iap10@3443 223 */
kaf24@9660 224 int xc_domain_unpause(int xc_handle,
kaf24@7339 225 uint32_t domid);
iap10@3443 226
iap10@3443 227 /**
iap10@3443 228 * This function will destroy a domain. Destroying a domain removes the domain
iap10@3443 229 * completely from memory. This function should be called after sending the
iap10@3443 230 * domain a SHUTDOWN control message to free up the domain resources.
iap10@3443 231 *
iap10@3443 232 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 233 * @parm domid the domain id to destroy
iap10@3443 234 * @return 0 on success, -1 on failure
iap10@3443 235 */
kaf24@9660 236 int xc_domain_destroy(int xc_handle,
kaf24@7339 237 uint32_t domid);
kaf24@8500 238
kaf24@9560 239 /**
kaf24@9560 240 * This function will shutdown a domain. This is intended for use in
kaf24@9560 241 * fully-virtualized domains where this operation is analogous to the
kaf24@9560 242 * sched_op operations in a paravirtualized domain. The caller is
kaf24@9560 243 * expected to give the reason for the shutdown.
kaf24@9560 244 *
kaf24@9560 245 * @parm xc_handle a handle to an open hypervisor interface
kaf24@9560 246 * @parm domid the domain id to destroy
kaf24@9560 247 * @parm reason is the reason (SHUTDOWN_xxx) for the shutdown
kaf24@9560 248 * @return 0 on success, -1 on failure
kaf24@9560 249 */
kaf24@9660 250 int xc_domain_shutdown(int xc_handle,
kaf24@9560 251 uint32_t domid,
kaf24@9560 252 int reason);
kaf24@9560 253
kaf24@8500 254 int xc_vcpu_setaffinity(int xc_handle,
kaf24@8500 255 uint32_t domid,
kaf24@8500 256 int vcpu,
kfraser@11257 257 uint64_t cpumap);
kfraser@11257 258 int xc_vcpu_getaffinity(int xc_handle,
kfraser@11257 259 uint32_t domid,
kfraser@11257 260 int vcpu,
kfraser@11257 261 uint64_t *cpumap);
kaf24@7378 262
iap10@3443 263 /**
dsteklof@5498 264 * This function will return information about one or more domains. It is
dsteklof@5498 265 * designed to iterate over the list of domains. If a single domain is
dsteklof@5498 266 * requested, this function will return the next domain in the list - if
dsteklof@5498 267 * one exists. It is, therefore, important in this case to make sure the
dsteklof@5498 268 * domain requested was the one returned.
iap10@3443 269 *
iap10@3443 270 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 271 * @parm first_domid the first domain to enumerate information from. Domains
iap10@3443 272 * are currently enumerate in order of creation.
iap10@3443 273 * @parm max_doms the number of elements in info
iap10@3443 274 * @parm info an array of max_doms size that will contain the information for
iap10@3443 275 * the enumerated domains.
iap10@3443 276 * @return the number of domains enumerated or -1 on error
iap10@3443 277 */
mjw@1623 278 int xc_domain_getinfo(int xc_handle,
kaf24@9660 279 uint32_t first_domid,
mjw@1623 280 unsigned int max_doms,
mjw@1623 281 xc_dominfo_t *info);
iap10@3443 282
kaf24@8381 283
kaf24@8381 284 /**
kaf24@8500 285 * This function will set the execution context for the specified vcpu.
kaf24@8381 286 *
kaf24@8381 287 * @parm xc_handle a handle to an open hypervisor interface
kaf24@8381 288 * @parm domid the domain to set the vcpu context for
kaf24@8381 289 * @parm vcpu the vcpu number for the context
kaf24@8381 290 * @parm ctxt pointer to the the cpu context with the values to set
kaf24@8381 291 * @return the number of domains enumerated or -1 on error
kaf24@8381 292 */
kaf24@8500 293 int xc_vcpu_setcontext(int xc_handle,
kaf24@8500 294 uint32_t domid,
kaf24@8500 295 uint32_t vcpu,
kaf24@8500 296 vcpu_guest_context_t *ctxt);
iap10@3443 297 /**
kaf24@5699 298 * This function will return information about one or more domains, using a
kaf24@5699 299 * single hypercall. The domain information will be stored into the supplied
kaf24@5699 300 * array of xc_domaininfo_t structures.
kaf24@5699 301 *
kaf24@5699 302 * @parm xc_handle a handle to an open hypervisor interface
kaf24@5699 303 * @parm first_domain the first domain to enumerate information from.
kaf24@5699 304 * Domains are currently enumerate in order of creation.
kaf24@5699 305 * @parm max_domains the number of elements in info
kaf24@5699 306 * @parm info an array of max_doms size that will contain the information for
kaf24@5699 307 * the enumerated domains.
kaf24@5699 308 * @return the number of domains enumerated or -1 on error
kaf24@5699 309 */
kaf24@5699 310 int xc_domain_getinfolist(int xc_handle,
kaf24@7339 311 uint32_t first_domain,
kaf24@5699 312 unsigned int max_domains,
kaf24@5699 313 xc_domaininfo_t *info);
kaf24@5699 314
kaf24@5699 315 /**
emellor@7404 316 * This function returns information about the execution context of a
emellor@7404 317 * particular vcpu of a domain.
iap10@3443 318 *
iap10@3443 319 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 320 * @parm domid the domain to get information from
emellor@7404 321 * @parm vcpu the vcpu number
iap10@3443 322 * @parm ctxt a pointer to a structure to store the execution context of the
iap10@3443 323 * domain
iap10@3443 324 * @return 0 on success, -1 on failure
iap10@3443 325 */
kaf24@8500 326 int xc_vcpu_getcontext(int xc_handle,
kaf24@7339 327 uint32_t domid,
kaf24@7339 328 uint32_t vcpu,
cl349@4853 329 vcpu_guest_context_t *ctxt);
cl349@4849 330
kfraser@11257 331 typedef xen_domctl_getvcpuinfo_t xc_vcpuinfo_t;
kaf24@8500 332 int xc_vcpu_getinfo(int xc_handle,
kaf24@8500 333 uint32_t domid,
kaf24@8500 334 uint32_t vcpu,
kaf24@8500 335 xc_vcpuinfo_t *info);
kaf24@7397 336
gm281@2236 337 int xc_domain_setcpuweight(int xc_handle,
kaf24@7339 338 uint32_t domid,
gm281@2236 339 float weight);
kaf24@2787 340 long long xc_domain_get_cpu_usage(int xc_handle,
mafetter@3435 341 domid_t domid,
mafetter@3435 342 int vcpu);
mjw@1623 343
kaf24@9660 344 int xc_domain_sethandle(int xc_handle, uint32_t domid,
kaf24@7379 345 xen_domain_handle_t handle);
kaf24@2787 346
kfraser@11257 347 typedef xen_domctl_shadow_op_stats_t xc_shadow_op_stats_t;
mjw@1623 348 int xc_shadow_control(int xc_handle,
kaf24@9660 349 uint32_t domid,
mjw@1623 350 unsigned int sop,
mjw@1623 351 unsigned long *dirty_bitmap,
mjw@1623 352 unsigned long pages,
tdeegan@11151 353 unsigned long *mb,
tdeegan@11151 354 uint32_t mode,
kfraser@11257 355 xc_shadow_op_stats_t *stats);
mjw@1623 356
sd386@3449 357 int xc_sedf_domain_set(int xc_handle,
kaf24@7339 358 uint32_t domid,
kaf24@7339 359 uint64_t period, uint64_t slice,
kaf24@7339 360 uint64_t latency, uint16_t extratime,
kaf24@7339 361 uint16_t weight);
sd386@3449 362
sd386@3449 363 int xc_sedf_domain_get(int xc_handle,
kaf24@7339 364 uint32_t domid,
kaf24@7339 365 uint64_t* period, uint64_t *slice,
kaf24@7339 366 uint64_t *latency, uint16_t *extratime,
kaf24@7339 367 uint16_t *weight);
sd386@3449 368
kaf24@10174 369 int xc_sched_credit_domain_set(int xc_handle,
kaf24@10174 370 uint32_t domid,
kfraser@11257 371 struct xen_domctl_sched_credit *sdom);
ack@10168 372
kaf24@10174 373 int xc_sched_credit_domain_get(int xc_handle,
kaf24@10174 374 uint32_t domid,
kfraser@11257 375 struct xen_domctl_sched_credit *sdom);
ack@10168 376
kaf24@3961 377 /*
iap10@3443 378 * EVENT CHANNEL FUNCTIONS
kaf24@3961 379 */
iap10@3443 380
iap10@3443 381 /**
iap10@3443 382 * This function allocates an unbound port. Ports are named endpoints used for
iap10@3443 383 * interdomain communication. This function is most useful in opening a
iap10@3443 384 * well-known port within a domain to receive events on.
kfraser@12694 385 *
kfraser@12694 386 * NOTE: If you are allocating a *local* unbound port, you probably want to
kfraser@12694 387 * use xc_evtchn_bind_unbound_port(). This function is intended for allocating
kfraser@12694 388 * ports *only* during domain creation.
iap10@3443 389 *
iap10@3443 390 * @parm xc_handle a handle to an open hypervisor interface
kaf24@7223 391 * @parm dom the ID of the local domain (the 'allocatee')
kaf24@7237 392 * @parm remote_dom the ID of the domain who will later bind
kaf24@7237 393 * @return allocated port (in @dom) on success, -1 on failure
iap10@3443 394 */
kaf24@2713 395 int xc_evtchn_alloc_unbound(int xc_handle,
kaf24@7339 396 uint32_t dom,
kaf24@7339 397 uint32_t remote_dom);
iap10@3443 398
mjw@1623 399 int xc_physdev_pci_access_modify(int xc_handle,
kaf24@7339 400 uint32_t domid,
mjw@1623 401 int bus,
mjw@1623 402 int dev,
mjw@1623 403 int func,
mjw@1623 404 int enable);
mjw@1623 405
mjw@1623 406 int xc_readconsolering(int xc_handle,
kaf24@5327 407 char **pbuffer,
kaf24@9660 408 unsigned int *pnr_chars,
mjw@1623 409 int clear);
mjw@1623 410
kfraser@11257 411 typedef xen_sysctl_physinfo_t xc_physinfo_t;
mjw@1623 412 int xc_physinfo(int xc_handle,
mjw@1623 413 xc_physinfo_t *info);
mjw@1623 414
gm281@2236 415 int xc_sched_id(int xc_handle,
gm281@2236 416 int *sched_id);
gm281@2236 417
mjw@1623 418 int xc_domain_setmaxmem(int xc_handle,
kaf24@9660 419 uint32_t domid,
kaf24@3231 420 unsigned int max_memkb);
mjw@1623 421
kaf24@10474 422 int xc_domain_set_time_offset(int xc_handle,
kaf24@10474 423 uint32_t domid,
kaf24@10474 424 int32_t time_offset_seconds);
kaf24@10474 425
cl349@5045 426 int xc_domain_memory_increase_reservation(int xc_handle,
kaf24@9660 427 uint32_t domid,
iap10@6688 428 unsigned long nr_extents,
iap10@6682 429 unsigned int extent_order,
iap10@6688 430 unsigned int address_bits,
kaf24@10276 431 xen_pfn_t *extent_start);
iap10@6688 432
iap10@6688 433 int xc_domain_memory_decrease_reservation(int xc_handle,
kaf24@9660 434 uint32_t domid,
iap10@6688 435 unsigned long nr_extents,
iap10@6688 436 unsigned int extent_order,
kaf24@10276 437 xen_pfn_t *extent_start);
iap10@6688 438
kaf24@8856 439 int xc_domain_memory_populate_physmap(int xc_handle,
kaf24@8856 440 uint32_t domid,
kaf24@8856 441 unsigned long nr_extents,
kaf24@8856 442 unsigned int extent_order,
kaf24@8856 443 unsigned int address_bits,
kaf24@10276 444 xen_pfn_t *extent_start);
kaf24@8856 445
kaf24@7624 446 int xc_domain_ioport_permission(int xc_handle,
kaf24@7624 447 uint32_t domid,
kaf24@8121 448 uint32_t first_port,
kaf24@8121 449 uint32_t nr_ports,
kaf24@8121 450 uint32_t allow_access);
kaf24@7624 451
kaf24@8460 452 int xc_domain_irq_permission(int xc_handle,
kaf24@8460 453 uint32_t domid,
kaf24@8460 454 uint8_t pirq,
kaf24@8460 455 uint8_t allow_access);
kaf24@8460 456
kaf24@8460 457 int xc_domain_iomem_permission(int xc_handle,
kaf24@8460 458 uint32_t domid,
kaf24@8736 459 unsigned long first_mfn,
kaf24@8736 460 unsigned long nr_mfns,
kaf24@8460 461 uint8_t allow_access);
kaf24@8460 462
kaf24@10266 463 unsigned long xc_make_page_below_4G(int xc_handle, uint32_t domid,
kaf24@10266 464 unsigned long mfn);
kaf24@10266 465
kfraser@11257 466 typedef xen_sysctl_perfc_desc_t xc_perfc_desc_t;
kfraser@11257 467 typedef xen_sysctl_perfc_val_t xc_perfc_val_t;
kaf24@10953 468 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc and @val
kaf24@10953 469 arrays. */
kaf24@3231 470 int xc_perfc_control(int xc_handle,
kaf24@7339 471 uint32_t op,
kaf24@10953 472 xc_perfc_desc_t *desc,
kaf24@10953 473 xc_perfc_val_t *val,
kaf24@10953 474 int *nbr_desc,
kaf24@10953 475 int *nbr_val);
mjw@1623 476
iap10@3443 477 /**
iap10@3443 478 * Memory maps a range within one domain to a local address range. Mappings
iap10@3443 479 * should be unmapped with munmap and should follow the same rules as mmap
rusty@4866 480 * regarding page alignment. Returns NULL on failure.
iap10@3443 481 *
iap10@3443 482 * In Linux, the ring queue for the control channel is accessible by mapping
iap10@3443 483 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
iap10@3443 484 * stored there is of type control_if_t.
iap10@3443 485 *
iap10@3443 486 * @parm xc_handle a handle on an open hypervisor interface
iap10@3443 487 * @parm dom the domain to map memory from
iap10@3443 488 * @parm size the amount of memory to map (in multiples of page size)
iap10@3443 489 * @parm prot same flag as in mmap().
iap10@3443 490 * @parm mfn the frame address to map.
iap10@3443 491 */
kaf24@7339 492 void *xc_map_foreign_range(int xc_handle, uint32_t dom,
iap10@2325 493 int size, int prot,
iap10@2325 494 unsigned long mfn );
iap10@2325 495
kaf24@7339 496 void *xc_map_foreign_batch(int xc_handle, uint32_t dom, int prot,
kaf24@10276 497 xen_pfn_t *arr, int num );
iap10@2325 498
Ian@8435 499 /**
Ian@8435 500 * Translates a virtual address in the context of a given domain and
Ian@8435 501 * vcpu returning the machine page frame number of the associated
Ian@8435 502 * page.
Ian@8435 503 *
Ian@8435 504 * @parm xc_handle a handle on an open hypervisor interface
Ian@8435 505 * @parm dom the domain to perform the translation in
Ian@8435 506 * @parm vcpu the vcpu to perform the translation on
Ian@8435 507 * @parm virt the virtual address to translate
Ian@8435 508 */
Ian@8435 509 unsigned long xc_translate_foreign_address(int xc_handle, uint32_t dom,
kaf24@9221 510 int vcpu, unsigned long long virt);
Ian@8435 511
kaf24@10276 512 int xc_get_pfn_list(int xc_handle, uint32_t domid, xen_pfn_t *pfn_buf,
cl349@4853 513 unsigned long max_pfns);
iap10@3390 514
awilliam@12005 515 unsigned long xc_ia64_fpsr_default(void);
awilliam@12005 516
kaf24@7339 517 int xc_ia64_get_pfn_list(int xc_handle, uint32_t domid,
kaf24@10276 518 xen_pfn_t *pfn_buf,
kaf24@7339 519 unsigned int start_page, unsigned int nr_pages);
kaf24@5914 520
djm@7536 521 int xc_copy_to_domain_page(int xc_handle, uint32_t domid,
kaf24@9221 522 unsigned long dst_pfn, const char *src_page);
djm@7536 523
kaf24@7786 524 int xc_clear_domain_page(int xc_handle, uint32_t domid,
kaf24@7786 525 unsigned long dst_pfn);
kaf24@7786 526
kaf24@7339 527 long xc_get_max_pages(int xc_handle, uint32_t domid);
djm@6856 528
cl349@6389 529 int xc_mmuext_op(int xc_handle, struct mmuext_op *op, unsigned int nr_ops,
kaf24@9221 530 domid_t dom);
cl349@6389 531
kaf24@6468 532 int xc_memory_op(int xc_handle, int cmd, void *arg);
cl349@6389 533
kaf24@7339 534 int xc_get_pfn_type_batch(int xc_handle, uint32_t dom,
kaf24@7339 535 int num, unsigned long *arr);
cl349@6389 536
cl349@6389 537
kaf24@5318 538 /* Get current total pages allocated to a domain. */
kaf24@7339 539 long xc_get_tot_pages(int xc_handle, uint32_t domid);
kaf24@5318 540
kaf24@7566 541
kaf24@7566 542 /*
kaf24@7566 543 * Trace Buffer Operations
kaf24@7566 544 */
kaf24@7566 545
kaf24@7566 546 /**
kaf24@9996 547 * xc_tbuf_enable - enable tracing buffers
kaf24@7566 548 *
kaf24@7566 549 * @parm xc_handle a handle to an open hypervisor interface
kaf24@9996 550 * @parm cnt size of tracing buffers to create (in pages)
kaf24@9996 551 * @parm mfn location to store mfn of the trace buffers to
kaf24@9996 552 * @parm size location to store the size (in bytes) of a trace buffer to
kaf24@9996 553 *
kaf24@9996 554 * Gets the machine address of the trace pointer area and the size of the
kaf24@9996 555 * per CPU buffers.
kaf24@7566 556 */
kfraser@12485 557 int xc_tbuf_enable(int xc_handle, unsigned long pages,
kfraser@12485 558 unsigned long *mfn, unsigned long *size);
kaf24@9996 559
kaf24@9996 560 /*
kaf24@9996 561 * Disable tracing buffers.
kaf24@9996 562 */
kaf24@9996 563 int xc_tbuf_disable(int xc_handle);
kaf24@7566 564
kaf24@7566 565 /**
kaf24@7571 566 * This function sets the size of the trace buffers. Setting the size
kaf24@7571 567 * is currently a one-shot operation that may be performed either at boot
kaf24@7571 568 * time or via this interface, not both. The buffer size must be set before
kaf24@7571 569 * enabling tracing.
kaf24@7566 570 *
kaf24@7566 571 * @parm xc_handle a handle to an open hypervisor interface
kaf24@7566 572 * @parm size the size in pages per cpu for the trace buffers
kaf24@7566 573 * @return 0 on success, -1 on failure.
kaf24@7566 574 */
kaf24@9996 575 int xc_tbuf_set_size(int xc_handle, unsigned long size);
kaf24@7566 576
kaf24@7566 577 /**
kaf24@9660 578 * This function retrieves the current size of the trace buffers.
kaf24@7566 579 * Note that the size returned is in terms of bytes, not pages.
kaf24@7566 580
kaf24@7566 581 * @parm xc_handle a handle to an open hypervisor interface
kaf24@7566 582 * @parm size will contain the size in bytes for the trace buffers
kaf24@7566 583 * @return 0 on success, -1 on failure.
kaf24@7566 584 */
kaf24@9996 585 int xc_tbuf_get_size(int xc_handle, unsigned long *size);
kaf24@9907 586
kaf24@9907 587 int xc_tbuf_set_cpu_mask(int xc_handle, uint32_t mask);
kaf24@9907 588
kaf24@9907 589 int xc_tbuf_set_evt_mask(int xc_handle, uint32_t mask);
kaf24@7566 590
kfraser@11257 591 int xc_domctl(int xc_handle, struct xen_domctl *domctl);
kfraser@11257 592 int xc_sysctl(int xc_handle, struct xen_sysctl *sysctl);
cwc22@3985 593
vh249@6549 594 int xc_version(int xc_handle, int cmd, void *arg);
vh249@6549 595
cl349@6389 596 /*
cl349@6389 597 * MMU updates.
cl349@6389 598 */
cl349@6389 599 #define MAX_MMU_UPDATES 1024
cl349@6389 600 struct xc_mmu {
cl349@6389 601 mmu_update_t updates[MAX_MMU_UPDATES];
cl349@6389 602 int idx;
cl349@6389 603 domid_t subject;
cl349@6389 604 };
cl349@6389 605 typedef struct xc_mmu xc_mmu_t;
cl349@6389 606 xc_mmu_t *xc_init_mmu_updates(int xc_handle, domid_t dom);
kaf24@9660 607 int xc_add_mmu_update(int xc_handle, xc_mmu_t *mmu,
iap10@6680 608 unsigned long long ptr, unsigned long long val);
cl349@6389 609 int xc_finish_mmu_updates(int xc_handle, xc_mmu_t *mmu);
cl349@6389 610
kfraser@12485 611 int xc_acm_op(int xc_handle, int cmd, void *arg, unsigned long arg_size);
kaf24@9907 612
kaf24@10355 613 /*
kaf24@10355 614 * Return a handle to the event channel driver, or -1 on failure, in which case
kaf24@10355 615 * errno will be set appropriately.
kaf24@10355 616 */
kaf24@10355 617 int xc_evtchn_open(void);
kaf24@10355 618
kaf24@10355 619 /*
kaf24@10355 620 * Close a handle previously allocated with xc_evtchn_open().
kaf24@10355 621 */
kaf24@10355 622 int xc_evtchn_close(int xce_handle);
kaf24@10355 623
kaf24@10355 624 /*
kaf24@10355 625 * Return an fd that can be select()ed on for further calls to
kaf24@10355 626 * xc_evtchn_pending().
kaf24@10355 627 */
kaf24@10355 628 int xc_evtchn_fd(int xce_handle);
kaf24@10355 629
kaf24@10355 630 /*
kaf24@10355 631 * Notify the given event channel. Returns -1 on failure, in which case
kaf24@10355 632 * errno will be set appropriately.
kaf24@10355 633 */
kaf24@10355 634 int xc_evtchn_notify(int xce_handle, evtchn_port_t port);
kaf24@10355 635
kaf24@10355 636 /*
kfraser@12694 637 * Returns a new event port awaiting interdomain connection from the given
kfraser@12694 638 * domain ID, or -1 on failure, in which case errno will be set appropriately.
kfraser@12694 639 */
kfraser@12694 640 evtchn_port_t xc_evtchn_bind_unbound_port(int xce_handle, int domid);
kfraser@12694 641
kfraser@12694 642 /*
kaf24@10355 643 * Returns a new event port bound to the remote port for the given domain ID,
kaf24@10355 644 * or -1 on failure, in which case errno will be set appropriately.
kaf24@10355 645 */
kaf24@10355 646 evtchn_port_t xc_evtchn_bind_interdomain(int xce_handle, int domid,
kaf24@10355 647 evtchn_port_t remote_port);
kaf24@10355 648
kaf24@10355 649 /*
kaf24@10355 650 * Unbind the given event channel. Returns -1 on failure, in which case errno
kaf24@10355 651 * will be set appropriately.
kaf24@10355 652 */
kaf24@10355 653 int xc_evtchn_unbind(int xce_handle, evtchn_port_t port);
kaf24@10355 654
kaf24@10355 655 /*
kaf24@10355 656 * Bind an event channel to the given VIRQ. Returns the event channel bound to
kaf24@10355 657 * the VIRQ, or -1 on failure, in which case errno will be set appropriately.
kaf24@10355 658 */
kaf24@10355 659 evtchn_port_t xc_evtchn_bind_virq(int xce_handle, unsigned int virq);
kaf24@10355 660
kaf24@10355 661 /*
kaf24@10355 662 * Return the next event channel to become pending, or -1 on failure, in which
kaf24@10355 663 * case errno will be set appropriately.
kaf24@10355 664 */
kaf24@10355 665 evtchn_port_t xc_evtchn_pending(int xce_handle);
kaf24@10355 666
kaf24@10355 667 /*
kaf24@10355 668 * Unmask the given event channel. Returns -1 on failure, in which case errno
kaf24@10355 669 * will be set appropriately.
kaf24@10355 670 */
kaf24@10355 671 int xc_evtchn_unmask(int xce_handle, evtchn_port_t port);
kaf24@10355 672
kfraser@12504 673 int xc_hvm_set_pci_intx_level(
kfraser@12694 674 int xc_handle, domid_t dom,
kfraser@12504 675 uint8_t domain, uint8_t bus, uint8_t device, uint8_t intx,
kfraser@12504 676 unsigned int level);
kfraser@12504 677 int xc_hvm_set_isa_irq_level(
kfraser@12694 678 int xc_handle, domid_t dom,
kfraser@12504 679 uint8_t isa_irq,
kfraser@12504 680 unsigned int level);
kfraser@12504 681
kfraser@12504 682 int xc_hvm_set_pci_link_route(
kfraser@12694 683 int xc_handle, domid_t dom, uint8_t link, uint8_t isa_irq);
kfraser@12275 684
kfraser@12765 685
kfraser@12765 686 typedef enum {
kfraser@12765 687 XC_ERROR_NONE = 0,
kfraser@12765 688 XC_INTERNAL_ERROR = 1,
kfraser@12765 689 XC_INVALID_KERNEL = 2,
kfraser@12765 690 } xc_error_code;
kfraser@12765 691
kfraser@12765 692 #define XC_MAX_ERROR_MSG_LEN 1024
kfraser@12765 693 typedef struct {
kfraser@12765 694 int code;
kfraser@12765 695 char message[XC_MAX_ERROR_MSG_LEN];
kfraser@12765 696 } xc_error;
kfraser@12765 697
kfraser@12765 698 /*
kfraser@12765 699 * Return a pointer to the last error. This pointer and the
kfraser@12765 700 * data pointed to are only valid until the next call to
kfraser@12765 701 * libxc.
kfraser@12765 702 */
kfraser@12765 703 const xc_error const *xc_get_last_error(void);
kfraser@12765 704
kfraser@12765 705 /*
kfraser@12765 706 * Clear the last error
kfraser@12765 707 */
kfraser@12765 708 void xc_clear_last_error(void);
kfraser@12765 709
kfraser@12765 710 typedef void (*xc_error_handler)(const xc_error const* err);
kfraser@12765 711
kfraser@12765 712 /*
kfraser@12765 713 * The default error handler which prints to stderr
kfraser@12765 714 */
kfraser@12765 715 void xc_default_error_handler(const xc_error const* err);
kfraser@12765 716
kfraser@12765 717 /*
kfraser@12765 718 * Convert an error code into a text description
kfraser@12765 719 */
kfraser@12765 720 const char *xc_error_code_to_desc(int code);
kfraser@12765 721
kfraser@12765 722 /*
kfraser@12765 723 * Registers a callback to handle errors
kfraser@12765 724 */
kfraser@12765 725 xc_error_handler xc_set_error_handler(xc_error_handler handler);
kfraser@12765 726
cl349@6389 727 #endif