ia64/xen-unstable

view docs/xen-api/wire-protocol.tex @ 13297:ee395551208d

Enable compatibility mode operation for HYPERVISOR_physdev_op and
HYPERVISOR_event_channel_op.

Signed-off-by: Jan Beulich <jbeulich@novell.com>
author Emmanuel Ackaouy <ack@xensource.com>
date Fri Jan 05 17:34:32 2007 +0000 (2007-01-05)
parents 568efb79a0f6
children 77041741529c
line source
1 %
2 % Copyright (c) 2006 XenSource, Inc.
3 %
4 % Permission is granted to copy, distribute and/or modify this document under
5 % the terms of the GNU Free Documentation License, Version 1.2 or any later
6 % version published by the Free Software Foundation; with no Invariant
7 % Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the
8 % license is included in the section entitled
9 % "GNU Free Documentation License" or the file fdl.tex.
10 %
11 % Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
12 %
14 \section{Wire Protocol for Remote API Calls}
16 API calls are sent over a network to a Xen-enabled host using
17 the XML-RPC protocol. In this Section we describe how the
18 higher-level types used in our API Reference are mapped to
19 primitive XML-RPC types.
21 In our API Reference we specify the signatures of API functions in the following
22 style:
23 \begin{verbatim}
24 (ref_vm Set) VM.get_all()
25 \end{verbatim}
26 This specifies that the function with name {\tt VM.get\_all} takes
27 no parameters and returns a Set of {\tt ref\_vm}s.
28 These types are mapped onto XML-RPC types in a straight-forward manner:
29 \begin{itemize}
30 \item Floats, Bools, DateTimes and Strings map directly to the XML-RPC {\tt
31 double}, {\tt boolean}, {\tt dateTime.iso8601}, and {\tt string} elements.
33 \item all our ``{\tt ref\_}'' types (e.g.\ {\tt ref\_vm} in the above
34 example) map to XML-RPC's {\tt String} type. The string itself is the OSF
35 DCE UUID presentation format (as output by {\tt uuidgen}, etc).
37 \item ints are all assumed to be 64-bit in our API and are encoded as a
38 string of decimal digits (rather than using XML-RPC's built-in 32-bit {\tt
39 i4} type).
41 \item values of enum types are encoded as strings. For example, a value of
42 {\tt destroy} of type {\tt on\_normal\_exit}, would be conveyed as:
43 \begin{verbatim}
44 <value><string>destroy</string></value>
45 \end{verbatim}
47 \item for all our types, {\tt t}, our type {\tt t Set} simply maps to
48 XML-RPC's {\tt Array} type, so for example a value of type {\tt cpu\_feature
49 Set} would be transmitted like this:
51 \begin{verbatim}
52 <array>
53 <data>
54 <value><string>CX8</string></value>
55 <value><string>PSE36</string></value>
56 <value><string>FPU</string></value>
57 </data>
58 </array>
59 \end{verbatim}
61 \item for types {\tt k} and {\tt v}, our type {\tt (k, v) Map} maps onto an
62 XML-RPC struct, with the key as the name of the struct. Note that the {\tt
63 (k, v) Map} type is only valid when {\tt k} is a {\tt String}, {\tt Ref}, or
64 {\tt Int}, and in each case the keys of the maps are stringified as
65 above. For example, the {\tt (String, double) Map} containing a the mappings
66 Mike $\rightarrow$ 2.3 and John $\rightarrow$ 1.2 would be represented as:
68 \begin{verbatim}
69 <value>
70 <struct>
71 <member>
72 <name>Mike</name>
73 <value><double>2.3</double></value>
74 </member>
75 <member>
76 <name>John</name>
77 <value><double>1.2</double></value>
78 </member>
79 </struct>
80 </value>
81 \end{verbatim}
83 \item our {\tt Void} type is transmitted as an empty string.
85 \end{itemize}
87 \subsection{Return Values/Status Codes}
88 \label{synchronous-result}
90 The return value of an RPC call is an XML-RPC {\tt Struct}.
92 \begin{itemize}
93 \item The first element of the struct is named {\tt Status}; it
94 contains a string value indicating whether the result of the call was
95 a ``{\tt Success}'' or a ``{\tt Failure}''.
96 \end{itemize}
98 If {\tt Status} was set to {\tt Success} then the Struct contains a second
99 element named {\tt Value}:
100 \begin{itemize}
101 \item The element of the struct named {\tt Value} contains the function's return value.
102 \end{itemize}
104 In the case where {\tt Status} is set to {\tt Failure} then
105 the struct contains a second element named {\tt ErrorDescription}:
106 \begin{itemize}
107 \item The element of the struct named {\tt ErrorDescription} contains
108 an array of string values. The first element of the array is an error code;
109 the remainder of the array are strings representing error parameters relating
110 to that code.
111 \end{itemize}
113 For example, an XML-RPC return value from the {\tt host.get\_resident\_VMs}
114 function above
115 may look like this:
116 \begin{verbatim}
117 <struct>
118 <member>
119 <name>Status</name>
120 <value>Success</value>
121 </member>
122 <member>
123 <name>Value</name>
124 <value>
125 <array>
126 <data>
127 <value>81547a35-205c-a551-c577-00b982c5fe00</value>
128 <value>61c85a22-05da-b8a2-2e55-06b0847da503</value>
129 <value>1d401ec4-3c17-35a6-fc79-cee6bd9811fe</value>
130 </data>
131 </array>
132 </value>
133 </member>
134 </struct>
135 \end{verbatim}
137 \section{Making XML-RPC Calls}
139 \subsection{Transport Layer}
141 We ought to support at least
142 \begin{itemize}
143 \item HTTP/S for remote administration
144 \item HTTP over Unix domain sockets for local administration
145 \end{itemize}
147 \subsection{Session Layer}
149 The XML-RPC interface is session-based; before you can make arbitrary RPC calls
150 you must login and initiate a session. For example:
151 \begin{verbatim}
152 session_id session.login_with_password(string uname, string pwd)
153 \end{verbatim}
154 Where {\tt uname} and {\tt password} refer to your username and password
155 respectively, as defined by the Xen administrator.
156 The {\tt session\_id} returned by {\tt session.login_with_password} is passed
157 to subequent RPC calls as an authentication token.
159 A session can be terminated with the {\tt session.logout} function:
160 \begin{verbatim}
161 void session.logout(session_id session)
162 \end{verbatim}
164 \subsection{Synchronous and Asynchronous invocation}
166 Each method call (apart from methods on ``Session'' and ``Task'' objects
167 and ``getters'' and ``setters'' derived from fields)
168 can be made either synchronously or asynchronously.
169 A synchronous RPC call blocks until the
170 return value is received; the return value of a synchronous RPC call is
171 exactly as specified in Section~\ref{synchronous-result}.
173 Only synchronous API calls are listed explicitly in this document.
174 All asynchronous versions are in the special {\tt Async} namespace.
175 For example, synchronous call {\tt VM.clone(...)}
176 (described in Chapter~\ref{api-reference})
177 has an asynchronous counterpart, {\tt
178 Async.VM.clone(...)}, that is non-blocking.
180 Instead of returning its result directly, an asynchronous RPC call
181 returns a {\tt task-id}; this identifier is subsequently used
182 to track the status of a running asynchronous RPC. Note that an asychronous
183 call may fail immediately, before a {\tt task-id} has even been created---to
184 represent this eventuality, the returned {\tt task-id}
185 is wrapped in an XML-RPC struct with a {\tt Status}, {\tt ErrorDescription} and
186 {\tt Value} fields, exactly as specified in Section~\ref{synchronous-result}.
188 The {\tt task-id} is provided in the {\tt Value} field if {\tt Status} is set to
189 {\tt Success}.
191 The RPC call
192 \begin{verbatim}
193 (ref_task Set) Task.get_all(session_id s)
194 \end{verbatim}
195 returns a set of all task IDs known to the system. The status (including any
196 returned result and error codes) of these tasks
197 can then be queried by accessing the fields of the Task object in the usual way.
198 Note that, in order to get a consistent snapshot of a task's state, it is advisable to call the ``get\_record'' function.
200 \section{Example interactive session}
202 This section describes how an interactive session might look, using the python
203 XML-RPC client library.
205 First, initialise python and import the library {\tt xmlrpclib}:
207 \begin{verbatim}
208 \$ python2.4
209 ...
210 >>> import xmlrpclib
211 \end{verbatim}
213 Create a python object referencing the remote server:
215 \begin{verbatim}
216 >>> xen = xmlrpclib.Server("http://test:4464")
217 \end{verbatim}
219 Acquire a session token by logging in with a username and password
220 (error-handling ommitted for brevity; the session token is pointed to by the
221 key {\tt 'Value'} in the returned dictionary)
223 \begin{verbatim}
224 >>> session = session.login_with_password("user", "passwd")['Value']
225 \end{verbatim}
227 When serialised, this call looks like the following:
229 \begin{verbatim}
230 <?xml version='1.0'?>
231 <methodCall>
232 <methodName>session.login_with_password</methodName>
233 <params>
234 <param>
235 <value><string>user</string></value>
236 </param>
237 <param>
238 <value><string>passwd</string></value>
239 </param>
240 </params>
241 </methodCall>
242 \end{verbatim}
244 Next, the user may acquire a list of all the VMs known to the host: (Note the
245 call takes the session token as the only parameter)
247 \begin{verbatim}
248 >>> all_vms = host.get_resident_VMs(session)['Value']
249 >>> all_vms
250 ['b7b92d9e-d442-4710-92a5-ab039fd7d89b', '23e1e837-abbf-4675-b077-d4007989b0cc',
251 '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2', '3202ae18-a046-4c32-9fda-e32e9631866e']
252 \end{verbatim}
254 The VM references here are UUIDs, though they may not be that simple in the
255 future, and you should treat them as opaque strings. Once a reference to a VM
256 has been acquired a lifecycle operation may be invoked:
258 \begin{verbatim}
259 >>> xen.VM.start(session, all_vms[3], False)
260 {'Status': 'Failure', 'ErrorDescription': ['VM_BAD_POWER_STATE', 'Halted', 'Running']}
261 \end{verbatim}
263 In this case the {\tt start} message has been rejected, because the VM is
264 already running, and so an error response has been returned. These high-level
265 errors are returned as structured data (rather than as XML-RPC faults),
266 allowing them to be internationalised. Finally, here are some examples of
267 using accessors for object fields:
269 \begin{verbatim}
270 >>> xen.VM.get_name_label(session, all_vms[3])['Value']
271 'SMP'
272 >>> xen.VM.get_name_description(session, all_vms[3])['Value']
273 'Debian for Xen'
274 \end{verbatim}