ia64/xen-unstable

changeset 3443:6d86ef2aeb06

bitkeeper revision 1.1159.170.97 (41e94301axLnKknTNgYWn0ZFj5pHxg)

Documentation of xc.h library
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
author iap10@labyrinth.cl.cam.ac.uk
date Sat Jan 15 16:21:21 2005 +0000 (2005-01-15)
parents 565871eff231
children 5dd6907756ef 4138bf07f607
files tools/libxc/xc.h
line diff
     1.1 --- a/tools/libxc/xc.h	Sat Jan 15 11:18:02 2005 +0000
     1.2 +++ b/tools/libxc/xc.h	Sat Jan 15 16:21:21 2005 +0000
     1.3 @@ -25,10 +25,40 @@ typedef int64_t            s64;
     1.4  #include <xen/sched_ctl.h>
     1.5  #include <xen/io/domain_controller.h>
     1.6  
     1.7 -/* Obtain or relinquish a handle on the 'xc' library. */
     1.8 +/*\
     1.9 + *  INITIALIZATION FUNCTIONS
    1.10 +\*/ 
    1.11 +
    1.12 +/**
    1.13 + * This function opens a handle to the hypervisor interface.  This function can
    1.14 + * be called multiple times within a single process.  Multiple processes can
    1.15 + * have an open hypervisor interface at the same time.
    1.16 + *
    1.17 + * Each call to this function should have a corresponding call to
    1.18 + * xc_interface_close().
    1.19 + *
    1.20 + * This function can fail if the caller does not have superuser permission or
    1.21 + * if a Xen-enabled kernel is not currently running.
    1.22 + *
    1.23 + * @return a handle to the hypervisor interface or -1 on failure
    1.24 + */
    1.25  int xc_interface_open(void);
    1.26 +
    1.27 +/**
    1.28 + * This function closes an open hypervisor interface.
    1.29 + *
    1.30 + * This function can fail if the handle does not represent an open interface or
    1.31 + * if there were problems closing the interface.
    1.32 + *
    1.33 + * @parm xc_handle a handle to an open hypervisor interface
    1.34 + * @return 0 on success, -1 otherwise.
    1.35 + */
    1.36  int xc_interface_close(int xc_handle);
    1.37  
    1.38 +/*\
    1.39 + * DOMAIN MANAGEMENT FUNCTIONS
    1.40 +\*/
    1.41 +
    1.42  typedef struct {
    1.43      u32           domid;
    1.44      unsigned int  cpu;
    1.45 @@ -47,19 +77,69 @@ int xc_domain_create(int xc_handle,
    1.46                       int cpu,
    1.47                       float cpu_weight,
    1.48                       u32 *pdomid);
    1.49 +
    1.50 +/**
    1.51 + * This function pauses a domain. A paused domain still exists in memory
    1.52 + * however it does not receive any timeslices from the hypervisor.
    1.53 + *
    1.54 + * @parm xc_handle a handle to an open hypervisor interface
    1.55 + * @parm domid the domain id to pause
    1.56 + * @return 0 on success, -1 on failure.
    1.57 + */
    1.58  int xc_domain_pause(int xc_handle, 
    1.59                      u32 domid);
    1.60 +/**
    1.61 + * This function unpauses a domain.  The domain should have been previously
    1.62 + * paused.
    1.63 + *
    1.64 + * @parm xc_handle a handle to an open hypervisor interface
    1.65 + * @parm domid the domain id to unpause
    1.66 + * return 0 on success, -1 on failure
    1.67 + */
    1.68  int xc_domain_unpause(int xc_handle, 
    1.69                        u32 domid);
    1.70 +
    1.71 +/**
    1.72 + * This function will destroy a domain.  Destroying a domain removes the domain
    1.73 + * completely from memory.  This function should be called after sending the
    1.74 + * domain a SHUTDOWN control message to free up the domain resources.
    1.75 + *
    1.76 + * @parm xc_handle a handle to an open hypervisor interface
    1.77 + * @parm domid the domain id to destroy
    1.78 + * @return 0 on success, -1 on failure
    1.79 + */
    1.80  int xc_domain_destroy(int xc_handle, 
    1.81                        u32 domid);
    1.82  int xc_domain_pincpu(int xc_handle,
    1.83                       u32 domid,
    1.84                       int cpu);
    1.85 +/**
    1.86 + * This function will return information about one or more domains.
    1.87 + *
    1.88 + * @parm xc_handle a handle to an open hypervisor interface
    1.89 + * @parm first_domid the first domain to enumerate information from.  Domains
    1.90 + *                   are currently enumerate in order of creation.
    1.91 + * @parm max_doms the number of elements in info
    1.92 + * @parm info an array of max_doms size that will contain the information for
    1.93 + *            the enumerated domains.
    1.94 + * @return the number of domains enumerated or -1 on error
    1.95 + */
    1.96  int xc_domain_getinfo(int xc_handle,
    1.97                        u32 first_domid, 
    1.98                        unsigned int max_doms,
    1.99                        xc_dominfo_t *info);
   1.100 +
   1.101 +/**
   1.102 + * This function returns information about one domain.  This information is
   1.103 + * more detailed than the information from xc_domain_getinfo().
   1.104 + *
   1.105 + * @parm xc_handle a handle to an open hypervisor interface
   1.106 + * @parm domid the domain to get information from
   1.107 + * @parm info a pointer to an xc_domaininfo_t to store the domain information
   1.108 + * @parm ctxt a pointer to a structure to store the execution context of the
   1.109 + *            domain
   1.110 + * @return 0 on success, -1 on failure
   1.111 + */
   1.112  int xc_domain_getfullinfo(int xc_handle,
   1.113                            u32 domid,
   1.114                            xc_domaininfo_t *info,
   1.115 @@ -86,7 +166,27 @@ int xc_shadow_control(int xc_handle,
   1.116  #define XCFLAGS_CONFIGURE 8
   1.117  
   1.118  struct XcIOContext;
   1.119 +
   1.120 +/**
   1.121 + * This function will save a domain running Linux to an IO context.  This
   1.122 + * IO context is currently a private interface making this function difficult
   1.123 + * to call.  It's interface will likely change in the future.
   1.124 + *
   1.125 + * @parm xc_handle a handle to an open hypervisor interface
   1.126 + * @parm ioctxt the IO context to save a domain to
   1.127 + * @return 0 on success, -1 on failure
   1.128 + */
   1.129  int xc_linux_save(int xc_handle, struct XcIOContext *ioctxt);
   1.130 +
   1.131 +/**
   1.132 + * This function will restore a saved domain running Linux to an IO context.
   1.133 + * Like xc_linux_save(), this function uses a parameter who's structure is
   1.134 + * privately defined.  It's interface will also likely change.
   1.135 + *
   1.136 + * @parm xc_handle a handle to an open hypervisor interface
   1.137 + * @parm ioctxt the IO context to restore a domain from
   1.138 + * @return 0 on success, -1 on failure
   1.139 + */
   1.140  int xc_linux_restore(int xc_handle, struct XcIOContext *ioctxt);
   1.141  
   1.142  int xc_linux_build(int xc_handle,
   1.143 @@ -142,20 +242,75 @@ int xc_rrobin_global_set(int xc_handle, 
   1.144  int xc_rrobin_global_get(int xc_handle, u64 *slice);
   1.145  
   1.146  typedef evtchn_status_t xc_evtchn_status_t;
   1.147 +
   1.148 +/*\
   1.149 + * EVENT CHANNEL FUNCTIONS
   1.150 +\*/
   1.151 +
   1.152 +/**
   1.153 + * This function allocates an unbound port.  Ports are named endpoints used for
   1.154 + * interdomain communication.  This function is most useful in opening a
   1.155 + * well-known port within a domain to receive events on.
   1.156 + *
   1.157 + * @parm xc_handle a handle to an open hypervisor interface
   1.158 + * @parm dom the ID of the domain.  This maybe DOMID_SELF
   1.159 + * @parm port a pointer to a port.  This is an in/out parameter.  If *port is
   1.160 + *            0, then a new port will be assigned, if port is > 0 then that
   1.161 + *            port is allocated if the port is unallocated.
   1.162 + * @return 0 on success, -1 on failure
   1.163 + */
   1.164  int xc_evtchn_alloc_unbound(int xc_handle,
   1.165                              u32 dom,
   1.166                              int *port);
   1.167 +
   1.168 +/**
   1.169 + * This function creates a pair of ports between two domains.  A port can only
   1.170 + * be bound once within a domain.
   1.171 + *
   1.172 + * @parm xc_handle a handle to an open hypervisor interface
   1.173 + * @parm dom1 one of the two domains to connect.  Can be DOMID_SELF.
   1.174 + * @parm dom2 the other domain to connect.  Can be DOMID_SELF.
   1.175 + * @parm port1 an in/out parameter.  If > 0, then try to connect *port.  If
   1.176 + *             0, then allocate a new port and store the port in *port.
   1.177 + * @parm port2 the port connected on port2.  This parameter behaves the same
   1.178 + *             way as port1.
   1.179 + * @return 0 on success, -1 on error.
   1.180 + */
   1.181  int xc_evtchn_bind_interdomain(int xc_handle,
   1.182 -                               u32 dom1,   /* may be DOMID_SELF */
   1.183 -                               u32 dom2,   /* may be DOMID_SELF */
   1.184 +                               u32 dom1,
   1.185 +                               u32 dom2,
   1.186                                 int *port1,
   1.187                                 int *port2);
   1.188  int xc_evtchn_bind_virq(int xc_handle,
   1.189                          int virq,
   1.190                          int *port);
   1.191 +
   1.192 +/**
   1.193 + * This function will close a single port on an event channel.
   1.194 + *
   1.195 + * @parm xc_handle a handle to an open hypervisor interface
   1.196 + * @parm dom the domain that the port exists on.  May be DOMID_SELF.
   1.197 + * @parm port the port to close
   1.198 + * @return 0 on success, -1 on error
   1.199 + */
   1.200  int xc_evtchn_close(int xc_handle,
   1.201                      u32 dom,   /* may be DOMID_SELF */
   1.202                      int port);
   1.203 +
   1.204 +/**
   1.205 + * This function generates a notify event on a bound port.
   1.206 + *
   1.207 + * Notifies can be read within Linux by opening /dev/xen/evtchn and reading
   1.208 + * a 16 bit value.  The result will be the port the event occurred on.  When
   1.209 + * events occur, the port is masked until the 16 bit port value is written back
   1.210 + * to the file.  When /dev/xen/evtchn is opened, it has to be bound via an
   1.211 + * ioctl to each port to listen on.  The ioctl for binding is _IO('E', 2).  The
   1.212 + * parameter is the port to listen on.
   1.213 + *
   1.214 + * @parm xc_handle a handle to an open hypervisor interface
   1.215 + * @parm local_port the port to generate the notify on
   1.216 + * @return 0 on success, -1 on error
   1.217 + */
   1.218  int xc_evtchn_send(int xc_handle,
   1.219                     int local_port);
   1.220  int xc_evtchn_status(int xc_handle,
   1.221 @@ -201,6 +356,21 @@ int xc_perfc_control(int xc_handle,
   1.222                       u32 op,
   1.223                       xc_perfc_desc_t *desc);
   1.224  
   1.225 +/**
   1.226 + * Memory maps a range within one domain to a local address range.  Mappings
   1.227 + * should be unmapped with munmap and should follow the same rules as mmap
   1.228 + * regarding page alignment.
   1.229 + *
   1.230 + * In Linux, the ring queue for the control channel is accessible by mapping
   1.231 + * the shared_info_frame (from xc_domain_getinfo()) + 2048.  The structure
   1.232 + * stored there is of type control_if_t.
   1.233 + *
   1.234 + * @parm xc_handle a handle on an open hypervisor interface
   1.235 + * @parm dom the domain to map memory from
   1.236 + * @parm size the amount of memory to map (in multiples of page size)
   1.237 + * @parm prot same flag as in mmap().
   1.238 + * @parm mfn the frame address to map.
   1.239 + */
   1.240  void *xc_map_foreign_range(int xc_handle, u32 dom,
   1.241                              int size, int prot,
   1.242                              unsigned long mfn );