1.1 --- a/docs/src/interface.tex	Mon Nov 01 16:33:44 2004 +0000
     1.2 +++ b/docs/src/interface.tex	Mon Nov 01 17:05:45 2004 +0000
     1.3 @@ -525,7 +525,11 @@ Hypercalls are invoked in a manner analo
     1.4  conventional operating system; a software interrupt is issued which
     1.5  vectors to an entry point within Xen. On x86\_32 machines the
     1.6  instruction required is {\tt int \$82}; the (real) IDT is setup so
     1.7 -that this may only be issued from within ring 1.
     1.8 +that this may only be issued from within ring 1. The particular 
     1.9 +hypercall to be invoked is contained in {\tt EAX} --- a list 
    1.10 +mapping these values to symbolic hypercall names can be found 
    1.11 +in {\tt xen/include/public/xen.h}. 
    1.12 +
    1.13  
    1.14  On some occasions a set of hypercalls will be required to carry
    1.15  out a higher-level function; a good example is when a guest 
    1.16 @@ -543,6 +547,9 @@ call\_list}. Each entry contains the hyp
    1.17  by up to 7 word-sized arguments.
    1.18  \end{quote}
    1.19  
    1.20 +Note that multicalls are provided purely as an optimization; there is
    1.21 +no requirement to use them when first porting a guest operating
    1.22 +system.
    1.23  
    1.24  
    1.25  \section{Virtual CPU Setup} 
    1.26 @@ -561,7 +568,7 @@ use when it wishes to notify the guest O
    1.27  
    1.28  Register the normal (``event'') and failsafe callbacks for 
    1.29  event processing. In each case the code segment selector and 
    1.30 -address withing that segment are provided. The selectors must
    1.31 +address within that segment are provided. The selectors must
    1.32  have RPL 1; in XenLinux we simply use the kernel's CS for both 
    1.33  {\tt event\_selector} and {\tt failsafe\_selector}.
    1.34  
    1.35 @@ -572,15 +579,41 @@ when Xen attempts to use the normal call
    1.36  \end{quote} 
    1.37  
    1.38  
    1.39 +After installing the hypervisor callbacks, the guest OS can 
    1.40 +install a `virtual IDT' by using the following hypercall: 
    1.41 +
    1.42 +\begin{quote} 
    1.43  \hypercall{set\_trap\_table(trap\_info\_t *table)} 
    1.44  
    1.45 -Install trap handler table.
    1.46 +Install one or more entries into the per-domain 
    1.47 +trap handler table (essentially a software version of the IDT). 
    1.48 +Each entry in the array pointed to by {\tt table} includes the 
    1.49 +exception vector number with the corresponding segement selector 
    1.50 +and entry point. Most guest OSes can use the same handlers on 
    1.51 +Xen as when running on the real hardware; an exception is the 
    1.52 +page fault handler (exception vector 14) where a modified 
    1.53 +stack-frame layout is used. 
    1.54  
    1.55  
    1.56 +\end{quote} 
    1.57 +
    1.58 +Finally, as an optimization it is possible for each guest OS 
    1.59 +to install one ``fast trap'': this is a trap gate which will 
    1.60 +allow direct transfer of control from ring 3 into ring 1 without
    1.61 +indirecting via Xen. In most cases this is suitable for use by 
    1.62 +the guest OS system call mechanism, although it may be used for
    1.63 +any purpose. 
    1.64 +
    1.65 +
    1.66 +\begin{quote}
    1.67  \hypercall{set\_fast\_trap(int idx)}
    1.68  
    1.69 - install traps to allow guest OS to bypass hypervisor
    1.70 +Install the handler for exception vector {\tt idx} as the ``fast
    1.71 +trap'' for this domaim. Note that this installs the current handler 
    1.72 +(i.e. that which has been installed previously via a call 
    1.73 +to {\tt set\_trap\_table()}). 
    1.74  
    1.75 +\end{quote}
    1.76  
    1.77  
    1.78