ia64/xen-unstable

changeset 2824:702b7ec55776

bitkeeper revision 1.1159.1.335 (4187be71RLo0Og_rlHhOrsashHTMyA)

more iface updates
author smh22@tempest.cl.cam.ac.uk
date Tue Nov 02 17:05:53 2004 +0000 (2004-11-02)
parents 3772ff7c4023
children 9a63b52734c4
files BitKeeper/etc/ignore docs/src/interface.tex
line diff
     1.1 --- a/BitKeeper/etc/ignore	Tue Nov 02 15:54:40 2004 +0000
     1.2 +++ b/BitKeeper/etc/ignore	Tue Nov 02 17:05:53 2004 +0000
     1.3 @@ -53,3 +53,23 @@ xen/tools/figlet/figlet
     1.4  xen/xen
     1.5  xen/xen-syms
     1.6  xen/xen.*
     1.7 +docs/interface/WARNINGS
     1.8 +docs/interface/images.pl
     1.9 +docs/interface/images.tex
    1.10 +docs/interface/img1.png
    1.11 +docs/interface/index.html
    1.12 +docs/interface/interface.css
    1.13 +docs/interface/interface.html
    1.14 +docs/interface/labels.pl
    1.15 +docs/user/WARNINGS
    1.16 +docs/user/images.pl
    1.17 +docs/user/images.tex
    1.18 +docs/user/img1.png
    1.19 +docs/user/img2.png
    1.20 +docs/user/img3.png
    1.21 +docs/user/index.html
    1.22 +docs/user/internals.pl
    1.23 +docs/user/labels.pl
    1.24 +docs/user/user.css
    1.25 +docs/user/user.html
    1.26 +linux-xen-sparse
     2.1 --- a/docs/src/interface.tex	Tue Nov 02 15:54:40 2004 +0000
     2.2 +++ b/docs/src/interface.tex	Tue Nov 02 17:05:53 2004 +0000
     2.3 @@ -196,6 +196,7 @@ implement timeout values when they block
     2.4  
     2.5  
     2.6  \chapter{Memory}
     2.7 +\label{c:memory} 
     2.8  
     2.9  Xen is responsible for managing the allocation of physical memory to
    2.10  domains, and for ensuring safe use of the paging and segmentation
    2.11 @@ -530,7 +531,6 @@ hypercall to be invoked is contained in 
    2.12  mapping these values to symbolic hypercall names can be found 
    2.13  in {\tt xen/include/public/xen.h}. 
    2.14  
    2.15 -
    2.16  On some occasions a set of hypercalls will be required to carry
    2.17  out a higher-level function; a good example is when a guest 
    2.18  operating wishes to context switch to a new process which 
    2.19 @@ -574,7 +574,7 @@ have RPL 1; in XenLinux we simply use th
    2.20  
    2.21  The value {\tt event\_address} specifies the address of the guest OSes
    2.22  event handling and dispatch routine; the {\tt failsafe\_address}
    2.23 -specifies separate entry point which is used only if a fault occurs
    2.24 +specifies a separate entry point which is used only if a fault occurs
    2.25  when Xen attempts to use the normal callback. 
    2.26  \end{quote} 
    2.27  
    2.28 @@ -609,63 +609,121 @@ any purpose.
    2.29  \hypercall{set\_fast\_trap(int idx)}
    2.30  
    2.31  Install the handler for exception vector {\tt idx} as the ``fast
    2.32 -trap'' for this domaim. Note that this installs the current handler 
    2.33 -(i.e. that which has been installed previously via a call 
    2.34 +trap'' for this domain. Note that this installs the current handler 
    2.35 +(i.e. that which has been installed more recently via a call 
    2.36  to {\tt set\_trap\_table()}). 
    2.37  
    2.38  \end{quote}
    2.39  
    2.40  
    2.41  
    2.42 -\section{Scheduling} 
    2.43 -
    2.44 -
    2.45 -\hypercall{stack\_switch(unsigned long ss, unsigned long esp)} 
    2.46 -
    2.47 -Request context switch from hypervisor.
    2.48 +\section{Scheduling and Timer}
    2.49  
    2.50 -
    2.51 -\hypercall{fpu\_taskswitch(void)} 
    2.52 +Domains are premptively scheduled by Xen according to the 
    2.53 +parameters installed by Domain-0 (see Section~\ref{s:dom0ops}). 
    2.54 +In addition, however, a domain may choose to explicitly 
    2.55 +control certain behaviour with the following hypercall: 
    2.56  
    2.57 -Notify hypervisor that fpu registers needed to be save on context switch.
    2.58 -
    2.59 -
    2.60 +\begin{quote} 
    2.61  \hypercall{sched\_op(unsigned long op)} 
    2.62  
    2.63  Request scheduling operation from hypervisor. The options are: {\it
    2.64  yield}, {\it block}, and {\it shutdown}.  {\it yield} keeps the
    2.65 -calling domain run-able but may cause a reschedule if other domains
    2.66 -are run-able.  {\it block} removes the calling domain from the run
    2.67 -queue and the domains sleeps until an event is delivered to it.  {\it
    2.68 -shutdown} is used to end the domain's execution and allows to specify
    2.69 -whether the domain should reboot, halt or suspend..
    2.70 +calling domain runnable but may cause a reschedule if other domains
    2.71 +are runnable.  {\it block} removes the calling domain from the run
    2.72 +queue and cause is to sleeps until an event is delivered to it.  {\it
    2.73 +shutdown} is used to end the domain's execution; the caller can
    2.74 +additionally specify whether the domain should reboot, halt or
    2.75 +suspend.
    2.76 +\end{quote} 
    2.77  
    2.78 +To aid the implementation of a process scheduler within a guest OS,
    2.79 +Xen provides a virtual programmable timer:
    2.80 +
    2.81 +\begin{quote}
    2.82  \hypercall{set\_timer\_op(uint64\_t timeout)} 
    2.83  
    2.84 -Request a timer event to be sent at the specified system time.
    2.85 +Request a timer event to be sent at the specified system time (time 
    2.86 +in nanoseconds since system boot). The hypercall actually passes the 
    2.87 +64-bit timeout value as a pair of 32-bit values. 
    2.88 +
    2.89 +\end{quote} 
    2.90 +
    2.91 +Note that calling {\tt set\_timer\_op()} prior to {\tt sched\_op} 
    2.92 +allows block-with-timeout semantics. 
    2.93  
    2.94  
    2.95  \section{Page Table Management} 
    2.96  
    2.97 +Since guest operating systems have read-only access to their page 
    2.98 +tables, Xen must be involved when making any changes. The following
    2.99 +multi-purpose hypercall can be used to modify page-table entries, 
   2.100 +update the machine-to-physical mapping table, flush the TLB, install 
   2.101 +a new page-table base pointer, and more.
   2.102 +
   2.103 +\begin{quote} 
   2.104  \hypercall{mmu\_update(mmu\_update\_t *req, int count, int *success\_count)} 
   2.105  
   2.106 -Update the page table for the domain. Updates can be batched.
   2.107 -success\_count will be updated to report the number of successfull
   2.108 -updates.  The update types are:
   2.109 +Update the page table for the domain; a set of {\tt count} updates are
   2.110 +submitted for processing in a batch, with {\tt success\_count} being 
   2.111 +updated to report the number of successfull updates.  
   2.112 +
   2.113 +Each element of {\tt req[]} contains a pointer (address) and value; 
   2.114 +the least significant 2-bits of the pointer are used to distinguish 
   2.115 +the type of update requested as follows:
   2.116 +\begin{description} 
   2.117 +
   2.118 +\item[\it MMU\_NORMAL\_PT\_UPDATE:] update a page directory entry or
   2.119 +page table entry to the associated value; Xen will check that the
   2.120 +update is safe, as described in Chapter~\ref{c:memory}.
   2.121  
   2.122 -{\it MMU\_NORMAL\_PT\_UPDATE}:
   2.123 +\item[\it MMU\_MACHPHYS\_UPDATE:] update an entry in the
   2.124 +  machine-to-physical table. The calling domain must own the machine
   2.125 +  page in question (or be privileged).
   2.126  
   2.127 -{\it MMU\_MACHPHYS\_UPDATE}:
   2.128 +\item[\it MMU\_EXTENDED\_COMMAND:] perform additional MMU operations.
   2.129 +The set of additional MMU operations is considerable, and includes
   2.130 +updating {\tt cr3} (or just re-installing it for a TLB flush),
   2.131 +flushing the cache, installing a new LDT, or pinning \& unpinning
   2.132 +page-table pages (to ensure their reference count doesn't drop to zero
   2.133 +which would require a revalidation of all entries).
   2.134  
   2.135 -{\it MMU\_EXTENDED\_COMMAND}:
   2.136 +Further extended commands are used to deal with granting and 
   2.137 +acquiring page ownership; see Section~\ref{s:idc}. 
   2.138  
   2.139  
   2.140 -\hypercall{update\_va\_mapping(unsigned long page\_nr, unsigned long val, unsigned long flags)}
   2.141 +\end{description}
   2.142 +
   2.143 +More details on the precise format of all commands can be 
   2.144 +found in {\tt xen/include/public/xen.h}. 
   2.145 +
   2.146 +
   2.147 +\end{quote}
   2.148 +
   2.149 +Explicitly updating batches of page table entries is extremely
   2.150 +efficient, but can require a number of alterations to the guest 
   2.151 +OS. Using the writable page table mode is recommended 
   2.152 +for new OS ports. 
   2.153  
   2.154 +However in either mode, there are some occasions (in particular
   2.155 +handling a demand page fault) where a guest OS will wish to 
   2.156 +modify exactly one PTE rather than a batch. This is catered 
   2.157 +for by the following hypercall: 
   2.158 +
   2.159 +\begin{quote} 
   2.160 +\hypercall{update\_va\_mapping(unsigned long page\_nr, unsigned long
   2.161 +val, unsigned long flags)}
   2.162 +
   2.163 +\end{quote} 
   2.164 +
   2.165 +Finally, privileged domains may be able to xxx. 
   2.166 +
   2.167 +\begin{quote}
   2.168  
   2.169  \hypercall{update\_va\_mapping\_otherdomain(unsigned long page\_nr,
   2.170  unsigned long val, unsigned long flags, uint16\_t domid)}
   2.171  
   2.172 +\end{quote}
   2.173  
   2.174  \section{Segmentation Support}
   2.175  
   2.176 @@ -679,9 +737,22 @@ Set the global descriptor table - virtua
   2.177  \hypercall{update\_descriptor(unsigned long ma, unsigned long word1, unsigned long word2)} 
   2.178  
   2.179  
   2.180 +\section{Context Switching} 
   2.181 +
   2.182 +\hypercall{stack\_switch(unsigned long ss, unsigned long esp)} 
   2.183 +
   2.184 +Request context switch from hypervisor.
   2.185 +
   2.186 +
   2.187 +\hypercall{fpu\_taskswitch(void)} 
   2.188 +
   2.189 +Notify hypervisor that fpu registers needed to be save on context switch.
   2.190 +
   2.191 +
   2.192  
   2.193  
   2.194  \section{Inter-Domain Communication}
   2.195 +\label{s:idc} 
   2.196  
   2.197  
   2.198  \hypercall{event\_channel\_op(void *op)} 
   2.199 @@ -706,7 +777,7 @@ Increase or decrease memory reservations
   2.200  
   2.201  
   2.202  \section{Administrative Operations}
   2.203 -
   2.204 +\label{s:dom0ops}
   2.205  
   2.206  \hypercall{dom0\_op(dom0\_op\_t *op)} 
   2.207