ia64/xen-unstable

view tools/libxc/xc.h @ 6316:f7dfaa2af90c

merge?
author cl349@firebug.cl.cam.ac.uk
date Sun Aug 21 11:02:00 2005 +0000 (2005-08-21)
parents 1872e09bfba3
children 6721abf6b16d
line source
1 /******************************************************************************
2 * xc.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 __XC_H__
10 #define __XC_H__
12 #include <stdint.h>
14 typedef uint8_t u8;
15 typedef uint16_t u16;
16 typedef uint32_t u32;
17 typedef uint64_t u64;
18 typedef int8_t s8;
19 typedef int16_t s16;
20 typedef int32_t s32;
21 typedef int64_t s64;
23 #include <sys/ptrace.h>
24 #include <xen/xen.h>
25 #include <xen/dom0_ops.h>
26 #include <xen/event_channel.h>
27 #include <xen/sched_ctl.h>
28 #include <xen/acm.h>
30 #ifdef __ia64__
31 #define XC_PAGE_SHIFT 14
32 #else
33 #define XC_PAGE_SHIFT 12
34 #endif
35 #define XC_PAGE_SIZE (1UL << XC_PAGE_SHIFT)
36 #define XC_PAGE_MASK (~(XC_PAGE_SIZE-1))
38 /*
39 * DEFINITIONS FOR CPU BARRIERS
40 */
42 #if defined(__i386__)
43 #define mb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
44 #define rmb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
45 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
46 #elif defined(__x86_64__)
47 #define mb() __asm__ __volatile__ ( "mfence" : : : "memory")
48 #define rmb() __asm__ __volatile__ ( "lfence" : : : "memory")
49 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
50 #elif defined(__ia64__)
51 /* FIXME */
52 #define mb()
53 #define rmb()
54 #define wmb()
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;
103 long xc_ptrace(enum __ptrace_request request,
104 u32 domid,
105 long addr,
106 long data);
108 long xc_ptrace_core(enum __ptrace_request request,
109 u32 domid,
110 long addr,
111 long data);
113 int xc_waitdomain(int domain,
114 int *status,
115 int options);
117 int xc_waitdomain_core(int domain,
118 int *status,
119 int options);
121 /*
122 * DOMAIN MANAGEMENT FUNCTIONS
123 */
125 typedef struct {
126 u32 domid;
127 u32 ssidref;
128 unsigned int dying:1, crashed:1, shutdown:1,
129 paused:1, blocked:1, running:1;
130 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
131 unsigned long nr_pages;
132 unsigned long shared_info_frame;
133 u64 cpu_time;
134 unsigned long max_memkb;
135 unsigned int vcpus;
136 s32 vcpu_to_cpu[MAX_VIRT_CPUS];
137 cpumap_t cpumap[MAX_VIRT_CPUS];
138 } xc_dominfo_t;
140 typedef dom0_getdomaininfo_t xc_domaininfo_t;
141 int xc_domain_create(int xc_handle,
142 u32 ssidref,
143 u32 *pdomid);
146 int xc_domain_dumpcore(int xc_handle,
147 u32 domid,
148 const char *corename);
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 u32 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 u32 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 u32 domid);
183 int xc_domain_pincpu(int xc_handle,
184 u32 domid,
185 int vcpu,
186 cpumap_t *cpumap);
187 /**
188 * This function will return information about one or more domains. It is
189 * designed to iterate over the list of domains. If a single domain is
190 * requested, this function will return the next domain in the list - if
191 * one exists. It is, therefore, important in this case to make sure the
192 * domain requested was the one returned.
193 *
194 * @parm xc_handle a handle to an open hypervisor interface
195 * @parm first_domid the first domain to enumerate information from. Domains
196 * are currently enumerate in order of creation.
197 * @parm max_doms the number of elements in info
198 * @parm info an array of max_doms size that will contain the information for
199 * the enumerated domains.
200 * @return the number of domains enumerated or -1 on error
201 */
202 int xc_domain_getinfo(int xc_handle,
203 u32 first_domid,
204 unsigned int max_doms,
205 xc_dominfo_t *info);
207 /**
208 * This function will return information about one or more domains, using a
209 * single hypercall. The domain information will be stored into the supplied
210 * array of xc_domaininfo_t structures.
211 *
212 * @parm xc_handle a handle to an open hypervisor interface
213 * @parm first_domain the first domain to enumerate information from.
214 * Domains are currently enumerate in order of creation.
215 * @parm max_domains the number of elements in info
216 * @parm info an array of max_doms size that will contain the information for
217 * the enumerated domains.
218 * @return the number of domains enumerated or -1 on error
219 */
220 int xc_domain_getinfolist(int xc_handle,
221 u32 first_domain,
222 unsigned int max_domains,
223 xc_domaininfo_t *info);
225 /**
226 * This function returns information about one domain. This information is
227 * more detailed than the information from xc_domain_getinfo().
228 *
229 * @parm xc_handle a handle to an open hypervisor interface
230 * @parm domid the domain to get information from
231 * @parm info a pointer to an xc_domaininfo_t to store the domain information
232 * @parm ctxt a pointer to a structure to store the execution context of the
233 * domain
234 * @return 0 on success, -1 on failure
235 */
236 int xc_domain_get_vcpu_context(int xc_handle,
237 u32 domid,
238 u32 vcpu,
239 vcpu_guest_context_t *ctxt);
241 int xc_domain_setcpuweight(int xc_handle,
242 u32 domid,
243 float weight);
244 long long xc_domain_get_cpu_usage(int xc_handle,
245 domid_t domid,
246 int vcpu);
249 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
250 int xc_shadow_control(int xc_handle,
251 u32 domid,
252 unsigned int sop,
253 unsigned long *dirty_bitmap,
254 unsigned long pages,
255 xc_shadow_control_stats_t *stats);
258 #define XCFLAGS_VERBOSE 1
259 #define XCFLAGS_LIVE 2
260 #define XCFLAGS_DEBUG 4
261 #define XCFLAGS_CONFIGURE 8
263 struct XcIOContext;
265 /**
266 * This function will save a domain running Linux.
267 *
268 * @parm xc_handle a handle to an open hypervisor interface
269 * @parm fd the file descriptor to save a domain to
270 * @parm dom the id of the domain
271 * @return 0 on success, -1 on failure
272 */
273 int xc_linux_save(int xc_handle, int fd, u32 dom);
275 /**
276 * This function will restore a saved domain running Linux.
277 *
278 * @parm xc_handle a handle to an open hypervisor interface
279 * @parm fd the file descriptor to restore a domain from
280 * @parm dom the id of the domain
281 * @parm nr_pfns the number of pages
282 * @parm store_evtchn the store event channel for this domain to use
283 * @parm store_mfn returned with the mfn of the store page
284 * @return 0 on success, -1 on failure
285 */
286 int xc_linux_restore(int xc_handle, int io_fd, u32 dom, unsigned long nr_pfns,
287 unsigned int store_evtchn, unsigned long *store_mfn);
289 int xc_linux_build(int xc_handle,
290 u32 domid,
291 const char *image_name,
292 const char *ramdisk_name,
293 const char *cmdline,
294 unsigned int control_evtchn,
295 unsigned long flags,
296 unsigned int vcpus,
297 unsigned int store_evtchn,
298 unsigned long *store_mfn);
300 struct mem_map;
301 int xc_vmx_build(int xc_handle,
302 u32 domid,
303 int memsize,
304 const char *image_name,
305 struct mem_map *memmap,
306 const char *ramdisk_name,
307 const char *cmdline,
308 unsigned int control_evtchn,
309 unsigned long flags,
310 unsigned int vcpus,
311 unsigned int store_evtchn,
312 unsigned long *store_mfn);
314 int xc_bvtsched_global_set(int xc_handle,
315 unsigned long ctx_allow);
317 int xc_bvtsched_domain_set(int xc_handle,
318 u32 domid,
319 u32 mcuadv,
320 int warpback,
321 s32 warpvalue,
322 long long warpl,
323 long long warpu);
325 int xc_bvtsched_global_get(int xc_handle,
326 unsigned long *ctx_allow);
328 int xc_bvtsched_domain_get(int xc_handle,
329 u32 domid,
330 u32 *mcuadv,
331 int *warpback,
332 s32 *warpvalue,
333 long long *warpl,
334 long long *warpu);
336 int xc_sedf_domain_set(int xc_handle,
337 u32 domid,
338 u64 period, u64 slice, u64 latency, u16 extratime, u16 weight);
340 int xc_sedf_domain_get(int xc_handle,
341 u32 domid,
342 u64* period, u64 *slice, u64 *latency, u16 *extratime, u16* weight);
344 typedef evtchn_status_t xc_evtchn_status_t;
346 /*
347 * EVENT CHANNEL FUNCTIONS
348 */
350 /**
351 * This function allocates an unbound port. Ports are named endpoints used for
352 * interdomain communication. This function is most useful in opening a
353 * well-known port within a domain to receive events on.
354 *
355 * @parm xc_handle a handle to an open hypervisor interface
356 * @parm dom the ID of the domain. This maybe DOMID_SELF
357 * @parm port a pointer to a port. This is an in/out parameter. If *port is
358 * 0, then a new port will be assigned, if port is > 0 then that
359 * port is allocated if the port is unallocated.
360 * @return 0 on success, -1 on failure
361 */
362 int xc_evtchn_alloc_unbound(int xc_handle,
363 u32 dom,
364 int *port);
366 /**
367 * This function creates a pair of ports between two domains. A port can only
368 * be bound once within a domain.
369 *
370 * @parm xc_handle a handle to an open hypervisor interface
371 * @parm dom1 one of the two domains to connect. Can be DOMID_SELF.
372 * @parm dom2 the other domain to connect. Can be DOMID_SELF.
373 * @parm port1 an in/out parameter. If > 0, then try to connect *port. If
374 * 0, then allocate a new port and store the port in *port.
375 * @parm port2 the port connected on port2. This parameter behaves the same
376 * way as port1.
377 * @return 0 on success, -1 on error.
378 */
379 int xc_evtchn_bind_interdomain(int xc_handle,
380 u32 dom1,
381 u32 dom2,
382 int *port1,
383 int *port2);
384 int xc_evtchn_bind_virq(int xc_handle,
385 int virq,
386 int *port);
388 /**
389 * This function will close a single port on an event channel.
390 *
391 * @parm xc_handle a handle to an open hypervisor interface
392 * @parm dom the domain that the port exists on. May be DOMID_SELF.
393 * @parm port the port to close
394 * @return 0 on success, -1 on error
395 */
396 int xc_evtchn_close(int xc_handle,
397 u32 dom, /* may be DOMID_SELF */
398 int port);
400 /**
401 * This function generates a notify event on a bound port.
402 *
403 * Notifies can be read within Linux by opening /dev/xen/evtchn and reading
404 * a 16 bit value. The result will be the port the event occurred on. When
405 * events occur, the port is masked until the 16 bit port value is written back
406 * to the file. When /dev/xen/evtchn is opened, it has to be bound via an
407 * ioctl to each port to listen on. The ioctl for binding is _IO('E', 2). The
408 * parameter is the port to listen on.
409 *
410 * @parm xc_handle a handle to an open hypervisor interface
411 * @parm local_port the port to generate the notify on
412 * @return 0 on success, -1 on error
413 */
414 int xc_evtchn_send(int xc_handle,
415 int local_port);
416 int xc_evtchn_status(int xc_handle,
417 u32 dom, /* may be DOMID_SELF */
418 int port,
419 xc_evtchn_status_t *status);
421 int xc_physdev_pci_access_modify(int xc_handle,
422 u32 domid,
423 int bus,
424 int dev,
425 int func,
426 int enable);
428 int xc_readconsolering(int xc_handle,
429 char **pbuffer,
430 unsigned int *pnr_chars,
431 int clear);
433 typedef dom0_physinfo_t xc_physinfo_t;
434 int xc_physinfo(int xc_handle,
435 xc_physinfo_t *info);
437 int xc_sched_id(int xc_handle,
438 int *sched_id);
440 int xc_domain_setmaxmem(int xc_handle,
441 u32 domid,
442 unsigned int max_memkb);
444 int xc_domain_memory_increase_reservation(int xc_handle,
445 u32 domid,
446 unsigned int mem_kb);
448 typedef dom0_perfc_desc_t xc_perfc_desc_t;
449 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc array. */
450 int xc_perfc_control(int xc_handle,
451 u32 op,
452 xc_perfc_desc_t *desc);
454 /* read/write msr */
455 long long xc_msr_read(int xc_handle, int cpu_mask, int msr);
456 int xc_msr_write(int xc_handle, int cpu_mask, int msr, unsigned int low,
457 unsigned int high);
459 /**
460 * Memory maps a range within one domain to a local address range. Mappings
461 * should be unmapped with munmap and should follow the same rules as mmap
462 * regarding page alignment. Returns NULL on failure.
463 *
464 * In Linux, the ring queue for the control channel is accessible by mapping
465 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
466 * stored there is of type control_if_t.
467 *
468 * @parm xc_handle a handle on an open hypervisor interface
469 * @parm dom the domain to map memory from
470 * @parm size the amount of memory to map (in multiples of page size)
471 * @parm prot same flag as in mmap().
472 * @parm mfn the frame address to map.
473 */
474 void *xc_map_foreign_range(int xc_handle, u32 dom,
475 int size, int prot,
476 unsigned long mfn );
478 void *xc_map_foreign_batch(int xc_handle, u32 dom, int prot,
479 unsigned long *arr, int num );
481 int xc_get_pfn_list(int xc_handle, u32 domid, unsigned long *pfn_buf,
482 unsigned long max_pfns);
484 int xc_ia64_get_pfn_list(int xc_handle, u32 domid, unsigned long *pfn_buf,
485 unsigned int start_page, unsigned int nr_pages);
487 /*\
488 * GRANT TABLE FUNCTIONS
489 \*/
491 /**
492 * This function opens a handle to the more restricted grant table hypervisor
493 * interface. This may be used where the standard interface is not
494 * available because the domain is not privileged.
495 * This function can be called multiple times within a single process.
496 * Multiple processes can have an open hypervisor interface at the same time.
497 *
498 * Each call to this function should have a corresponding call to
499 * xc_grant_interface_close().
500 *
501 * This function can fail if a Xen-enabled kernel is not currently running.
502 *
503 * @return a handle to the hypervisor grant table interface or -1 on failure
504 */
505 int xc_grant_interface_open(void);
507 /**
508 * This function closes an open grant table hypervisor interface.
509 *
510 * This function can fail if the handle does not represent an open interface or
511 * if there were problems closing the interface.
512 *
513 * @parm xc_handle a handle to an open grant table hypervisor interface
514 * @return 0 on success, -1 otherwise.
515 */
516 int xc_grant_interface_close(int xc_handle);
518 int xc_gnttab_map_grant_ref(int xc_handle,
519 u64 host_virt_addr,
520 u32 dom,
521 u16 ref,
522 u16 flags,
523 s16 *handle,
524 u64 *dev_bus_addr);
526 int xc_gnttab_unmap_grant_ref(int xc_handle,
527 u64 host_virt_addr,
528 u64 dev_bus_addr,
529 u16 handle,
530 s16 *status);
532 int xc_gnttab_setup_table(int xc_handle,
533 u32 dom,
534 u16 nr_frames,
535 s16 *status,
536 unsigned long **frame_list);
538 /* Grant debug builds only: */
539 int xc_gnttab_dump_table(int xc_handle,
540 u32 dom,
541 s16 *status);
543 /* Get current total pages allocated to a domain. */
544 long xc_get_tot_pages(int xc_handle, u32 domid);
546 /* Execute a privileged dom0 operation. */
547 int xc_dom0_op(int xc_handle, dom0_op_t *op);
549 /* Initializes the store (for dom0)
550 remote_port should be the remote end of a bound interdomain channel between
551 the store and dom0.
553 This function returns a shared frame that should be passed to
554 xs_introduce_domain
555 */
556 long xc_init_store(int xc_handle, int remote_port);
558 #endif /* __XC_H__ */