ia64/xen-unstable

view tools/libxc/xenctrl.h @ 9730:74ee53209cca

Fix whitespace in libxc. Tabs are manually fixed.
Trailing whitespace removed with:
perl -p -i -e 's/\s+$/\n/g' tools/libxc/*.[ch]

Signed-off-by: Hollis Blanchard <hollisb@us.ibm.com>
author kaf24@firebug.cl.cam.ac.uk
date Sat Apr 15 10:07:31 2006 +0100 (2006-04-15)
parents b128f55ca05c
children 24dbb153ab39
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 <stdint.h>
13 #include <sys/ptrace.h>
14 #include <xen/xen.h>
15 #include <xen/dom0_ops.h>
16 #include <xen/version.h>
17 #include <xen/event_channel.h>
18 #include <xen/sched.h>
19 #include <xen/sched_ctl.h>
20 #include <xen/memory.h>
21 #include <xen/acm.h>
23 #ifdef __ia64__
24 #define XC_PAGE_SHIFT 14
25 #else
26 #define XC_PAGE_SHIFT 12
27 #endif
28 #define XC_PAGE_SIZE (1UL << XC_PAGE_SHIFT)
29 #define XC_PAGE_MASK (~(XC_PAGE_SIZE-1))
31 /*
32 * DEFINITIONS FOR CPU BARRIERS
33 */
35 #if defined(__i386__)
36 #define mb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
37 #define rmb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
38 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
39 #elif defined(__x86_64__)
40 #define mb() __asm__ __volatile__ ( "mfence" : : : "memory")
41 #define rmb() __asm__ __volatile__ ( "lfence" : : : "memory")
42 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
43 #elif defined(__ia64__)
44 /* FIXME */
45 #define mb()
46 #define rmb()
47 #define wmb()
48 #else
49 #error "Define barriers"
50 #endif
52 /*
53 * INITIALIZATION FUNCTIONS
54 */
56 /**
57 * This function opens a handle to the hypervisor interface. This function can
58 * be called multiple times within a single process. Multiple processes can
59 * have an open hypervisor interface at the same time.
60 *
61 * Each call to this function should have a corresponding call to
62 * xc_interface_close().
63 *
64 * This function can fail if the caller does not have superuser permission or
65 * if a Xen-enabled kernel is not currently running.
66 *
67 * @return a handle to the hypervisor interface or -1 on failure
68 */
69 int xc_interface_open(void);
71 /**
72 * This function closes an open hypervisor interface.
73 *
74 * This function can fail if the handle does not represent an open interface or
75 * if there were problems closing the interface.
76 *
77 * @parm xc_handle a handle to an open hypervisor interface
78 * @return 0 on success, -1 otherwise.
79 */
80 int xc_interface_close(int xc_handle);
82 /*
83 * DOMAIN DEBUGGING FUNCTIONS
84 */
86 typedef struct xc_core_header {
87 unsigned int xch_magic;
88 unsigned int xch_nr_vcpus;
89 unsigned int xch_nr_pages;
90 unsigned int xch_ctxt_offset;
91 unsigned int xch_index_offset;
92 unsigned int xch_pages_offset;
93 } xc_core_header_t;
95 #define XC_CORE_MAGIC 0xF00FEBED
97 long xc_ptrace_core(
98 int xc_handle,
99 enum __ptrace_request request,
100 uint32_t domid,
101 long addr,
102 long data,
103 vcpu_guest_context_t *ctxt);
104 void * map_domain_va_core(
105 unsigned long domfd,
106 int cpu,
107 void *guest_va,
108 vcpu_guest_context_t *ctxt);
109 int xc_waitdomain_core(
110 int xc_handle,
111 int domain,
112 int *status,
113 int options,
114 vcpu_guest_context_t *ctxt);
116 /*
117 * DOMAIN MANAGEMENT FUNCTIONS
118 */
120 typedef struct {
121 uint32_t domid;
122 uint32_t ssidref;
123 unsigned int dying:1, crashed:1, shutdown:1,
124 paused:1, blocked:1, running:1;
125 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
126 unsigned long nr_pages;
127 unsigned long shared_info_frame;
128 uint64_t cpu_time;
129 unsigned long max_memkb;
130 unsigned int nr_online_vcpus;
131 unsigned int max_vcpu_id;
132 xen_domain_handle_t handle;
133 } xc_dominfo_t;
135 typedef dom0_getdomaininfo_t xc_domaininfo_t;
136 int xc_domain_create(int xc_handle,
137 uint32_t ssidref,
138 xen_domain_handle_t handle,
139 uint32_t *pdomid);
142 /* Functions to produce a dump of a given domain
143 * xc_domain_dumpcore - produces a dump to a specified file
144 * xc_domain_dumpcore_via_callback - produces a dump, using a specified
145 * callback function
146 */
147 int xc_domain_dumpcore(int xc_handle,
148 uint32_t domid,
149 const char *corename);
151 /* Define the callback function type for xc_domain_dumpcore_via_callback.
152 *
153 * This function is called by the coredump code for every "write",
154 * and passes an opaque object for the use of the function and
155 * created by the caller of xc_domain_dumpcore_via_callback.
156 */
157 typedef int (dumpcore_rtn_t)(void *arg, char *buffer, unsigned int length);
159 int xc_domain_dumpcore_via_callback(int xc_handle,
160 uint32_t domid,
161 void *arg,
162 dumpcore_rtn_t dump_rtn);
164 /*
165 * This function sets the maximum number of vcpus that a domain may create.
166 *
167 * @parm xc_handle a handle to an open hypervisor interface.
168 * @parm domid the domain id in which vcpus are to be created.
169 * @parm max the maximum number of vcpus that the domain may create.
170 * @return 0 on success, -1 on failure.
171 */
172 int xc_domain_max_vcpus(int xc_handle,
173 uint32_t domid,
174 unsigned int max);
176 /**
177 * This function pauses a domain. A paused domain still exists in memory
178 * however it does not receive any timeslices from the hypervisor.
179 *
180 * @parm xc_handle a handle to an open hypervisor interface
181 * @parm domid the domain id to pause
182 * @return 0 on success, -1 on failure.
183 */
184 int xc_domain_pause(int xc_handle,
185 uint32_t domid);
186 /**
187 * This function unpauses a domain. The domain should have been previously
188 * paused.
189 *
190 * @parm xc_handle a handle to an open hypervisor interface
191 * @parm domid the domain id to unpause
192 * return 0 on success, -1 on failure
193 */
194 int xc_domain_unpause(int xc_handle,
195 uint32_t domid);
197 /**
198 * This function will destroy a domain. Destroying a domain removes the domain
199 * completely from memory. This function should be called after sending the
200 * domain a SHUTDOWN control message to free up the domain resources.
201 *
202 * @parm xc_handle a handle to an open hypervisor interface
203 * @parm domid the domain id to destroy
204 * @return 0 on success, -1 on failure
205 */
206 int xc_domain_destroy(int xc_handle,
207 uint32_t domid);
209 /**
210 * This function will shutdown a domain. This is intended for use in
211 * fully-virtualized domains where this operation is analogous to the
212 * sched_op operations in a paravirtualized domain. The caller is
213 * expected to give the reason for the shutdown.
214 *
215 * @parm xc_handle a handle to an open hypervisor interface
216 * @parm domid the domain id to destroy
217 * @parm reason is the reason (SHUTDOWN_xxx) for the shutdown
218 * @return 0 on success, -1 on failure
219 */
220 int xc_domain_shutdown(int xc_handle,
221 uint32_t domid,
222 int reason);
224 int xc_vcpu_setaffinity(int xc_handle,
225 uint32_t domid,
226 int vcpu,
227 cpumap_t cpumap);
229 /**
230 * This function will return information about one or more domains. It is
231 * designed to iterate over the list of domains. If a single domain is
232 * requested, this function will return the next domain in the list - if
233 * one exists. It is, therefore, important in this case to make sure the
234 * domain requested was the one returned.
235 *
236 * @parm xc_handle a handle to an open hypervisor interface
237 * @parm first_domid the first domain to enumerate information from. Domains
238 * are currently enumerate in order of creation.
239 * @parm max_doms the number of elements in info
240 * @parm info an array of max_doms size that will contain the information for
241 * the enumerated domains.
242 * @return the number of domains enumerated or -1 on error
243 */
244 int xc_domain_getinfo(int xc_handle,
245 uint32_t first_domid,
246 unsigned int max_doms,
247 xc_dominfo_t *info);
250 /**
251 * This function will set the execution context for the specified vcpu.
252 *
253 * @parm xc_handle a handle to an open hypervisor interface
254 * @parm domid the domain to set the vcpu context for
255 * @parm vcpu the vcpu number for the context
256 * @parm ctxt pointer to the the cpu context with the values to set
257 * @return the number of domains enumerated or -1 on error
258 */
259 int xc_vcpu_setcontext(int xc_handle,
260 uint32_t domid,
261 uint32_t vcpu,
262 vcpu_guest_context_t *ctxt);
263 /**
264 * This function will return information about one or more domains, using a
265 * single hypercall. The domain information will be stored into the supplied
266 * array of xc_domaininfo_t structures.
267 *
268 * @parm xc_handle a handle to an open hypervisor interface
269 * @parm first_domain the first domain to enumerate information from.
270 * Domains are currently enumerate in order of creation.
271 * @parm max_domains the number of elements in info
272 * @parm info an array of max_doms size that will contain the information for
273 * the enumerated domains.
274 * @return the number of domains enumerated or -1 on error
275 */
276 int xc_domain_getinfolist(int xc_handle,
277 uint32_t first_domain,
278 unsigned int max_domains,
279 xc_domaininfo_t *info);
281 /**
282 * This function returns information about the execution context of a
283 * particular vcpu of a domain.
284 *
285 * @parm xc_handle a handle to an open hypervisor interface
286 * @parm domid the domain to get information from
287 * @parm vcpu the vcpu number
288 * @parm ctxt a pointer to a structure to store the execution context of the
289 * domain
290 * @return 0 on success, -1 on failure
291 */
292 int xc_vcpu_getcontext(int xc_handle,
293 uint32_t domid,
294 uint32_t vcpu,
295 vcpu_guest_context_t *ctxt);
297 typedef dom0_getvcpuinfo_t xc_vcpuinfo_t;
298 int xc_vcpu_getinfo(int xc_handle,
299 uint32_t domid,
300 uint32_t vcpu,
301 xc_vcpuinfo_t *info);
303 int xc_domain_setcpuweight(int xc_handle,
304 uint32_t domid,
305 float weight);
306 long long xc_domain_get_cpu_usage(int xc_handle,
307 domid_t domid,
308 int vcpu);
310 int xc_domain_sethandle(int xc_handle, uint32_t domid,
311 xen_domain_handle_t handle);
313 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
314 int xc_shadow_control(int xc_handle,
315 uint32_t domid,
316 unsigned int sop,
317 unsigned long *dirty_bitmap,
318 unsigned long pages,
319 xc_shadow_control_stats_t *stats);
321 int xc_bvtsched_global_set(int xc_handle,
322 unsigned long ctx_allow);
324 int xc_bvtsched_domain_set(int xc_handle,
325 uint32_t domid,
326 uint32_t mcuadv,
327 int warpback,
328 int32_t warpvalue,
329 long long warpl,
330 long long warpu);
332 int xc_bvtsched_global_get(int xc_handle,
333 unsigned long *ctx_allow);
335 int xc_bvtsched_domain_get(int xc_handle,
336 uint32_t domid,
337 uint32_t *mcuadv,
338 int *warpback,
339 int32_t *warpvalue,
340 long long *warpl,
341 long long *warpu);
343 int xc_sedf_domain_set(int xc_handle,
344 uint32_t domid,
345 uint64_t period, uint64_t slice,
346 uint64_t latency, uint16_t extratime,
347 uint16_t weight);
349 int xc_sedf_domain_get(int xc_handle,
350 uint32_t domid,
351 uint64_t* period, uint64_t *slice,
352 uint64_t *latency, uint16_t *extratime,
353 uint16_t *weight);
355 typedef evtchn_status_t xc_evtchn_status_t;
357 /*
358 * EVENT CHANNEL FUNCTIONS
359 */
361 /**
362 * This function allocates an unbound port. Ports are named endpoints used for
363 * interdomain communication. This function is most useful in opening a
364 * well-known port within a domain to receive events on.
365 *
366 * @parm xc_handle a handle to an open hypervisor interface
367 * @parm dom the ID of the local domain (the 'allocatee')
368 * @parm remote_dom the ID of the domain who will later bind
369 * @return allocated port (in @dom) on success, -1 on failure
370 */
371 int xc_evtchn_alloc_unbound(int xc_handle,
372 uint32_t dom,
373 uint32_t remote_dom);
375 int xc_evtchn_status(int xc_handle,
376 uint32_t dom, /* may be DOMID_SELF */
377 evtchn_port_t port,
378 xc_evtchn_status_t *status);
380 int xc_physdev_pci_access_modify(int xc_handle,
381 uint32_t domid,
382 int bus,
383 int dev,
384 int func,
385 int enable);
387 int xc_readconsolering(int xc_handle,
388 char **pbuffer,
389 unsigned int *pnr_chars,
390 int clear);
392 typedef dom0_physinfo_t xc_physinfo_t;
393 int xc_physinfo(int xc_handle,
394 xc_physinfo_t *info);
396 int xc_sched_id(int xc_handle,
397 int *sched_id);
399 int xc_domain_setmaxmem(int xc_handle,
400 uint32_t domid,
401 unsigned int max_memkb);
403 int xc_domain_memory_increase_reservation(int xc_handle,
404 uint32_t domid,
405 unsigned long nr_extents,
406 unsigned int extent_order,
407 unsigned int address_bits,
408 unsigned long *extent_start);
410 int xc_domain_memory_decrease_reservation(int xc_handle,
411 uint32_t domid,
412 unsigned long nr_extents,
413 unsigned int extent_order,
414 unsigned long *extent_start);
416 int xc_domain_memory_populate_physmap(int xc_handle,
417 uint32_t domid,
418 unsigned long nr_extents,
419 unsigned int extent_order,
420 unsigned int address_bits,
421 unsigned long *extent_start);
423 int xc_domain_translate_gpfn_list(int xc_handle,
424 uint32_t domid,
425 unsigned long nr_gpfns,
426 unsigned long *gpfn_list,
427 unsigned long *mfn_list);
429 int xc_domain_ioport_permission(int xc_handle,
430 uint32_t domid,
431 uint32_t first_port,
432 uint32_t nr_ports,
433 uint32_t allow_access);
435 int xc_domain_irq_permission(int xc_handle,
436 uint32_t domid,
437 uint8_t pirq,
438 uint8_t allow_access);
440 int xc_domain_iomem_permission(int xc_handle,
441 uint32_t domid,
442 unsigned long first_mfn,
443 unsigned long nr_mfns,
444 uint8_t allow_access);
446 unsigned long xc_make_page_below_4G(int xc_handle, uint32_t domid,
447 unsigned long mfn);
449 typedef dom0_perfc_desc_t xc_perfc_desc_t;
450 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc array. */
451 int xc_perfc_control(int xc_handle,
452 uint32_t op,
453 xc_perfc_desc_t *desc);
455 /* read/write msr */
456 long long xc_msr_read(int xc_handle, int cpu_mask, int msr);
457 int xc_msr_write(int xc_handle, int cpu_mask, int msr, unsigned int low,
458 unsigned int high);
460 /**
461 * Memory maps a range within one domain to a local address range. Mappings
462 * should be unmapped with munmap and should follow the same rules as mmap
463 * regarding page alignment. Returns NULL on failure.
464 *
465 * In Linux, the ring queue for the control channel is accessible by mapping
466 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
467 * stored there is of type control_if_t.
468 *
469 * @parm xc_handle a handle on an open hypervisor interface
470 * @parm dom the domain to map memory from
471 * @parm size the amount of memory to map (in multiples of page size)
472 * @parm prot same flag as in mmap().
473 * @parm mfn the frame address to map.
474 */
475 void *xc_map_foreign_range(int xc_handle, uint32_t dom,
476 int size, int prot,
477 unsigned long mfn );
479 void *xc_map_foreign_batch(int xc_handle, uint32_t dom, int prot,
480 unsigned long *arr, int num );
482 /**
483 * Translates a virtual address in the context of a given domain and
484 * vcpu returning the machine page frame number of the associated
485 * page.
486 *
487 * @parm xc_handle a handle on an open hypervisor interface
488 * @parm dom the domain to perform the translation in
489 * @parm vcpu the vcpu to perform the translation on
490 * @parm virt the virtual address to translate
491 */
492 unsigned long xc_translate_foreign_address(int xc_handle, uint32_t dom,
493 int vcpu, unsigned long long virt);
495 int xc_get_pfn_list(int xc_handle, uint32_t domid, unsigned long *pfn_buf,
496 unsigned long max_pfns);
498 int xc_ia64_get_pfn_list(int xc_handle, uint32_t domid,
499 unsigned long *pfn_buf,
500 unsigned int start_page, unsigned int nr_pages);
502 int xc_copy_to_domain_page(int xc_handle, uint32_t domid,
503 unsigned long dst_pfn, const char *src_page);
505 int xc_clear_domain_page(int xc_handle, uint32_t domid,
506 unsigned long dst_pfn);
508 int xc_ia64_copy_to_domain_pages(int xc_handle, uint32_t domid,
509 void* src_page, unsigned long dst_pfn, int nr_pages);
511 long xc_get_max_pages(int xc_handle, uint32_t domid);
513 int xc_mmuext_op(int xc_handle, struct mmuext_op *op, unsigned int nr_ops,
514 domid_t dom);
516 int xc_memory_op(int xc_handle, int cmd, void *arg);
518 int xc_get_pfn_type_batch(int xc_handle, uint32_t dom,
519 int num, unsigned long *arr);
522 /* Get current total pages allocated to a domain. */
523 long xc_get_tot_pages(int xc_handle, uint32_t domid);
526 /*
527 * Trace Buffer Operations
528 */
530 /**
531 * This function enables or disables tracing. Trace buffer memory must
532 * be already allocated by setting the size to a non-zero value, otherwise
533 * tracing cannot be enabled.
534 *
535 * @parm xc_handle a handle to an open hypervisor interface
536 * @parm enable the desired action, 1 for enable, 0 for disable
537 * @return 0 on success, -1 on failure.
538 */
539 int xc_tbuf_enable(int xc_handle, int enable);
541 /**
542 * This function sets the size of the trace buffers. Setting the size
543 * is currently a one-shot operation that may be performed either at boot
544 * time or via this interface, not both. The buffer size must be set before
545 * enabling tracing.
546 *
547 * @parm xc_handle a handle to an open hypervisor interface
548 * @parm size the size in pages per cpu for the trace buffers
549 * @return 0 on success, -1 on failure.
550 */
551 int xc_tbuf_set_size(int xc_handle, uint32_t size);
553 /**
554 * This function retrieves the current size of the trace buffers.
555 * Note that the size returned is in terms of bytes, not pages.
557 * @parm xc_handle a handle to an open hypervisor interface
558 * @parm size will contain the size in bytes for the trace buffers
559 * @return 0 on success, -1 on failure.
560 */
561 int xc_tbuf_get_size(int xc_handle, uint32_t *size);
564 /* Execute a privileged dom0 operation. */
565 int xc_dom0_op(int xc_handle, dom0_op_t *op);
567 int xc_version(int xc_handle, int cmd, void *arg);
569 /*
570 * MMU updates.
571 */
572 #define MAX_MMU_UPDATES 1024
573 struct xc_mmu {
574 mmu_update_t updates[MAX_MMU_UPDATES];
575 int idx;
576 domid_t subject;
577 };
578 typedef struct xc_mmu xc_mmu_t;
579 xc_mmu_t *xc_init_mmu_updates(int xc_handle, domid_t dom);
580 int xc_add_mmu_update(int xc_handle, xc_mmu_t *mmu,
581 unsigned long long ptr, unsigned long long val);
582 int xc_finish_mmu_updates(int xc_handle, xc_mmu_t *mmu);
584 #endif