1.1 --- a/docs/src/interface.tex	Mon Nov 01 15:53:14 2004 +0000
     1.2 +++ b/docs/src/interface.tex	Mon Nov 01 16:33:44 2004 +0000
     1.3 @@ -521,24 +521,56 @@ categorizes and describes the current se
     1.4  
     1.5  \section{Invoking Hypercalls} 
     1.6  
     1.7 +Hypercalls are invoked in a manner analogous to system calls in a
     1.8 +conventional operating system; a software interrupt is issued which
     1.9 +vectors to an entry point within Xen. On x86\_32 machines the
    1.10 +instruction required is {\tt int \$82}; the (real) IDT is setup so
    1.11 +that this may only be issued from within ring 1.
    1.12 +
    1.13 +On some occasions a set of hypercalls will be required to carry
    1.14 +out a higher-level function; a good example is when a guest 
    1.15 +operating wishes to context switch to a new process which 
    1.16 +requires updating various privileged CPU state. As an optimization
    1.17 +for these cases, there is a generic mechanism to issue a set of 
    1.18 +hypercalls as a batch: 
    1.19 +
    1.20 +\begin{quote}
    1.21  \hypercall{multicall(void *call\_list, int nr\_calls)}
    1.22  
    1.23 -Execute a series of hypervisor calls
    1.24 -
    1.25 +Execute a series of hypervisor calls; {\tt nr\_calls} is the length of
    1.26 +the array of {\tt multicall\_entry\_t} structures pointed to be {\tt
    1.27 +call\_list}. Each entry contains the hypercall operation code followed
    1.28 +by up to 7 word-sized arguments.
    1.29 +\end{quote}
    1.30  
    1.31  
    1.32  
    1.33  \section{Virtual CPU Setup} 
    1.34  
    1.35 +At start of day, a guest operating system needs to setup the virtual
    1.36 +CPU it is executing on. This includes installing vectors for the
    1.37 +virtual IDT so that the guest OS can handle interrupts, page faults,
    1.38 +etc. However the very first thing a guest OS must setup is a pair 
    1.39 +of hypervisor callbacks: these are the entry points which Xen will
    1.40 +use when it wishes to notify the guest OS of an occurrence. 
    1.41 +
    1.42 +\begin{quote}
    1.43  \hypercall{set\_callbacks(unsigned long event\_selector, unsigned long
    1.44    event\_address, unsigned long failsafe\_selector, unsigned long
    1.45    failsafe\_address) }
    1.46  
    1.47 -Register OS event processing routine.  In
    1.48 -Linux both the event\_selector and failsafe\_selector are the
    1.49 -kernel's CS.  The value event\_address specifies the address for an
    1.50 -interrupt handler dispatch routine and failsafe\_address specifies a
    1.51 -handler for application faults.
    1.52 +Register the normal (``event'') and failsafe callbacks for 
    1.53 +event processing. In each case the code segment selector and 
    1.54 +address withing that segment are provided. The selectors must
    1.55 +have RPL 1; in XenLinux we simply use the kernel's CS for both 
    1.56 +{\tt event\_selector} and {\tt failsafe\_selector}.
    1.57 +
    1.58 +The value {\tt event\_address} specifies the address of the guest OSes
    1.59 +event handling and dispatch routine; the {\tt failsafe\_address}
    1.60 +specifies separate entry point which is used only if a fault occurs
    1.61 +when Xen attempts to use the normal callback. 
    1.62 +\end{quote} 
    1.63 +
    1.64  
    1.65  \hypercall{set\_trap\_table(trap\_info\_t *table)} 
    1.66