Merge with xen-unstable.hg.

Signed-off-by: Hollis Blanchard <hollisb@us.ibm.com>

1 files changed, 149 insertions, 0 deletions

diff --git a/docs/xen-api/presentation.tex b/docs/xen-api/presentation.tex
new file mode 100644
index 0000000000..0072704646
--- /dev/null
+++ b/docs/xen-api/presentation.tex
@@ -0,0 +1,149 @@
+%
+% Copyright (c) 2006 XenSource, Inc.
+%
+% Permission is granted to copy, distribute and/or modify this document under
+% the terms of the GNU Free Documentation License, Version 1.2 or any later
+% version published by the Free Software Foundation; with no Invariant
+% Sections, no Front-Cover Texts and no Back-Cover Texts.  A copy of the
+% license is included in the section entitled
+% "GNU Free Documentation License" or the file fdl.tex.
+%
+% Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
+%
+
+The API is presented here as a set of Remote Procedure Calls, with a wire
+format based upon XML-RPC. No specific language bindings are prescribed,
+although examples will be given in the python programming language.
+ 
+Although we adopt some terminology from object-oriented programming, 
+future client language bindings may or may not be object oriented.
+The API reference uses the terminology {\em classes\/} and {\em objects\/}.
+For our purposes a {\em class\/} is simply a hierarchical namespace;
+an {\em object\/} is an instance of a class with its fields set to
+specific values. Objects are persistent and exist on the server-side.
+Clients may obtain opaque references to these server-side objects and then
+access their fields via get/set RPCs.
+
+%In each class there is a $\mathit{uid}$ field that assigns an indentifier
+%to each object. This $\mathit{uid}$ serves as an object reference
+%on both client- and server-side, and is often included as an argument in
+%RPC messages.
+
+For each class we specify a list of
+fields along with their {\em types\/} and {\em qualifiers\/}.  A
+qualifier is one of:
+\begin{itemize}
+  \item $\mathit{RO}_\mathit{run}$: the field is Read
+Only. Furthermore, its value is automatically computed at runtime.
+For example: current CPU load and disk IO throughput.
+  \item $\mathit{RO}_\mathit{ins}$: the field must be manually set
+when a new object is created, but is then Read Only for
+the duration of the object's life.
+For example, the maximum memory addressable by a guest is set 
+before the guest boots.
+  \item $\mathit{RW}$: the field is Read/Write. For example, the name
+of a VM.
+\end{itemize}
+
+A full list of types is given in Chapter~\ref{api-reference}. However,
+there are three types that require explicit mention:
+\begin{itemize}
+  \item $t~\mathit{Ref}$: signifies a reference to an object
+of type $t$.
+  \item $t~\mathit{Set}$: signifies a set containing
+values of type $t$.
+  \item $(t_1, t_2)~\mathit{Map}$: signifies a mapping from values of
+type $t_1$ to values of type $t_2$.
+\end{itemize}
+
+Note that there are a number of cases where {\em Ref}s are {\em doubly
+linked\/}---e.g.\ a VM has a field called {\tt groups} of type
+$(\mathit{VMGroup}~\mathit{Ref})~\mathit{Set}$; this field lists
+the VMGroups that a particular VM is part of. Similarly, the VMGroups
+class has a field called {\tt VMs} of type $(\mathit{VM}~{\mathit
+Ref})~\mathit{Set}$ that contains the VMs that are part of a particular
+VMGroup. These two fields are {\em bound together\/}, in the sense that
+adding a new VMGroup to a VM causes the VMs field of the corresponding
+VMGroup object to be updated automatically.
+
+The API reference explicitly lists the fields that are
+bound together in this way. It also contains a diagram that shows
+relationships between classes. In this diagram an edge signifies the
+existance of a pair of fields that are bound together, using standard
+crows-foot notation to signify the type of relationship (e.g.\
+one-many, many-many).
+
+\section{RPCs associated with fields}
+
+Each field, {\tt f}, has an RPC accessor associated with it
+that returns {\tt f}'s value:
+\begin{itemize}
+\item ``{\tt get\_f(Ref x)}'': takes a
+{\tt Ref} that refers to an object and returns the value of {\tt f}.
+\end{itemize}
+
+Each field, {\tt f}, with attribute
+{\em RW} and whose outermost type is {\em Set\/} has the following
+additional RPCs associated with it:
+\begin{itemize}
+\item an ``{\tt add\_to\_f(Ref x, v)}'' RPC adds a new element v to the set\footnote{
+%
+Since sets cannot contain duplicate values this operation has no action in the case
+that {\tt v} was already in the set.
+%
+};
+\item a ``{\tt remove\_from\_f(Ref x, v)}'' RPC removes element {\tt v} from the set;
+\end{itemize}
+
+Each field, {\tt f}, with attribute
+{\em RW} and whose outermost type is {\em Map\/} has the following
+additional RPCs associated with it:
+\begin{itemize}
+\item an ``{\tt add\_to\_f(Ref x, k, v)}'' RPC adds new pair {\tt (k, v)}
+to the mapping stored in {\tt f} in object {\tt x}. Adding a new pair for duplicate
+key, {\tt k}, overwrites any previous mapping for {\tt k}.
+\item a ``{\tt remove\_from\_f(Ref x, k)}'' RPC removes the pair with key {\tt k}
+from the mapping stored in {\tt f} in object {\tt x}.
+\end{itemize}
+
+Each field whose outermost type is neither {\em Set\/} nor {\em Map\/}, 
+but whose attribute is {\em RW} has an RPC acessor associated with it
+that sets its value:
+\begin{itemize}
+\item For {\em RW\/} ({\em R\/}ead/{\em
+W\/}rite), a ``{\tt set\_f(Ref x, v)}'' RPC function is also provided.
+This sets field {\tt f} on object {\tt x} to value {\tt v}.
+\end{itemize}
+
+\section{RPCs associated with classes}
+
+\begin{itemize}
+\item Each class has a {\em constructor\/} RPC named ``{\tt create}'' that
+takes as parameters all fields marked {\em RW\/} and
+$\mathit{RO}_\mathit{ins}$. The result of this RPC is that a new {\em
+persistent\/} object is created on the server-side with the specified field
+values.
+
+\item Each class has a {\tt get\_by\_uuid(uuid)} RPC that returns the object
+of that class that has the specified {\tt uuid}.
+
+\item Each class that has a {\tt name\_label} field has a
+``{\tt get\_by\_name\_label(name)}'' RPC that returns a set of objects of that
+class that have the specified {\tt label}.
+
+\item Each class has a ``{\tt to\_XML()}'' RPC that serialises the
+state of all fields as an XML string.
+
+\item Each class has a ``{\tt destroy(Ref x)}'' RPC that explicitly deletes
+the persistent object specified by {\tt x} from the system.  This is a
+non-cascading delete -- if the object being removed is referenced by another
+object then the {\tt destroy} call will fail.
+
+\end{itemize}
+
+\subsection{Additional RPCs}
+
+As well as the RPCs enumerated above, some classes have additional RPCs
+associated with them. For example, the {\tt VM} class have RPCs for cloning,
+suspending, starting etc. Such additional RPCs are described explicitly
+in the API reference.