debuggers.hg

view tools/libxc/xc.h @ 4647:9c88ba91d330

bitkeeper revision 1.1346.1.1 (42670505dNhgnJm5dQD81pCalXMZgw)

manual merge
author iap10@freefall.cl.cam.ac.uk
date Thu Apr 21 01:42:29 2005 +0000 (2005-04-21)
parents 7fc6eac6da3a 3dc193a9786a
children 86285c9c18c1
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 <xen/xen.h>
24 #include <xen/dom0_ops.h>
25 #include <xen/event_channel.h>
26 #include <xen/sched_ctl.h>
28 /*
29 * DEFINITIONS FOR CPU BARRIERS
30 */
32 #if defined(__i386__)
33 #define mb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
34 #define rmb() __asm__ __volatile__ ( "lock; addl $0,0(%%esp)" : : : "memory" )
35 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
36 #elif defined(__x86_64__)
37 #define mb() __asm__ __volatile__ ( "mfence" : : : "memory")
38 #define rmb() __asm__ __volatile__ ( "lfence" : : : "memory")
39 #define wmb() __asm__ __volatile__ ( "" : : : "memory")
40 #else
41 #error "Define barriers"
42 #endif
44 /*
45 * INITIALIZATION FUNCTIONS
46 */
48 /**
49 * This function opens a handle to the hypervisor interface. This function can
50 * be called multiple times within a single process. Multiple processes can
51 * have an open hypervisor interface at the same time.
52 *
53 * Each call to this function should have a corresponding call to
54 * xc_interface_close().
55 *
56 * This function can fail if the caller does not have superuser permission or
57 * if a Xen-enabled kernel is not currently running.
58 *
59 * @return a handle to the hypervisor interface or -1 on failure
60 */
61 int xc_interface_open(void);
63 /**
64 * This function closes an open hypervisor interface.
65 *
66 * This function can fail if the handle does not represent an open interface or
67 * if there were problems closing the interface.
68 *
69 * @parm xc_handle a handle to an open hypervisor interface
70 * @return 0 on success, -1 otherwise.
71 */
72 int xc_interface_close(int xc_handle);
74 /*
75 * DOMAIN MANAGEMENT FUNCTIONS
76 */
78 typedef struct {
79 u32 domid;
80 unsigned int cpu;
81 unsigned int dying:1, crashed:1, shutdown:1,
82 paused:1, blocked:1, running:1;
83 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
84 unsigned long nr_pages;
85 unsigned long shared_info_frame;
86 u64 cpu_time;
87 unsigned long max_memkb;
88 } xc_dominfo_t;
90 typedef dom0_getdomaininfo_t xc_domaininfo_t;
91 int xc_domain_create(int xc_handle,
92 unsigned int mem_kb,
93 int cpu,
94 float cpu_weight,
95 u32 *pdomid);
97 /**
98 * This function pauses a domain. A paused domain still exists in memory
99 * however it does not receive any timeslices from the hypervisor.
100 *
101 * @parm xc_handle a handle to an open hypervisor interface
102 * @parm domid the domain id to pause
103 * @return 0 on success, -1 on failure.
104 */
105 int xc_domain_pause(int xc_handle,
106 u32 domid);
107 /**
108 * This function unpauses a domain. The domain should have been previously
109 * paused.
110 *
111 * @parm xc_handle a handle to an open hypervisor interface
112 * @parm domid the domain id to unpause
113 * return 0 on success, -1 on failure
114 */
115 int xc_domain_unpause(int xc_handle,
116 u32 domid);
118 /**
119 * This function will destroy a domain. Destroying a domain removes the domain
120 * completely from memory. This function should be called after sending the
121 * domain a SHUTDOWN control message to free up the domain resources.
122 *
123 * @parm xc_handle a handle to an open hypervisor interface
124 * @parm domid the domain id to destroy
125 * @return 0 on success, -1 on failure
126 */
127 int xc_domain_destroy(int xc_handle,
128 u32 domid);
129 int xc_domain_pincpu(int xc_handle,
130 u32 domid,
131 int cpu);
132 /**
133 * This function will return information about one or more domains.
134 *
135 * @parm xc_handle a handle to an open hypervisor interface
136 * @parm first_domid the first domain to enumerate information from. Domains
137 * are currently enumerate in order of creation.
138 * @parm max_doms the number of elements in info
139 * @parm info an array of max_doms size that will contain the information for
140 * the enumerated domains.
141 * @return the number of domains enumerated or -1 on error
142 */
143 int xc_domain_getinfo(int xc_handle,
144 u32 first_domid,
145 unsigned int max_doms,
146 xc_dominfo_t *info);
148 /**
149 * This function returns information about one domain. This information is
150 * more detailed than the information from xc_domain_getinfo().
151 *
152 * @parm xc_handle a handle to an open hypervisor interface
153 * @parm domid the domain to get information from
154 * @parm info a pointer to an xc_domaininfo_t to store the domain information
155 * @parm ctxt a pointer to a structure to store the execution context of the
156 * domain
157 * @return 0 on success, -1 on failure
158 */
159 int xc_domain_getfullinfo(int xc_handle,
160 u32 domid,
161 u32 vcpu,
162 xc_domaininfo_t *info,
163 full_execution_context_t *ctxt);
164 int xc_domain_setcpuweight(int xc_handle,
165 u32 domid,
166 float weight);
167 long long xc_domain_get_cpu_usage(int xc_handle,
168 domid_t domid,
169 int vcpu);
172 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
173 int xc_shadow_control(int xc_handle,
174 u32 domid,
175 unsigned int sop,
176 unsigned long *dirty_bitmap,
177 unsigned long pages,
178 xc_shadow_control_stats_t *stats);
181 #define XCFLAGS_VERBOSE 1
182 #define XCFLAGS_LIVE 2
183 #define XCFLAGS_DEBUG 4
184 #define XCFLAGS_CONFIGURE 8
186 struct XcIOContext;
188 /**
189 * This function will save a domain running Linux to an IO context. This
190 * IO context is currently a private interface making this function difficult
191 * to call. It's interface will likely change in the future.
192 *
193 * @parm xc_handle a handle to an open hypervisor interface
194 * @parm ioctxt the IO context to save a domain to
195 * @return 0 on success, -1 on failure
196 */
197 int xc_linux_save(int xc_handle, struct XcIOContext *ioctxt);
199 /**
200 * This function will restore a saved domain running Linux to an IO context.
201 * Like xc_linux_save(), this function uses a parameter who's structure is
202 * privately defined. It's interface will also likely change.
203 *
204 * @parm xc_handle a handle to an open hypervisor interface
205 * @parm ioctxt the IO context to restore a domain from
206 * @return 0 on success, -1 on failure
207 */
208 int xc_linux_restore(int xc_handle, struct XcIOContext *ioctxt);
210 int xc_linux_build(int xc_handle,
211 u32 domid,
212 const char *image_name,
213 const char *ramdisk_name,
214 const char *cmdline,
215 unsigned int control_evtchn,
216 unsigned long flags,
217 unsigned int vcpus);
219 int
220 xc_plan9_build (int xc_handle,
221 u32 domid,
222 const char *image_name,
223 const char *cmdline,
224 unsigned int control_evtchn,
225 unsigned long flags);
227 struct mem_map;
228 int xc_vmx_build(int xc_handle,
229 u32 domid,
230 int memsize,
231 const char *image_name,
232 struct mem_map *memmap,
233 const char *ramdisk_name,
234 const char *cmdline,
235 unsigned int control_evtchn,
236 unsigned long flags);
238 int xc_bvtsched_global_set(int xc_handle,
239 unsigned long ctx_allow);
241 int xc_bvtsched_domain_set(int xc_handle,
242 u32 domid,
243 u32 mcuadv,
244 int warpback,
245 s32 warpvalue,
246 long long warpl,
247 long long warpu);
249 int xc_bvtsched_global_get(int xc_handle,
250 unsigned long *ctx_allow);
252 int xc_bvtsched_domain_get(int xc_handle,
253 u32 domid,
254 u32 *mcuadv,
255 int *warpback,
256 s32 *warpvalue,
257 long long *warpl,
258 long long *warpu);
260 int xc_sedf_domain_set(int xc_handle,
261 u32 domid,
262 u64 period, u64 slice, u64 latency, u16 extratime, u16 weight);
264 int xc_sedf_domain_get(int xc_handle,
265 u32 domid,
266 u64* period, u64 *slice, u64 *latency, u16 *extratime, u16* weight);
268 typedef evtchn_status_t xc_evtchn_status_t;
270 /*
271 * EVENT CHANNEL FUNCTIONS
272 */
274 /**
275 * This function allocates an unbound port. Ports are named endpoints used for
276 * interdomain communication. This function is most useful in opening a
277 * well-known port within a domain to receive events on.
278 *
279 * @parm xc_handle a handle to an open hypervisor interface
280 * @parm dom the ID of the domain. This maybe DOMID_SELF
281 * @parm port a pointer to a port. This is an in/out parameter. If *port is
282 * 0, then a new port will be assigned, if port is > 0 then that
283 * port is allocated if the port is unallocated.
284 * @return 0 on success, -1 on failure
285 */
286 int xc_evtchn_alloc_unbound(int xc_handle,
287 u32 dom,
288 int *port);
290 /**
291 * This function creates a pair of ports between two domains. A port can only
292 * be bound once within a domain.
293 *
294 * @parm xc_handle a handle to an open hypervisor interface
295 * @parm dom1 one of the two domains to connect. Can be DOMID_SELF.
296 * @parm dom2 the other domain to connect. Can be DOMID_SELF.
297 * @parm port1 an in/out parameter. If > 0, then try to connect *port. If
298 * 0, then allocate a new port and store the port in *port.
299 * @parm port2 the port connected on port2. This parameter behaves the same
300 * way as port1.
301 * @return 0 on success, -1 on error.
302 */
303 int xc_evtchn_bind_interdomain(int xc_handle,
304 u32 dom1,
305 u32 dom2,
306 int *port1,
307 int *port2);
308 int xc_evtchn_bind_virq(int xc_handle,
309 int virq,
310 int *port);
312 /**
313 * This function will close a single port on an event channel.
314 *
315 * @parm xc_handle a handle to an open hypervisor interface
316 * @parm dom the domain that the port exists on. May be DOMID_SELF.
317 * @parm port the port to close
318 * @return 0 on success, -1 on error
319 */
320 int xc_evtchn_close(int xc_handle,
321 u32 dom, /* may be DOMID_SELF */
322 int port);
324 /**
325 * This function generates a notify event on a bound port.
326 *
327 * Notifies can be read within Linux by opening /dev/xen/evtchn and reading
328 * a 16 bit value. The result will be the port the event occurred on. When
329 * events occur, the port is masked until the 16 bit port value is written back
330 * to the file. When /dev/xen/evtchn is opened, it has to be bound via an
331 * ioctl to each port to listen on. The ioctl for binding is _IO('E', 2). The
332 * parameter is the port to listen on.
333 *
334 * @parm xc_handle a handle to an open hypervisor interface
335 * @parm local_port the port to generate the notify on
336 * @return 0 on success, -1 on error
337 */
338 int xc_evtchn_send(int xc_handle,
339 int local_port);
340 int xc_evtchn_status(int xc_handle,
341 u32 dom, /* may be DOMID_SELF */
342 int port,
343 xc_evtchn_status_t *status);
345 int xc_physdev_pci_access_modify(int xc_handle,
346 u32 domid,
347 int bus,
348 int dev,
349 int func,
350 int enable);
352 int xc_readconsolering(int xc_handle,
353 char *str,
354 unsigned int max_chars,
355 int clear);
357 typedef dom0_physinfo_t xc_physinfo_t;
358 int xc_physinfo(int xc_handle,
359 xc_physinfo_t *info);
361 int xc_sched_id(int xc_handle,
362 int *sched_id);
364 int xc_domain_setinitialmem(int xc_handle,
365 u32 domid,
366 unsigned int initial_memkb);
368 int xc_domain_setmaxmem(int xc_handle,
369 u32 domid,
370 unsigned int max_memkb);
372 typedef dom0_perfc_desc_t xc_perfc_desc_t;
373 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc array. */
374 int xc_perfc_control(int xc_handle,
375 u32 op,
376 xc_perfc_desc_t *desc);
378 /* read/write msr */
379 long long xc_msr_read(int xc_handle, int cpu_mask, int msr);
380 int xc_msr_write(int xc_handle, int cpu_mask, int msr, unsigned int low,
381 unsigned int high);
383 /**
384 * Memory maps a range within one domain to a local address range. Mappings
385 * should be unmapped with munmap and should follow the same rules as mmap
386 * regarding page alignment.
387 *
388 * In Linux, the ring queue for the control channel is accessible by mapping
389 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
390 * stored there is of type control_if_t.
391 *
392 * @parm xc_handle a handle on an open hypervisor interface
393 * @parm dom the domain to map memory from
394 * @parm size the amount of memory to map (in multiples of page size)
395 * @parm prot same flag as in mmap().
396 * @parm mfn the frame address to map.
397 */
398 void *xc_map_foreign_range(int xc_handle, u32 dom,
399 int size, int prot,
400 unsigned long mfn );
402 void *xc_map_foreign_batch(int xc_handle, u32 dom, int prot,
403 unsigned long *arr, int num );
405 int xc_get_pfn_list(int xc_handle, u32 domid, unsigned long *pfn_buf,
406 unsigned long max_pfns);
408 /*\
409 * GRANT TABLE FUNCTIONS
410 \*/
412 /**
413 * This function opens a handle to the more restricted grant table hypervisor
414 * interface. This may be used where the standard interface is not
415 * available because the domain is not privileged.
416 * This function can be called multiple times within a single process.
417 * Multiple processes can have an open hypervisor interface at the same time.
418 *
419 * Each call to this function should have a corresponding call to
420 * xc_grant_interface_close().
421 *
422 * This function can fail if a Xen-enabled kernel is not currently running.
423 *
424 * @return a handle to the hypervisor grant table interface or -1 on failure
425 */
426 int xc_grant_interface_open(void);
428 /**
429 * This function closes an open grant table hypervisor interface.
430 *
431 * This function can fail if the handle does not represent an open interface or
432 * if there were problems closing the interface.
433 *
434 * @parm xc_handle a handle to an open grant table hypervisor interface
435 * @return 0 on success, -1 otherwise.
436 */
437 int xc_grant_interface_close(int xc_handle);
439 int xc_gnttab_map_grant_ref(int xc_handle,
440 memory_t host_virt_addr,
441 u32 dom,
442 u16 ref,
443 u16 flags,
444 s16 *handle,
445 memory_t *dev_bus_addr);
447 int xc_gnttab_unmap_grant_ref(int xc_handle,
448 memory_t host_virt_addr,
449 memory_t dev_bus_addr,
450 u16 handle,
451 s16 *status);
453 int xc_gnttab_setup_table(int xc_handle,
454 u32 dom,
455 u16 nr_frames,
456 s16 *status,
457 memory_t **frame_list);
459 /* Grant debug builds only: */
460 int xc_gnttab_dump_table(int xc_handle,
461 u32 dom,
462 s16 *status);
465 #endif /* __XC_H__ */