direct-io.hg

view tools/libxc/xc.h @ 5502:0d1166678d9b

bitkeeper revision 1.1719 (42b36f87tzUHBhdJfZKC_wBV271T0g)

manual merge
author iap10@freefall.cl.cam.ac.uk
date Sat Jun 18 00:49:11 2005 +0000 (2005-06-18)
parents 6d3e8f90c2df ae0cf78f78bd
children 649cd37aa1ab
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>
29 /*
30 * DEFINITIONS FOR CPU BARRIERS
31 */
33 #if defined(__i386__)
34 #define mb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
35 #define rmb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
36 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
37 #elif defined(__x86_64__)
38 #define mb() __asm__ __volatile__ ( "mfence" : : : "memory")
39 #define rmb() __asm__ __volatile__ ( "lfence" : : : "memory")
40 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
41 #else
42 #error "Define barriers"
43 #endif
45 /*
46 * INITIALIZATION FUNCTIONS
47 */
49 /**
50 * This function opens a handle to the hypervisor interface. This function can
51 * be called multiple times within a single process. Multiple processes can
52 * have an open hypervisor interface at the same time.
53 *
54 * Each call to this function should have a corresponding call to
55 * xc_interface_close().
56 *
57 * This function can fail if the caller does not have superuser permission or
58 * if a Xen-enabled kernel is not currently running.
59 *
60 * @return a handle to the hypervisor interface or -1 on failure
61 */
62 int xc_interface_open(void);
64 /**
65 * This function closes an open hypervisor interface.
66 *
67 * This function can fail if the handle does not represent an open interface or
68 * if there were problems closing the interface.
69 *
70 * @parm xc_handle a handle to an open hypervisor interface
71 * @return 0 on success, -1 otherwise.
72 */
73 int xc_interface_close(int xc_handle);
75 /*
76 * DOMAIN DEBUGGING FUNCTIONS
77 */
79 typedef struct xc_core_header {
80 unsigned int xch_magic;
81 unsigned int xch_nr_vcpus;
82 unsigned int xch_nr_pages;
83 unsigned int xch_ctxt_offset;
84 unsigned int xch_index_offset;
85 unsigned int xch_pages_offset;
86 } xc_core_header_t;
89 long xc_ptrace(enum __ptrace_request request,
90 u32 domid,
91 long addr,
92 long data);
94 long xc_ptrace_core(enum __ptrace_request request,
95 u32 domid,
96 long addr,
97 long data);
99 int xc_waitdomain(int domain,
100 int *status,
101 int options);
103 int xc_waitdomain_core(int domain,
104 int *status,
105 int options);
107 /*
108 * DOMAIN MANAGEMENT FUNCTIONS
109 */
111 typedef struct {
112 u32 domid;
113 unsigned int dying:1, crashed:1, shutdown:1,
114 paused:1, blocked:1, running:1;
115 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
116 unsigned long nr_pages;
117 unsigned long shared_info_frame;
118 u64 cpu_time;
119 unsigned long max_memkb;
120 unsigned int vcpus;
121 s32 vcpu_to_cpu[MAX_VIRT_CPUS];
122 cpumap_t cpumap[MAX_VIRT_CPUS];
123 } xc_dominfo_t;
125 typedef dom0_getdomaininfo_t xc_domaininfo_t;
126 int xc_domain_create(int xc_handle,
127 u32 *pdomid);
130 int xc_domain_dumpcore(int xc_handle,
131 u32 domid,
132 const char *corename);
135 /**
136 * This function pauses a domain. A paused domain still exists in memory
137 * however it does not receive any timeslices from the hypervisor.
138 *
139 * @parm xc_handle a handle to an open hypervisor interface
140 * @parm domid the domain id to pause
141 * @return 0 on success, -1 on failure.
142 */
143 int xc_domain_pause(int xc_handle,
144 u32 domid);
145 /**
146 * This function unpauses a domain. The domain should have been previously
147 * paused.
148 *
149 * @parm xc_handle a handle to an open hypervisor interface
150 * @parm domid the domain id to unpause
151 * return 0 on success, -1 on failure
152 */
153 int xc_domain_unpause(int xc_handle,
154 u32 domid);
156 /**
157 * This function will destroy a domain. Destroying a domain removes the domain
158 * completely from memory. This function should be called after sending the
159 * domain a SHUTDOWN control message to free up the domain resources.
160 *
161 * @parm xc_handle a handle to an open hypervisor interface
162 * @parm domid the domain id to destroy
163 * @return 0 on success, -1 on failure
164 */
165 int xc_domain_destroy(int xc_handle,
166 u32 domid);
167 int xc_domain_pincpu(int xc_handle,
168 u32 domid,
169 int vcpu,
170 cpumap_t *cpumap);
171 /**
172 * This function will return information about one or more domains. It is
173 * designed to iterate over the list of domains. If a single domain is
174 * requested, this function will return the next domain in the list - if
175 * one exists. It is, therefore, important in this case to make sure the
176 * domain requested was the one returned.
177 *
178 * @parm xc_handle a handle to an open hypervisor interface
179 * @parm first_domid the first domain to enumerate information from. Domains
180 * are currently enumerate in order of creation.
181 * @parm max_doms the number of elements in info
182 * @parm info an array of max_doms size that will contain the information for
183 * the enumerated domains.
184 * @return the number of domains enumerated or -1 on error
185 */
186 int xc_domain_getinfo(int xc_handle,
187 u32 first_domid,
188 unsigned int max_doms,
189 xc_dominfo_t *info);
191 /**
192 * This function returns information about one domain. This information is
193 * more detailed than the information from xc_domain_getinfo().
194 *
195 * @parm xc_handle a handle to an open hypervisor interface
196 * @parm domid the domain to get information from
197 * @parm info a pointer to an xc_domaininfo_t to store the domain information
198 * @parm ctxt a pointer to a structure to store the execution context of the
199 * domain
200 * @return 0 on success, -1 on failure
201 */
202 int xc_domain_get_vcpu_context(int xc_handle,
203 u32 domid,
204 u32 vcpu,
205 vcpu_guest_context_t *ctxt);
207 int xc_domain_setcpuweight(int xc_handle,
208 u32 domid,
209 float weight);
210 long long xc_domain_get_cpu_usage(int xc_handle,
211 domid_t domid,
212 int vcpu);
215 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
216 int xc_shadow_control(int xc_handle,
217 u32 domid,
218 unsigned int sop,
219 unsigned long *dirty_bitmap,
220 unsigned long pages,
221 xc_shadow_control_stats_t *stats);
224 #define XCFLAGS_VERBOSE 1
225 #define XCFLAGS_LIVE 2
226 #define XCFLAGS_DEBUG 4
227 #define XCFLAGS_CONFIGURE 8
229 struct XcIOContext;
231 /**
232 * This function will save a domain running Linux.
233 *
234 * @parm xc_handle a handle to an open hypervisor interface
235 * @parm fd the file descriptor to save a domain to
236 * @parm dom the id of the domain
237 * @return 0 on success, -1 on failure
238 */
239 int xc_linux_save(int xc_handle, int fd, u32 dom);
241 /**
242 * This function will restore a saved domain running Linux.
243 *
244 * @parm xc_handle a handle to an open hypervisor interface
245 * @parm fd the file descriptor to restore a domain from
246 * @parm dom the id of the domain
247 * @parm nr_pfns the number of pages
248 * @return 0 on success, -1 on failure
249 */
250 int xc_linux_restore(int xc_handle, int io_fd, u32 dom, unsigned long nr_pfns);
252 int xc_linux_build(int xc_handle,
253 u32 domid,
254 const char *image_name,
255 const char *ramdisk_name,
256 const char *cmdline,
257 unsigned int control_evtchn,
258 unsigned long flags,
259 unsigned int vcpus,
260 unsigned int store_evtchn,
261 unsigned long *store_mfn);
263 int
264 xc_plan9_build (int xc_handle,
265 u32 domid,
266 const char *image_name,
267 const char *cmdline,
268 unsigned int control_evtchn,
269 unsigned long flags);
271 struct mem_map;
272 int xc_vmx_build(int xc_handle,
273 u32 domid,
274 int memsize,
275 const char *image_name,
276 struct mem_map *memmap,
277 const char *ramdisk_name,
278 const char *cmdline,
279 unsigned int control_evtchn,
280 unsigned long flags);
282 int xc_bvtsched_global_set(int xc_handle,
283 unsigned long ctx_allow);
285 int xc_bvtsched_domain_set(int xc_handle,
286 u32 domid,
287 u32 mcuadv,
288 int warpback,
289 s32 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 u32 domid,
298 u32 *mcuadv,
299 int *warpback,
300 s32 *warpvalue,
301 long long *warpl,
302 long long *warpu);
304 int xc_sedf_domain_set(int xc_handle,
305 u32 domid,
306 u64 period, u64 slice, u64 latency, u16 extratime, u16 weight);
308 int xc_sedf_domain_get(int xc_handle,
309 u32 domid,
310 u64* period, u64 *slice, u64 *latency, u16 *extratime, u16* weight);
312 typedef evtchn_status_t xc_evtchn_status_t;
314 /*
315 * EVENT CHANNEL FUNCTIONS
316 */
318 /**
319 * This function allocates an unbound port. Ports are named endpoints used for
320 * interdomain communication. This function is most useful in opening a
321 * well-known port within a domain to receive events on.
322 *
323 * @parm xc_handle a handle to an open hypervisor interface
324 * @parm dom the ID of the domain. This maybe DOMID_SELF
325 * @parm port a pointer to a port. This is an in/out parameter. If *port is
326 * 0, then a new port will be assigned, if port is > 0 then that
327 * port is allocated if the port is unallocated.
328 * @return 0 on success, -1 on failure
329 */
330 int xc_evtchn_alloc_unbound(int xc_handle,
331 u32 dom,
332 int *port);
334 /**
335 * This function creates a pair of ports between two domains. A port can only
336 * be bound once within a domain.
337 *
338 * @parm xc_handle a handle to an open hypervisor interface
339 * @parm dom1 one of the two domains to connect. Can be DOMID_SELF.
340 * @parm dom2 the other domain to connect. Can be DOMID_SELF.
341 * @parm port1 an in/out parameter. If > 0, then try to connect *port. If
342 * 0, then allocate a new port and store the port in *port.
343 * @parm port2 the port connected on port2. This parameter behaves the same
344 * way as port1.
345 * @return 0 on success, -1 on error.
346 */
347 int xc_evtchn_bind_interdomain(int xc_handle,
348 u32 dom1,
349 u32 dom2,
350 int *port1,
351 int *port2);
352 int xc_evtchn_bind_virq(int xc_handle,
353 int virq,
354 int *port);
356 /**
357 * This function will close a single port on an event channel.
358 *
359 * @parm xc_handle a handle to an open hypervisor interface
360 * @parm dom the domain that the port exists on. May be DOMID_SELF.
361 * @parm port the port to close
362 * @return 0 on success, -1 on error
363 */
364 int xc_evtchn_close(int xc_handle,
365 u32 dom, /* may be DOMID_SELF */
366 int port);
368 /**
369 * This function generates a notify event on a bound port.
370 *
371 * Notifies can be read within Linux by opening /dev/xen/evtchn and reading
372 * a 16 bit value. The result will be the port the event occurred on. When
373 * events occur, the port is masked until the 16 bit port value is written back
374 * to the file. When /dev/xen/evtchn is opened, it has to be bound via an
375 * ioctl to each port to listen on. The ioctl for binding is _IO('E', 2). The
376 * parameter is the port to listen on.
377 *
378 * @parm xc_handle a handle to an open hypervisor interface
379 * @parm local_port the port to generate the notify on
380 * @return 0 on success, -1 on error
381 */
382 int xc_evtchn_send(int xc_handle,
383 int local_port);
384 int xc_evtchn_status(int xc_handle,
385 u32 dom, /* may be DOMID_SELF */
386 int port,
387 xc_evtchn_status_t *status);
389 int xc_physdev_pci_access_modify(int xc_handle,
390 u32 domid,
391 int bus,
392 int dev,
393 int func,
394 int enable);
396 int xc_readconsolering(int xc_handle,
397 char **pbuffer,
398 unsigned int *pnr_chars,
399 int clear);
401 typedef dom0_physinfo_t xc_physinfo_t;
402 int xc_physinfo(int xc_handle,
403 xc_physinfo_t *info);
405 int xc_sched_id(int xc_handle,
406 int *sched_id);
408 int xc_domain_setmaxmem(int xc_handle,
409 u32 domid,
410 unsigned int max_memkb);
412 int xc_domain_memory_increase_reservation(int xc_handle,
413 u32 domid,
414 unsigned int mem_kb);
416 typedef dom0_perfc_desc_t xc_perfc_desc_t;
417 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc array. */
418 int xc_perfc_control(int xc_handle,
419 u32 op,
420 xc_perfc_desc_t *desc);
422 /* read/write msr */
423 long long xc_msr_read(int xc_handle, int cpu_mask, int msr);
424 int xc_msr_write(int xc_handle, int cpu_mask, int msr, unsigned int low,
425 unsigned int high);
427 /**
428 * Memory maps a range within one domain to a local address range. Mappings
429 * should be unmapped with munmap and should follow the same rules as mmap
430 * regarding page alignment. Returns NULL on failure.
431 *
432 * In Linux, the ring queue for the control channel is accessible by mapping
433 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
434 * stored there is of type control_if_t.
435 *
436 * @parm xc_handle a handle on an open hypervisor interface
437 * @parm dom the domain to map memory from
438 * @parm size the amount of memory to map (in multiples of page size)
439 * @parm prot same flag as in mmap().
440 * @parm mfn the frame address to map.
441 */
442 void *xc_map_foreign_range(int xc_handle, u32 dom,
443 int size, int prot,
444 unsigned long mfn );
446 void *xc_map_foreign_batch(int xc_handle, u32 dom, int prot,
447 unsigned long *arr, int num );
449 int xc_get_pfn_list(int xc_handle, u32 domid, unsigned long *pfn_buf,
450 unsigned long max_pfns);
452 /*\
453 * GRANT TABLE FUNCTIONS
454 \*/
456 /**
457 * This function opens a handle to the more restricted grant table hypervisor
458 * interface. This may be used where the standard interface is not
459 * available because the domain is not privileged.
460 * This function can be called multiple times within a single process.
461 * Multiple processes can have an open hypervisor interface at the same time.
462 *
463 * Each call to this function should have a corresponding call to
464 * xc_grant_interface_close().
465 *
466 * This function can fail if a Xen-enabled kernel is not currently running.
467 *
468 * @return a handle to the hypervisor grant table interface or -1 on failure
469 */
470 int xc_grant_interface_open(void);
472 /**
473 * This function closes an open grant table hypervisor interface.
474 *
475 * This function can fail if the handle does not represent an open interface or
476 * if there were problems closing the interface.
477 *
478 * @parm xc_handle a handle to an open grant table hypervisor interface
479 * @return 0 on success, -1 otherwise.
480 */
481 int xc_grant_interface_close(int xc_handle);
483 int xc_gnttab_map_grant_ref(int xc_handle,
484 memory_t host_virt_addr,
485 u32 dom,
486 u16 ref,
487 u16 flags,
488 s16 *handle,
489 memory_t *dev_bus_addr);
491 int xc_gnttab_unmap_grant_ref(int xc_handle,
492 memory_t host_virt_addr,
493 memory_t dev_bus_addr,
494 u16 handle,
495 s16 *status);
497 int xc_gnttab_setup_table(int xc_handle,
498 u32 dom,
499 u16 nr_frames,
500 s16 *status,
501 memory_t **frame_list);
503 /* Grant debug builds only: */
504 int xc_gnttab_dump_table(int xc_handle,
505 u32 dom,
506 s16 *status);
508 /* Get current total pages allocated to a domain. */
509 long xc_get_tot_pages(int xc_handle, u32 domid);
511 /* Execute a privileged dom0 operation. */
512 int xc_dom0_op(int xc_handle, dom0_op_t *op);
514 #endif /* __XC_H__ */