direct-io.hg

view tools/libxc/xenctrl.h @ 8686:c0a0f4db5ab1

Create a block of reserved PFNs in shadow translate mode guests, and
move the shared info and grant table pfns into that block. This
allows us to remove the get_gnttablist dom0 op, and simplifies the
domain creation code slightly. Having the reserved block managed by
Xen may also make it slightly easier to handle the case where the
grant table needs to be extended at run time.

Suggested-by: kaf24
Signed-off-by: Steven Smith, sos22@cam.ac.uk
author sos22@douglas.cl.cam.ac.uk
date Thu Jan 26 19:40:13 2006 +0100 (2006-01-26)
parents d8232e9f7988
children 1db05e589fa0
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;
96 long xc_ptrace_core(
97 int xc_handle,
98 enum __ptrace_request request,
99 uint32_t domid,
100 long addr,
101 long data);
103 int xc_waitdomain_core(
104 int xc_handle,
105 int domain,
106 int *status,
107 int options);
109 /*
110 * DOMAIN MANAGEMENT FUNCTIONS
111 */
113 typedef struct {
114 uint32_t domid;
115 uint32_t ssidref;
116 unsigned int dying:1, crashed:1, shutdown:1,
117 paused:1, blocked:1, running:1;
118 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
119 unsigned long nr_pages;
120 unsigned long shared_info_frame;
121 uint64_t cpu_time;
122 unsigned long max_memkb;
123 unsigned int nr_online_vcpus;
124 unsigned int max_vcpu_id;
125 xen_domain_handle_t handle;
126 } xc_dominfo_t;
128 typedef dom0_getdomaininfo_t xc_domaininfo_t;
129 int xc_domain_create(int xc_handle,
130 uint32_t ssidref,
131 xen_domain_handle_t handle,
132 uint32_t *pdomid);
135 int xc_domain_dumpcore(int xc_handle,
136 uint32_t domid,
137 const char *corename);
139 /*
140 * This function sets the maximum number of vcpus that a domain may create.
141 *
142 * @parm xc_handle a handle to an open hypervisor interface.
143 * @parm domid the domain id in which vcpus are to be created.
144 * @parm max the maximum number of vcpus that the domain may create.
145 * @return 0 on success, -1 on failure.
146 */
147 int xc_domain_max_vcpus(int xc_handle,
148 uint32_t domid,
149 unsigned int max);
151 /**
152 * This function pauses a domain. A paused domain still exists in memory
153 * however it does not receive any timeslices from the hypervisor.
154 *
155 * @parm xc_handle a handle to an open hypervisor interface
156 * @parm domid the domain id to pause
157 * @return 0 on success, -1 on failure.
158 */
159 int xc_domain_pause(int xc_handle,
160 uint32_t domid);
161 /**
162 * This function unpauses a domain. The domain should have been previously
163 * paused.
164 *
165 * @parm xc_handle a handle to an open hypervisor interface
166 * @parm domid the domain id to unpause
167 * return 0 on success, -1 on failure
168 */
169 int xc_domain_unpause(int xc_handle,
170 uint32_t domid);
172 /**
173 * This function will destroy a domain. Destroying a domain removes the domain
174 * completely from memory. This function should be called after sending the
175 * domain a SHUTDOWN control message to free up the domain resources.
176 *
177 * @parm xc_handle a handle to an open hypervisor interface
178 * @parm domid the domain id to destroy
179 * @return 0 on success, -1 on failure
180 */
181 int xc_domain_destroy(int xc_handle,
182 uint32_t domid);
184 int xc_vcpu_setaffinity(int xc_handle,
185 uint32_t domid,
186 int vcpu,
187 cpumap_t cpumap);
189 /**
190 * This function will return information about one or more domains. It is
191 * designed to iterate over the list of domains. If a single domain is
192 * requested, this function will return the next domain in the list - if
193 * one exists. It is, therefore, important in this case to make sure the
194 * domain requested was the one returned.
195 *
196 * @parm xc_handle a handle to an open hypervisor interface
197 * @parm first_domid the first domain to enumerate information from. Domains
198 * are currently enumerate in order of creation.
199 * @parm max_doms the number of elements in info
200 * @parm info an array of max_doms size that will contain the information for
201 * the enumerated domains.
202 * @return the number of domains enumerated or -1 on error
203 */
204 int xc_domain_getinfo(int xc_handle,
205 uint32_t first_domid,
206 unsigned int max_doms,
207 xc_dominfo_t *info);
210 /**
211 * This function will set the execution context for the specified vcpu.
212 *
213 * @parm xc_handle a handle to an open hypervisor interface
214 * @parm domid the domain to set the vcpu context for
215 * @parm vcpu the vcpu number for the context
216 * @parm ctxt pointer to the the cpu context with the values to set
217 * @return the number of domains enumerated or -1 on error
218 */
219 int xc_vcpu_setcontext(int xc_handle,
220 uint32_t domid,
221 uint32_t vcpu,
222 vcpu_guest_context_t *ctxt);
223 /**
224 * This function will return information about one or more domains, using a
225 * single hypercall. The domain information will be stored into the supplied
226 * array of xc_domaininfo_t structures.
227 *
228 * @parm xc_handle a handle to an open hypervisor interface
229 * @parm first_domain the first domain to enumerate information from.
230 * Domains are currently enumerate in order of creation.
231 * @parm max_domains the number of elements in info
232 * @parm info an array of max_doms size that will contain the information for
233 * the enumerated domains.
234 * @return the number of domains enumerated or -1 on error
235 */
236 int xc_domain_getinfolist(int xc_handle,
237 uint32_t first_domain,
238 unsigned int max_domains,
239 xc_domaininfo_t *info);
241 /**
242 * This function returns information about the execution context of a
243 * particular vcpu of a domain.
244 *
245 * @parm xc_handle a handle to an open hypervisor interface
246 * @parm domid the domain to get information from
247 * @parm vcpu the vcpu number
248 * @parm ctxt a pointer to a structure to store the execution context of the
249 * domain
250 * @return 0 on success, -1 on failure
251 */
252 int xc_vcpu_getcontext(int xc_handle,
253 uint32_t domid,
254 uint32_t vcpu,
255 vcpu_guest_context_t *ctxt);
257 typedef dom0_getvcpuinfo_t xc_vcpuinfo_t;
258 int xc_vcpu_getinfo(int xc_handle,
259 uint32_t domid,
260 uint32_t vcpu,
261 xc_vcpuinfo_t *info);
263 int xc_domain_setcpuweight(int xc_handle,
264 uint32_t domid,
265 float weight);
266 long long xc_domain_get_cpu_usage(int xc_handle,
267 domid_t domid,
268 int vcpu);
270 int xc_domain_sethandle(int xc_handle, uint32_t domid,
271 xen_domain_handle_t handle);
273 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
274 int xc_shadow_control(int xc_handle,
275 uint32_t domid,
276 unsigned int sop,
277 unsigned long *dirty_bitmap,
278 unsigned long pages,
279 xc_shadow_control_stats_t *stats);
281 int xc_bvtsched_global_set(int xc_handle,
282 unsigned long ctx_allow);
284 int xc_bvtsched_domain_set(int xc_handle,
285 uint32_t domid,
286 uint32_t mcuadv,
287 int warpback,
288 int32_t warpvalue,
289 long long warpl,
290 long long warpu);
292 int xc_bvtsched_global_get(int xc_handle,
293 unsigned long *ctx_allow);
295 int xc_bvtsched_domain_get(int xc_handle,
296 uint32_t domid,
297 uint32_t *mcuadv,
298 int *warpback,
299 int32_t *warpvalue,
300 long long *warpl,
301 long long *warpu);
303 int xc_sedf_domain_set(int xc_handle,
304 uint32_t domid,
305 uint64_t period, uint64_t slice,
306 uint64_t latency, uint16_t extratime,
307 uint16_t weight);
309 int xc_sedf_domain_get(int xc_handle,
310 uint32_t domid,
311 uint64_t* period, uint64_t *slice,
312 uint64_t *latency, uint16_t *extratime,
313 uint16_t *weight);
315 typedef evtchn_status_t xc_evtchn_status_t;
317 /*
318 * EVENT CHANNEL FUNCTIONS
319 */
321 /**
322 * This function allocates an unbound port. Ports are named endpoints used for
323 * interdomain communication. This function is most useful in opening a
324 * well-known port within a domain to receive events on.
325 *
326 * @parm xc_handle a handle to an open hypervisor interface
327 * @parm dom the ID of the local domain (the 'allocatee')
328 * @parm remote_dom the ID of the domain who will later bind
329 * @return allocated port (in @dom) on success, -1 on failure
330 */
331 int xc_evtchn_alloc_unbound(int xc_handle,
332 uint32_t dom,
333 uint32_t remote_dom);
335 int xc_evtchn_status(int xc_handle,
336 uint32_t dom, /* may be DOMID_SELF */
337 evtchn_port_t port,
338 xc_evtchn_status_t *status);
340 int xc_physdev_pci_access_modify(int xc_handle,
341 uint32_t domid,
342 int bus,
343 int dev,
344 int func,
345 int enable);
347 int xc_readconsolering(int xc_handle,
348 char **pbuffer,
349 unsigned int *pnr_chars,
350 int clear);
352 typedef dom0_physinfo_t xc_physinfo_t;
353 int xc_physinfo(int xc_handle,
354 xc_physinfo_t *info);
356 int xc_sched_id(int xc_handle,
357 int *sched_id);
359 int xc_domain_setmaxmem(int xc_handle,
360 uint32_t domid,
361 unsigned int max_memkb);
363 int xc_domain_memory_increase_reservation(int xc_handle,
364 uint32_t domid,
365 unsigned long nr_extents,
366 unsigned int extent_order,
367 unsigned int address_bits,
368 unsigned long *extent_start);
370 int xc_domain_memory_decrease_reservation(int xc_handle,
371 uint32_t domid,
372 unsigned long nr_extents,
373 unsigned int extent_order,
374 unsigned long *extent_start);
376 int xc_domain_ioport_permission(int xc_handle,
377 uint32_t domid,
378 uint32_t first_port,
379 uint32_t nr_ports,
380 uint32_t allow_access);
382 int xc_domain_irq_permission(int xc_handle,
383 uint32_t domid,
384 uint8_t pirq,
385 uint8_t allow_access);
387 int xc_domain_iomem_permission(int xc_handle,
388 uint32_t domid,
389 unsigned long first_pfn,
390 unsigned long nr_pfns,
391 uint8_t allow_access);
393 unsigned long xc_make_page_below_4G(int xc_handle, uint32_t domid,
394 unsigned long mfn);
396 typedef dom0_perfc_desc_t xc_perfc_desc_t;
397 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc array. */
398 int xc_perfc_control(int xc_handle,
399 uint32_t op,
400 xc_perfc_desc_t *desc);
402 /* read/write msr */
403 long long xc_msr_read(int xc_handle, int cpu_mask, int msr);
404 int xc_msr_write(int xc_handle, int cpu_mask, int msr, unsigned int low,
405 unsigned int high);
407 /**
408 * Memory maps a range within one domain to a local address range. Mappings
409 * should be unmapped with munmap and should follow the same rules as mmap
410 * regarding page alignment. Returns NULL on failure.
411 *
412 * In Linux, the ring queue for the control channel is accessible by mapping
413 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
414 * stored there is of type control_if_t.
415 *
416 * @parm xc_handle a handle on an open hypervisor interface
417 * @parm dom the domain to map memory from
418 * @parm size the amount of memory to map (in multiples of page size)
419 * @parm prot same flag as in mmap().
420 * @parm mfn the frame address to map.
421 */
422 void *xc_map_foreign_range(int xc_handle, uint32_t dom,
423 int size, int prot,
424 unsigned long mfn );
426 void *xc_map_foreign_batch(int xc_handle, uint32_t dom, int prot,
427 unsigned long *arr, int num );
429 /**
430 * Translates a virtual address in the context of a given domain and
431 * vcpu returning the machine page frame number of the associated
432 * page.
433 *
434 * @parm xc_handle a handle on an open hypervisor interface
435 * @parm dom the domain to perform the translation in
436 * @parm vcpu the vcpu to perform the translation on
437 * @parm virt the virtual address to translate
438 */
439 unsigned long xc_translate_foreign_address(int xc_handle, uint32_t dom,
440 int vcpu, unsigned long long virt);
442 int xc_get_pfn_list(int xc_handle, uint32_t domid, unsigned long *pfn_buf,
443 unsigned long max_pfns);
445 int xc_ia64_get_pfn_list(int xc_handle, uint32_t domid,
446 unsigned long *pfn_buf,
447 unsigned int start_page, unsigned int nr_pages);
449 int xc_copy_to_domain_page(int xc_handle, uint32_t domid,
450 unsigned long dst_pfn, void *src_page);
452 int xc_clear_domain_page(int xc_handle, uint32_t domid,
453 unsigned long dst_pfn);
455 int xc_ia64_copy_to_domain_pages(int xc_handle, uint32_t domid,
456 void* src_page, unsigned long dst_pfn, int nr_pages);
458 long xc_get_max_pages(int xc_handle, uint32_t domid);
460 int xc_mmuext_op(int xc_handle, struct mmuext_op *op, unsigned int nr_ops,
461 domid_t dom);
463 int xc_memory_op(int xc_handle, int cmd, void *arg);
465 int xc_get_pfn_type_batch(int xc_handle, uint32_t dom,
466 int num, unsigned long *arr);
469 /* Get current total pages allocated to a domain. */
470 long xc_get_tot_pages(int xc_handle, uint32_t domid);
473 /*
474 * Trace Buffer Operations
475 */
477 /**
478 * This function enables or disables tracing. Trace buffer memory must
479 * be already allocated by setting the size to a non-zero value, otherwise
480 * tracing cannot be enabled.
481 *
482 * @parm xc_handle a handle to an open hypervisor interface
483 * @parm enable the desired action, 1 for enable, 0 for disable
484 * @return 0 on success, -1 on failure.
485 */
486 int xc_tbuf_enable(int xc_handle, int enable);
488 /**
489 * This function sets the size of the trace buffers. Setting the size
490 * is currently a one-shot operation that may be performed either at boot
491 * time or via this interface, not both. The buffer size must be set before
492 * enabling tracing.
493 *
494 * @parm xc_handle a handle to an open hypervisor interface
495 * @parm size the size in pages per cpu for the trace buffers
496 * @return 0 on success, -1 on failure.
497 */
498 int xc_tbuf_set_size(int xc_handle, uint32_t size);
500 /**
501 * This function retrieves the current size of the trace buffers.
502 * Note that the size returned is in terms of bytes, not pages.
504 * @parm xc_handle a handle to an open hypervisor interface
505 * @parm size will contain the size in bytes for the trace buffers
506 * @return 0 on success, -1 on failure.
507 */
508 int xc_tbuf_get_size(int xc_handle, uint32_t *size);
511 /* Execute a privileged dom0 operation. */
512 int xc_dom0_op(int xc_handle, dom0_op_t *op);
514 int xc_version(int xc_handle, int cmd, void *arg);
516 /*
517 * MMU updates.
518 */
519 #define MAX_MMU_UPDATES 1024
520 struct xc_mmu {
521 mmu_update_t updates[MAX_MMU_UPDATES];
522 int idx;
523 domid_t subject;
524 };
525 typedef struct xc_mmu xc_mmu_t;
526 xc_mmu_t *xc_init_mmu_updates(int xc_handle, domid_t dom);
527 int xc_add_mmu_update(int xc_handle, xc_mmu_t *mmu,
528 unsigned long long ptr, unsigned long long val);
529 int xc_finish_mmu_updates(int xc_handle, xc_mmu_t *mmu);
531 int xc_get_pfn_hole_start(int xc_handle, domid_t dom);
533 #endif