ia64/xen-unstable

view tools/libxc/xenctrl.h @ 8468:d966b7a00959

Allow non-privileged domains restricted access to
I/O memory and physical interrupts, under control
of domain0. Capabilities are maintained as rangesets
in Xen.

Signed-off-by: Ryan Wilson <hap9@epoch.ncsc.mil>
Signed-off-by: Keir Fraser <keir@xensource.com>
author kaf24@firebug.cl.cam.ac.uk
date Sat Dec 31 14:15:22 2005 +0100 (2005-12-31)
parents 8d5d4d58407f
children dd5649730b32
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/grant_table.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>
24 #ifdef __ia64__
25 #define XC_PAGE_SHIFT 14
26 #else
27 #define XC_PAGE_SHIFT 12
28 #endif
29 #define XC_PAGE_SIZE (1UL << XC_PAGE_SHIFT)
30 #define XC_PAGE_MASK (~(XC_PAGE_SIZE-1))
32 /*
33 * DEFINITIONS FOR CPU BARRIERS
34 */
36 #if defined(__i386__)
37 #define mb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
38 #define rmb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
39 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
40 #elif defined(__x86_64__)
41 #define mb() __asm__ __volatile__ ( "mfence" : : : "memory")
42 #define rmb() __asm__ __volatile__ ( "lfence" : : : "memory")
43 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
44 #elif defined(__ia64__)
45 /* FIXME */
46 #define mb()
47 #define rmb()
48 #define wmb()
49 #else
50 #error "Define barriers"
51 #endif
53 /*
54 * INITIALIZATION FUNCTIONS
55 */
57 /**
58 * This function opens a handle to the hypervisor interface. This function can
59 * be called multiple times within a single process. Multiple processes can
60 * have an open hypervisor interface at the same time.
61 *
62 * Each call to this function should have a corresponding call to
63 * xc_interface_close().
64 *
65 * This function can fail if the caller does not have superuser permission or
66 * if a Xen-enabled kernel is not currently running.
67 *
68 * @return a handle to the hypervisor interface or -1 on failure
69 */
70 int xc_interface_open(void);
72 /**
73 * This function closes an open hypervisor interface.
74 *
75 * This function can fail if the handle does not represent an open interface or
76 * if there were problems closing the interface.
77 *
78 * @parm xc_handle a handle to an open hypervisor interface
79 * @return 0 on success, -1 otherwise.
80 */
81 int xc_interface_close(int xc_handle);
83 /*
84 * DOMAIN DEBUGGING FUNCTIONS
85 */
87 typedef struct xc_core_header {
88 unsigned int xch_magic;
89 unsigned int xch_nr_vcpus;
90 unsigned int xch_nr_pages;
91 unsigned int xch_ctxt_offset;
92 unsigned int xch_index_offset;
93 unsigned int xch_pages_offset;
94 } xc_core_header_t;
97 long xc_ptrace_core(
98 int xc_handle,
99 enum __ptrace_request request,
100 uint32_t domid,
101 long addr,
102 long data);
104 int xc_waitdomain_core(
105 int xc_handle,
106 int domain,
107 int *status,
108 int options);
110 /*
111 * DOMAIN MANAGEMENT FUNCTIONS
112 */
114 typedef struct {
115 uint32_t domid;
116 uint32_t ssidref;
117 unsigned int dying:1, crashed:1, shutdown:1,
118 paused:1, blocked:1, running:1;
119 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
120 unsigned long nr_pages;
121 unsigned long shared_info_frame;
122 uint64_t cpu_time;
123 unsigned long max_memkb;
124 unsigned int nr_online_vcpus;
125 unsigned int max_vcpu_id;
126 xen_domain_handle_t handle;
127 } xc_dominfo_t;
129 typedef dom0_getdomaininfo_t xc_domaininfo_t;
130 int xc_domain_create(int xc_handle,
131 uint32_t ssidref,
132 xen_domain_handle_t handle,
133 uint32_t *pdomid);
136 int xc_domain_dumpcore(int xc_handle,
137 uint32_t domid,
138 const char *corename);
140 /*
141 * This function sets the maximum number of vcpus that a domain may create.
142 *
143 * @parm xc_handle a handle to an open hypervisor interface.
144 * @parm domid the domain id in which vcpus are to be created.
145 * @parm max the maximum number of vcpus that the domain may create.
146 * @return 0 on success, -1 on failure.
147 */
148 int xc_domain_max_vcpus(int xc_handle,
149 uint32_t domid,
150 unsigned int max);
152 /**
153 * This function pauses a domain. A paused domain still exists in memory
154 * however it does not receive any timeslices from the hypervisor.
155 *
156 * @parm xc_handle a handle to an open hypervisor interface
157 * @parm domid the domain id to pause
158 * @return 0 on success, -1 on failure.
159 */
160 int xc_domain_pause(int xc_handle,
161 uint32_t domid);
162 /**
163 * This function unpauses a domain. The domain should have been previously
164 * paused.
165 *
166 * @parm xc_handle a handle to an open hypervisor interface
167 * @parm domid the domain id to unpause
168 * return 0 on success, -1 on failure
169 */
170 int xc_domain_unpause(int xc_handle,
171 uint32_t domid);
173 /**
174 * This function will destroy a domain. Destroying a domain removes the domain
175 * completely from memory. This function should be called after sending the
176 * domain a SHUTDOWN control message to free up the domain resources.
177 *
178 * @parm xc_handle a handle to an open hypervisor interface
179 * @parm domid the domain id to destroy
180 * @return 0 on success, -1 on failure
181 */
182 int xc_domain_destroy(int xc_handle,
183 uint32_t domid);
184 int xc_domain_pincpu(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 vcpu context for the specified domain.
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_domain_setinfo(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_domain_get_vcpu_context(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_domain_get_vcpu_info(int xc_handle,
259 uint32_t domid,
260 uint32_t vcpu,
261 xc_vcpuinfo_t *info);
264 int xc_domain_setcpuweight(int xc_handle,
265 uint32_t domid,
266 float weight);
267 long long xc_domain_get_cpu_usage(int xc_handle,
268 domid_t domid,
269 int vcpu);
271 int xc_domain_sethandle(int xc_handle, uint32_t domid,
272 xen_domain_handle_t handle);
274 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
275 int xc_shadow_control(int xc_handle,
276 uint32_t domid,
277 unsigned int sop,
278 unsigned long *dirty_bitmap,
279 unsigned long pages,
280 xc_shadow_control_stats_t *stats);
282 int xc_bvtsched_global_set(int xc_handle,
283 unsigned long ctx_allow);
285 int xc_bvtsched_domain_set(int xc_handle,
286 uint32_t domid,
287 uint32_t mcuadv,
288 int warpback,
289 int32_t warpvalue,
290 long long warpl,
291 long long warpu);
293 int xc_bvtsched_global_get(int xc_handle,
294 unsigned long *ctx_allow);
296 int xc_bvtsched_domain_get(int xc_handle,
297 uint32_t domid,
298 uint32_t *mcuadv,
299 int *warpback,
300 int32_t *warpvalue,
301 long long *warpl,
302 long long *warpu);
304 int xc_sedf_domain_set(int xc_handle,
305 uint32_t domid,
306 uint64_t period, uint64_t slice,
307 uint64_t latency, uint16_t extratime,
308 uint16_t weight);
310 int xc_sedf_domain_get(int xc_handle,
311 uint32_t domid,
312 uint64_t* period, uint64_t *slice,
313 uint64_t *latency, uint16_t *extratime,
314 uint16_t *weight);
316 typedef evtchn_status_t xc_evtchn_status_t;
318 /*
319 * EVENT CHANNEL FUNCTIONS
320 */
322 /**
323 * This function allocates an unbound port. Ports are named endpoints used for
324 * interdomain communication. This function is most useful in opening a
325 * well-known port within a domain to receive events on.
326 *
327 * @parm xc_handle a handle to an open hypervisor interface
328 * @parm dom the ID of the local domain (the 'allocatee')
329 * @parm remote_dom the ID of the domain who will later bind
330 * @return allocated port (in @dom) on success, -1 on failure
331 */
332 int xc_evtchn_alloc_unbound(int xc_handle,
333 uint32_t dom,
334 uint32_t remote_dom);
336 int xc_evtchn_status(int xc_handle,
337 uint32_t dom, /* may be DOMID_SELF */
338 evtchn_port_t port,
339 xc_evtchn_status_t *status);
341 int xc_physdev_pci_access_modify(int xc_handle,
342 uint32_t domid,
343 int bus,
344 int dev,
345 int func,
346 int enable);
348 int xc_readconsolering(int xc_handle,
349 char **pbuffer,
350 unsigned int *pnr_chars,
351 int clear);
353 typedef dom0_physinfo_t xc_physinfo_t;
354 int xc_physinfo(int xc_handle,
355 xc_physinfo_t *info);
357 int xc_sched_id(int xc_handle,
358 int *sched_id);
360 int xc_domain_setmaxmem(int xc_handle,
361 uint32_t domid,
362 unsigned int max_memkb);
364 int xc_domain_memory_increase_reservation(int xc_handle,
365 uint32_t domid,
366 unsigned long nr_extents,
367 unsigned int extent_order,
368 unsigned int address_bits,
369 unsigned long *extent_start);
371 int xc_domain_memory_decrease_reservation(int xc_handle,
372 uint32_t domid,
373 unsigned long nr_extents,
374 unsigned int extent_order,
375 unsigned long *extent_start);
377 int xc_domain_ioport_permission(int xc_handle,
378 uint32_t domid,
379 uint32_t first_port,
380 uint32_t nr_ports,
381 uint32_t allow_access);
383 int xc_domain_irq_permission(int xc_handle,
384 uint32_t domid,
385 uint8_t pirq,
386 uint8_t allow_access);
388 int xc_domain_iomem_permission(int xc_handle,
389 uint32_t domid,
390 unsigned long first_pfn,
391 unsigned long nr_pfns,
392 uint8_t allow_access);
394 unsigned long xc_make_page_below_4G(int xc_handle, uint32_t domid,
395 unsigned long mfn);
397 typedef dom0_perfc_desc_t xc_perfc_desc_t;
398 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc array. */
399 int xc_perfc_control(int xc_handle,
400 uint32_t op,
401 xc_perfc_desc_t *desc);
403 /* read/write msr */
404 long long xc_msr_read(int xc_handle, int cpu_mask, int msr);
405 int xc_msr_write(int xc_handle, int cpu_mask, int msr, unsigned int low,
406 unsigned int high);
408 /**
409 * Memory maps a range within one domain to a local address range. Mappings
410 * should be unmapped with munmap and should follow the same rules as mmap
411 * regarding page alignment. Returns NULL on failure.
412 *
413 * In Linux, the ring queue for the control channel is accessible by mapping
414 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
415 * stored there is of type control_if_t.
416 *
417 * @parm xc_handle a handle on an open hypervisor interface
418 * @parm dom the domain to map memory from
419 * @parm size the amount of memory to map (in multiples of page size)
420 * @parm prot same flag as in mmap().
421 * @parm mfn the frame address to map.
422 */
423 void *xc_map_foreign_range(int xc_handle, uint32_t dom,
424 int size, int prot,
425 unsigned long mfn );
427 void *xc_map_foreign_batch(int xc_handle, uint32_t dom, int prot,
428 unsigned long *arr, int num );
430 /**
431 * Translates a virtual address in the context of a given domain and
432 * vcpu returning the machine page frame number of the associated
433 * page.
434 *
435 * @parm xc_handle a handle on an open hypervisor interface
436 * @parm dom the domain to perform the translation in
437 * @parm vcpu the vcpu to perform the translation on
438 * @parm virt the virtual address to translate
439 */
440 unsigned long xc_translate_foreign_address(int xc_handle, uint32_t dom,
441 int vcpu, unsigned long long virt);
443 int xc_get_pfn_list(int xc_handle, uint32_t domid, unsigned long *pfn_buf,
444 unsigned long max_pfns);
446 int xc_ia64_get_pfn_list(int xc_handle, uint32_t domid,
447 unsigned long *pfn_buf,
448 unsigned int start_page, unsigned int nr_pages);
450 int xc_copy_to_domain_page(int xc_handle, uint32_t domid,
451 unsigned long dst_pfn, void *src_page);
453 int xc_clear_domain_page(int xc_handle, uint32_t domid,
454 unsigned long dst_pfn);
456 int xc_ia64_copy_to_domain_pages(int xc_handle, uint32_t domid,
457 void* src_page, unsigned long dst_pfn, int nr_pages);
459 long xc_get_max_pages(int xc_handle, uint32_t domid);
461 int xc_mmuext_op(int xc_handle, struct mmuext_op *op, unsigned int nr_ops,
462 domid_t dom);
464 int xc_memory_op(int xc_handle, int cmd, void *arg);
466 int xc_get_pfn_type_batch(int xc_handle, uint32_t dom,
467 int num, unsigned long *arr);
470 /*\
471 * GRANT TABLE FUNCTIONS
472 \*/
474 /**
475 * This function opens a handle to the more restricted grant table hypervisor
476 * interface. This may be used where the standard interface is not
477 * available because the domain is not privileged.
478 * This function can be called multiple times within a single process.
479 * Multiple processes can have an open hypervisor interface at the same time.
480 *
481 * Each call to this function should have a corresponding call to
482 * xc_grant_interface_close().
483 *
484 * This function can fail if a Xen-enabled kernel is not currently running.
485 *
486 * @return a handle to the hypervisor grant table interface or -1 on failure
487 */
488 int xc_grant_interface_open(void);
490 /**
491 * This function closes an open grant table hypervisor interface.
492 *
493 * This function can fail if the handle does not represent an open interface or
494 * if there were problems closing the interface.
495 *
496 * @parm xc_handle a handle to an open grant table hypervisor interface
497 * @return 0 on success, -1 otherwise.
498 */
499 int xc_grant_interface_close(int xc_handle);
501 int xc_gnttab_map_grant_ref(int xc_handle,
502 uint64_t host_virt_addr,
503 uint32_t dom,
504 grant_ref_t ref,
505 uint16_t flags,
506 int16_t *status,
507 grant_handle_t *handle,
508 uint64_t *dev_bus_addr);
510 int xc_gnttab_unmap_grant_ref(int xc_handle,
511 uint64_t host_virt_addr,
512 uint64_t dev_bus_addr,
513 grant_handle_t handle,
514 int16_t *status);
516 int xc_gnttab_setup_table(int xc_handle,
517 uint32_t dom,
518 uint16_t nr_frames,
519 int16_t *status,
520 unsigned long **frame_list);
522 /* Grant debug builds only: */
523 int xc_gnttab_dump_table(int xc_handle,
524 uint32_t dom,
525 int16_t *status);
527 /* Get current total pages allocated to a domain. */
528 long xc_get_tot_pages(int xc_handle, uint32_t domid);
531 /*
532 * Trace Buffer Operations
533 */
535 /**
536 * This function enables or disables tracing. Trace buffer memory must
537 * be already allocated by setting the size to a non-zero value, otherwise
538 * tracing cannot be enabled.
539 *
540 * @parm xc_handle a handle to an open hypervisor interface
541 * @parm enable the desired action, 1 for enable, 0 for disable
542 * @return 0 on success, -1 on failure.
543 */
544 int xc_tbuf_enable(int xc_handle, int enable);
546 /**
547 * This function sets the size of the trace buffers. Setting the size
548 * is currently a one-shot operation that may be performed either at boot
549 * time or via this interface, not both. The buffer size must be set before
550 * enabling tracing.
551 *
552 * @parm xc_handle a handle to an open hypervisor interface
553 * @parm size the size in pages per cpu for the trace buffers
554 * @return 0 on success, -1 on failure.
555 */
556 int xc_tbuf_set_size(int xc_handle, uint32_t size);
558 /**
559 * This function retrieves the current size of the trace buffers.
560 * Note that the size returned is in terms of bytes, not pages.
562 * @parm xc_handle a handle to an open hypervisor interface
563 * @parm size will contain the size in bytes for the trace buffers
564 * @return 0 on success, -1 on failure.
565 */
566 int xc_tbuf_get_size(int xc_handle, uint32_t *size);
569 /* Execute a privileged dom0 operation. */
570 int xc_dom0_op(int xc_handle, dom0_op_t *op);
572 int xc_version(int xc_handle, int cmd, void *arg);
574 /*
575 * MMU updates.
576 */
577 #define MAX_MMU_UPDATES 1024
578 struct xc_mmu {
579 mmu_update_t updates[MAX_MMU_UPDATES];
580 int idx;
581 domid_t subject;
582 };
583 typedef struct xc_mmu xc_mmu_t;
584 xc_mmu_t *xc_init_mmu_updates(int xc_handle, domid_t dom);
585 int xc_add_mmu_update(int xc_handle, xc_mmu_t *mmu,
586 unsigned long long ptr, unsigned long long val);
587 int xc_finish_mmu_updates(int xc_handle, xc_mmu_t *mmu);
589 #endif