direct-io.hg

view tools/libxc/xenctrl.h @ 11393:fd6c2b5e041f

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