direct-io.hg

view tools/libxc/xenctrl.h @ 10474:12aaf4a2486b

[XEN] localtime support for paravirtualized guests

It is quite minimal
in its approach, satisfying the purposes of the paravirtualized
NetWare operating system as well as any others that expect the time
base to be provided in localtime.

Signed-off-by: Bruce Rogers <brogers@novell.com>
author kaf24@firebug.cl.cam.ac.uk
date Wed Jun 21 17:09:14 2006 +0100 (2006-06-21)
parents 7fba181c8531
children 80055bb36dc7 dab0a5650e6d
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/dom0_ops.h>
17 #include <xen/version.h>
18 #include <xen/event_channel.h>
19 #include <xen/sched.h>
20 #include <xen/sched_ctl.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 #else
51 #error "Define barriers"
52 #endif
54 /*
55 * INITIALIZATION FUNCTIONS
56 */
58 /**
59 * This function opens a handle to the hypervisor interface. This function can
60 * be called multiple times within a single process. Multiple processes can
61 * have an open hypervisor interface at the same time.
62 *
63 * Each call to this function should have a corresponding call to
64 * xc_interface_close().
65 *
66 * This function can fail if the caller does not have superuser permission or
67 * if a Xen-enabled kernel is not currently running.
68 *
69 * @return a handle to the hypervisor interface or -1 on failure
70 */
71 int xc_interface_open(void);
73 /**
74 * This function closes an open hypervisor interface.
75 *
76 * This function can fail if the handle does not represent an open interface or
77 * if there were problems closing the interface.
78 *
79 * @parm xc_handle a handle to an open hypervisor interface
80 * @return 0 on success, -1 otherwise.
81 */
82 int xc_interface_close(int xc_handle);
84 /*
85 * DOMAIN DEBUGGING FUNCTIONS
86 */
88 typedef struct xc_core_header {
89 unsigned int xch_magic;
90 unsigned int xch_nr_vcpus;
91 unsigned int xch_nr_pages;
92 unsigned int xch_ctxt_offset;
93 unsigned int xch_index_offset;
94 unsigned int xch_pages_offset;
95 } xc_core_header_t;
97 #define XC_CORE_MAGIC 0xF00FEBED
99 long xc_ptrace_core(
100 int xc_handle,
101 enum __ptrace_request request,
102 uint32_t domid,
103 long addr,
104 long data,
105 vcpu_guest_context_t *ctxt);
106 void * map_domain_va_core(
107 unsigned long domfd,
108 int cpu,
109 void *guest_va,
110 vcpu_guest_context_t *ctxt);
111 int xc_waitdomain_core(
112 int xc_handle,
113 int domain,
114 int *status,
115 int options,
116 vcpu_guest_context_t *ctxt);
118 /*
119 * DOMAIN MANAGEMENT FUNCTIONS
120 */
122 typedef struct {
123 uint32_t domid;
124 uint32_t ssidref;
125 unsigned int dying:1, crashed:1, shutdown:1,
126 paused:1, blocked:1, running:1;
127 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
128 unsigned long nr_pages;
129 unsigned long shared_info_frame;
130 uint64_t cpu_time;
131 unsigned long max_memkb;
132 unsigned int nr_online_vcpus;
133 unsigned int max_vcpu_id;
134 xen_domain_handle_t handle;
135 } xc_dominfo_t;
137 typedef dom0_getdomaininfo_t xc_domaininfo_t;
138 int xc_domain_create(int xc_handle,
139 uint32_t ssidref,
140 xen_domain_handle_t handle,
141 uint32_t *pdomid);
144 /* Functions to produce a dump of a given domain
145 * xc_domain_dumpcore - produces a dump to a specified file
146 * xc_domain_dumpcore_via_callback - produces a dump, using a specified
147 * callback function
148 */
149 int xc_domain_dumpcore(int xc_handle,
150 uint32_t domid,
151 const char *corename);
153 /* Define the callback function type for xc_domain_dumpcore_via_callback.
154 *
155 * This function is called by the coredump code for every "write",
156 * and passes an opaque object for the use of the function and
157 * created by the caller of xc_domain_dumpcore_via_callback.
158 */
159 typedef int (dumpcore_rtn_t)(void *arg, char *buffer, unsigned int length);
161 int xc_domain_dumpcore_via_callback(int xc_handle,
162 uint32_t domid,
163 void *arg,
164 dumpcore_rtn_t dump_rtn);
166 /*
167 * This function sets the maximum number of vcpus that a domain may create.
168 *
169 * @parm xc_handle a handle to an open hypervisor interface.
170 * @parm domid the domain id in which vcpus are to be created.
171 * @parm max the maximum number of vcpus that the domain may create.
172 * @return 0 on success, -1 on failure.
173 */
174 int xc_domain_max_vcpus(int xc_handle,
175 uint32_t domid,
176 unsigned int max);
178 /**
179 * This function pauses a domain. A paused domain still exists in memory
180 * however it does not receive any timeslices from the hypervisor.
181 *
182 * @parm xc_handle a handle to an open hypervisor interface
183 * @parm domid the domain id to pause
184 * @return 0 on success, -1 on failure.
185 */
186 int xc_domain_pause(int xc_handle,
187 uint32_t domid);
188 /**
189 * This function unpauses a domain. The domain should have been previously
190 * paused.
191 *
192 * @parm xc_handle a handle to an open hypervisor interface
193 * @parm domid the domain id to unpause
194 * return 0 on success, -1 on failure
195 */
196 int xc_domain_unpause(int xc_handle,
197 uint32_t domid);
199 /**
200 * This function will destroy a domain. Destroying a domain removes the domain
201 * completely from memory. This function should be called after sending the
202 * domain a SHUTDOWN control message to free up the domain resources.
203 *
204 * @parm xc_handle a handle to an open hypervisor interface
205 * @parm domid the domain id to destroy
206 * @return 0 on success, -1 on failure
207 */
208 int xc_domain_destroy(int xc_handle,
209 uint32_t domid);
211 /**
212 * This function will shutdown a domain. This is intended for use in
213 * fully-virtualized domains where this operation is analogous to the
214 * sched_op operations in a paravirtualized domain. The caller is
215 * expected to give the reason for the shutdown.
216 *
217 * @parm xc_handle a handle to an open hypervisor interface
218 * @parm domid the domain id to destroy
219 * @parm reason is the reason (SHUTDOWN_xxx) for the shutdown
220 * @return 0 on success, -1 on failure
221 */
222 int xc_domain_shutdown(int xc_handle,
223 uint32_t domid,
224 int reason);
226 int xc_vcpu_setaffinity(int xc_handle,
227 uint32_t domid,
228 int vcpu,
229 cpumap_t cpumap);
231 /**
232 * This function will return information about one or more domains. It is
233 * designed to iterate over the list of domains. If a single domain is
234 * requested, this function will return the next domain in the list - if
235 * one exists. It is, therefore, important in this case to make sure the
236 * domain requested was the one returned.
237 *
238 * @parm xc_handle a handle to an open hypervisor interface
239 * @parm first_domid the first domain to enumerate information from. Domains
240 * are currently enumerate in order of creation.
241 * @parm max_doms the number of elements in info
242 * @parm info an array of max_doms size that will contain the information for
243 * the enumerated domains.
244 * @return the number of domains enumerated or -1 on error
245 */
246 int xc_domain_getinfo(int xc_handle,
247 uint32_t first_domid,
248 unsigned int max_doms,
249 xc_dominfo_t *info);
252 /**
253 * This function will set the execution context for the specified vcpu.
254 *
255 * @parm xc_handle a handle to an open hypervisor interface
256 * @parm domid the domain to set the vcpu context for
257 * @parm vcpu the vcpu number for the context
258 * @parm ctxt pointer to the the cpu context with the values to set
259 * @return the number of domains enumerated or -1 on error
260 */
261 int xc_vcpu_setcontext(int xc_handle,
262 uint32_t domid,
263 uint32_t vcpu,
264 vcpu_guest_context_t *ctxt);
265 /**
266 * This function will return information about one or more domains, using a
267 * single hypercall. The domain information will be stored into the supplied
268 * array of xc_domaininfo_t structures.
269 *
270 * @parm xc_handle a handle to an open hypervisor interface
271 * @parm first_domain the first domain to enumerate information from.
272 * Domains are currently enumerate in order of creation.
273 * @parm max_domains the number of elements in info
274 * @parm info an array of max_doms size that will contain the information for
275 * the enumerated domains.
276 * @return the number of domains enumerated or -1 on error
277 */
278 int xc_domain_getinfolist(int xc_handle,
279 uint32_t first_domain,
280 unsigned int max_domains,
281 xc_domaininfo_t *info);
283 /**
284 * This function returns information about the execution context of a
285 * particular vcpu of a domain.
286 *
287 * @parm xc_handle a handle to an open hypervisor interface
288 * @parm domid the domain to get information from
289 * @parm vcpu the vcpu number
290 * @parm ctxt a pointer to a structure to store the execution context of the
291 * domain
292 * @return 0 on success, -1 on failure
293 */
294 int xc_vcpu_getcontext(int xc_handle,
295 uint32_t domid,
296 uint32_t vcpu,
297 vcpu_guest_context_t *ctxt);
299 typedef dom0_getvcpuinfo_t xc_vcpuinfo_t;
300 int xc_vcpu_getinfo(int xc_handle,
301 uint32_t domid,
302 uint32_t vcpu,
303 xc_vcpuinfo_t *info);
305 int xc_domain_setcpuweight(int xc_handle,
306 uint32_t domid,
307 float weight);
308 long long xc_domain_get_cpu_usage(int xc_handle,
309 domid_t domid,
310 int vcpu);
312 int xc_domain_sethandle(int xc_handle, uint32_t domid,
313 xen_domain_handle_t handle);
315 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
316 int xc_shadow_control(int xc_handle,
317 uint32_t domid,
318 unsigned int sop,
319 unsigned long *dirty_bitmap,
320 unsigned long pages,
321 xc_shadow_control_stats_t *stats);
323 int xc_bvtsched_global_set(int xc_handle,
324 unsigned long ctx_allow);
326 int xc_bvtsched_domain_set(int xc_handle,
327 uint32_t domid,
328 uint32_t mcuadv,
329 int warpback,
330 int32_t warpvalue,
331 long long warpl,
332 long long warpu);
334 int xc_bvtsched_global_get(int xc_handle,
335 unsigned long *ctx_allow);
337 int xc_bvtsched_domain_get(int xc_handle,
338 uint32_t domid,
339 uint32_t *mcuadv,
340 int *warpback,
341 int32_t *warpvalue,
342 long long *warpl,
343 long long *warpu);
345 int xc_sedf_domain_set(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_sedf_domain_get(int xc_handle,
352 uint32_t domid,
353 uint64_t* period, uint64_t *slice,
354 uint64_t *latency, uint16_t *extratime,
355 uint16_t *weight);
357 int xc_sched_credit_domain_set(int xc_handle,
358 uint32_t domid,
359 struct sched_credit_adjdom *sdom);
361 int xc_sched_credit_domain_get(int xc_handle,
362 uint32_t domid,
363 struct sched_credit_adjdom *sdom);
365 typedef evtchn_status_t xc_evtchn_status_t;
367 /*
368 * EVENT CHANNEL FUNCTIONS
369 */
371 /**
372 * This function allocates an unbound port. Ports are named endpoints used for
373 * interdomain communication. This function is most useful in opening a
374 * well-known port within a domain to receive events on.
375 *
376 * @parm xc_handle a handle to an open hypervisor interface
377 * @parm dom the ID of the local domain (the 'allocatee')
378 * @parm remote_dom the ID of the domain who will later bind
379 * @return allocated port (in @dom) on success, -1 on failure
380 */
381 int xc_evtchn_alloc_unbound(int xc_handle,
382 uint32_t dom,
383 uint32_t remote_dom);
385 int xc_evtchn_status(int xc_handle,
386 uint32_t dom, /* may be DOMID_SELF */
387 evtchn_port_t port,
388 xc_evtchn_status_t *status);
390 int xc_physdev_pci_access_modify(int xc_handle,
391 uint32_t domid,
392 int bus,
393 int dev,
394 int func,
395 int enable);
397 int xc_readconsolering(int xc_handle,
398 char **pbuffer,
399 unsigned int *pnr_chars,
400 int clear);
402 typedef dom0_physinfo_t xc_physinfo_t;
403 int xc_physinfo(int xc_handle,
404 xc_physinfo_t *info);
406 int xc_sched_id(int xc_handle,
407 int *sched_id);
409 int xc_domain_setmaxmem(int xc_handle,
410 uint32_t domid,
411 unsigned int max_memkb);
413 int xc_domain_set_time_offset(int xc_handle,
414 uint32_t domid,
415 int32_t time_offset_seconds);
417 int xc_domain_memory_increase_reservation(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_memory_decrease_reservation(int xc_handle,
425 uint32_t domid,
426 unsigned long nr_extents,
427 unsigned int extent_order,
428 xen_pfn_t *extent_start);
430 int xc_domain_memory_populate_physmap(int xc_handle,
431 uint32_t domid,
432 unsigned long nr_extents,
433 unsigned int extent_order,
434 unsigned int address_bits,
435 xen_pfn_t *extent_start);
437 int xc_domain_translate_gpfn_list(int xc_handle,
438 uint32_t domid,
439 unsigned long nr_gpfns,
440 xen_pfn_t *gpfn_list,
441 xen_pfn_t *mfn_list);
443 int xc_domain_ioport_permission(int xc_handle,
444 uint32_t domid,
445 uint32_t first_port,
446 uint32_t nr_ports,
447 uint32_t allow_access);
449 int xc_domain_irq_permission(int xc_handle,
450 uint32_t domid,
451 uint8_t pirq,
452 uint8_t allow_access);
454 int xc_domain_iomem_permission(int xc_handle,
455 uint32_t domid,
456 unsigned long first_mfn,
457 unsigned long nr_mfns,
458 uint8_t allow_access);
460 unsigned long xc_make_page_below_4G(int xc_handle, uint32_t domid,
461 unsigned long mfn);
463 typedef dom0_perfc_desc_t xc_perfc_desc_t;
464 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc array. */
465 int xc_perfc_control(int xc_handle,
466 uint32_t op,
467 xc_perfc_desc_t *desc);
469 /* read/write msr */
470 long long xc_msr_read(int xc_handle, int cpu_mask, int msr);
471 int xc_msr_write(int xc_handle, int cpu_mask, int msr, unsigned int low,
472 unsigned int high);
474 /**
475 * Memory maps a range within one domain to a local address range. Mappings
476 * should be unmapped with munmap and should follow the same rules as mmap
477 * regarding page alignment. Returns NULL on failure.
478 *
479 * In Linux, the ring queue for the control channel is accessible by mapping
480 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
481 * stored there is of type control_if_t.
482 *
483 * @parm xc_handle a handle on an open hypervisor interface
484 * @parm dom the domain to map memory from
485 * @parm size the amount of memory to map (in multiples of page size)
486 * @parm prot same flag as in mmap().
487 * @parm mfn the frame address to map.
488 */
489 void *xc_map_foreign_range(int xc_handle, uint32_t dom,
490 int size, int prot,
491 unsigned long mfn );
493 void *xc_map_foreign_batch(int xc_handle, uint32_t dom, int prot,
494 xen_pfn_t *arr, int num );
496 /**
497 * Translates a virtual address in the context of a given domain and
498 * vcpu returning the machine page frame number of the associated
499 * page.
500 *
501 * @parm xc_handle a handle on an open hypervisor interface
502 * @parm dom the domain to perform the translation in
503 * @parm vcpu the vcpu to perform the translation on
504 * @parm virt the virtual address to translate
505 */
506 unsigned long xc_translate_foreign_address(int xc_handle, uint32_t dom,
507 int vcpu, unsigned long long virt);
509 int xc_get_pfn_list(int xc_handle, uint32_t domid, xen_pfn_t *pfn_buf,
510 unsigned long max_pfns);
512 int xc_ia64_get_pfn_list(int xc_handle, uint32_t domid,
513 xen_pfn_t *pfn_buf,
514 unsigned int start_page, unsigned int nr_pages);
516 int xc_copy_to_domain_page(int xc_handle, uint32_t domid,
517 unsigned long dst_pfn, const char *src_page);
519 int xc_clear_domain_page(int xc_handle, uint32_t domid,
520 unsigned long dst_pfn);
522 int xc_ia64_copy_to_domain_pages(int xc_handle, uint32_t domid,
523 void* src_page, unsigned long dst_pfn, int nr_pages);
525 long xc_get_max_pages(int xc_handle, uint32_t domid);
527 int xc_mmuext_op(int xc_handle, struct mmuext_op *op, unsigned int nr_ops,
528 domid_t dom);
530 int xc_memory_op(int xc_handle, int cmd, void *arg);
532 int xc_get_pfn_type_batch(int xc_handle, uint32_t dom,
533 int num, unsigned long *arr);
536 /* Get current total pages allocated to a domain. */
537 long xc_get_tot_pages(int xc_handle, uint32_t domid);
540 /*
541 * Trace Buffer Operations
542 */
544 /**
545 * xc_tbuf_enable - enable tracing buffers
546 *
547 * @parm xc_handle a handle to an open hypervisor interface
548 * @parm cnt size of tracing buffers to create (in pages)
549 * @parm mfn location to store mfn of the trace buffers to
550 * @parm size location to store the size (in bytes) of a trace buffer to
551 *
552 * Gets the machine address of the trace pointer area and the size of the
553 * per CPU buffers.
554 */
555 int xc_tbuf_enable(int xc_handle, size_t cnt, unsigned long *mfn,
556 unsigned long *size);
558 /*
559 * Disable tracing buffers.
560 */
561 int xc_tbuf_disable(int xc_handle);
563 /**
564 * This function sets the size of the trace buffers. Setting the size
565 * is currently a one-shot operation that may be performed either at boot
566 * time or via this interface, not both. The buffer size must be set before
567 * enabling tracing.
568 *
569 * @parm xc_handle a handle to an open hypervisor interface
570 * @parm size the size in pages per cpu for the trace buffers
571 * @return 0 on success, -1 on failure.
572 */
573 int xc_tbuf_set_size(int xc_handle, unsigned long size);
575 /**
576 * This function retrieves the current size of the trace buffers.
577 * Note that the size returned is in terms of bytes, not pages.
579 * @parm xc_handle a handle to an open hypervisor interface
580 * @parm size will contain the size in bytes for the trace buffers
581 * @return 0 on success, -1 on failure.
582 */
583 int xc_tbuf_get_size(int xc_handle, unsigned long *size);
585 int xc_tbuf_set_cpu_mask(int xc_handle, uint32_t mask);
587 int xc_tbuf_set_evt_mask(int xc_handle, uint32_t mask);
589 /* Execute a privileged dom0 operation. */
590 int xc_dom0_op(int xc_handle, dom0_op_t *op);
592 int xc_version(int xc_handle, int cmd, void *arg);
594 /*
595 * MMU updates.
596 */
597 #define MAX_MMU_UPDATES 1024
598 struct xc_mmu {
599 mmu_update_t updates[MAX_MMU_UPDATES];
600 int idx;
601 domid_t subject;
602 };
603 typedef struct xc_mmu xc_mmu_t;
604 xc_mmu_t *xc_init_mmu_updates(int xc_handle, domid_t dom);
605 int xc_add_mmu_update(int xc_handle, xc_mmu_t *mmu,
606 unsigned long long ptr, unsigned long long val);
607 int xc_finish_mmu_updates(int xc_handle, xc_mmu_t *mmu);
609 int xc_acm_op(int xc_handle, int cmd, void *arg, size_t arg_size);
611 /*
612 * Return a handle to the event channel driver, or -1 on failure, in which case
613 * errno will be set appropriately.
614 */
615 int xc_evtchn_open(void);
617 /*
618 * Close a handle previously allocated with xc_evtchn_open().
619 */
620 int xc_evtchn_close(int xce_handle);
622 /*
623 * Return an fd that can be select()ed on for further calls to
624 * xc_evtchn_pending().
625 */
626 int xc_evtchn_fd(int xce_handle);
628 /*
629 * Notify the given event channel. Returns -1 on failure, in which case
630 * errno will be set appropriately.
631 */
632 int xc_evtchn_notify(int xce_handle, evtchn_port_t port);
634 /*
635 * Returns a new event port bound to the remote port for the given domain ID,
636 * or -1 on failure, in which case errno will be set appropriately.
637 */
638 evtchn_port_t xc_evtchn_bind_interdomain(int xce_handle, int domid,
639 evtchn_port_t remote_port);
641 /*
642 * Unbind the given event channel. Returns -1 on failure, in which case errno
643 * will be set appropriately.
644 */
645 int xc_evtchn_unbind(int xce_handle, evtchn_port_t port);
647 /*
648 * Bind an event channel to the given VIRQ. Returns the event channel bound to
649 * the VIRQ, or -1 on failure, in which case errno will be set appropriately.
650 */
651 evtchn_port_t xc_evtchn_bind_virq(int xce_handle, unsigned int virq);
653 /*
654 * Return the next event channel to become pending, or -1 on failure, in which
655 * case errno will be set appropriately.
656 */
657 evtchn_port_t xc_evtchn_pending(int xce_handle);
659 /*
660 * Unmask the given event channel. Returns -1 on failure, in which case errno
661 * will be set appropriately.
662 */
663 int xc_evtchn_unmask(int xce_handle, evtchn_port_t port);
665 #endif