direct-io.hg

view tools/libxc/xenctrl.h @ 11257:86d26e6ec89b

Replace dom0_ops hypercall with three new hypercalls:
1. platform_op -- used by dom0 kernel to perform actions on the
hardware platform (e.g., MTRR access, microcode update, platform
quirks, ...)
2. domctl -- used by management tools to control a specified domain
3. sysctl -- used by management tools for system-wide actions

Benefits include more sensible factoring of actions to
hypercalls. Also allows tool compatibility to be tracked separately
from the dom0 kernel. The assumption is that it will be easier to
replace libxenctrl, libxenguest and Xen as a matched set if the
dom0 kernel does not need to be replaced too (e.g., because that
would require vendor revalidation).

From here on we hope to maintain dom0 kernel compatibility. This
promise is not extended to tool compatibility beyond the existing
guarantee that compatibility will not be broken within a three-level
stable release [3.0.2, 3.0.3, etc.].

Signed-off-by: Keir Fraser <keir@xensource.com>
author kfraser@localhost.localdomain
date Fri Aug 25 18:39:10 2006 +0100 (2006-08-25)
parents 26b673aeff8b
children fd6c2b5e041f
line source
1 /******************************************************************************
2 * xenctrl.h
3 *
4 * A library for low-level access to the Xen control interfaces.
5 *
6 * Copyright (c) 2003-2004, K A Fraser.
7 */
9 #ifndef XENCTRL_H
10 #define XENCTRL_H
12 #include <stddef.h>
13 #include <stdint.h>
14 #include <sys/ptrace.h>
15 #include <xen/xen.h>
16 #include <xen/domctl.h>
17 #include <xen/sysctl.h>
18 #include <xen/version.h>
19 #include <xen/event_channel.h>
20 #include <xen/sched.h>
21 #include <xen/memory.h>
22 #include <xen/acm.h>
23 #include <xen/acm_ops.h>
25 #ifdef __ia64__
26 #define XC_PAGE_SHIFT 14
27 #else
28 #define XC_PAGE_SHIFT 12
29 #endif
30 #define XC_PAGE_SIZE (1UL << XC_PAGE_SHIFT)
31 #define XC_PAGE_MASK (~(XC_PAGE_SIZE-1))
33 /*
34 * DEFINITIONS FOR CPU BARRIERS
35 */
37 #if defined(__i386__)
38 #define mb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
39 #define rmb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
40 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
41 #elif defined(__x86_64__)
42 #define mb() __asm__ __volatile__ ( "mfence" : : : "memory")
43 #define rmb() __asm__ __volatile__ ( "lfence" : : : "memory")
44 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
45 #elif defined(__ia64__)
46 /* FIXME */
47 #define mb()
48 #define rmb()
49 #define wmb()
50 #elif defined(__powerpc__)
51 /* XXX loosen these up later */
52 #define mb() __asm__ __volatile__ ("sync" : : : "memory")
53 #define rmb() __asm__ __volatile__ ("sync" : : : "memory") /* lwsync? */
54 #define wmb() __asm__ __volatile__ ("sync" : : : "memory") /* eieio? */
55 #else
56 #error "Define barriers"
57 #endif
59 /*
60 * INITIALIZATION FUNCTIONS
61 */
63 /**
64 * This function opens a handle to the hypervisor interface. This function can
65 * be called multiple times within a single process. Multiple processes can
66 * have an open hypervisor interface at the same time.
67 *
68 * Each call to this function should have a corresponding call to
69 * xc_interface_close().
70 *
71 * This function can fail if the caller does not have superuser permission or
72 * if a Xen-enabled kernel is not currently running.
73 *
74 * @return a handle to the hypervisor interface or -1 on failure
75 */
76 int xc_interface_open(void);
78 /**
79 * This function closes an open hypervisor interface.
80 *
81 * This function can fail if the handle does not represent an open interface or
82 * if there were problems closing the interface.
83 *
84 * @parm xc_handle a handle to an open hypervisor interface
85 * @return 0 on success, -1 otherwise.
86 */
87 int xc_interface_close(int xc_handle);
89 /*
90 * DOMAIN DEBUGGING FUNCTIONS
91 */
93 typedef struct xc_core_header {
94 unsigned int xch_magic;
95 unsigned int xch_nr_vcpus;
96 unsigned int xch_nr_pages;
97 unsigned int xch_ctxt_offset;
98 unsigned int xch_index_offset;
99 unsigned int xch_pages_offset;
100 } xc_core_header_t;
102 #define XC_CORE_MAGIC 0xF00FEBED
104 long xc_ptrace_core(
105 int xc_handle,
106 enum __ptrace_request request,
107 uint32_t domid,
108 long addr,
109 long data,
110 vcpu_guest_context_t *ctxt);
111 void * map_domain_va_core(
112 unsigned long domfd,
113 int cpu,
114 void *guest_va,
115 vcpu_guest_context_t *ctxt);
116 int xc_waitdomain_core(
117 int xc_handle,
118 int domain,
119 int *status,
120 int options,
121 vcpu_guest_context_t *ctxt);
123 /*
124 * DOMAIN MANAGEMENT FUNCTIONS
125 */
127 typedef struct {
128 uint32_t domid;
129 uint32_t ssidref;
130 unsigned int dying:1, crashed:1, shutdown:1,
131 paused:1, blocked:1, running:1;
132 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
133 unsigned long nr_pages;
134 unsigned long shared_info_frame;
135 uint64_t cpu_time;
136 unsigned long max_memkb;
137 unsigned int nr_online_vcpus;
138 unsigned int max_vcpu_id;
139 xen_domain_handle_t handle;
140 } xc_dominfo_t;
142 typedef xen_domctl_getdomaininfo_t xc_domaininfo_t;
143 int xc_domain_create(int xc_handle,
144 uint32_t ssidref,
145 xen_domain_handle_t handle,
146 uint32_t *pdomid);
149 /* Functions to produce a dump of a given domain
150 * xc_domain_dumpcore - produces a dump to a specified file
151 * xc_domain_dumpcore_via_callback - produces a dump, using a specified
152 * callback function
153 */
154 int xc_domain_dumpcore(int xc_handle,
155 uint32_t domid,
156 const char *corename);
158 /* Define the callback function type for xc_domain_dumpcore_via_callback.
159 *
160 * This function is called by the coredump code for every "write",
161 * and passes an opaque object for the use of the function and
162 * created by the caller of xc_domain_dumpcore_via_callback.
163 */
164 typedef int (dumpcore_rtn_t)(void *arg, char *buffer, unsigned int length);
166 int xc_domain_dumpcore_via_callback(int xc_handle,
167 uint32_t domid,
168 void *arg,
169 dumpcore_rtn_t dump_rtn);
171 /*
172 * This function sets the maximum number of vcpus that a domain may create.
173 *
174 * @parm xc_handle a handle to an open hypervisor interface.
175 * @parm domid the domain id in which vcpus are to be created.
176 * @parm max the maximum number of vcpus that the domain may create.
177 * @return 0 on success, -1 on failure.
178 */
179 int xc_domain_max_vcpus(int xc_handle,
180 uint32_t domid,
181 unsigned int max);
183 /**
184 * This function pauses a domain. A paused domain still exists in memory
185 * however it does not receive any timeslices from the hypervisor.
186 *
187 * @parm xc_handle a handle to an open hypervisor interface
188 * @parm domid the domain id to pause
189 * @return 0 on success, -1 on failure.
190 */
191 int xc_domain_pause(int xc_handle,
192 uint32_t domid);
193 /**
194 * This function unpauses a domain. The domain should have been previously
195 * paused.
196 *
197 * @parm xc_handle a handle to an open hypervisor interface
198 * @parm domid the domain id to unpause
199 * return 0 on success, -1 on failure
200 */
201 int xc_domain_unpause(int xc_handle,
202 uint32_t domid);
204 /**
205 * This function will destroy a domain. Destroying a domain removes the domain
206 * completely from memory. This function should be called after sending the
207 * domain a SHUTDOWN control message to free up the domain resources.
208 *
209 * @parm xc_handle a handle to an open hypervisor interface
210 * @parm domid the domain id to destroy
211 * @return 0 on success, -1 on failure
212 */
213 int xc_domain_destroy(int xc_handle,
214 uint32_t domid);
216 /**
217 * This function will shutdown a domain. This is intended for use in
218 * fully-virtualized domains where this operation is analogous to the
219 * sched_op operations in a paravirtualized domain. The caller is
220 * expected to give the reason for the shutdown.
221 *
222 * @parm xc_handle a handle to an open hypervisor interface
223 * @parm domid the domain id to destroy
224 * @parm reason is the reason (SHUTDOWN_xxx) for the shutdown
225 * @return 0 on success, -1 on failure
226 */
227 int xc_domain_shutdown(int xc_handle,
228 uint32_t domid,
229 int reason);
231 int xc_vcpu_setaffinity(int xc_handle,
232 uint32_t domid,
233 int vcpu,
234 uint64_t cpumap);
235 int xc_vcpu_getaffinity(int xc_handle,
236 uint32_t domid,
237 int vcpu,
238 uint64_t *cpumap);
240 /**
241 * This function will return information about one or more domains. It is
242 * designed to iterate over the list of domains. If a single domain is
243 * requested, this function will return the next domain in the list - if
244 * one exists. It is, therefore, important in this case to make sure the
245 * domain requested was the one returned.
246 *
247 * @parm xc_handle a handle to an open hypervisor interface
248 * @parm first_domid the first domain to enumerate information from. Domains
249 * are currently enumerate in order of creation.
250 * @parm max_doms the number of elements in info
251 * @parm info an array of max_doms size that will contain the information for
252 * the enumerated domains.
253 * @return the number of domains enumerated or -1 on error
254 */
255 int xc_domain_getinfo(int xc_handle,
256 uint32_t first_domid,
257 unsigned int max_doms,
258 xc_dominfo_t *info);
261 /**
262 * This function will set the execution context for the specified vcpu.
263 *
264 * @parm xc_handle a handle to an open hypervisor interface
265 * @parm domid the domain to set the vcpu context for
266 * @parm vcpu the vcpu number for the context
267 * @parm ctxt pointer to the the cpu context with the values to set
268 * @return the number of domains enumerated or -1 on error
269 */
270 int xc_vcpu_setcontext(int xc_handle,
271 uint32_t domid,
272 uint32_t vcpu,
273 vcpu_guest_context_t *ctxt);
274 /**
275 * This function will return information about one or more domains, using a
276 * single hypercall. The domain information will be stored into the supplied
277 * array of xc_domaininfo_t structures.
278 *
279 * @parm xc_handle a handle to an open hypervisor interface
280 * @parm first_domain the first domain to enumerate information from.
281 * Domains are currently enumerate in order of creation.
282 * @parm max_domains the number of elements in info
283 * @parm info an array of max_doms size that will contain the information for
284 * the enumerated domains.
285 * @return the number of domains enumerated or -1 on error
286 */
287 int xc_domain_getinfolist(int xc_handle,
288 uint32_t first_domain,
289 unsigned int max_domains,
290 xc_domaininfo_t *info);
292 /**
293 * This function returns information about the execution context of a
294 * particular vcpu of a domain.
295 *
296 * @parm xc_handle a handle to an open hypervisor interface
297 * @parm domid the domain to get information from
298 * @parm vcpu the vcpu number
299 * @parm ctxt a pointer to a structure to store the execution context of the
300 * domain
301 * @return 0 on success, -1 on failure
302 */
303 int xc_vcpu_getcontext(int xc_handle,
304 uint32_t domid,
305 uint32_t vcpu,
306 vcpu_guest_context_t *ctxt);
308 typedef xen_domctl_getvcpuinfo_t xc_vcpuinfo_t;
309 int xc_vcpu_getinfo(int xc_handle,
310 uint32_t domid,
311 uint32_t vcpu,
312 xc_vcpuinfo_t *info);
314 int xc_domain_setcpuweight(int xc_handle,
315 uint32_t domid,
316 float weight);
317 long long xc_domain_get_cpu_usage(int xc_handle,
318 domid_t domid,
319 int vcpu);
321 int xc_domain_sethandle(int xc_handle, uint32_t domid,
322 xen_domain_handle_t handle);
324 typedef xen_domctl_shadow_op_stats_t xc_shadow_op_stats_t;
325 int xc_shadow_control(int xc_handle,
326 uint32_t domid,
327 unsigned int sop,
328 unsigned long *dirty_bitmap,
329 unsigned long pages,
330 unsigned long *mb,
331 uint32_t mode,
332 xc_shadow_op_stats_t *stats);
334 int xc_sedf_domain_set(int xc_handle,
335 uint32_t domid,
336 uint64_t period, uint64_t slice,
337 uint64_t latency, uint16_t extratime,
338 uint16_t weight);
340 int xc_sedf_domain_get(int xc_handle,
341 uint32_t domid,
342 uint64_t* period, uint64_t *slice,
343 uint64_t *latency, uint16_t *extratime,
344 uint16_t *weight);
346 int xc_sched_credit_domain_set(int xc_handle,
347 uint32_t domid,
348 struct xen_domctl_sched_credit *sdom);
350 int xc_sched_credit_domain_get(int xc_handle,
351 uint32_t domid,
352 struct xen_domctl_sched_credit *sdom);
354 /*
355 * EVENT CHANNEL FUNCTIONS
356 */
358 /**
359 * This function allocates an unbound port. Ports are named endpoints used for
360 * interdomain communication. This function is most useful in opening a
361 * well-known port within a domain to receive events on.
362 *
363 * @parm xc_handle a handle to an open hypervisor interface
364 * @parm dom the ID of the local domain (the 'allocatee')
365 * @parm remote_dom the ID of the domain who will later bind
366 * @return allocated port (in @dom) on success, -1 on failure
367 */
368 int xc_evtchn_alloc_unbound(int xc_handle,
369 uint32_t dom,
370 uint32_t remote_dom);
372 int xc_physdev_pci_access_modify(int xc_handle,
373 uint32_t domid,
374 int bus,
375 int dev,
376 int func,
377 int enable);
379 int xc_readconsolering(int xc_handle,
380 char **pbuffer,
381 unsigned int *pnr_chars,
382 int clear);
384 typedef xen_sysctl_physinfo_t xc_physinfo_t;
385 int xc_physinfo(int xc_handle,
386 xc_physinfo_t *info);
388 int xc_sched_id(int xc_handle,
389 int *sched_id);
391 int xc_domain_setmaxmem(int xc_handle,
392 uint32_t domid,
393 unsigned int max_memkb);
395 int xc_domain_set_time_offset(int xc_handle,
396 uint32_t domid,
397 int32_t time_offset_seconds);
399 int xc_domain_memory_increase_reservation(int xc_handle,
400 uint32_t domid,
401 unsigned long nr_extents,
402 unsigned int extent_order,
403 unsigned int address_bits,
404 xen_pfn_t *extent_start);
406 int xc_domain_memory_decrease_reservation(int xc_handle,
407 uint32_t domid,
408 unsigned long nr_extents,
409 unsigned int extent_order,
410 xen_pfn_t *extent_start);
412 int xc_domain_memory_populate_physmap(int xc_handle,
413 uint32_t domid,
414 unsigned long nr_extents,
415 unsigned int extent_order,
416 unsigned int address_bits,
417 xen_pfn_t *extent_start);
419 int xc_domain_translate_gpfn_list(int xc_handle,
420 uint32_t domid,
421 unsigned long nr_gpfns,
422 xen_pfn_t *gpfn_list,
423 xen_pfn_t *mfn_list);
425 int xc_domain_ioport_permission(int xc_handle,
426 uint32_t domid,
427 uint32_t first_port,
428 uint32_t nr_ports,
429 uint32_t allow_access);
431 int xc_domain_irq_permission(int xc_handle,
432 uint32_t domid,
433 uint8_t pirq,
434 uint8_t allow_access);
436 int xc_domain_iomem_permission(int xc_handle,
437 uint32_t domid,
438 unsigned long first_mfn,
439 unsigned long nr_mfns,
440 uint8_t allow_access);
442 unsigned long xc_make_page_below_4G(int xc_handle, uint32_t domid,
443 unsigned long mfn);
445 typedef xen_sysctl_perfc_desc_t xc_perfc_desc_t;
446 typedef xen_sysctl_perfc_val_t xc_perfc_val_t;
447 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc and @val
448 arrays. */
449 int xc_perfc_control(int xc_handle,
450 uint32_t op,
451 xc_perfc_desc_t *desc,
452 xc_perfc_val_t *val,
453 int *nbr_desc,
454 int *nbr_val);
456 /**
457 * Memory maps a range within one domain to a local address range. Mappings
458 * should be unmapped with munmap and should follow the same rules as mmap
459 * regarding page alignment. Returns NULL on failure.
460 *
461 * In Linux, the ring queue for the control channel is accessible by mapping
462 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
463 * stored there is of type control_if_t.
464 *
465 * @parm xc_handle a handle on an open hypervisor interface
466 * @parm dom the domain to map memory from
467 * @parm size the amount of memory to map (in multiples of page size)
468 * @parm prot same flag as in mmap().
469 * @parm mfn the frame address to map.
470 */
471 void *xc_map_foreign_range(int xc_handle, uint32_t dom,
472 int size, int prot,
473 unsigned long mfn );
475 void *xc_map_foreign_batch(int xc_handle, uint32_t dom, int prot,
476 xen_pfn_t *arr, int num );
478 /**
479 * Translates a virtual address in the context of a given domain and
480 * vcpu returning the machine page frame number of the associated
481 * page.
482 *
483 * @parm xc_handle a handle on an open hypervisor interface
484 * @parm dom the domain to perform the translation in
485 * @parm vcpu the vcpu to perform the translation on
486 * @parm virt the virtual address to translate
487 */
488 unsigned long xc_translate_foreign_address(int xc_handle, uint32_t dom,
489 int vcpu, unsigned long long virt);
491 int xc_get_pfn_list(int xc_handle, uint32_t domid, xen_pfn_t *pfn_buf,
492 unsigned long max_pfns);
494 int xc_ia64_get_pfn_list(int xc_handle, uint32_t domid,
495 xen_pfn_t *pfn_buf,
496 unsigned int start_page, unsigned int nr_pages);
498 int xc_copy_to_domain_page(int xc_handle, uint32_t domid,
499 unsigned long dst_pfn, const char *src_page);
501 int xc_clear_domain_page(int xc_handle, uint32_t domid,
502 unsigned long dst_pfn);
504 long xc_get_max_pages(int xc_handle, uint32_t domid);
506 int xc_mmuext_op(int xc_handle, struct mmuext_op *op, unsigned int nr_ops,
507 domid_t dom);
509 int xc_memory_op(int xc_handle, int cmd, void *arg);
511 int xc_get_pfn_type_batch(int xc_handle, uint32_t dom,
512 int num, unsigned long *arr);
515 /* Get current total pages allocated to a domain. */
516 long xc_get_tot_pages(int xc_handle, uint32_t domid);
519 /*
520 * Trace Buffer Operations
521 */
523 /**
524 * xc_tbuf_enable - enable tracing buffers
525 *
526 * @parm xc_handle a handle to an open hypervisor interface
527 * @parm cnt size of tracing buffers to create (in pages)
528 * @parm mfn location to store mfn of the trace buffers to
529 * @parm size location to store the size (in bytes) of a trace buffer to
530 *
531 * Gets the machine address of the trace pointer area and the size of the
532 * per CPU buffers.
533 */
534 int xc_tbuf_enable(int xc_handle, size_t cnt, unsigned long *mfn,
535 unsigned long *size);
537 /*
538 * Disable tracing buffers.
539 */
540 int xc_tbuf_disable(int xc_handle);
542 /**
543 * This function sets the size of the trace buffers. Setting the size
544 * is currently a one-shot operation that may be performed either at boot
545 * time or via this interface, not both. The buffer size must be set before
546 * enabling tracing.
547 *
548 * @parm xc_handle a handle to an open hypervisor interface
549 * @parm size the size in pages per cpu for the trace buffers
550 * @return 0 on success, -1 on failure.
551 */
552 int xc_tbuf_set_size(int xc_handle, unsigned long size);
554 /**
555 * This function retrieves the current size of the trace buffers.
556 * Note that the size returned is in terms of bytes, not pages.
558 * @parm xc_handle a handle to an open hypervisor interface
559 * @parm size will contain the size in bytes for the trace buffers
560 * @return 0 on success, -1 on failure.
561 */
562 int xc_tbuf_get_size(int xc_handle, unsigned long *size);
564 int xc_tbuf_set_cpu_mask(int xc_handle, uint32_t mask);
566 int xc_tbuf_set_evt_mask(int xc_handle, uint32_t mask);
568 int xc_domctl(int xc_handle, struct xen_domctl *domctl);
569 int xc_sysctl(int xc_handle, struct xen_sysctl *sysctl);
571 int xc_version(int xc_handle, int cmd, void *arg);
573 /*
574 * MMU updates.
575 */
576 #define MAX_MMU_UPDATES 1024
577 struct xc_mmu {
578 mmu_update_t updates[MAX_MMU_UPDATES];
579 int idx;
580 domid_t subject;
581 };
582 typedef struct xc_mmu xc_mmu_t;
583 xc_mmu_t *xc_init_mmu_updates(int xc_handle, domid_t dom);
584 int xc_add_mmu_update(int xc_handle, xc_mmu_t *mmu,
585 unsigned long long ptr, unsigned long long val);
586 int xc_finish_mmu_updates(int xc_handle, xc_mmu_t *mmu);
588 int xc_acm_op(int xc_handle, int cmd, void *arg, size_t arg_size);
590 /*
591 * Return a handle to the event channel driver, or -1 on failure, in which case
592 * errno will be set appropriately.
593 */
594 int xc_evtchn_open(void);
596 /*
597 * Close a handle previously allocated with xc_evtchn_open().
598 */
599 int xc_evtchn_close(int xce_handle);
601 /*
602 * Return an fd that can be select()ed on for further calls to
603 * xc_evtchn_pending().
604 */
605 int xc_evtchn_fd(int xce_handle);
607 /*
608 * Notify the given event channel. Returns -1 on failure, in which case
609 * errno will be set appropriately.
610 */
611 int xc_evtchn_notify(int xce_handle, evtchn_port_t port);
613 /*
614 * Returns a new event port bound to the remote port for the given domain ID,
615 * or -1 on failure, in which case errno will be set appropriately.
616 */
617 evtchn_port_t xc_evtchn_bind_interdomain(int xce_handle, int domid,
618 evtchn_port_t remote_port);
620 /*
621 * Unbind the given event channel. Returns -1 on failure, in which case errno
622 * will be set appropriately.
623 */
624 int xc_evtchn_unbind(int xce_handle, evtchn_port_t port);
626 /*
627 * Bind an event channel to the given VIRQ. Returns the event channel bound to
628 * the VIRQ, or -1 on failure, in which case errno will be set appropriately.
629 */
630 evtchn_port_t xc_evtchn_bind_virq(int xce_handle, unsigned int virq);
632 /*
633 * Return the next event channel to become pending, or -1 on failure, in which
634 * case errno will be set appropriately.
635 */
636 evtchn_port_t xc_evtchn_pending(int xce_handle);
638 /*
639 * Unmask the given event channel. Returns -1 on failure, in which case errno
640 * will be set appropriately.
641 */
642 int xc_evtchn_unmask(int xce_handle, evtchn_port_t port);
644 #endif