direct-io.hg

changeset 9252:f85bb99187bf

Update interface documentation to include sched_op_new hypercall
and clean up the style a bit. Also clean up the sched_op_new
description in the sched.h public header.

Signed-off-by: Keir Fraser <keir@xensource.com>
author kaf24@firebug.cl.cam.ac.uk
date Wed Mar 15 19:19:22 2006 +0100 (2006-03-15)
parents 96ba0a2bc9de
children d3b0d74702b5
files docs/src/interface.tex xen/include/public/sched.h
line diff
     1.1 --- a/docs/src/interface.tex	Wed Mar 15 13:35:43 2006 +0100
     1.2 +++ b/docs/src/interface.tex	Wed Mar 15 19:19:22 2006 +0100
     1.3 @@ -128,7 +128,7 @@ A list of all hypercalls is given in App
     1.4  \section{Exceptions}
     1.5  
     1.6  A virtual IDT is provided --- a domain can submit a table of trap
     1.7 -handlers to Xen via the {\tt set\_trap\_table()} hypercall.  The
     1.8 +handlers to Xen via the {\bf set\_trap\_table} hypercall.  The
     1.9  exception stack frame presented to a virtual trap handler is identical
    1.10  to its native equivalent.
    1.11  
    1.12 @@ -137,7 +137,7 @@ to its native equivalent.
    1.13  
    1.14  Interrupts are virtualized by mapping them to \emph{event channels},
    1.15  which are delivered asynchronously to the target domain using a callback
    1.16 -supplied via the {\tt set\_callbacks()} hypercall.  A guest OS can map
    1.17 +supplied via the {\bf set\_callbacks} hypercall.  A guest OS can map
    1.18  these events onto its standard interrupt dispatch mechanisms.  Xen is
    1.19  responsible for determining the target domain that will handle each
    1.20  physical interrupt source. For more details on the binding of event
    1.21 @@ -167,7 +167,7 @@ is used for scheduling. The following no
    1.22  
    1.23  \item[Wall clock time.]
    1.24  
    1.25 -  This is the time of day in a Unix-style {\tt struct timeval}
    1.26 +  This is the time of day in a Unix-style {\bf struct timeval}
    1.27    (seconds and microseconds since 1 January 1970, adjusted by leap
    1.28    seconds).  An NTP client hosted by {\it domain 0} can keep this
    1.29    value accurate.
    1.30 @@ -200,8 +200,8 @@ currently executing domain every 10ms.  
    1.31  timer event whenever a domain is scheduled; this allows the guest OS
    1.32  to adjust for the time that has passed while it has been inactive.  In
    1.33  addition, Xen allows each domain to request that they receive a timer
    1.34 -event sent at a specified system time by using the {\tt
    1.35 -  set\_timer\_op()} hypercall.  Guest OSes may use this timer to
    1.36 +event sent at a specified system time by using the {\bf
    1.37 +  set\_timer\_op} hypercall.  Guest OSes may use this timer to
    1.38  implement timeout values when they block.
    1.39  
    1.40  
    1.41 @@ -232,7 +232,7 @@ load-balancing between CPUs.
    1.42  
    1.43  
    1.44  %% More information on the characteristics and use of these schedulers
    1.45 -%% is available in {\tt Sched-HOWTO.txt}.
    1.46 +%% is available in {\bf Sched-HOWTO.txt}.
    1.47  
    1.48  
    1.49  \section{Privileged operations}
    1.50 @@ -354,7 +354,7 @@ page-table page, when the domain is pree
    1.51  uses Xen's explicit page-table update interfaces.
    1.52  
    1.53  Writable pagetable functionality is enabled when the guest requests
    1.54 -it, using a {\tt vm\_assist} hypercall.  Writable pagetables do {\em
    1.55 +it, using a {\bf vm\_assist} hypercall.  Writable pagetables do {\em
    1.56  not} provide full virtualisation of the MMU, so the memory management
    1.57  code of the guest still needs to be aware that it is running on Xen.
    1.58  Since the guest's page tables are used directly, it must translate
    1.59 @@ -400,7 +400,7 @@ The following hypercall is used to speci
    1.60  \end{quote}
    1.61  
    1.62  The LDT is updated via the generic MMU update mechanism (i.e., via the
    1.63 -{\tt mmu\_update()} hypercall.
    1.64 +{\bf mmu\_update} hypercall.
    1.65  
    1.66  \section{Start of Day}
    1.67  
    1.68 @@ -423,8 +423,8 @@ extra functionality to a guest.
    1.69  
    1.70  \hypercall{vm\_assist(unsigned int cmd, unsigned int type)}
    1.71  
    1.72 -The {\tt cmd} parameter describes the action to be taken, whilst the
    1.73 -{\tt type} parameter describes the kind of assist that is being
    1.74 +The {\bf cmd} parameter describes the action to be taken, whilst the
    1.75 +{\bf type} parameter describes the kind of assist that is being
    1.76  referred to.  Available commands are as follows:
    1.77  
    1.78  \begin{description}
    1.79 @@ -453,18 +453,18 @@ between the guest OS and the hypervisor.
    1.80  status, time information and event channel (virtual interrupt) state.
    1.81  The {\bf Start info page} is used to pass build-time information to
    1.82  the guest when it boots and when it is resumed from a suspended state.
    1.83 -This chapter documents the fields included in the {\tt
    1.84 -shared\_info\_t} and {\tt start\_info\_t} structures for use by the
    1.85 +This chapter documents the fields included in the {\bf
    1.86 +shared\_info\_t} and {\bf start\_info\_t} structures for use by the
    1.87  guest OS.
    1.88  
    1.89  \section{Shared info page}
    1.90  
    1.91 -The {\tt shared\_info\_t} is accessed at run time by both Xen and the
    1.92 +The {\bf shared\_info\_t} is accessed at run time by both Xen and the
    1.93  guest OS.  It is used to pass information relating to the
    1.94  virtual CPU and virtual machine state between the OS and the
    1.95  hypervisor.
    1.96  
    1.97 -The structure is declared in {\tt xen/include/public/xen.h}:
    1.98 +The structure is declared in {\bf xen/include/public/xen.h}:
    1.99  
   1.100  \scriptsize
   1.101  \begin{verbatim}
   1.102 @@ -520,7 +520,7 @@ typedef struct shared_info {
   1.103  \normalsize
   1.104  
   1.105  \begin{description}
   1.106 -\item[vcpu\_info] An array of {\tt vcpu\_info\_t} structures, each of
   1.107 +\item[vcpu\_info] An array of {\bf vcpu\_info\_t} structures, each of
   1.108    which holds either runtime information about a virtual CPU, or is
   1.109    ``empty'' if the corresponding VCPU does not exist.
   1.110  \item[evtchn\_pending] Guest-global array, with one bit per event
   1.111 @@ -579,11 +579,11 @@ typedef struct vcpu_info {
   1.112    that there are pending events to be received.
   1.113  \item[evtchn\_upcall\_mask] This is set non-zero to disable all
   1.114    interrupts for this CPU for short periods of time.  If individual
   1.115 -  event channels need to be masked, the {\tt evtchn\_mask} in the {\tt
   1.116 +  event channels need to be masked, the {\bf evtchn\_mask} in the {\bf
   1.117    shared\_info\_t} is used instead.
   1.118  \item[evtchn\_pending\_sel] When an event is delivered to this VCPU, a
   1.119 -  bit is set in this selector to indicate which word of the {\tt
   1.120 -  evtchn\_pending} array in the {\tt shared\_info\_t} contains the
   1.121 +  bit is set in this selector to indicate which word of the {\bf
   1.122 +  evtchn\_pending} array in the {\bf shared\_info\_t} contains the
   1.123    event in question.
   1.124  \item[arch] Architecture-specific VCPU info. On x86 this contains the
   1.125    virtualized CR2 register (page fault linear address) for this VCPU.
   1.126 @@ -634,7 +634,7 @@ extrapolating current time).
   1.127  
   1.128  \subsection{arch\_shared\_info\_t}
   1.129  
   1.130 -On x86, the {\tt arch\_shared\_info\_t} is defined as follows (from
   1.131 +On x86, the {\bf arch\_shared\_info\_t} is defined as follows (from
   1.132  xen/public/arch-x86\_32.h):
   1.133  
   1.134  \scriptsize
   1.135 @@ -656,7 +656,7 @@ typedef struct arch_shared_info {
   1.136  
   1.137  \section{Start info page}
   1.138  
   1.139 -The start info structure is declared as the following (in {\tt
   1.140 +The start info structure is declared as the following (in {\bf
   1.141  xen/include/public/xen.h}):
   1.142  
   1.143  \scriptsize
   1.144 @@ -745,7 +745,7 @@ of certain operations in the guest kerne
   1.145  
   1.146  The event channel operation hypercall is used for all operations on
   1.147  event channels / ports.  Operations are distinguished by the value of
   1.148 -the {\tt cmd} field of the {\tt op} structure.  The possible commands
   1.149 +the {\bf cmd} field of the {\bf op} structure.  The possible commands
   1.150  are described below:
   1.151  
   1.152  \begin{description}
   1.153 @@ -880,12 +880,12 @@ table op hypercall takes three arguments
   1.154  
   1.155  \hypercall{grant\_table\_op(unsigned int cmd, void *uop, unsigned int count)}
   1.156  
   1.157 -{\tt cmd} indicates the grant table operation of interest.  {\tt uop}
   1.158 +{\bf cmd} indicates the grant table operation of interest.  {\bf uop}
   1.159  is a pointer to a structure (or an array of structures) describing the
   1.160 -operation to be performed.  The {\tt count} field describes how many
   1.161 +operation to be performed.  The {\bf count} field describes how many
   1.162  grant table operations are being batched together.
   1.163  
   1.164 -The core logic is situated in {\tt xen/common/grant\_table.c}.  The
   1.165 +The core logic is situated in {\bf xen/common/grant\_table.c}.  The
   1.166  grant table operation hypercall can be used to perform the following
   1.167  actions:
   1.168  
   1.169 @@ -957,9 +957,9 @@ There are three main paths in XenStore:
   1.170  \item[/tool] stores information for the various tools
   1.171  \end{description}
   1.172  
   1.173 -The {\tt /vm} path stores configuration information for a domain.
   1.174 +The {\bf /vm} path stores configuration information for a domain.
   1.175  This information doesn't change and is indexed by the domain's UUID.
   1.176 -A {\tt /vm} entry contains the following information:
   1.177 +A {\bf /vm} entry contains the following information:
   1.178  
   1.179  \begin{description}
   1.180  \item[ssidref] ssid reference for domain
   1.181 @@ -974,7 +974,7 @@ A {\tt /vm} entry contains the following
   1.182  \end{description}
   1.183  
   1.184  
   1.185 -{\tt /vm/$<$uuid$>$/image/}
   1.186 +{\bf /vm/$<$uuid$>$/image/}
   1.187  
   1.188  The image path is only available for Domain-Us and contains:
   1.189  \begin{description}
   1.190 @@ -984,7 +984,7 @@ The image path is only available for Dom
   1.191  \item[ramdisk] path to ramdisk on domain-0
   1.192  \end{description}
   1.193  
   1.194 -{\tt /local}
   1.195 +{\bf /local}
   1.196  
   1.197  The {\tt /local} path currently only contains one directory, {\tt
   1.198  /local/domain} that is indexed by domain id.  It contains the running
   1.199 @@ -993,7 +993,7 @@ during migration, the uuid doesn't chang
   1.200  {\tt /local/domain} directory can be created and populated before
   1.201  finalizing the migration enabling localhost to localhost migration.
   1.202  
   1.203 -{\tt /local/domain/$<$domid$>$}
   1.204 +{\bf /local/domain/$<$domid$>$}
   1.205  
   1.206  This path contains:
   1.207  
   1.208 @@ -1663,10 +1663,10 @@ Register the normal (``event'') and fail
   1.209  event processing. In each case the code segment selector and 
   1.210  address within that segment are provided. The selectors must
   1.211  have RPL 1; in XenLinux we simply use the kernel's CS for both 
   1.212 -{\tt event\_selector} and {\tt failsafe\_selector}.
   1.213 -
   1.214 -The value {\tt event\_address} specifies the address of the guest OSes
   1.215 -event handling and dispatch routine; the {\tt failsafe\_address}
   1.216 +{\bf event\_selector} and {\bf failsafe\_selector}.
   1.217 +
   1.218 +The value {\bf event\_address} specifies the address of the guest OSes
   1.219 +event handling and dispatch routine; the {\bf failsafe\_address}
   1.220  specifies a separate entry point which is used only if a fault occurs
   1.221  when Xen attempts to use the normal callback. 
   1.222  
   1.223 @@ -1692,7 +1692,7 @@ install a `virtual IDT' by using the fol
   1.224  
   1.225  Install one or more entries into the per-domain 
   1.226  trap handler table (essentially a software version of the IDT). 
   1.227 -Each entry in the array pointed to by {\tt table} includes the 
   1.228 +Each entry in the array pointed to by {\bf table} includes the 
   1.229  exception vector number with the corresponding segment selector 
   1.230  and entry point. Most guest OSes can use the same handlers on 
   1.231  Xen as when running on the real hardware.
   1.232 @@ -1718,18 +1718,45 @@ In addition, however, a domain may choos
   1.233  control certain behavior with the following hypercall: 
   1.234  
   1.235  \begin{quote} 
   1.236 -\hypercall{sched\_op(unsigned long op)} 
   1.237 -
   1.238 -Request scheduling operation from hypervisor. The options are: {\it
   1.239 -SCHEDOP\_yield}, {\it SCHEDOP\_block}, and {\it SCHEDOP\_shutdown}.
   1.240 -{\it yield} keeps the calling domain runnable but may cause a
   1.241 -reschedule if other domains are runnable.  {\it block} removes the
   1.242 -calling domain from the run queue and cause is to sleeps until an
   1.243 -event is delivered to it.  {\it shutdown} is used to end the domain's
   1.244 -execution; the caller can additionally specify whether the domain
   1.245 -should reboot, halt or suspend.
   1.246 +\hypercall{sched\_op\_new(int cmd, void *extra\_args)}
   1.247 +
   1.248 +Request scheduling operation from hypervisor. The following
   1.249 +sub-commands are available:
   1.250 +
   1.251 +\begin{description}
   1.252 +\item[SCHEDOP\_yield] voluntarily yields the CPU, but leaves the
   1.253 +caller marked as runnable. No extra arguments are passed to this
   1.254 +command. 
   1.255 +\item[SCHEDOP\_block] removes the calling domain from the run queue
   1.256 +and causes it to sleep until an event is delivered to it. No extra 
   1.257 +arguments are passed to this command. 
   1.258 +\item[SCHEDOP\_shutdown] is used to end the calling domain's
   1.259 +execution. The extra argument is a {\bf sched\_shutdown} structure
   1.260 +which indicates the reason why the domain suspended (e.g., for reboot,
   1.261 +halt, power-off).
   1.262 +\item[SCHEDOP\_poll] allows a VCPU to wait on a set of event channels
   1.263 +with an optional timeout (all of which are specified in the {\bf
   1.264 +sched\_poll} extra argument). The semantics are similar to the UNIX
   1.265 +{\bf poll} system call. The caller must have event-channel upcalls
   1.266 +masked when executing this command.
   1.267 +\end{description}
   1.268  \end{quote} 
   1.269  
   1.270 +{\bf sched\_op\_new}  was not available prior to Xen 3.0.2. Older versions
   1.271 +provide only the following hypercall:
   1.272 +
   1.273 +\begin{quote} 
   1.274 +\hypercall{sched\_op(int cmd, unsigned long extra\_arg)}
   1.275 +
   1.276 +This hypercall supports the following subset of {\bf sched\_op\_new} commands:
   1.277 +
   1.278 +\begin{description}
   1.279 +\item[SCHEDOP\_yield] (extra argument is 0).
   1.280 +\item[SCHEDOP\_block] (extra argument is 0).
   1.281 +\item[SCHEDOP\_shutdown] (extra argument is numeric reason code).
   1.282 +\end{description}
   1.283 +\end{quote}
   1.284 +
   1.285  To aid the implementation of a process scheduler within a guest OS,
   1.286  Xen provides a virtual programmable timer:
   1.287  
   1.288 @@ -1737,12 +1764,11 @@ Xen provides a virtual programmable time
   1.289  \hypercall{set\_timer\_op(uint64\_t timeout)} 
   1.290  
   1.291  Request a timer event to be sent at the specified system time (time 
   1.292 -in nanoseconds since system boot). The hypercall actually passes the 
   1.293 -64-bit timeout value as a pair of 32-bit values. 
   1.294 +in nanoseconds since system boot).
   1.295  
   1.296  \end{quote} 
   1.297  
   1.298 -Note that calling {\tt set\_timer\_op()} prior to {\tt sched\_op} 
   1.299 +Note that calling {\bf set\_timer\_op} prior to {\bf sched\_op} 
   1.300  allows block-with-timeout semantics. 
   1.301  
   1.302  
   1.303 @@ -1757,20 +1783,20 @@ a new page-table base pointer, and more.
   1.304  \begin{quote} 
   1.305  \hypercall{mmu\_update(mmu\_update\_t *req, int count, int *success\_count)} 
   1.306  
   1.307 -Update the page table for the domain; a set of {\tt count} updates are
   1.308 -submitted for processing in a batch, with {\tt success\_count} being 
   1.309 +Update the page table for the domain; a set of {\bf count} updates are
   1.310 +submitted for processing in a batch, with {\bf success\_count} being 
   1.311  updated to report the number of successful updates.  
   1.312  
   1.313 -Each element of {\tt req[]} contains a pointer (address) and value; 
   1.314 +Each element of {\bf req[]} contains a pointer (address) and value; 
   1.315  the least significant 2-bits of the pointer are used to distinguish 
   1.316  the type of update requested as follows:
   1.317  \begin{description} 
   1.318  
   1.319 -\item[\it MMU\_NORMAL\_PT\_UPDATE:] update a page directory entry or
   1.320 +\item[MMU\_NORMAL\_PT\_UPDATE:] update a page directory entry or
   1.321  page table entry to the associated value; Xen will check that the
   1.322  update is safe, as described in Chapter~\ref{c:memory}.
   1.323  
   1.324 -\item[\it MMU\_MACHPHYS\_UPDATE:] update an entry in the
   1.325 +\item[MMU\_MACHPHYS\_UPDATE:] update an entry in the
   1.326    machine-to-physical table. The calling domain must own the machine
   1.327    page in question (or be privileged).
   1.328  \end{description}
   1.329 @@ -1792,9 +1818,9 @@ This is catered for by the following:
   1.330  \hypercall{update\_va\_mapping(unsigned long va, uint64\_t val,
   1.331                           unsigned long flags)}
   1.332  
   1.333 -Update the currently installed PTE that maps virtual address {\tt va}
   1.334 -to new value {\tt val}. As with {\tt mmu\_update()}, Xen checks the
   1.335 -modification  is safe before applying it. The {\tt flags} determine
   1.336 +Update the currently installed PTE that maps virtual address {\bf va}
   1.337 +to new value {\bf val}. As with {\bf mmu\_update}, Xen checks the
   1.338 +modification  is safe before applying it. The {\bf flags} determine
   1.339  which kind of TLB flush, if any, should follow the update. 
   1.340  
   1.341  \end{quote} 
   1.342 @@ -1806,8 +1832,8 @@ the pages of others:
   1.343  \hypercall{update\_va\_mapping(unsigned long va, uint64\_t val,
   1.344                           unsigned long flags, domid\_t domid)}
   1.345  
   1.346 -Identical to {\tt update\_va\_mapping()} save that the pages being
   1.347 -mapped must belong to the domain {\tt domid}. 
   1.348 +Identical to {\bf update\_va\_mapping} save that the pages being
   1.349 +mapped must belong to the domain {\bf domid}. 
   1.350  
   1.351  \end{quote}
   1.352  
   1.353 @@ -1854,17 +1880,17 @@ this is context switched transparently w
   1.354  \begin{quote}
   1.355  \hypercall{set\_gdt(unsigned long *frame\_list, int entries)} 
   1.356  
   1.357 -Install a global descriptor table for a domain; {\tt frame\_list} is
   1.358 +Install a global descriptor table for a domain; {\bf frame\_list} is
   1.359  an array of up to 16 machine page frames within which the GDT resides,
   1.360 -with {\tt entries} being the actual number of descriptor-entry
   1.361 +with {\bf entries} being the actual number of descriptor-entry
   1.362  slots. All page frames must be mapped read-only within the guest's
   1.363  address space, and the table must be large enough to contain Xen's
   1.364 -reserved entries (see {\tt xen/include/public/arch-x86\_32.h}).
   1.365 +reserved entries (see {\bf xen/include/public/arch-x86\_32.h}).
   1.366  
   1.367  \end{quote}
   1.368  
   1.369  Many guest OSes will also wish to install LDTs; this is achieved by
   1.370 -using {\tt mmu\_update()} with an extended command, passing the
   1.371 +using {\bf mmu\_update} with an extended command, passing the
   1.372  linear address of the LDT base along with the number of entries. No
   1.373  special safety checks are required; Xen needs to perform this task
   1.374  simply since {\tt lldt} requires CPL 0.
   1.375 @@ -1876,8 +1902,8 @@ individual segment descriptor in the GDT
   1.376  \begin{quote}
   1.377  \hypercall{update\_descriptor(uint64\_t ma, uint64\_t desc)}
   1.378  
   1.379 -Update the GDT/LDT entry at machine address {\tt ma}; the new
   1.380 -8-byte descriptor is stored in {\tt desc}.
   1.381 +Update the GDT/LDT entry at machine address {\bf ma}; the new
   1.382 +8-byte descriptor is stored in {\bf desc}.
   1.383  Xen performs a number of checks to ensure the descriptor is 
   1.384  valid. 
   1.385  
   1.386 @@ -1897,8 +1923,8 @@ stack pointer:
   1.387  \begin{quote} 
   1.388  \hypercall{stack\_switch(unsigned long ss, unsigned long esp)} 
   1.389  
   1.390 -Request kernel stack switch from hypervisor; {\tt ss} is the new 
   1.391 -stack segment, which {\tt esp} is the new stack pointer. 
   1.392 +Request kernel stack switch from hypervisor; {\bf ss} is the new 
   1.393 +stack segment, which {\bf esp} is the new stack pointer. 
   1.394  
   1.395  \end{quote} 
   1.396  
   1.397 @@ -1939,18 +1965,18 @@ following call:
   1.398  \hypercall{memory\_op(unsigned int op, void *arg)}
   1.399  
   1.400  Increase or decrease current memory allocation (as determined by 
   1.401 -the value of {\tt op}).  The available operations are:
   1.402 +the value of {\bf op}).  The available operations are:
   1.403  
   1.404  \begin{description}
   1.405  \item[XENMEM\_increase\_reservation] Request an increase in machine
   1.406 -  memory allocation; {\tt arg} must point to a {\tt
   1.407 +  memory allocation; {\bf arg} must point to a {\bf
   1.408    xen\_memory\_reservation} structure.
   1.409  \item[XENMEM\_decrease\_reservation] Request a decrease in machine
   1.410 -  memory allocation; {\tt arg} must point to a {\tt
   1.411 +  memory allocation; {\bf arg} must point to a {\bf
   1.412    xen\_memory\_reservation} structure.
   1.413  \item[XENMEM\_maximum\_ram\_page] Request the frame number of the
   1.414 -  highest-addressed frame of machine memory in the system.  {\tt arg}
   1.415 -  must point to an {\tt unsigned long} where this value will be
   1.416 +  highest-addressed frame of machine memory in the system.  {\bf arg}
   1.417 +  must point to an {\bf unsigned long} where this value will be
   1.418    stored.
   1.419  \item[XENMEM\_current\_reservation] Returns current memory reservation
   1.420    of the specified domain.
   1.421 @@ -1982,31 +2008,31 @@ The control and use of event channels in
   1.422  \begin{quote}
   1.423  \hypercall{event\_channel\_op(evtchn\_op\_t *op)} 
   1.424  
   1.425 -Inter-domain event-channel management; {\tt op} is a discriminated 
   1.426 +Inter-domain event-channel management; {\bf op} is a discriminated 
   1.427  union which allows the following 7 operations: 
   1.428  
   1.429  \begin{description} 
   1.430  
   1.431 -\item[\it alloc\_unbound:] allocate a free (unbound) local
   1.432 +\item[alloc\_unbound:] allocate a free (unbound) local
   1.433    port and prepare for connection from a specified domain. 
   1.434 -\item[\it bind\_virq:] bind a local port to a virtual 
   1.435 +\item[bind\_virq:] bind a local port to a virtual 
   1.436  IRQ; any particular VIRQ can be bound to at most one port per domain. 
   1.437 -\item[\it bind\_pirq:] bind a local port to a physical IRQ;
   1.438 +\item[bind\_pirq:] bind a local port to a physical IRQ;
   1.439  once more, a given pIRQ can be bound to at most one port per
   1.440  domain. Furthermore the calling domain must be sufficiently
   1.441  privileged.
   1.442 -\item[\it bind\_interdomain:] construct an interdomain event 
   1.443 +\item[bind\_interdomain:] construct an interdomain event 
   1.444  channel; in general, the target domain must have previously allocated 
   1.445  an unbound port for this channel, although this can be bypassed by 
   1.446  privileged domains during domain setup. 
   1.447 -\item[\it close:] close an interdomain event channel. 
   1.448 -\item[\it send:] send an event to the remote end of a 
   1.449 +\item[close:] close an interdomain event channel. 
   1.450 +\item[send:] send an event to the remote end of a 
   1.451  interdomain event channel. 
   1.452 -\item[\it status:] determine the current status of a local port. 
   1.453 +\item[status:] determine the current status of a local port. 
   1.454  \end{description} 
   1.455  
   1.456  For more details see
   1.457 -{\tt xen/include/public/event\_channel.h}. 
   1.458 +{\bf xen/include/public/event\_channel.h}. 
   1.459  
   1.460  \end{quote} 
   1.461  
   1.462 @@ -2018,7 +2044,7 @@ high-performance inter-domain communicat
   1.463  
   1.464  Safe sharing of memory pages between guest OSes is carried out by
   1.465  granting access on a per page basis to individual domains. This is
   1.466 -achieved by using the {\tt grant\_table\_op()} hypercall.
   1.467 +achieved by using the {\tt grant\_table\_op} hypercall.
   1.468  
   1.469  \begin{quote}
   1.470  \hypercall{grant\_table\_op(unsigned int cmd, void *uop, unsigned int count)}
   1.471 @@ -2047,7 +2073,7 @@ TSS IO bitmap.
   1.472  \end{quote} 
   1.473  
   1.474  
   1.475 -For examples of using {\tt physdev\_op()}, see the 
   1.476 +For examples of using {\tt physdev\_op}, see the 
   1.477  Xen-specific PCI code in the linux sparse tree. 
   1.478  
   1.479  \section{Administrative Operations}
   1.480 @@ -2066,81 +2092,81 @@ below: for more details on any or all of
   1.481  Administrative domain operations for domain management. The options are:
   1.482  
   1.483  \begin{description} 
   1.484 -\item [\it DOM0\_GETMEMLIST:] get list of pages used by the domain
   1.485 -
   1.486 -\item [\it DOM0\_SCHEDCTL:]
   1.487 -
   1.488 -\item [\it DOM0\_ADJUSTDOM:] adjust scheduling priorities for domain
   1.489 -
   1.490 -\item [\it DOM0\_CREATEDOMAIN:] create a new domain
   1.491 -
   1.492 -\item [\it DOM0\_DESTROYDOMAIN:] deallocate all resources associated
   1.493 +\item [DOM0\_GETMEMLIST:] get list of pages used by the domain
   1.494 +
   1.495 +\item [DOM0\_SCHEDCTL:]
   1.496 +
   1.497 +\item [DOM0\_ADJUSTDOM:] adjust scheduling priorities for domain
   1.498 +
   1.499 +\item [DOM0\_CREATEDOMAIN:] create a new domain
   1.500 +
   1.501 +\item [DOM0\_DESTROYDOMAIN:] deallocate all resources associated
   1.502  with a domain
   1.503  
   1.504 -\item [\it DOM0\_PAUSEDOMAIN:] remove a domain from the scheduler run 
   1.505 +\item [DOM0\_PAUSEDOMAIN:] remove a domain from the scheduler run 
   1.506  queue. 
   1.507  
   1.508 -\item [\it DOM0\_UNPAUSEDOMAIN:] mark a paused domain as schedulable
   1.509 +\item [DOM0\_UNPAUSEDOMAIN:] mark a paused domain as schedulable
   1.510    once again. 
   1.511  
   1.512 -\item [\it DOM0\_GETDOMAININFO:] get statistics about the domain
   1.513 -
   1.514 -\item [\it DOM0\_SETDOMAININFO:] set VCPU-related attributes
   1.515 -
   1.516 -\item [\it DOM0\_MSR:] read or write model specific registers
   1.517 -
   1.518 -\item [\it DOM0\_DEBUG:] interactively invoke the debugger
   1.519 -
   1.520 -\item [\it DOM0\_SETTIME:] set system time
   1.521 -
   1.522 -\item [\it DOM0\_GETPAGEFRAMEINFO:] 
   1.523 -
   1.524 -\item [\it DOM0\_READCONSOLE:] read console content from hypervisor buffer ring
   1.525 -
   1.526 -\item [\it DOM0\_PINCPUDOMAIN:] pin domain to a particular CPU
   1.527 -
   1.528 -\item [\it DOM0\_TBUFCONTROL:] get and set trace buffer attributes
   1.529 -
   1.530 -\item [\it DOM0\_PHYSINFO:] get information about the host machine
   1.531 -
   1.532 -\item [\it DOM0\_SCHED\_ID:] get the ID of the current Xen scheduler
   1.533 -
   1.534 -\item [\it DOM0\_SHADOW\_CONTROL:] switch between shadow page-table modes
   1.535 -
   1.536 -\item [\it DOM0\_SETDOMAINMAXMEM:] set maximum memory allocation of a domain
   1.537 -
   1.538 -\item [\it DOM0\_GETPAGEFRAMEINFO2:] batched interface for getting
   1.539 +\item [DOM0\_GETDOMAININFO:] get statistics about the domain
   1.540 +
   1.541 +\item [DOM0\_SETDOMAININFO:] set VCPU-related attributes
   1.542 +
   1.543 +\item [DOM0\_MSR:] read or write model specific registers
   1.544 +
   1.545 +\item [DOM0\_DEBUG:] interactively invoke the debugger
   1.546 +
   1.547 +\item [DOM0\_SETTIME:] set system time
   1.548 +
   1.549 +\item [DOM0\_GETPAGEFRAMEINFO:] 
   1.550 +
   1.551 +\item [DOM0\_READCONSOLE:] read console content from hypervisor buffer ring
   1.552 +
   1.553 +\item [DOM0\_PINCPUDOMAIN:] pin domain to a particular CPU
   1.554 +
   1.555 +\item [DOM0\_TBUFCONTROL:] get and set trace buffer attributes
   1.556 +
   1.557 +\item [DOM0\_PHYSINFO:] get information about the host machine
   1.558 +
   1.559 +\item [DOM0\_SCHED\_ID:] get the ID of the current Xen scheduler
   1.560 +
   1.561 +\item [DOM0\_SHADOW\_CONTROL:] switch between shadow page-table modes
   1.562 +
   1.563 +\item [DOM0\_SETDOMAINMAXMEM:] set maximum memory allocation of a domain
   1.564 +
   1.565 +\item [DOM0\_GETPAGEFRAMEINFO2:] batched interface for getting
   1.566  page frame info
   1.567  
   1.568 -\item [\it DOM0\_ADD\_MEMTYPE:] set MTRRs
   1.569 -
   1.570 -\item [\it DOM0\_DEL\_MEMTYPE:] remove a memory type range
   1.571 -
   1.572 -\item [\it DOM0\_READ\_MEMTYPE:] read MTRR
   1.573 -
   1.574 -\item [\it DOM0\_PERFCCONTROL:] control Xen's software performance
   1.575 +\item [DOM0\_ADD\_MEMTYPE:] set MTRRs
   1.576 +
   1.577 +\item [DOM0\_DEL\_MEMTYPE:] remove a memory type range
   1.578 +
   1.579 +\item [DOM0\_READ\_MEMTYPE:] read MTRR
   1.580 +
   1.581 +\item [DOM0\_PERFCCONTROL:] control Xen's software performance
   1.582  counters
   1.583  
   1.584 -\item [\it DOM0\_MICROCODE:] update CPU microcode
   1.585 -
   1.586 -\item [\it DOM0\_IOPORT\_PERMISSION:] modify domain permissions for an
   1.587 +\item [DOM0\_MICROCODE:] update CPU microcode
   1.588 +
   1.589 +\item [DOM0\_IOPORT\_PERMISSION:] modify domain permissions for an
   1.590  IO port range (enable / disable a range for a particular domain)
   1.591  
   1.592 -\item [\it DOM0\_GETVCPUCONTEXT:] get context from a VCPU
   1.593 -
   1.594 -\item [\it DOM0\_GETVCPUINFO:] get current state for a VCPU
   1.595 -\item [\it DOM0\_GETDOMAININFOLIST:] batched interface to get domain
   1.596 +\item [DOM0\_GETVCPUCONTEXT:] get context from a VCPU
   1.597 +
   1.598 +\item [DOM0\_GETVCPUINFO:] get current state for a VCPU
   1.599 +\item [DOM0\_GETDOMAININFOLIST:] batched interface to get domain
   1.600  info
   1.601  
   1.602 -\item [\it DOM0\_PLATFORM\_QUIRK:] inform Xen of a platform quirk it
   1.603 +\item [DOM0\_PLATFORM\_QUIRK:] inform Xen of a platform quirk it
   1.604  needs to handle (e.g. noirqbalance)
   1.605  
   1.606 -\item [\it DOM0\_PHYSICAL\_MEMORY\_MAP:] get info about dom0's memory
   1.607 +\item [DOM0\_PHYSICAL\_MEMORY\_MAP:] get info about dom0's memory
   1.608  map
   1.609  
   1.610 -\item [\it DOM0\_MAX\_VCPUS:] change max number of VCPUs for a domain
   1.611 -
   1.612 -\item [\it DOM0\_SETDOMAINHANDLE:] set the handle for a domain
   1.613 +\item [DOM0\_MAX\_VCPUS:] change max number of VCPUs for a domain
   1.614 +
   1.615 +\item [DOM0\_SETDOMAINHANDLE:] set the handle for a domain
   1.616  
   1.617  \end{description} 
   1.618  \end{quote} 
   1.619 @@ -2172,20 +2198,20 @@ A few additional hypercalls are mainly u
   1.620  
   1.621  Use Xen to interact with the console; operations are:
   1.622  
   1.623 -{\it CONSOLEIO\_write}: Output count characters from buffer str.
   1.624 -
   1.625 -{\it CONSOLEIO\_read}: Input at most count characters into buffer str.
   1.626 +{CONSOLEIO\_write}: Output count characters from buffer str.
   1.627 +
   1.628 +{CONSOLEIO\_read}: Input at most count characters into buffer str.
   1.629  \end{quote} 
   1.630  
   1.631  A pair of hypercalls allows access to the underlying debug registers: 
   1.632  \begin{quote}
   1.633  \hypercall{set\_debugreg(int reg, unsigned long value)}
   1.634  
   1.635 -Set debug register {\tt reg} to {\tt value} 
   1.636 +Set debug register {\bf reg} to {\bf value} 
   1.637  
   1.638  \hypercall{get\_debugreg(int reg)}
   1.639  
   1.640 -Return the contents of the debug register {\tt reg}
   1.641 +Return the contents of the debug register {\bf reg}
   1.642  \end{quote}
   1.643  
   1.644  And finally: 
     2.1 --- a/xen/include/public/sched.h	Wed Mar 15 13:35:43 2006 +0100
     2.2 +++ b/xen/include/public/sched.h	Wed Mar 15 19:19:22 2006 +0100
     2.3 @@ -12,24 +12,18 @@
     2.4  #include "event_channel.h"
     2.5  
     2.6  /*
     2.7 - * There are two forms of this hypercall.
     2.8 - * 
     2.9 - * The first and preferred version is only available from Xen 3.0.2. 
    2.10   * The prototype for this hypercall is:
    2.11   *  long sched_op_new(int cmd, void *arg)
    2.12   * @cmd == SCHEDOP_??? (scheduler operation).
    2.13   * @arg == Operation-specific extra argument(s), as described below.
    2.14   * 
    2.15 - * The legacy version of this hypercall supports only the following commands:
    2.16 - * SCHEDOP_yield, SCHEDOP_block, and SCHEDOP_shutdown. The prototype for the
    2.17 - * legacy hypercall is:
    2.18 + * **NOTE**:
    2.19 + * Versions of Xen prior to 3.0.2 provide only the following legacy version
    2.20 + * of this hypercall, supporting only the commands yield, block and shutdown:
    2.21   *  long sched_op(int cmd, unsigned long arg)
    2.22   * @cmd == SCHEDOP_??? (scheduler operation).
    2.23   * @arg == 0               (SCHEDOP_yield and SCHEDOP_block)
    2.24   *      == SHUTDOWN_* code (SCHEDOP_shutdown)
    2.25 - * 
    2.26 - * The sub-command descriptions below describe extra arguments for the
    2.27 - * sched_op_new() hypercall.
    2.28   */
    2.29  
    2.30  /*