ia64/xen-unstable

changeset 1940:0e15e81cb8a2

bitkeeper revision 1.1108.23.8 (4106ba094B7aR7HwylABYVZ3aPpD8Q)

Bring portions of the interface docs more in line with 2.0.
author mwilli2@equilibrium.research.intel-research.net
date Tue Jul 27 20:24:41 2004 +0000 (2004-07-27)
parents 5f7f135d0209
children d3c2a4bdc6b4
files docs/interface.tex
line diff
     1.1 --- a/docs/interface.tex	Tue Jul 27 20:03:13 2004 +0000
     1.2 +++ b/docs/interface.tex	Tue Jul 27 20:24:41 2004 +0000
     1.3 @@ -259,37 +259,43 @@ table updates and also on remapping memo
     1.4  
     1.5  
     1.6  \chapter{Network I/O}
     1.7 -Since the hypervisor must multiplex network resources, its network subsystem
     1.8 -may be viewed as a virtual network switching element with each domain having
     1.9 -one or more virtual network interfaces to this network.
    1.10  
    1.11 -The hypervisor acts conceptually as an IP router, forwarding each domain's
    1.12 -traffic according to a set of rules.
    1.13 +Virtual network device services are provided by shared memory
    1.14 +communications with a `backend' domain.  From the point of view of
    1.15 +other domains, the backend may be viewed as a virtual ethernet switch
    1.16 +element with each domain having one or more virtual network interfaces
    1.17 +connected to it.
    1.18  
    1.19 -\section{Hypervisor Packet Handling}
    1.20 -The hypervisor is responsible primarily for {\it data-path} operations.
    1.21 +\section{Backend Packet Handling}
    1.22 +The backend driver is responsible primarily for {\it data-path} operations.
    1.23  In terms of networking this means packet transmission and reception.
    1.24  
    1.25 -On the transmission side, the hypervisor needs to perform two key actions:
    1.26 +On the transmission side, the backend needs to perform two key actions:
    1.27  \begin{itemize}
    1.28 -\item {\tt Validation:} A domain is only allowed to emit packets matching a certain
    1.29 -specification; for example, ones in which the source IP address matches
    1.30 -one assigned to the virtual interface over which it is sent. The hypervisor
    1.31 -is responsible for ensuring any such requirements are met, either by checking
    1.32 -or by stamping outgoing packets with prescribed values for certain fields.
    1.33 +\item {\tt Validation:} A domain is only allowed to emit packets
    1.34 +matching a certain specification; for example, ones in which the
    1.35 +source IP address matches one assigned to the virtual interface over
    1.36 +which it is sent. The backend is responsible for ensuring any such
    1.37 +requirements are met, either by checking or by stamping outgoing
    1.38 +packets with prescribed values for certain fields.
    1.39 +
    1.40 +Validation functions can be configured using standard firewall rules
    1.41 +(i.e. IP Tables, in the case of Linux).
    1.42  
    1.43 -\item {\tt Scheduling:} Since a number of domains can share a single ``real'' network 
    1.44 -interface, the hypervisor must mediate access when several domains each 
    1.45 -have packets queued for transmission. Of course, this general scheduling
    1.46 -function subsumes basic shaping or rate-limiting schemes.
    1.47 +\item {\tt Scheduling:} Since a number of domains can share a single
    1.48 +``real'' network interface, the hypervisor must mediate access when
    1.49 +several domains each have packets queued for transmission. Of course,
    1.50 +this general scheduling function subsumes basic shaping or
    1.51 +rate-limiting schemes.
    1.52  
    1.53 -\item {\tt Logging and Accounting:} The hypervisor can be configured with classifier 
    1.54 -rules that control how packets are accounted or logged. For example, 
    1.55 -{\it domain0} could request that it receives a log message or copy of the
    1.56 -packet whenever another domain attempts to send a TCP packet containg a 
    1.57 -SYN.
    1.58 +\item {\tt Logging and Accounting:} The hypervisor can be configured
    1.59 +with classifier rules that control how packets are accounted or
    1.60 +logged. For example, {\it domain0} could request that it receives a
    1.61 +log message or copy of the packet whenever another domain attempts to
    1.62 +send a TCP packet containg a SYN.
    1.63  \end{itemize}
    1.64 -On the recive side, the hypervisor's role is relatively straightforward:
    1.65 +
    1.66 +On the recive side, the backend's role is relatively straightforward:
    1.67  once a packet is received, it just needs to determine the virtual interface(s)
    1.68  to which it must be delivered and deliver it via page-flipping. 
    1.69  
    1.70 @@ -336,42 +342,33 @@ an event to the domain.
    1.71  
    1.72  \section{Virtual Block Devices (VBDs)}
    1.73  
    1.74 -All guest OS disk access goes through the VBD interface. The VBD interface
    1.75 -provides the administrator with the ability to selectively grant domains 
    1.76 -access to portions of block storage devices visible to the system.
    1.77 -
    1.78 -A VBD can also be comprised of a set of extents from multiple storage devices.
    1.79 -This provides the same functionality as a concatenated disk driver.
    1.80 -
    1.81 -\section{Virtual Disks (VDs)}
    1.82 +All guest OS disk access goes through the VBD interface. The VBD
    1.83 +interface provides the administrator with the ability to selectively
    1.84 +grant domains access to portions of block storage devices visible to
    1.85 +the the block backend device (usually domain 0).
    1.86  
    1.87 -VDs are an abstraction built on top of the VBD interface. One can reserve disk
    1.88 -space for use by the VD layer. This space is then managed as a pool of free extents.
    1.89 -The VD tools can automatically allocate collections of extents from this pool to
    1.90 -create ``virtual disks'' on demand. 
    1.91 +VBDs can literally be backed by any block device accessible to the
    1.92 +backend domain, including network-based block devices (iSCSI, *NBD,
    1.93 +etc), loopback devices and LVM / MD devices.
    1.94  
    1.95 -\subsection{Virtual Disk Management}
    1.96 -The VD management code consists of a set of python libraries. It can therefore
    1.97 -be accessed by custom scripts as well as the convenience scripts provided. The
    1.98 -VD database is a SQLite database in /var/db/xen\_vdisks.sqlite.
    1.99 -
   1.100 -The VD scripts and general VD usage are documented in the VBD-HOWTO.txt.
   1.101 +Old (Xen 1.2) virtual disks are not supported under Xen 2.0, since
   1.102 +similar functionality can be achieved using the (more advanced) LVM
   1.103 +system, which is already in widespread use.
   1.104  
   1.105  \subsection{Data Transfer}
   1.106  Domains which have been granted access to a logical block device are permitted
   1.107 -to read and write it directly through the hypervisor, rather than requiring
   1.108 -{\it domain0} to mediate every data access. 
   1.109 -
   1.110 -In overview, the same style of descriptor-ring that is used for network
   1.111 -packets is used here. Each domain has one ring that carries operation requests to the 
   1.112 -hypervisor and carries the results back again. 
   1.113 +to read and write it by shared memory communications with the backend domain. 
   1.114  
   1.115 -Rather than copying data in and out of the hypervisor, we use page pinning to
   1.116 -enable DMA transfers directly between the physical device and the domain's 
   1.117 -buffers. Disk read operations are straightforward; the hypervisor just needs
   1.118 -to know which pages have pending DMA transfers, and prevent the guest OS from
   1.119 -giving the page back to the hypervisor, or to use them for storing page tables.
   1.120 +In overview, the same style of descriptor-ring that is used for
   1.121 +network packets is used here. Each domain has one ring that carries
   1.122 +operation requests to the hypervisor and carries the results back
   1.123 +again.
   1.124  
   1.125 +Rather than copying data, the backend simply maps the domain's buffers
   1.126 +in order to enable direct DMA to them.  The act of mapping the buffers
   1.127 +also increases the reference counts of the underlying pages, so that
   1.128 +the unprivileged domain cannot try to return them to the hypervisor,
   1.129 +install them as page tables, or any other unsafe behaviour.
   1.130  %block API here 
   1.131  
   1.132  \chapter{Privileged operations}
   1.133 @@ -811,9 +808,7 @@ in kilobytes.
   1.134  
   1.135  {\it DOM0\_GETPAGEFRAMEINFO}:
   1.136  
   1.137 -{\it DOM0\_IOPL}:
   1.138 -
   1.139 -{\it DOM0\_MSR}:
   1.140 +{\it DOM0\_IOPL}: set IO privilege level
   1.141  
   1.142  {\it DOM0\_DEBUG}: interactively call pervasive debugger
   1.143  
   1.144 @@ -830,11 +825,13 @@ in kilobytes.
   1.145  
   1.146  {\it DOM0\_PCIDEV\_ACCESS}: modify PCI device access permissions
   1.147  
   1.148 +{\it DOM0\_SCHED\_ID}: get the ID of the current Xen scheduler
   1.149  
   1.150 -\section{network\_op(network\_op\_t *op)} 
   1.151 -update network ruleset
   1.152 +{\it DOM0\_SETDOMAINNAME}: set the name of a domain
   1.153  
   1.154 -\section{ block\_io\_op(block\_io\_op\_t *op)}
   1.155 +{\it DOM0\_SETDOMAININITIALMEM}: set initial memory allocation of a domain
   1.156 +
   1.157 +{\it DOM0\_GETPAGEFRAMEINFO2}:
   1.158  
   1.159  \section{ set\_debugreg(int reg, unsigned long value)}
   1.160  set debug register reg to value
   1.161 @@ -847,7 +844,7 @@ set debug register reg to value
   1.162  \section{ set\_fast\_trap(int idx)}
   1.163   install traps to allow guest OS to bypass hypervisor
   1.164  
   1.165 -\section{ dom\_mem\_op(dom\_mem\_op\_t *op)}
   1.166 +\section{ dom\_mem\_op(unsigned int op, void *pages, unsigned long nr\_pages)}
   1.167   increase or decrease memory reservations for guest OS
   1.168  
   1.169  \section{ multicall(multicall\_entry\_t *call\_list, int nr\_calls)}