debuggers.hg

view tools/libxc/xenctrl.h @ 10991:7924b6bd728a

Change DOM0_PERFCCONTROL: remove array limit.

Descriptors and values are passed by two distinct buffers.

Signed-off-by: Tristan Gingold <tristan.gingold@bull.net>
author kaf24@firebug.cl.cam.ac.uk
date Mon Aug 07 15:53:06 2006 +0100 (2006-08-07)
parents f7b43e5c42b9
children 2afc3f16ae6e
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 #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 dom0_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 cpumap_t cpumap);
236 /**
237 * This function will return information about one or more domains. It is
238 * designed to iterate over the list of domains. If a single domain is
239 * requested, this function will return the next domain in the list - if
240 * one exists. It is, therefore, important in this case to make sure the
241 * domain requested was the one returned.
242 *
243 * @parm xc_handle a handle to an open hypervisor interface
244 * @parm first_domid the first domain to enumerate information from. Domains
245 * are currently enumerate in order of creation.
246 * @parm max_doms the number of elements in info
247 * @parm info an array of max_doms size that will contain the information for
248 * the enumerated domains.
249 * @return the number of domains enumerated or -1 on error
250 */
251 int xc_domain_getinfo(int xc_handle,
252 uint32_t first_domid,
253 unsigned int max_doms,
254 xc_dominfo_t *info);
257 /**
258 * This function will set the execution context for the specified vcpu.
259 *
260 * @parm xc_handle a handle to an open hypervisor interface
261 * @parm domid the domain to set the vcpu context for
262 * @parm vcpu the vcpu number for the context
263 * @parm ctxt pointer to the the cpu context with the values to set
264 * @return the number of domains enumerated or -1 on error
265 */
266 int xc_vcpu_setcontext(int xc_handle,
267 uint32_t domid,
268 uint32_t vcpu,
269 vcpu_guest_context_t *ctxt);
270 /**
271 * This function will return information about one or more domains, using a
272 * single hypercall. The domain information will be stored into the supplied
273 * array of xc_domaininfo_t structures.
274 *
275 * @parm xc_handle a handle to an open hypervisor interface
276 * @parm first_domain the first domain to enumerate information from.
277 * Domains are currently enumerate in order of creation.
278 * @parm max_domains the number of elements in info
279 * @parm info an array of max_doms size that will contain the information for
280 * the enumerated domains.
281 * @return the number of domains enumerated or -1 on error
282 */
283 int xc_domain_getinfolist(int xc_handle,
284 uint32_t first_domain,
285 unsigned int max_domains,
286 xc_domaininfo_t *info);
288 /**
289 * This function returns information about the execution context of a
290 * particular vcpu of a domain.
291 *
292 * @parm xc_handle a handle to an open hypervisor interface
293 * @parm domid the domain to get information from
294 * @parm vcpu the vcpu number
295 * @parm ctxt a pointer to a structure to store the execution context of the
296 * domain
297 * @return 0 on success, -1 on failure
298 */
299 int xc_vcpu_getcontext(int xc_handle,
300 uint32_t domid,
301 uint32_t vcpu,
302 vcpu_guest_context_t *ctxt);
304 typedef dom0_getvcpuinfo_t xc_vcpuinfo_t;
305 int xc_vcpu_getinfo(int xc_handle,
306 uint32_t domid,
307 uint32_t vcpu,
308 xc_vcpuinfo_t *info);
310 int xc_domain_setcpuweight(int xc_handle,
311 uint32_t domid,
312 float weight);
313 long long xc_domain_get_cpu_usage(int xc_handle,
314 domid_t domid,
315 int vcpu);
317 int xc_domain_sethandle(int xc_handle, uint32_t domid,
318 xen_domain_handle_t handle);
320 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
321 int xc_shadow_control(int xc_handle,
322 uint32_t domid,
323 unsigned int sop,
324 unsigned long *dirty_bitmap,
325 unsigned long pages,
326 xc_shadow_control_stats_t *stats);
328 int xc_bvtsched_global_set(int xc_handle,
329 unsigned long ctx_allow);
331 int xc_bvtsched_domain_set(int xc_handle,
332 uint32_t domid,
333 uint32_t mcuadv,
334 int warpback,
335 int32_t warpvalue,
336 long long warpl,
337 long long warpu);
339 int xc_bvtsched_global_get(int xc_handle,
340 unsigned long *ctx_allow);
342 int xc_bvtsched_domain_get(int xc_handle,
343 uint32_t domid,
344 uint32_t *mcuadv,
345 int *warpback,
346 int32_t *warpvalue,
347 long long *warpl,
348 long long *warpu);
350 int xc_sedf_domain_set(int xc_handle,
351 uint32_t domid,
352 uint64_t period, uint64_t slice,
353 uint64_t latency, uint16_t extratime,
354 uint16_t weight);
356 int xc_sedf_domain_get(int xc_handle,
357 uint32_t domid,
358 uint64_t* period, uint64_t *slice,
359 uint64_t *latency, uint16_t *extratime,
360 uint16_t *weight);
362 int xc_sched_credit_domain_set(int xc_handle,
363 uint32_t domid,
364 struct sched_credit_adjdom *sdom);
366 int xc_sched_credit_domain_get(int xc_handle,
367 uint32_t domid,
368 struct sched_credit_adjdom *sdom);
370 typedef evtchn_status_t xc_evtchn_status_t;
372 /*
373 * EVENT CHANNEL FUNCTIONS
374 */
376 /**
377 * This function allocates an unbound port. Ports are named endpoints used for
378 * interdomain communication. This function is most useful in opening a
379 * well-known port within a domain to receive events on.
380 *
381 * @parm xc_handle a handle to an open hypervisor interface
382 * @parm dom the ID of the local domain (the 'allocatee')
383 * @parm remote_dom the ID of the domain who will later bind
384 * @return allocated port (in @dom) on success, -1 on failure
385 */
386 int xc_evtchn_alloc_unbound(int xc_handle,
387 uint32_t dom,
388 uint32_t remote_dom);
390 int xc_evtchn_status(int xc_handle,
391 uint32_t dom, /* may be DOMID_SELF */
392 evtchn_port_t port,
393 xc_evtchn_status_t *status);
395 int xc_physdev_pci_access_modify(int xc_handle,
396 uint32_t domid,
397 int bus,
398 int dev,
399 int func,
400 int enable);
402 int xc_readconsolering(int xc_handle,
403 char **pbuffer,
404 unsigned int *pnr_chars,
405 int clear);
407 typedef dom0_physinfo_t xc_physinfo_t;
408 int xc_physinfo(int xc_handle,
409 xc_physinfo_t *info);
411 int xc_sched_id(int xc_handle,
412 int *sched_id);
414 int xc_domain_setmaxmem(int xc_handle,
415 uint32_t domid,
416 unsigned int max_memkb);
418 int xc_domain_set_time_offset(int xc_handle,
419 uint32_t domid,
420 int32_t time_offset_seconds);
422 int xc_domain_memory_increase_reservation(int xc_handle,
423 uint32_t domid,
424 unsigned long nr_extents,
425 unsigned int extent_order,
426 unsigned int address_bits,
427 xen_pfn_t *extent_start);
429 int xc_domain_memory_decrease_reservation(int xc_handle,
430 uint32_t domid,
431 unsigned long nr_extents,
432 unsigned int extent_order,
433 xen_pfn_t *extent_start);
435 int xc_domain_memory_populate_physmap(int xc_handle,
436 uint32_t domid,
437 unsigned long nr_extents,
438 unsigned int extent_order,
439 unsigned int address_bits,
440 xen_pfn_t *extent_start);
442 int xc_domain_translate_gpfn_list(int xc_handle,
443 uint32_t domid,
444 unsigned long nr_gpfns,
445 xen_pfn_t *gpfn_list,
446 xen_pfn_t *mfn_list);
448 int xc_domain_ioport_permission(int xc_handle,
449 uint32_t domid,
450 uint32_t first_port,
451 uint32_t nr_ports,
452 uint32_t allow_access);
454 int xc_domain_irq_permission(int xc_handle,
455 uint32_t domid,
456 uint8_t pirq,
457 uint8_t allow_access);
459 int xc_domain_iomem_permission(int xc_handle,
460 uint32_t domid,
461 unsigned long first_mfn,
462 unsigned long nr_mfns,
463 uint8_t allow_access);
465 unsigned long xc_make_page_below_4G(int xc_handle, uint32_t domid,
466 unsigned long mfn);
468 typedef dom0_perfc_desc_t xc_perfc_desc_t;
469 typedef dom0_perfc_val_t xc_perfc_val_t;
470 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc and @val
471 arrays. */
472 int xc_perfc_control(int xc_handle,
473 uint32_t op,
474 xc_perfc_desc_t *desc,
475 xc_perfc_val_t *val,
476 int *nbr_desc,
477 int *nbr_val);
479 /* read/write msr */
480 long long xc_msr_read(int xc_handle, int cpu_mask, int msr);
481 int xc_msr_write(int xc_handle, int cpu_mask, int msr, unsigned int low,
482 unsigned int high);
484 /**
485 * Memory maps a range within one domain to a local address range. Mappings
486 * should be unmapped with munmap and should follow the same rules as mmap
487 * regarding page alignment. Returns NULL on failure.
488 *
489 * In Linux, the ring queue for the control channel is accessible by mapping
490 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
491 * stored there is of type control_if_t.
492 *
493 * @parm xc_handle a handle on an open hypervisor interface
494 * @parm dom the domain to map memory from
495 * @parm size the amount of memory to map (in multiples of page size)
496 * @parm prot same flag as in mmap().
497 * @parm mfn the frame address to map.
498 */
499 void *xc_map_foreign_range(int xc_handle, uint32_t dom,
500 int size, int prot,
501 unsigned long mfn );
503 void *xc_map_foreign_batch(int xc_handle, uint32_t dom, int prot,
504 xen_pfn_t *arr, int num );
506 /**
507 * Translates a virtual address in the context of a given domain and
508 * vcpu returning the machine page frame number of the associated
509 * page.
510 *
511 * @parm xc_handle a handle on an open hypervisor interface
512 * @parm dom the domain to perform the translation in
513 * @parm vcpu the vcpu to perform the translation on
514 * @parm virt the virtual address to translate
515 */
516 unsigned long xc_translate_foreign_address(int xc_handle, uint32_t dom,
517 int vcpu, unsigned long long virt);
519 int xc_get_pfn_list(int xc_handle, uint32_t domid, xen_pfn_t *pfn_buf,
520 unsigned long max_pfns);
522 int xc_ia64_get_pfn_list(int xc_handle, uint32_t domid,
523 xen_pfn_t *pfn_buf,
524 unsigned int start_page, unsigned int nr_pages);
526 int xc_copy_to_domain_page(int xc_handle, uint32_t domid,
527 unsigned long dst_pfn, const char *src_page);
529 int xc_clear_domain_page(int xc_handle, uint32_t domid,
530 unsigned long dst_pfn);
532 long xc_get_max_pages(int xc_handle, uint32_t domid);
534 int xc_mmuext_op(int xc_handle, struct mmuext_op *op, unsigned int nr_ops,
535 domid_t dom);
537 int xc_memory_op(int xc_handle, int cmd, void *arg);
539 int xc_get_pfn_type_batch(int xc_handle, uint32_t dom,
540 int num, unsigned long *arr);
543 /* Get current total pages allocated to a domain. */
544 long xc_get_tot_pages(int xc_handle, uint32_t domid);
547 /*
548 * Trace Buffer Operations
549 */
551 /**
552 * xc_tbuf_enable - enable tracing buffers
553 *
554 * @parm xc_handle a handle to an open hypervisor interface
555 * @parm cnt size of tracing buffers to create (in pages)
556 * @parm mfn location to store mfn of the trace buffers to
557 * @parm size location to store the size (in bytes) of a trace buffer to
558 *
559 * Gets the machine address of the trace pointer area and the size of the
560 * per CPU buffers.
561 */
562 int xc_tbuf_enable(int xc_handle, size_t cnt, unsigned long *mfn,
563 unsigned long *size);
565 /*
566 * Disable tracing buffers.
567 */
568 int xc_tbuf_disable(int xc_handle);
570 /**
571 * This function sets the size of the trace buffers. Setting the size
572 * is currently a one-shot operation that may be performed either at boot
573 * time or via this interface, not both. The buffer size must be set before
574 * enabling tracing.
575 *
576 * @parm xc_handle a handle to an open hypervisor interface
577 * @parm size the size in pages per cpu for the trace buffers
578 * @return 0 on success, -1 on failure.
579 */
580 int xc_tbuf_set_size(int xc_handle, unsigned long size);
582 /**
583 * This function retrieves the current size of the trace buffers.
584 * Note that the size returned is in terms of bytes, not pages.
586 * @parm xc_handle a handle to an open hypervisor interface
587 * @parm size will contain the size in bytes for the trace buffers
588 * @return 0 on success, -1 on failure.
589 */
590 int xc_tbuf_get_size(int xc_handle, unsigned long *size);
592 int xc_tbuf_set_cpu_mask(int xc_handle, uint32_t mask);
594 int xc_tbuf_set_evt_mask(int xc_handle, uint32_t mask);
596 /* Execute a privileged dom0 operation. */
597 int xc_dom0_op(int xc_handle, dom0_op_t *op);
599 int xc_version(int xc_handle, int cmd, void *arg);
601 /*
602 * MMU updates.
603 */
604 #define MAX_MMU_UPDATES 1024
605 struct xc_mmu {
606 mmu_update_t updates[MAX_MMU_UPDATES];
607 int idx;
608 domid_t subject;
609 };
610 typedef struct xc_mmu xc_mmu_t;
611 xc_mmu_t *xc_init_mmu_updates(int xc_handle, domid_t dom);
612 int xc_add_mmu_update(int xc_handle, xc_mmu_t *mmu,
613 unsigned long long ptr, unsigned long long val);
614 int xc_finish_mmu_updates(int xc_handle, xc_mmu_t *mmu);
616 int xc_acm_op(int xc_handle, int cmd, void *arg, size_t arg_size);
618 /*
619 * Return a handle to the event channel driver, or -1 on failure, in which case
620 * errno will be set appropriately.
621 */
622 int xc_evtchn_open(void);
624 /*
625 * Close a handle previously allocated with xc_evtchn_open().
626 */
627 int xc_evtchn_close(int xce_handle);
629 /*
630 * Return an fd that can be select()ed on for further calls to
631 * xc_evtchn_pending().
632 */
633 int xc_evtchn_fd(int xce_handle);
635 /*
636 * Notify the given event channel. Returns -1 on failure, in which case
637 * errno will be set appropriately.
638 */
639 int xc_evtchn_notify(int xce_handle, evtchn_port_t port);
641 /*
642 * Returns a new event port bound to the remote port for the given domain ID,
643 * or -1 on failure, in which case errno will be set appropriately.
644 */
645 evtchn_port_t xc_evtchn_bind_interdomain(int xce_handle, int domid,
646 evtchn_port_t remote_port);
648 /*
649 * Unbind the given event channel. Returns -1 on failure, in which case errno
650 * will be set appropriately.
651 */
652 int xc_evtchn_unbind(int xce_handle, evtchn_port_t port);
654 /*
655 * Bind an event channel to the given VIRQ. Returns the event channel bound to
656 * the VIRQ, or -1 on failure, in which case errno will be set appropriately.
657 */
658 evtchn_port_t xc_evtchn_bind_virq(int xce_handle, unsigned int virq);
660 /*
661 * Return the next event channel to become pending, or -1 on failure, in which
662 * case errno will be set appropriately.
663 */
664 evtchn_port_t xc_evtchn_pending(int xce_handle);
666 /*
667 * Unmask the given event channel. Returns -1 on failure, in which case errno
668 * will be set appropriately.
669 */
670 int xc_evtchn_unmask(int xce_handle, evtchn_port_t port);
672 #endif