direct-io.hg

annotate tools/libxc/xc.h @ 5498:ae0cf78f78bd

bitkeeper revision 1.1159.258.169 (42b35222QJFB1A-V4mSUnrUrLfA8xA)

[PATCH] RE: [Xen-devel] DOM0_GETDOMAININFO intended behavior

Ok... now that I (unintentionally) went overboard on this, why not just
document how it works and leave it as is?

signed-off-by: dsteklof@us.ibm.com
signed-off-by: ian@xensource.com
author dsteklof@us.ibm.com[iap10]
date Fri Jun 17 22:43:46 2005 +0000 (2005-06-17)
parents 6d86ef2aeb06
children 0d1166678d9b
rev   line source
mjw@1623 1 /******************************************************************************
mjw@1623 2 * xc.h
mjw@1623 3 *
mjw@1623 4 * A library for low-level access to the Xen control interfaces.
mjw@1623 5 *
kaf24@2787 6 * Copyright (c) 2003-2004, K A Fraser.
mjw@1623 7 */
mjw@1623 8
mjw@1623 9 #ifndef __XC_H__
mjw@1623 10 #define __XC_H__
mjw@1623 11
kaf24@3266 12 #include <stdint.h>
kaf24@3266 13 typedef uint8_t u8;
kaf24@3266 14 typedef uint16_t u16;
kaf24@3266 15 typedef uint32_t u32;
kaf24@3266 16 typedef uint64_t u64;
kaf24@3266 17 typedef int8_t s8;
kaf24@3266 18 typedef int16_t s16;
kaf24@3266 19 typedef int32_t s32;
kaf24@3266 20 typedef int64_t s64;
mjw@1623 21
kaf24@2821 22 #include <xen/xen.h>
kaf24@2821 23 #include <xen/dom0_ops.h>
kaf24@2821 24 #include <xen/event_channel.h>
kaf24@2821 25 #include <xen/sched_ctl.h>
kaf24@2821 26 #include <xen/io/domain_controller.h>
kaf24@2787 27
iap10@3443 28 /*\
iap10@3443 29 * INITIALIZATION FUNCTIONS
iap10@3443 30 \*/
iap10@3443 31
iap10@3443 32 /**
iap10@3443 33 * This function opens a handle to the hypervisor interface. This function can
iap10@3443 34 * be called multiple times within a single process. Multiple processes can
iap10@3443 35 * have an open hypervisor interface at the same time.
iap10@3443 36 *
iap10@3443 37 * Each call to this function should have a corresponding call to
iap10@3443 38 * xc_interface_close().
iap10@3443 39 *
iap10@3443 40 * This function can fail if the caller does not have superuser permission or
iap10@3443 41 * if a Xen-enabled kernel is not currently running.
iap10@3443 42 *
iap10@3443 43 * @return a handle to the hypervisor interface or -1 on failure
iap10@3443 44 */
mjw@1623 45 int xc_interface_open(void);
iap10@3443 46
iap10@3443 47 /**
iap10@3443 48 * This function closes an open hypervisor interface.
iap10@3443 49 *
iap10@3443 50 * This function can fail if the handle does not represent an open interface or
iap10@3443 51 * if there were problems closing the interface.
iap10@3443 52 *
iap10@3443 53 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 54 * @return 0 on success, -1 otherwise.
iap10@3443 55 */
mjw@1623 56 int xc_interface_close(int xc_handle);
mjw@1623 57
iap10@3443 58 /*\
iap10@3443 59 * DOMAIN MANAGEMENT FUNCTIONS
iap10@3443 60 \*/
iap10@3443 61
mjw@1623 62 typedef struct {
mjw@1623 63 u32 domid;
mjw@1623 64 unsigned int cpu;
mjw@1623 65 unsigned int dying:1, crashed:1, shutdown:1,
mjw@1623 66 paused:1, blocked:1, running:1;
mjw@1623 67 unsigned int shutdown_reason; /* only meaningful if shutdown==1 */
mjw@1623 68 unsigned long nr_pages;
mjw@1623 69 unsigned long shared_info_frame;
mjw@1623 70 u64 cpu_time;
mjw@1623 71 unsigned long max_memkb;
mjw@1623 72 } xc_dominfo_t;
mjw@1623 73
kaf24@2787 74 typedef dom0_getdomaininfo_t xc_domaininfo_t;
mjw@1623 75 int xc_domain_create(int xc_handle,
mjw@1623 76 unsigned int mem_kb,
mjw@1623 77 int cpu,
gm281@2236 78 float cpu_weight,
mjw@1623 79 u32 *pdomid);
iap10@3443 80
iap10@3443 81 /**
iap10@3443 82 * This function pauses a domain. A paused domain still exists in memory
iap10@3443 83 * however it does not receive any timeslices from the hypervisor.
iap10@3443 84 *
iap10@3443 85 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 86 * @parm domid the domain id to pause
iap10@3443 87 * @return 0 on success, -1 on failure.
iap10@3443 88 */
mjw@1623 89 int xc_domain_pause(int xc_handle,
mjw@1623 90 u32 domid);
iap10@3443 91 /**
iap10@3443 92 * This function unpauses a domain. The domain should have been previously
iap10@3443 93 * paused.
iap10@3443 94 *
iap10@3443 95 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 96 * @parm domid the domain id to unpause
iap10@3443 97 * return 0 on success, -1 on failure
iap10@3443 98 */
mjw@1623 99 int xc_domain_unpause(int xc_handle,
mjw@1623 100 u32 domid);
iap10@3443 101
iap10@3443 102 /**
iap10@3443 103 * This function will destroy a domain. Destroying a domain removes the domain
iap10@3443 104 * completely from memory. This function should be called after sending the
iap10@3443 105 * domain a SHUTDOWN control message to free up the domain resources.
iap10@3443 106 *
iap10@3443 107 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 108 * @parm domid the domain id to destroy
iap10@3443 109 * @return 0 on success, -1 on failure
iap10@3443 110 */
mjw@1623 111 int xc_domain_destroy(int xc_handle,
mjw@1623 112 u32 domid);
mjw@1623 113 int xc_domain_pincpu(int xc_handle,
mjw@1623 114 u32 domid,
mjw@1623 115 int cpu);
iap10@3443 116 /**
dsteklof@5498 117 * This function will return information about one or more domains. It is
dsteklof@5498 118 * designed to iterate over the list of domains. If a single domain is
dsteklof@5498 119 * requested, this function will return the next domain in the list - if
dsteklof@5498 120 * one exists. It is, therefore, important in this case to make sure the
dsteklof@5498 121 * domain requested was the one returned.
iap10@3443 122 *
iap10@3443 123 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 124 * @parm first_domid the first domain to enumerate information from. Domains
iap10@3443 125 * are currently enumerate in order of creation.
iap10@3443 126 * @parm max_doms the number of elements in info
iap10@3443 127 * @parm info an array of max_doms size that will contain the information for
iap10@3443 128 * the enumerated domains.
iap10@3443 129 * @return the number of domains enumerated or -1 on error
iap10@3443 130 */
mjw@1623 131 int xc_domain_getinfo(int xc_handle,
mjw@1623 132 u32 first_domid,
mjw@1623 133 unsigned int max_doms,
mjw@1623 134 xc_dominfo_t *info);
iap10@3443 135
iap10@3443 136 /**
iap10@3443 137 * This function returns information about one domain. This information is
iap10@3443 138 * more detailed than the information from xc_domain_getinfo().
iap10@3443 139 *
iap10@3443 140 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 141 * @parm domid the domain to get information from
iap10@3443 142 * @parm info a pointer to an xc_domaininfo_t to store the domain information
iap10@3443 143 * @parm ctxt a pointer to a structure to store the execution context of the
iap10@3443 144 * domain
iap10@3443 145 * @return 0 on success, -1 on failure
iap10@3443 146 */
kaf24@2787 147 int xc_domain_getfullinfo(int xc_handle,
kaf24@2787 148 u32 domid,
kaf24@2787 149 xc_domaininfo_t *info,
kaf24@2787 150 full_execution_context_t *ctxt);
gm281@2236 151 int xc_domain_setcpuweight(int xc_handle,
gm281@2236 152 u32 domid,
gm281@2236 153 float weight);
kaf24@2787 154 long long xc_domain_get_cpu_usage(int xc_handle,
kaf24@2787 155 domid_t domid);
mjw@1623 156
kaf24@2787 157
kaf24@2787 158 typedef dom0_shadow_control_stats_t xc_shadow_control_stats_t;
mjw@1623 159 int xc_shadow_control(int xc_handle,
mjw@1623 160 u32 domid,
mjw@1623 161 unsigned int sop,
mjw@1623 162 unsigned long *dirty_bitmap,
mjw@1623 163 unsigned long pages,
mjw@1623 164 xc_shadow_control_stats_t *stats);
mjw@1623 165
mjw@1623 166
mjw@2574 167 #define XCFLAGS_VERBOSE 1
mjw@2574 168 #define XCFLAGS_LIVE 2
mjw@2574 169 #define XCFLAGS_DEBUG 4
mjw@2574 170 #define XCFLAGS_CONFIGURE 8
mjw@1623 171
mjw@1623 172 struct XcIOContext;
iap10@3443 173
iap10@3443 174 /**
iap10@3443 175 * This function will save a domain running Linux to an IO context. This
iap10@3443 176 * IO context is currently a private interface making this function difficult
iap10@3443 177 * to call. It's interface will likely change in the future.
iap10@3443 178 *
iap10@3443 179 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 180 * @parm ioctxt the IO context to save a domain to
iap10@3443 181 * @return 0 on success, -1 on failure
iap10@3443 182 */
mjw@1623 183 int xc_linux_save(int xc_handle, struct XcIOContext *ioctxt);
iap10@3443 184
iap10@3443 185 /**
iap10@3443 186 * This function will restore a saved domain running Linux to an IO context.
iap10@3443 187 * Like xc_linux_save(), this function uses a parameter who's structure is
iap10@3443 188 * privately defined. It's interface will also likely change.
iap10@3443 189 *
iap10@3443 190 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 191 * @parm ioctxt the IO context to restore a domain from
iap10@3443 192 * @return 0 on success, -1 on failure
iap10@3443 193 */
mjw@1623 194 int xc_linux_restore(int xc_handle, struct XcIOContext *ioctxt);
mjw@1623 195
mjw@1623 196 int xc_linux_build(int xc_handle,
mjw@1623 197 u32 domid,
mjw@1623 198 const char *image_name,
mjw@1623 199 const char *ramdisk_name,
mjw@1623 200 const char *cmdline,
mjw@1623 201 unsigned int control_evtchn,
mjw@1623 202 unsigned long flags);
mjw@1623 203
iap10@3326 204 int
iap10@3326 205 xc_plan9_build (int xc_handle,
iap10@3326 206 u32 domid,
iap10@3326 207 const char *image_name,
iap10@3326 208 const char *cmdline,
iap10@3326 209 unsigned int control_evtchn,
iap10@3326 210 unsigned long flags);
iap10@3326 211
mjw@1623 212 int xc_bvtsched_global_set(int xc_handle,
mjw@1623 213 unsigned long ctx_allow);
mjw@1623 214
mjw@1623 215 int xc_bvtsched_domain_set(int xc_handle,
mjw@1623 216 u32 domid,
gm281@2058 217 u32 mcuadv,
gm281@2058 218 int warpback,
gm281@2058 219 s32 warpvalue,
gm281@2058 220 long long warpl,
gm281@2058 221 long long warpu);
mjw@1623 222
mjw@1623 223 int xc_bvtsched_global_get(int xc_handle,
mjw@1623 224 unsigned long *ctx_allow);
mjw@1623 225
mjw@1623 226 int xc_bvtsched_domain_get(int xc_handle,
mjw@1623 227 u32 domid,
gm281@2058 228 u32 *mcuadv,
gm281@2058 229 int *warpback,
gm281@2058 230 s32 *warpvalue,
gm281@2058 231 long long *warpl,
gm281@2058 232 long long *warpu);
mjw@1623 233
mjw@1623 234 int xc_atropos_domain_set(int xc_handle,
mjw@1623 235 u32 domid,
mjw@1623 236 u64 period, u64 slice, u64 latency,
mjw@1623 237 int xtratime);
mjw@1623 238
mjw@1623 239 int xc_atropos_domain_get(int xc_handle,
mjw@1623 240 u32 domid,
mjw@1623 241 u64* period, u64 *slice, u64 *latency,
mjw@1623 242 int *xtratime);
mjw@1623 243
mjw@1623 244 int xc_rrobin_global_set(int xc_handle, u64 slice);
mjw@1623 245
mjw@1623 246 int xc_rrobin_global_get(int xc_handle, u64 *slice);
mjw@1623 247
kaf24@2787 248 typedef evtchn_status_t xc_evtchn_status_t;
iap10@3443 249
iap10@3443 250 /*\
iap10@3443 251 * EVENT CHANNEL FUNCTIONS
iap10@3443 252 \*/
iap10@3443 253
iap10@3443 254 /**
iap10@3443 255 * This function allocates an unbound port. Ports are named endpoints used for
iap10@3443 256 * interdomain communication. This function is most useful in opening a
iap10@3443 257 * well-known port within a domain to receive events on.
iap10@3443 258 *
iap10@3443 259 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 260 * @parm dom the ID of the domain. This maybe DOMID_SELF
iap10@3443 261 * @parm port a pointer to a port. This is an in/out parameter. If *port is
iap10@3443 262 * 0, then a new port will be assigned, if port is > 0 then that
iap10@3443 263 * port is allocated if the port is unallocated.
iap10@3443 264 * @return 0 on success, -1 on failure
iap10@3443 265 */
kaf24@2713 266 int xc_evtchn_alloc_unbound(int xc_handle,
kaf24@2713 267 u32 dom,
kaf24@2713 268 int *port);
iap10@3443 269
iap10@3443 270 /**
iap10@3443 271 * This function creates a pair of ports between two domains. A port can only
iap10@3443 272 * be bound once within a domain.
iap10@3443 273 *
iap10@3443 274 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 275 * @parm dom1 one of the two domains to connect. Can be DOMID_SELF.
iap10@3443 276 * @parm dom2 the other domain to connect. Can be DOMID_SELF.
iap10@3443 277 * @parm port1 an in/out parameter. If > 0, then try to connect *port. If
iap10@3443 278 * 0, then allocate a new port and store the port in *port.
iap10@3443 279 * @parm port2 the port connected on port2. This parameter behaves the same
iap10@3443 280 * way as port1.
iap10@3443 281 * @return 0 on success, -1 on error.
iap10@3443 282 */
mjw@1623 283 int xc_evtchn_bind_interdomain(int xc_handle,
iap10@3443 284 u32 dom1,
iap10@3443 285 u32 dom2,
mjw@1623 286 int *port1,
mjw@1623 287 int *port2);
mjw@1623 288 int xc_evtchn_bind_virq(int xc_handle,
mjw@1623 289 int virq,
mjw@1623 290 int *port);
iap10@3443 291
iap10@3443 292 /**
iap10@3443 293 * This function will close a single port on an event channel.
iap10@3443 294 *
iap10@3443 295 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 296 * @parm dom the domain that the port exists on. May be DOMID_SELF.
iap10@3443 297 * @parm port the port to close
iap10@3443 298 * @return 0 on success, -1 on error
iap10@3443 299 */
mjw@1623 300 int xc_evtchn_close(int xc_handle,
mjw@1623 301 u32 dom, /* may be DOMID_SELF */
mjw@1623 302 int port);
iap10@3443 303
iap10@3443 304 /**
iap10@3443 305 * This function generates a notify event on a bound port.
iap10@3443 306 *
iap10@3443 307 * Notifies can be read within Linux by opening /dev/xen/evtchn and reading
iap10@3443 308 * a 16 bit value. The result will be the port the event occurred on. When
iap10@3443 309 * events occur, the port is masked until the 16 bit port value is written back
iap10@3443 310 * to the file. When /dev/xen/evtchn is opened, it has to be bound via an
iap10@3443 311 * ioctl to each port to listen on. The ioctl for binding is _IO('E', 2). The
iap10@3443 312 * parameter is the port to listen on.
iap10@3443 313 *
iap10@3443 314 * @parm xc_handle a handle to an open hypervisor interface
iap10@3443 315 * @parm local_port the port to generate the notify on
iap10@3443 316 * @return 0 on success, -1 on error
iap10@3443 317 */
mjw@1623 318 int xc_evtchn_send(int xc_handle,
mjw@1623 319 int local_port);
mjw@1623 320 int xc_evtchn_status(int xc_handle,
mjw@1623 321 u32 dom, /* may be DOMID_SELF */
mjw@1623 322 int port,
mjw@1623 323 xc_evtchn_status_t *status);
mjw@1623 324
mjw@1623 325 int xc_physdev_pci_access_modify(int xc_handle,
mjw@1623 326 u32 domid,
mjw@1623 327 int bus,
mjw@1623 328 int dev,
mjw@1623 329 int func,
mjw@1623 330 int enable);
mjw@1623 331
mjw@1623 332 int xc_readconsolering(int xc_handle,
mjw@1623 333 char *str,
mjw@1623 334 unsigned int max_chars,
mjw@1623 335 int clear);
mjw@1623 336
kaf24@2787 337 typedef dom0_physinfo_t xc_physinfo_t;
mjw@1623 338 int xc_physinfo(int xc_handle,
mjw@1623 339 xc_physinfo_t *info);
mjw@1623 340
gm281@2236 341 int xc_sched_id(int xc_handle,
gm281@2236 342 int *sched_id);
gm281@2236 343
mjw@1623 344 int xc_domain_setinitialmem(int xc_handle,
mjw@1623 345 u32 domid,
mjw@1623 346 unsigned int initial_memkb);
mjw@1623 347
mjw@1623 348 int xc_domain_setmaxmem(int xc_handle,
kaf24@3231 349 u32 domid,
kaf24@3231 350 unsigned int max_memkb);
mjw@1623 351
cl349@2449 352 int xc_domain_setvmassist(int xc_handle,
cl349@2449 353 u32 domid,
cl349@2449 354 unsigned int cmd,
cl349@2449 355 unsigned int type);
cl349@2449 356
kaf24@3231 357 typedef dom0_perfc_desc_t xc_perfc_desc_t;
kaf24@3231 358 /* IMPORTANT: The caller is responsible for mlock()'ing the @desc array. */
kaf24@3231 359 int xc_perfc_control(int xc_handle,
kaf24@3231 360 u32 op,
kaf24@3231 361 xc_perfc_desc_t *desc);
mjw@1623 362
iap10@3443 363 /**
iap10@3443 364 * Memory maps a range within one domain to a local address range. Mappings
iap10@3443 365 * should be unmapped with munmap and should follow the same rules as mmap
iap10@3443 366 * regarding page alignment.
iap10@3443 367 *
iap10@3443 368 * In Linux, the ring queue for the control channel is accessible by mapping
iap10@3443 369 * the shared_info_frame (from xc_domain_getinfo()) + 2048. The structure
iap10@3443 370 * stored there is of type control_if_t.
iap10@3443 371 *
iap10@3443 372 * @parm xc_handle a handle on an open hypervisor interface
iap10@3443 373 * @parm dom the domain to map memory from
iap10@3443 374 * @parm size the amount of memory to map (in multiples of page size)
iap10@3443 375 * @parm prot same flag as in mmap().
iap10@3443 376 * @parm mfn the frame address to map.
iap10@3443 377 */
iap10@2325 378 void *xc_map_foreign_range(int xc_handle, u32 dom,
iap10@2325 379 int size, int prot,
iap10@2325 380 unsigned long mfn );
iap10@2325 381
iap10@2325 382 void *xc_map_foreign_batch(int xc_handle, u32 dom, int prot,
iap10@2325 383 unsigned long *arr, int num );
iap10@2325 384
mjw@1623 385 #endif /* __XC_H__ */